Commit Graph
1 Commits
Author SHA1 Message Date
Chris LeeandClaude Opus 5 0db295d802 R1 ring: health-data BLE protocol (codec, five record decoders, page ACK)
Implements the Even R1 ring's health-sync protocol, reverse-engineered from
Bluetooth HCI snoop captures of Even's own app and confirmed field-by-field
against that app's CSV export. Answers the open question in issue #22, and in
notes/apps.txt, about where interpretation happens: it happens ON THE RING.
Sleep arrives already classified into stages; the phone does no inference.

RingProtocol.java: 15-byte header, 2-byte command id, CRC-32C (non-reflected)
over the frame body, fragment reassembly, and decoders for all five record
types -- heart rate, HRV, SpO2, sleep and steps. Hourly types share the shape
[hour_index][avg][max][min]. Steps are 10-minute buckets counted from the
record's anchor. RingProtocolSelfTest.java covers the codec against captured
bytes.

Three traps are documented in the code because each one costs days and a
reviewer "tidying" any of them would silently break the sync:

1. The 00:08 handshake frame is the ONE request whose payload carries no
   nonce -- it is exactly 3f 01 01. Measured across 46 real writes with zero
   exceptions: the 3-byte form is always answered, the 5-byte form never is.
   Prepending a nonce makes the ring discard the frame and then ignore every
   subsequent request on that connection.

2. The ring holds only one health type's response in flight. Requesting the
   next type before the previous type's DATA arrives silently drops it, and a
   lost race appears to discard that backlog PERMANENTLY rather than delaying
   it. requestRingHealth() is therefore response-paced, not sleep-paced, and
   ACKs each page as it lands.

3. HEALTH_COMMANDS mirrors the order Even's app uses. Whether the ring cares
   is untested, and matching is the cheap way not to find out the hard way.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-17 20:14:09 -07:00