Protocol and Architecture

Protocol and Architecture

EarA has two independent layers:

1. Host audio — BlueZ plus PipeWire/PulseAudio provides A2DP/HFP profiles, audio routing, and codecs.
2. Earbud control — a Bluetooth Classic RFCOMM connection carries battery, ANC, EQ, gesture, and other device commands.

Control transport

• Service UUID: aeac4a03-dff5-498f-843a-34487cf133eb
• RFCOMM channel: discovered from SDP; channel 15 is the fallback
• Known exception: CMF Buds 2 commonly advertises channel 16
• Frame prefix: 55 60 01
• Integrity: CRC-16/ARC

Conceptual frame layout:

55 60 01 | command | direction | length | sequence | payload | CRC-16/ARC

Source layout

• eara/bluez.py — discovery, pairing, connection, SDP, and RFCOMM
• eara/audio.py — PipeWire/PulseAudio profiles, sinks, sources, and codecs
• eara/protocol.py — frame encoding, decoding, and feature commands
• eara/session.py — high-level device operations and state
• eara/models.py — model identification and capability flags
• eara/gui.py — GTK4/Libadwaita interface
• eara/cli.py — command-line interface

Unknown devices receive conservative controls until their model and feature set are confirmed. Products that use LE Audio/LC3-only transport will require a different transport implementation rather than only new command IDs.

Protocol contributions should include unit tests and, whenever possible, confirmation on physical hardware.