ObliviOS Developer portal Project site

Home / Decisions / ADR-124

The AirPods session speaks the real accessory protocol.

Proposed, recorded 2 October 2026.

Decision
ADR-124
Date
2026-10-02
Status
ProposedProposed (reviewed, built and checked on lynx in Plan 7A; becomes Accepted when AIR-121 to AIR-130 are filled)
Part
AirPods
Mentions
ADR-118, ADR-122
Mentioned by
ADR-136

1Decision

The AirPods session speaks the real accessory protocol (docs/research/airpods-aap-protocol-facts.md) through AapCodec, which replaces the placeholder parser; the channel is opened by reflection on the hidden BluetoothDevice#createL2capSocket(int) under the existing single-package hidden-API allow-list (the constructor route of ADR-118's evidence no longer exists in the tree); the session runs in a foreground service of type connectedDevice, started from the protected Bluetooth broadcasts and at process start, which adds FOREGROUND_SERVICE, FOREGROUND_SERVICE_CONNECTED_DEVICE and the privileged START_FOREGROUND_SERVICES_FROM_BACKGROUND; a device is a candidate when it is bonded and lists the accessory service UUID and is published only after a valid frame; the page state follows only what the AirPods report; while not connected the page offers no control.

Decisions at the capture gate (owner, 2026-10-02, after AIR-121 to AIR-123), and what became of them: (1) hide the off button until the device reports off, (2) show the written value of the comfort settings because they are not reported back, (3) hide the ear detection switch because this pair never reports it.

After seeing the result the owner reversed (1) and (3): every designed control must be present and must work. Now: Off is always offered and the app first enables the AirPods' "Allow Off" option (0x34), then asks for off (proven with the probe); the ear detection switch is always offered with the value the phone last wrote (kept in the app's private storage, default on), and its real effect on the AirPods is still to be proven (AIR-126); (2) stands (conversation awareness takes effect, proven by a fresh read); (4) state changes that depend on the current state go through an atomic transform.

The foreground session also repeats the notification request until battery and listening mode have arrived and the page request waits up to 1.5 s for a session being set up.

2Why and evidence

The old parser could not decode a single real frame. The public socket APIs open LE channels only. A cached app is frozen after about 30 s (ADR-122), so a long-lived session needs a foreground service, and the background start needs the privileged permission or an exemption we do not have. Evidence-based controls avoid a model table.

3Consequences

Three new permissions (one privileged, allow-listed). One new hidden-API use (a method, same package). A silent notification while connected. The listening-mode, ear-detection and conversation-awareness commands are sent to real hardware. The comfort switches can show a written value the device silently ignored until the next connection corrects it (ear detection is never corrected: this pair does not report it). Enabling "Allow Off" changes a persistent setting of the owner's AirPods. The protocol notes are third-party and model-specific: the capture on the owner's pair is the check, and other models are untested.

4Review when

Any change of the hidden-API enforcement or of BluetoothDevice#createL2capSocket; a model whose frames the codec rejects; Apple changing the protocol; a decision to ship to other users (model allow-list, consent for the grant).

Read from docs/governance/decision-log.md, entry ADR-124.