ADR: EMG backend uses USB CDC serial with hardware-agnostic message protocol¶

Context¶

YazSes v0.4 (cap-003) introduces EMG silent speech as a first-class input modality. The EMGBackend must receive events from EMG devices and route them to the daemon's state machine using the existing HotkeyBackend protocol.

The primary design question is how the EMG device communicates with the daemon: (1) USB CDC serial (the device presents as a virtual COM port), (2) Bluetooth Low Energy (BLE), or (3) device-vendor SDK integration (proprietary API per device family).

Consumer EMG hardware is fragmented: research-grade devices (OpenBCI Cyton) use USB serial; upcoming consumer wristband devices (Meta EMG) will use BLE; academic prototypes (src-005 headphone EMG) use custom radio protocols. A vendor SDK approach would lock YazSes to a single hardware vendor and require proprietary closed-source libraries — incompatible with YazSes' Apache-2.0 license and offline-first ethos.

The goal is to define a transport-independent message protocol that any EMG device can implement, with USB serial as the first transport because it is: well-supported on all platforms via pyserial, available on all research-grade devices, and deterministic in latency (no wireless jitter). BLE support is deferred to v0.4.1 pending consumer device availability.

The message protocol must be simple enough for a firmware developer with basic embedded experience to implement: the entire protocol must fit in a single page of documentation.

Decision¶

We will define the YazSes EMG Serial Protocol (YESP) as the standard interface between EMG devices and the YazSes daemon. YESP uses USB CDC serial at 115200 baud, 8-N-1, newline-delimited ASCII messages. The EMGBackend implementation uses pyserial >= 3.5 to read these messages on a background thread and dispatch events to the daemon.

The YESP message set is:

HOLD_START          — user began silent articulation (equivalent to hotkey press)
HOLD_END            — user stopped silent articulation (equivalent to hotkey release)
COMMAND:<label>     — device recognised a discrete command; label is an ASCII identifier
TEXT:<string>       — device recognised full text (sEMG full-text mode; deferred to v0.4.1)
HEARTBEAT           — device alive check; daemon ignores but logs at DEBUG

An EMG device must implement at minimum HOLD_START and HOLD_END for basic voice-gate mode, or COMMAND:<label> messages only for command-vocabulary mode. Any unrecognised message is silently discarded and logged at DEBUG. The protocol is documented in docs/emg-protocol.md. [HYPOTHESIS]

Consequences¶

Positive¶

• Any EMG hardware — research-grade (OpenBCI), DIY (Arduino), or future consumer devices — can integrate with YazSes by implementing 2–5 ASCII message types. The barrier to hardware compatibility is extremely low. [HYPOTHESIS]
• pyserial >= 3.5 is a stable, MIT-licensed library with no native code dependencies. It works on all three target platforms without platform-specific build requirements. [HYPOTHESIS]
• The protocol is transport-agnostic in its message layer — a BLE transport adapter or a WebSocket adapter can be added in v0.4.1 by implementing the same message parsing against a different transport. [HYPOTHESIS]
• [EVIDENCE src-005] The 10-command vocabulary demonstrated at 96% accuracy is directly compatible with the COMMAND:<label> message type. Device-side classification runs on the EMG hardware; YazSes receives only the labelled result, keeping the daemon implementation simple.
• Open documentation of the protocol enables hardware vendors and researchers to add YazSes compatibility to their devices without requiring changes to the YazSes codebase.

Negative¶

• USB serial requires physical cable connection. Most modern consumers expect wireless peripherals. BLE support deferred to v0.4.1 means that future consumer EMG devices (which will be BLE-primary) will not work out of the box with v0.4.0. [HYPOTHESIS]
• USB serial port names are platform-specific (/dev/ttyUSB0 on Linux, /dev/cu.usbmodem* on macOS, COMx on Windows). Users must configure the correct port name in the TOML config. yazses doctor will scan for connected serial devices and suggest candidates, but the user must select the correct one. [HYPOTHESIS]
• EMG command classification accuracy (96%, src-005) is measured for a well-calibrated per-user model. Real-world accuracy without per-user calibration may be 85–90%. The v0.4.0 release does not include a calibration wizard for EMG; users get the device's default model. [EVIDENCE src-005]

Neutral¶

• The HEARTBEAT message is included in the protocol for device health monitoring but the daemon does not act on its absence in v0.4.0 (connection loss is handled by pyserial read timeout and caught as serial.SerialException).
• The message protocol uses newline-delimited ASCII, which is human-readable and debuggable with any serial terminal (screen /dev/ttyUSB0 115200). This is a deliberate design choice for developer ergonomics.

Alternatives Considered¶

References¶

• [EVIDENCE src-005]: Headphone EMG, 96% accuracy, 10-command vocabulary, consumer form factor — directly validates the COMMAND:<label> path.
• [EVIDENCE src-006]: Transformer sEMG full-text, 10% CER — validates the TEXT:<string> path (deferred to v0.4.1).
• [EVIDENCE src-011]: Interspeech 2025 biosignal session — community validation of the research direction, not a specific technical reference for this ADR.

Output Quality Note¶

• All placeholders replaced.
• First sentence of Decision is "We will define..."
• Every claim tagged.
• deciders populated.
• Alternatives table has ≥ 2 rows.
• Negative consequences section is honest.

Study: [[yazses-future-voice-hci/input/research_scope|yazses-future-voice-hci]]