71 lines
3.7 KiB
Markdown
71 lines
3.7 KiB
Markdown
# Feature Specification: Hardware Devices
|
|
|
|
**Status**: Implemented
|
|
|
|
**Created**: 2026-09-20
|
|
|
|
**Scope**: MIDI hardware attached to the computer, and ports other applications provide: finding it,
|
|
following it as it is plugged in and out, recognising it again after a replug, telling identical
|
|
devices apart, and a device another application holds. Carrying hardware over the network is user
|
|
story 4, in [007-routing](../007-routing/spec.md).
|
|
|
|
Split out of the original Midi Harbor specification on 2026-09-27. Requirement, success criterion,
|
|
research and task numbers are the ones the original gave them, and the code cites them by number;
|
|
[the index](../README.md) says which spec holds each. The architecture, the daemon contract and the
|
|
command-line contract are in [001-service-and-clients](../001-service-and-clients/).
|
|
|
|
## User Scenarios & Testing *(mandatory)*
|
|
|
|
### Edge Cases
|
|
|
|
- **Device claimed by another application**: When a physical MIDI device is held exclusively by
|
|
another application, Midi Harbor reports it as in use by another application rather than failing
|
|
silently, and claims it when it becomes free.
|
|
- **Identical devices**: When two devices reporting the same name are attached at once, they are
|
|
distinguished in the interface so routes address the right one.
|
|
- **Device removed mid-message**: When a device is unplugged partway through a system-exclusive
|
|
transfer, the partial message is discarded rather than forwarded as corrupt data.
|
|
|
|
## Requirements *(mandatory)*
|
|
|
|
### Functional Requirements
|
|
|
|
#### Physical MIDI devices
|
|
|
|
- **FR-015a**: System MUST automatically discover and list physical MIDI hardware attached to the
|
|
computer — USB MIDI interfaces, DIN interfaces, controllers, and keyboards — presenting each with
|
|
its hardware-reported name.
|
|
- **FR-015b**: System MUST expose each physical MIDI input and output as an endpoint usable as a
|
|
route source or destination, on equal terms with virtual ports, network sessions, and Bluetooth
|
|
devices.
|
|
- **FR-015c**: System MUST detect physical devices being attached and removed while running, and
|
|
update the endpoint list without the user refreshing anything or restarting the service.
|
|
- **FR-015d**: System MUST retain the configuration of routes referencing a physical device while
|
|
that device is unplugged, and resume them automatically when the same device is reattached.
|
|
- **FR-015e**: System MUST identify a physical device stably enough that reattaching the same
|
|
device — including to a different port on the same computer — restores its routes rather than
|
|
presenting it as a new device.
|
|
- **FR-015f**: System MUST silence sounding notes at the destinations of a route when that route's
|
|
physical source device is removed.
|
|
- **FR-015g**: System MUST distinguish two physically identical devices attached at the same time,
|
|
so the user can tell them apart and route them separately.
|
|
|
|
### Key Entities
|
|
|
|
- **Physical MIDI Device**: An endpoint representing MIDI hardware attached to this computer. Has
|
|
a hardware-reported name, a stable identity that survives being unplugged and reattached, a
|
|
present/absent status, and separate input and output sides.
|
|
|
|
## Success Criteria *(mandatory)*
|
|
|
|
### Measurable Outcomes
|
|
|
|
- **SC-010a**: A physical MIDI device plugged in while the service is running appears as a routable
|
|
endpoint within 2 seconds, with no user action.
|
|
- **SC-010c**: Across 100 unplug-and-replug cycles of a routed physical device, 100% of routes
|
|
resume automatically and zero notes are left sounding.
|
|
|
|
## Assumptions
|
|
|
|
- Physical MIDI devices are accessed through the operating system's own MIDI layer, so any device
|
|
the operating system already recognises is usable; vendor-specific drivers are out of scope.
|