Extract the heart-rate protocol from Android PR #702

[AnujCtrl]

Question

What exactly does upstream PR librepods-org#702 (thibaup:heart-rate-monitoring, fetched locally as branch pr-702) send and parse for heart-rate? Needed: the HR enable/subscribe packet bytes and opcode(s), the notification opcode and byte-offset layout (HR value, sensor status, worn state), any iOS-27/feature-flag gating, the workout start/stop commands if HR only streams in a workout context, and which Kotlin files hold each piece. Deliverable: a findings doc on a research/pr702-hr-protocol branch precise enough to port from without re-reading the Kotlin.

[AnujCtrl]

Resolved. Full findings: research/pr702-hr-protocol.md (branch research/pr702-hr-protocol, extracted from PR librepods-org#702 at 3613d59).

TL;DR — HR rides the AAP channel under opcode 0x17 (RTBuddy sensor stream, protobuf bodies), same opcode as head tracking:

1. Init ("AACP 1.3") — replay the handshake with version 03 00 on services 0 and 4, each followed by a capabilities frame (delays 180/220/180/220 ms):
   00 00 00 00 01 00 03 00 00×8 → 04 00 00 00 01 00 00 → 00 00 04 00 01 00 03 00 00×8 → 04 00 04 00 01 00 00
2. Enable — control command HRM_STATE (0x30) on: 04 00 04 00 09 00 30 01 00 00 00, then wait 120 ms.
3. Start/stop — RTBuddy control frame 04 00 04 00 17 00 00 00 10 00 + u16le len + protobuf {1: seq (init 9059), 8: {1: serviceId, 2: 2, 3: 0x01‖u32le interval}}; interval 1_000_000 µs = start (1 Hz), 0 = stop. ServiceId discovered from metadata frames containing ASCII HeartRateService (fallback 19; HostLibHID = head tracking, blacklist).
   Example start: 04 00 04 00 17 00 00 00 10 00 10 00 08 E3 46 42 0B 08 13 10 02 1A 05 01 40 42 0F 00
4. Notifications — same 0x17 framing; live only when protobuf field 2 (logType) ∈ {1,3}; HR payload nested under command fields {5,7,8,9,12} → {1: serviceId, 3: payload}. Payload is exactly 18 bytes: BPM = unsigned byte at offset 1 (valid 30–220), 3-byte status tail at offset 15 ∈ {10 00 00, 10 00 80, 20 00 00, 20 80 00, 20 02 80, 20 82 80}. Worn status comes from normal ear-detection (0x06), not this payload.
5. Gating — no workout session required on the wire (workouts are app-local Room DB). Real gates: buds worn + head tracking stopped first (shared 0x17 channel). Warm-up: discard first 4 samples; watchdogs 8 s first-sample / 2 s stall.

Kotlin sources: bluetooth/RtBuddyHeartRate.kt (decoder + frame builder), bluetooth/AACPManager.kt (init frames, HRM_STATE, RX hook), services/HeartRateMonitor.kt (state machine), services/AirPodsService.kt (wiring).