From 0db295d80293822e56bd66f9247fe4a2b543368d Mon Sep 17 00:00:00 2001 From: Chris Lee Date: Sat, 12 Sep 2026 12:54:51 -0400 Subject: [PATCH] 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 --- .../faceclaw/app/FaceclawBleCommunicator.java | 1021 ++++++++++++++++- .../com/faceclaw/app/FaceclawBleManager.java | 22 +- .../faceclaw/app/g2protocol/BleProtocol.java | 19 + .../app/g2protocol/ConnectionOptions.java | 5 + .../faceclaw/app/g2protocol/RingProtocol.java | 951 +++++++++++++++ .../RingProtocolSelfTest.java | 483 ++++++++ 6 files changed, 2498 insertions(+), 3 deletions(-) create mode 100644 App_Resources/Android/src/main/java/com/faceclaw/app/g2protocol/RingProtocol.java create mode 100644 notes/ring-protocol-selftest/RingProtocolSelfTest.java diff --git a/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleCommunicator.java b/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleCommunicator.java index 0d38e59a..0affd31a 100644 --- a/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleCommunicator.java +++ b/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleCommunicator.java @@ -28,6 +28,7 @@ import java.util.List; import java.util.Locale; import java.util.Map; import java.util.Random; +import java.util.TimeZone; @SuppressLint("MissingPermission") public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { @@ -45,6 +46,13 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { private static final int COMPASS_REPORT_INTERVAL_MS = 100; private static final int COMPASS_MIN_CHANGE_DEGREES = 0; + /** + * Cap on decoded ring health pages held in memory. A full backlog sync is + * ~40 pages, so this holds several syncs; oldest is dropped first. This is a + * holding area for a later health feature, not storage. + */ + private static final int RING_HEALTH_MAX_RECORDS = 256; + private final Context appContext; private final PowerManager powerManager; private final KeyguardManager keyguardManager; @@ -91,6 +99,74 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { private boolean leftConnected; private boolean ringConnected; private boolean ringNotificationsReady; + // R1 health-data protocol (RingProtocol). The reassembler and the outbound + // queue are both guarded by `lock`. Page ACKs are queued rather than written + // inline because notifications arrive on the GATT callback thread and + // bleManager.writeFrames() blocks waiting for onCharacteristicWrite, which + // that same thread has to deliver — writing there would deadlock until the + // write timeout. The worker loop drains the queue instead. + private final RingProtocol.Reassembler ringReassembler = new RingProtocol.Reassembler(); + private final ArrayDeque ringOutbound = new ArrayDeque<>(); + private final List ringHealthRecords = new ArrayList<>(); + /** + * Total records ever appended to {@link #ringHealthRecords}, including every + * one already consumed or evicted. Never reset. + * + *

This is the identity behind the ingest watermark. Record N is the Nth + * ever decoded this session, so a consumer that has durably stored + * everything below some N can ask for exactly that much to be dropped + * without racing the pages still arriving above it - see + * {@link #takeRingHealthBatch()} and + * {@link #clearRingHealthRecordsBelow(long)}. A plain "clear the list" + * could not do that: a page landing between the read and the clear would be + * thrown away having never been ingested. Guarded by {@code lock}. + */ + private long ringHealthTotalAdded; + /** + * The phone-side sequence counter. One counter shared by BOTH ring channels + * (measured: 78 phone-to-ring writes in the reference capture step by + * exactly +1 regardless of channel, restarting at 1 on a new connection). + */ + private int ringSeq; + private int ringNonce; + /** + * Response-driven health-pull state (2026-09-11). Set from + * {@link #handleRingHealthNotification} (GATT callback thread), waited on + * from {@link #requestRingHealth} (worker thread), both guarded by + * {@code lock}. Replaces a blind fixed-sleep loop - see that method's + * own doc for why: a real successful Even sync (extracted from + * {@code /tmp/btsnoop_fresh.log} on bazzite-desktop, 2026-09-11) is + * response-paced, not sleep-paced, and ACKs each DATA page immediately + * rather than after the whole run. + */ + private boolean ringHealthRspSeen; + /** Bumped once per decoded health DATA page (any type) so a waiter can + * detect "a page just arrived" without polling ringHealthRecords. */ + private int ringHealthPageCounter; + /** + * elapsedRealtime() of the last time {@link #requestRingHealth()} was + * attempted, or 0 if never. Health data updates hourly at the source + * (heart rate/HRV/SpO2) or slower, but a ring reconnect can happen far + * more often than that (BLE drops, Doze, app restarts - this evening's + * own live testing saw reconnects every few seconds under load). Pulling + * on every reconnect would be pure waste even ignoring the risk below; + * given the race condition documented on requestRingHealth() - a request + * that loses its race may silently discard real backlog rather than just + * delay it - it is actively worse than waste, so this is throttled. + */ + private long ringHealthLastRequestedAtMs; + /** + * Set by {@link #requestRingHealthNow()} from whatever thread the UI is on; + * cleared by the worker loop, which is the only thread allowed to run the + * pull. Guarded by {@code lock}. + */ + private boolean ringHealthPullRequested; + /** + * Aborted-pull retries spent since the last pull that COMPLETED its + * sequence. Guarded by {@code lock}. See + * {@link #RING_HEALTH_ABORTED_RETRY_LIMIT}. + */ + private int ringHealthAbortedRetries; private boolean sessionReady; private boolean fixedLayoutCreated; private boolean shutdownRequested; @@ -1630,6 +1706,19 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { continue; } + // Page ACKs queued from the GATT callback thread are written + // here, on the only thread allowed to block on a GATT write. + flushRingOutbound(); + + // An on-demand pull asked for from the UI thread runs here for + // the same reason: requestRingHealth() blocks on GATT writes and + // on its own RSP/DATA waits, which only this thread may do. + runRequestedRingHealthPull(); + // An aborted pull is unfinished business, not a speculative + // repeat - see RING_HEALTH_ABORTED_RETRY_LIMIT. Cheap: returns + // immediately unless a pull actually failed to complete. + resumeAbortedRingHealthPull(); + long sleepMs = driveSession(); if (sleepMs > 0) { interruptibleSleep.sleep(sleepMs); @@ -1888,6 +1977,9 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { } private void handleDirectRingNotification(String characteristicUuid, byte[] data) { + if (handleRingHealthNotification(characteristicUuid, data)) { + return; + } FaceclawRingEventDecoder.DirectRingEvent decoded = FaceclawRingEventDecoder.decode(data); if (decoded == null) { Log.d(TAG, "direct ring notify ignored: characteristicUuid=" + characteristicUuid + " raw=" + hex(data)); @@ -1907,6 +1999,133 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { interruptibleSleep.interrupt(); } + /** + * The R1 health-data protocol branch. Returns true when the value belonged + * to that protocol and must not fall through to the gesture decoder. + * + *

Runs on the GATT callback thread, so it only ever queues writes. + * + *

Restricted to R1_NOTIFY_CHAR_UUID because that is the notify + * characteristic (ATT handle 0x0017) the reference capture shows this + * protocol on; gesture traffic on the other notify characteristic is left + * strictly alone rather than being offered to the reassembler. + */ + private boolean handleRingHealthNotification(String characteristicUuid, byte[] data) { + if (!BleProtocol.R1_NOTIFY_CHAR_UUID.equals(characteristicUuid)) { + return false; + } + + RingProtocol.Intake intake; + synchronized (lock) { + intake = ringReassembler.accept(data); + } + if (!intake.consumed) { + return false; + } + + long arrivalMs = SystemClock.elapsedRealtime(); + synchronized (lock) { + lastIncomingAtMs = arrivalMs; + } + if (intake.note != null) { + logLine("ring frame: " + intake.note); + } + RingProtocol.Frame frame = intake.frame; + if (frame == null) { + // Genuinely silent by default: the reassembler consumed these + // bytes (e.g. as a fragment awaiting its continuation) without + // yet producing a complete frame, and intake.note was null too. + // This exact blind spot cost real debugging time on 2026-09-10 - + // DATA appeared to simply never arrive, when the actual cause + // (once found, by temporarily logging every raw notification + // unconditionally) was a real handshake gap, not a dropped + // frame here. If DATA ever looks like it's going missing again + // with nothing logged at all, re-add that raw hex dump here + // rather than assuming nothing arrived on the wire. + logLine("ring frame: consumed, no complete frame yet, len=" + data.length); + return true; + } + if (!frame.crcOk) { + // Never act on a frame whose CRC failed: the payload offsets below + // are only meaningful for an intact frame. + logLine("ring frame CRC mismatch " + frame.describe()); + return true; + } + + // Route on the CHAN byte, not on the shape of the payload. + if (frame.chan != RingProtocol.CHAN_HEALTH) { + Log.d(TAG, "ring device frame " + frame.describe()); + return true; + } + + if (frame.kind == RingProtocol.KIND_RSP) { + Log.d(TAG, "ring health rsp " + frame.describe()); + synchronized (lock) { + ringHealthRspSeen = true; + lock.notifyAll(); + } + return true; + } + if (frame.kind != RingProtocol.KIND_DATA) { + Log.d(TAG, "ring health frame " + frame.describe()); + return true; + } + + RingProtocol.HealthRecord record = null; + try { + record = RingProtocol.decode(frame, System.currentTimeMillis()); + } catch (Throwable t) { + logLine("ring health decode error " + frame.describe() + ": " + safeMessage(t)); + } + if (record == null) { + logLine("ring health page undecoded " + frame.describe()); + } else { + synchronized (lock) { + if (ringHealthRecords.size() >= RING_HEALTH_MAX_RECORDS) { + // This was silent. An eviction here drops a record that + // nothing has ingested yet - real data lost inside the + // phone, with no trace anywhere. Say so. With the consume + // path in place the buffer should never reach this size; + // if this line ever appears, the consumer has stopped. + logLine("ring health: buffer FULL at " + RING_HEALTH_MAX_RECORDS + + " - dropping the oldest UNINGESTED record"); + ringHealthRecords.remove(0); + } + ringHealthRecords.add(record); + ringHealthTotalAdded++; + } + logLine("ring health " + record.summary()); + } + + // Acknowledge the page regardless of whether we could decode it: the + // ACK is what keeps the ring sending, and a decode gap must not stall + // the rest of the transfer. + queueRingPageAck(frame); + return true; + } + + private void queueRingPageAck(RingProtocol.Frame page) { + byte[] ack; + synchronized (lock) { + if (!ringNotificationsReady) { + return; + } + ack = RingProtocol.buildPageAck( + nextRingSeqLocked(), + nextRingNonceLocked(), + page.cmdHi, + page.cmdLo, + page.seq + ); + ringOutbound.add(ack); + ringHealthPageCounter++; + lock.notifyAll(); + } + // The worker loop does the actual write; wake it so the ACK is not held + // for a whole idle tick. + interruptibleSleep.interrupt(); + } + private void handleRenderNotification(String address, byte[] data) { FaceclawAudioPacketListener listenerToCall; long arrivalMs = SystemClock.elapsedRealtime(); @@ -1935,6 +2154,10 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { ringNotificationsReady = false; if (!connected) { ringReconnectAfterMs = SystemClock.elapsedRealtime() + ConnectionOptions.RING_RECONNECT_DELAY_MS; + // Half-received fragments and unsent ACKs do not survive the + // link; the sequence counter restarts on the next connect. + ringReassembler.reset(); + ringOutbound.clear(); } logLine(connected ? "direct ring BLE connected" : "direct ring BLE disconnected"); return; @@ -2121,17 +2344,43 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { private void connectRing() { logLine("connecting direct ring " + ringAddress); - if (!bleManager.connect(ringAddress, ConnectionOptions.CONNECT_TIMEOUT_MS)) { + // autoConnect=true (see FaceclawBleManager.connect's 3-arg overload) - + // matches what Even's own app does for this device specifically. + // Direct connect (false, the default used for the glasses) was + // measured tonight dying ~5s into an otherwise-idle ring connection, + // repeatedly, with nothing else competing for it. + if (!bleManager.connect(ringAddress, ConnectionOptions.RING_CONNECT_TIMEOUT_MS, true)) { throw new IllegalStateException("connect failed: " + ringAddress); } - bleManager.requestConnectionPriority(ringAddress, BluetoothGatt.CONNECTION_PRIORITY_HIGH); + // Deliberately NOT requesting CONNECTION_PRIORITY_HIGH here (2026-09-11). + // Even's own app never requests any priority for the ring at all - it + // logs no requestConnectionPriority/onConnectionUpdated call anywhere - + // and just runs on whatever Android's default (BALANCED) parameters are. + // HIGH negotiated interval=12 (15ms) / timeout=500 (5000ms) here, and a + // live test tonight found the ring-only connection reliably dying at + // 5.5-5.7s, matching that 5000ms supervision timeout almost exactly, + // on every attempt, with nothing else competing for the ring. If the + // ring's firmware occasionally needs more than 5s of headroom after a + // burst of writes, HIGH priority's short timeout would kill the link + // while Even's default (longer) one wouldn't - untested but the timing + // match is exact, not approximate. Leaving default priority for the + // ring only; the glasses' own HIGH-priority request above is untouched. bleManager.requestMtu(ringAddress, ConnectionOptions.RING_DESIRED_MTU, ConnectionOptions.CONNECT_TIMEOUT_MS); if (!bleManager.discoverServices(ringAddress, ConnectionOptions.SERVICES_TIMEOUT_MS)) { throw new IllegalStateException("discoverServices failed: " + ringAddress); } + // Even's app subscribes only to the health-data notify CCCD (ATT + // handle 24) and never touches the phone-notify one (handle 19). That + // difference was briefly suspected on 2026-09-11 of causing the ring's + // total silence and this call was dropped to match - it changed + // nothing, and the real cause turned out to be the malformed 00:08 + // frame (see sendRingHandshake). Restored, because the phone-notify + // channel is plausibly what carries ring-as-remote gesture events, + // which are a daily-driver feature; matching Even byte-for-byte here + // buys nothing and risks breaking them. boolean phoneNotify = enableRingNotification(BleProtocol.R1_PHONE_NOTIFY_CHAR_UUID); boolean dataNotify = enableRingNotification(BleProtocol.R1_NOTIFY_CHAR_UUID); if (!phoneNotify && !dataNotify) { @@ -2142,8 +2391,776 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { ringConnected = true; ringNotificationsReady = true; ringReconnectAfterMs = 0; + // The ring's sequence counter restarts with the connection. + ringSeq = 0; + ringNonce = 0; + ringReassembler.reset(); + ringOutbound.clear(); } logLine("direct ring ready phoneNotify=" + phoneNotify + " dataNotify=" + dataNotify); + + if (dataNotify) { + // The handshake mirrors what Even's own app repeats on every one + // of its sync bursts (confirmed in the reference capture), so + // sending it on every reconnect matches known-working behavior. + // The actual health pull is throttled separately below - see + // ringHealthLastRequestedAtMs and requestRingHealth()'s own + // race-condition warning for why. + sendRingHandshake(); + long now = SystemClock.elapsedRealtime(); + boolean dueForHealthPull; + synchronized (lock) { + dueForHealthPull = ringHealthPullDueLocked(now); + if (dueForHealthPull) { + ringHealthLastRequestedAtMs = now; + } + } + if (dueForHealthPull) { + runRingHealthPull(); + } else { + logLine("ring health: pull skipped, last one was " + + ((now - ringHealthLastRequestedAtMs) / 1000) + "s ago"); + } + } + } + + /** + * Floor between health pulls, independent of how often the ring + * reconnects. Heart rate/HRV/SpO2 update hourly at the source and steps + * every 10 minutes (confirmed from the real export, + * {@code knowledge/inbox/Even_health_data/}); 30 minutes is comfortably + * inside that cadence while keeping reconnect churn from turning into + * repeated pull attempts against the race condition documented on + * {@link #requestRingHealth()}. Not tuned against any real constraint + * from the ring itself - just a sane default. + * + *

Reduced 30min -> 5min on 2026-09-12, and its JOB CHANGED. The + * 30-minute figure was always meant as a CADENCE - how often to collect - + * but it was implemented here as a floor, which is a different thing. The + * result was that a connected, stable ring pulled never: nothing + * drives a pull on a timer, only {@code onRingReady()} on reconnect, so the + * floor was the only clock in the system and it gated a pull that had + * nothing to trigger it. + * + *

The cadence now lives where it belongs, on a wall-clock-aligned tick + * (:01 and :31) in {@code health-live.ts}. What remains here is purely an + * ANTI-SPAM floor: stop a burst of reconnects turning into a burst of + * requests against the race documented on {@link #requestRingHealth()}. + * That job needs 5 minutes, not 30. + */ + private static final long RING_HEALTH_MIN_PULL_INTERVAL_MS = 5L * 60L * 1000L; + + /** + * Floor for a pull the user actually asked for by opening the health app, + * as opposed to the automatic one above. + * + *

Deliberately much shorter than the automatic interval but not + * zero. The 30-minute figure is conservative because an automatic pull + * is speculative — nobody is waiting for it, so there is no reason to spend + * a request. Opening the health app is the opposite: it is an explicit ask, + * and the response-driven {@link #requestRingHealth()} now waits for each + * type's DATA and ACKs its pages before advancing, which is what made the + * backlog-discard race survivable in the first place. A floor still has to + * exist, because the discard risk documented on {@code requestRingHealth()} + * is real and open/close/open would otherwise hammer the ring. + */ + private static final long RING_HEALTH_ON_DEMAND_MIN_INTERVAL_MS = 60L * 1000L; + + /** + * How many times a pull that ABORTED may be resumed inside the anti-spam + * floor before it goes back to waiting that floor out. + * + *

The floor exists to stop SPECULATIVE repeat pulls, because a request + * that loses its race can permanently consume backlog - see + * {@link #requestRingHealth()}. Resuming a pull that never got a single + * answer is a different thing: nothing was ever in flight to be lost. + * + *

Measured 2026-09-12: the 09:33 pull got {@code no RSP} for 0x1, 0x4 + * and 0x2 and then died on {@code write error: IllegalStateException: Not + * connected}. Every attempt after it was refused by the 30-minute floor, so + * the rest of that night's data was simply never requested again - the + * night's second sleep block went with it. The floor was protecting against + * the wrong thing. + * + *

Bounded and non-looping on purpose: the budget is spent whether or not + * the retries help, and a pull that completes resets it. Worst case is two + * extra attempts, then silence until the floor expires. + * + *

⚠ UNTESTED, and worth knowing before trusting this: whether an aborted + * pull's data is still on the ring at all, or was discarded when the ring + * RSP'd (it did not RSP here, which is the reason to think it survives). + * Nobody knows. The retry costs little if the data is gone. + */ + private static final int RING_HEALTH_ABORTED_RETRY_LIMIT = 2; + + /** + * Gap before an aborted pull may be resumed. Short, but not zero - a link + * that just failed a write needs time to come back, and a tight loop + * against a dead connection helps nobody. + */ + private static final long RING_HEALTH_ABORTED_RETRY_GAP_MS = 60L * 1000L; + + /** + * Ask for a health pull as soon as the worker thread can run one. Safe to + * call from any thread; returns immediately without blocking. + * + *

Called when the health app opens, so a glance shows something current + * rather than whatever the last automatic pull happened to catch. Subject + * to {@link #RING_HEALTH_ON_DEMAND_MIN_INTERVAL_MS}; a request inside that + * window is dropped rather than queued, because a stale duplicate pull has + * no value and every pull carries the discard risk. + */ + public void requestRingHealthNow() { + synchronized (lock) { + ringHealthPullRequested = true; + } + interruptibleSleep.interrupt(); + } + + /** + * Whether an automatic pull may run now. Caller must hold {@code lock}. + * + *

Two ways to be due: the ordinary 30-minute floor has expired, or the + * last pull ABORTED and still has retry budget. The second is not a + * speculative repeat - see {@link #RING_HEALTH_ABORTED_RETRY_LIMIT}. + */ + private boolean ringHealthPullDueLocked(long now) { + if (ringHealthLastRequestedAtMs == 0) { + return true; + } + long since = now - ringHealthLastRequestedAtMs; + if (since >= RING_HEALTH_MIN_PULL_INTERVAL_MS) { + return true; + } + return ringHealthAbortedRetries > 0 && since >= RING_HEALTH_ABORTED_RETRY_GAP_MS; + } + + /** + * Run a pull and account for whether it finished. The ONLY place + * {@link #requestRingHealth()} may be called from, so that every path + * shares one definition of "aborted". + */ + private void runRingHealthPull() { + boolean completed = requestRingHealth(); + synchronized (lock) { + if (completed) { + ringHealthAbortedRetries = 0; + } else if (ringHealthAbortedRetries < RING_HEALTH_ABORTED_RETRY_LIMIT) { + ringHealthAbortedRetries++; + logLine("ring health: aborted pull may resume in " + + (RING_HEALTH_ABORTED_RETRY_GAP_MS / 1000L) + "s (retry " + + ringHealthAbortedRetries + "/" + RING_HEALTH_ABORTED_RETRY_LIMIT + ")"); + } else { + ringHealthAbortedRetries = 0; + logLine("ring health: aborted pull retry budget spent, back to the " + + (RING_HEALTH_MIN_PULL_INTERVAL_MS / 60000L) + "-minute anti-spam floor"); + } + } + } + + /** + * Worker-thread tick that resumes a pull which ABORTED. + * + *

Distinct from {@link #runRequestedRingHealthPull()}: nobody asked for + * this one. It exists because the automatic pull otherwise only fires from + * the ring-ready path, so an abort that is not followed by a reconnect + * would never be retried at all. + */ + private void resumeAbortedRingHealthPull() { + long now = SystemClock.elapsedRealtime(); + synchronized (lock) { + if (ringHealthAbortedRetries == 0) { + return; + } + if (!ringConnected || !ringNotificationsReady) { + return; + } + if (now - ringHealthLastRequestedAtMs < RING_HEALTH_ABORTED_RETRY_GAP_MS) { + return; + } + ringHealthLastRequestedAtMs = now; + } + logLine("ring health: resuming an aborted pull"); + runRingHealthPull(); + } + + /** Worker-thread side of {@link #requestRingHealthNow()}. */ + private void runRequestedRingHealthPull() { + long now = SystemClock.elapsedRealtime(); + synchronized (lock) { + if (!ringHealthPullRequested) { + return; + } + ringHealthPullRequested = false; + if (!ringConnected || !ringNotificationsReady) { + logLine("ring health: on-demand pull skipped, ring not ready"); + return; + } + if (ringHealthLastRequestedAtMs != 0 + && now - ringHealthLastRequestedAtMs < RING_HEALTH_ON_DEMAND_MIN_INTERVAL_MS) { + logLine("ring health: on-demand pull skipped, last one was " + + ((now - ringHealthLastRequestedAtMs) / 1000) + "s ago"); + return; + } + ringHealthLastRequestedAtMs = now; + } + logLine("ring health: on-demand pull requested"); + runRingHealthPull(); + } + + /** + * Device-channel prelude the ring requires before it will answer any + * channel-0x02 (health) request. Confirmed live, 2026-09-10: without + * this, the ring never responds at all to a bare health REQ - not even + * an RSP. With it, RSPs start flowing immediately. The direct-ring + * path has no other handshake or auth step, so this is the whole gate. + * + *

These five frames were found by byte-for-byte comparison against a + * real Even-app sync (pkt 8814-9153 in the capture behind + * {@code knowledge/staging/faceclaw-ring-protocol-decode-return.md}), + * replayed here in the same order, right after the ring connects. + * Which of the five is actually load-bearing is unknown - all + * five go out together because that combination is the only one proven + * to work; nobody has yet tried removing any of them. Three of them + * (00:08, 06:02, 00:0A) carry payload bytes with no known meaning beyond + * "the ring accepted them from Even's app" - opaque constants, copied + * verbatim, not derived. Do not change them without new evidence. + * + *

The other two (00:0E clock-set, 00:05 day-anchor) need a live + * value: both carry the current Unix time offset by the local UTC offset, + * which in EDT is +14400s (4h) - and +14400s is what a real Even write + * carries. Verified 2026-09-11 against six separate real Even clock-set + * writes. As of 2026-09-12 the offset is COMPUTED from the device time + * zone rather than hardcoded, which is identical in EDT and stays correct + * across a DST change; see the comment in {@code sendRingHandshake()}. + * + *

Skew trap - read before "correcting" this number. Earlier on + * 2026-09-11 this was changed to +28800s (8h) and that was wrong. The + * mistake: btsnoop packet timestamps on this phone run exactly 4 hours + * BEHIND the Android system clock (the system clock itself is correct - + * {@code adb shell date} agrees with real time). Measuring Even's sent + * value against the btsnoop timestamp therefore double-counts the 4h and + * makes a correct +14400 look like +28800. The skew is verified + * sub-second by lining btsnoop up against logcat on the same connect: + * logcat "direct ring BLE connected" 05:58:24.616 vs btsnoop MTU Req + * 01:58:24.618; "ring ready" .983 vs CCCD Write Rsp .981; "handshake + * sent" 25.085 vs first Write Command 25.071. Same milliseconds, hour + * off by four. Always convert btsnoop timestamps to real local time + * (+4h) before comparing them to anything. + * + *

A stale, yesterday's timestamp here was separately tested and ruled + * out as the reason DATA wasn't following RSP - but nothing says a stale + * value is harmless either, so this always sends the true current time. + */ + /** + * Round 2 (2026-09-11, ~00:55 EDT): compared this handshake against a + * fresh HCI-snoop capture of Even's own app completing a real successful + * sync minutes earlier. Two real findings from that comparison: + * - The 00:0A payload (the "app identity?" blob) is byte-for-byte + * identical between that capture and one from two nights before - a + * true fixed constant, not a rotating per-session token. Rules out the + * "stale identity token" theory tried first. + * - Even's real sequence also sends battery (00:01), firmware version + * (00:02), and device id (00:0B) - none of which round 1 ever sent - + * interleaved with the health requests, not just once upfront. Notably + * the firmware-version query lands immediately before Even's own first + * successful health request in the real trace. `06:02`, which round 1 + * did send, never appears anywhere in that real successful sync - + * dropped here since there's now real evidence it isn't needed and it + * was never more than a guess to begin with. + * This round adds 00:01/00:02/00:0B up front rather than interleaved + * (interleaving would need restructuring requestRingHealth() too - a + * bigger change deferred until this simpler version is shown to help or + * not). + */ + private void sendRingHandshake() { + // +14400s was hardcoded here because every capture behind this work was + // taken in EDT, where 14400s happens to be the magnitude of the UTC + // offset - so the constant was right by coincidence of season, not by + // derivation, and would have gone an hour wrong at the next DST change. + // This computes it instead: identical in EDT, correct year-round. + // + // ⚠ MIND THE SIGN. The ring's clock runs AHEAD of real time by the + // magnitude of a west-of-UTC offset, so the quantity wanted here is + // NEGATIVE `TimeZone.getOffset()`, which is itself negative west of UTC + // (-14400000ms in EDT). Getting this backwards sets the ring's clock 8h + // wrong rather than 0h wrong. Measured 2026-09-12: the un-negated form + // logged -14400 and the ring then returned step buckets dated 8h out. + // + // Note this is the OPPOSITE of the "ring stores naive local time" + // hypothesis, which predicts `epoch + utc_offset` = epoch - 14400. The + // measured, working value is epoch + 14400. The hypothesis is therefore + // NOT confirmed by this code; what is preserved here is the behaviour + // verified against six real Even clock-set writes. + // + // ⚠ PAIRED with `ringClockOffsetMs()` in `app/health/health-live.ts`, + // which subtracts the same quantity on the way back out. These two must + // move together; both now compute the value rather than hardcoding EDT. + long nowMs = System.currentTimeMillis(); + long clockOffsetSeconds = -TimeZone.getDefault().getOffset(nowMs) / 1000L; + long liveClockSeconds = (nowMs / 1000L) + clockOffsetSeconds; + // Asserted at every handshake: in EDT this must read 14400. The clock write + // is the part of this protocol that took two sessions to get working, so a + // changed value here is the one way a working pull silently breaks. + Log.i(TAG, "ring handshake clock offset seconds = " + clockOffsetSeconds + + " (tz " + TimeZone.getDefault().getID() + ")"); + byte[] clock = le32(liveClockSeconds); + + int seq1, nonce1, seq2, nonce2, seq3, nonce3, seq4, nonce4, seq5, nonce5, seq6, nonce6, seq7, nonce7; + synchronized (lock) { + seq1 = nextRingSeqLocked(); + nonce1 = nextRingNonceLocked(); + seq2 = nextRingSeqLocked(); + nonce2 = nextRingNonceLocked(); + seq3 = nextRingSeqLocked(); + nonce3 = nextRingNonceLocked(); + seq4 = nextRingSeqLocked(); + nonce4 = nextRingNonceLocked(); + seq5 = nextRingSeqLocked(); + nonce5 = nextRingNonceLocked(); + seq6 = nextRingSeqLocked(); + nonce6 = nextRingNonceLocked(); + seq7 = nextRingSeqLocked(); + nonce7 = nextRingNonceLocked(); + } + + byte[][] frames = { + RingProtocol.buildFrame(RingProtocol.CHAN_DEVICE, RingProtocol.KIND_REQ, 0x00, 0x08, seq1, + // NO nonce prefix on this one frame - payload is exactly the + // three bytes 3f 01 01. Every other request on both channels + // starts with the 2-byte nonce; 00:08 does not, and the ring + // silently drops the whole frame if you add one, then ignores + // everything that follows on the connection. + // + // Measured 2026-09-11 across all four btsnoop captures, 46 + // real 00:08 writes, zero exceptions: + // payload 3f0101 (3 bytes) -> 3 writes, ALL answered (12-21 notifications each) + // payload 01003f0101 (5 bytes) -> 43 writes, ALL silent (zero notifications) + // The 5-byte form is the more common one in the captures only + // because it is ours, failing and retrying all night. Do not + // "fix" this back to the nonce form by pattern-matching the + // other frames or by counting which variant appears more. + // + // This also explains 2026-09-10: the handshake worked when it + // was raw bytes replayed from the capture, and stopped working + // the moment it was rebuilt "properly" through buildFrame(), + // which is what introduced the nonce prefix. + new byte[] {0x3f, 0x01, 0x01}), + RingProtocol.buildFrame(RingProtocol.CHAN_DEVICE, RingProtocol.KIND_DATA, 0x00, 0x0e, seq2, + concatBytes(le16(nonce2), clock, new byte[] {0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00})), + RingProtocol.buildFrame(RingProtocol.CHAN_DEVICE, RingProtocol.KIND_DATA, 0x00, 0x05, seq3, + concatBytes(le16(nonce3), new byte[] {0x10, (byte) 0xff}, clock)), + // Battery, firmware version, device id - all bare nonce-only REQs, + // same shape as the health requests. New this round. + RingProtocol.buildFrame(RingProtocol.CHAN_DEVICE, RingProtocol.KIND_REQ, 0x00, 0x01, seq4, + le16(nonce4)), + RingProtocol.buildFrame(RingProtocol.CHAN_DEVICE, RingProtocol.KIND_REQ, 0x00, 0x02, seq5, + le16(nonce5)), + RingProtocol.buildFrame(RingProtocol.CHAN_DEVICE, RingProtocol.KIND_REQ, 0x00, 0x0b, seq6, + le16(nonce6)), + RingProtocol.buildFrame(RingProtocol.CHAN_DEVICE, RingProtocol.KIND_REQ, 0x00, 0x0a, seq7, + concatBytes(le16(nonce7), parseHex("f8f53d235ac4ceaa073885cc"))), + }; + for (byte[] frame : frames) { + if (!writeRingFrame(frame, "handshake")) { + return; + } + } + logLine("ring health: sent device-channel handshake (" + frames.length + " frames)"); + } + + private static byte[] parseHex(String hex) { + byte[] out = new byte[hex.length() / 2]; + for (int i = 0; i < out.length; i++) { + out[i] = (byte) Integer.parseInt(hex.substring(i * 2, i * 2 + 2), 16); + } + return out; + } + + private static byte[] le16(int value) { + return new byte[] {(byte) value, (byte) (value >>> 8)}; + } + + private static byte[] le32(long value) { + return new byte[] {(byte) value, (byte) (value >>> 8), (byte) (value >>> 16), (byte) (value >>> 24)}; + } + + private static byte[] concatBytes(byte[]... parts) { + int len = 0; + for (byte[] part : parts) { + len += part.length; + } + byte[] out = new byte[len]; + int offset = 0; + for (byte[] part : parts) { + System.arraycopy(part, 0, out, offset, part.length); + offset += part.length; + } + return out; + } + + /** + * Timeout waiting for a health REQ's own RSP. In the reference capture + * (a real successful Even sync, extracted from + * {@code /tmp/btsnoop_fresh.log} on bazzite-desktop, 2026-09-11) RSPs + * land within ~150ms; this only needs to bound the pathological "ring + * stopped answering entirely" case. + */ + private static final long RING_HEALTH_RSP_TIMEOUT_MS = 3000L; + + /** + * How long to keep waiting after the most recent DATA page for a health + * type before deciding its transfer is over (or that there was never + * going to be one). Chosen from the same reference capture: consecutive + * pages for one type land well under a second apart, so 1.5s covers + * that with real margin while still moving on quickly when a type + * genuinely has nothing new. + */ + private static final long RING_HEALTH_DATA_IDLE_MS = 1500L; + + /** + * Device-channel commands Even's real app fires in the gaps between + * health requests - identity (0x0a), battery (0x01), firmware version + * (0x02), device id (0x0b) - found by extracting the literal wire order + * of a real successful sync (same capture as above; two independent + * syncs in it agree). Rotated one-per-health-type here rather than + * replicated exactly (Even's real cadence isn't perfectly regular + * either - compare the two syncs in the capture), since which of these, + * if any, is actually load-bearing for the ring answering has never + * been isolated. This is matching cadence, not a confirmed protocol + * requirement. + */ + private static final int[] RING_DEVICE_PING_CMD_LO = {0x0a, 0x01, 0x02, 0x0b}; + + /** + * Pull the five health record types. Each request is a bare 17-byte frame + * carrying only a nonce; the ring answers with an RSP on the same + * sequence number, then - sometimes - pushes one or more DATA pages, + * which arrive through {@link #handleRingHealthNotification}. + * + *

Response-driven, not sleep-driven (rewritten 2026-09-11). + * The original version fired all five REQs on a blind fixed sleep and + * only flushed queued page ACKs after the whole loop finished - a real + * successful Even sync (see the constants above) does the opposite: it + * waits for each REQ's own RSP, waits for DATA to go idle, ACKs + * immediately, then interleaves one device-channel command before the + * next health type. This version does the same, using the existing + * lock.wait()/notifyAll() idiom already used elsewhere in this class + * (e.g. the shutdown-ack wait above) rather than a new mechanism. + * + *

Race condition, confirmed live 2026-09-10 - this is what the + * rewrite above addresses, not a reason to remove this warning. The + * ring appears to hold only one health type's response in flight at a + * time. Sending the next health REQ before the previous type's DATA + * page(s) have actually arrived silently drops the earlier type's DATA: + * you still get its RSP, you never get its DATA, and nothing in the + * protocol signals an error. Evidence: five REQs fired back-to-back (the + * old blind-sleep version, badly timed) got five RSPs and zero DATA + * pages over more than a minute of waiting. + * + *

Worse: a lost race may PERMANENTLY discard that backlog, not + * just delay it. On 2026-09-10, real HRV/SpO2/sleep backlog that + * should have existed (unreported since that morning, confirmed against + * the hourly export cadence in {@code knowledge/inbox/Even_health_data}) + * did not come back on a later, more carefully spaced retry. The working + * theory - not proven, but treat it as true until disproven, because the + * downside of being wrong is silent data loss with nothing to catch it + * - is that the ring advances its own "last delivered" watermark for a + * type as soon as it RSPs a REQ for it, whether or not the DATA page + * actually made it out. Do not send a speculative or test health REQ + * for a type unless you intend to actually receive and persist its + * DATA - re-requesting will not recover what an earlier, raced + * request already consumed. The rewrite below waiting for DATA to go + * idle before advancing reduces how often this can happen but does not + * prove it can no longer happen (e.g. if the ring's real per-type + * timeout is shorter than RING_HEALTH_DATA_IDLE_MS for some type). + * + *

A separate, completely ordinary case looks identical from the wire + * alone: an RSP with no DATA can also just mean the ring genuinely has + * nothing new for that metric since the last successful pull. There is + * currently no way to tell "raced and silently discarded" apart from + * "genuinely nothing new" other than knowing independently whether fresh + * data should exist (e.g. from the export's own sampling cadence). + * + *

Runs on the worker thread (from connectRing), which is the only + * thread allowed to call the blocking write path - the wait loops below + * block that same thread, which is why {@link #flushRingOutbound} is + * called explicitly after each type rather than relying on the main + * loop's own call to it. + */ + private boolean requestRingHealth() { + int[] commands = RingProtocol.HEALTH_COMMANDS; + int rspCount = 0; + for (int i = 0; i < commands.length; i++) { + int command = commands[i]; + byte[] frame; + synchronized (lock) { + ringHealthRspSeen = false; + frame = RingProtocol.buildHealthRequest(command, nextRingSeqLocked(), nextRingNonceLocked()); + } + if (!writeRingFrame(frame, "health request 0x" + Integer.toHexString(command))) { + // ABORTED: the sequence stopped partway. Distinct from "the + // ring had nothing for a type", which is an ordinary outcome + // and leaves the loop running - see the return below. + logLine("ring health: pull ABORTED on write at 0x" + Integer.toHexString(command) + + " (" + i + " of " + commands.length + " types attempted, " + + rspCount + " answered)"); + return false; + } + + if (awaitRingHealthRsp(RING_HEALTH_RSP_TIMEOUT_MS)) { + rspCount++; + awaitRingHealthDataIdle(RING_HEALTH_DATA_IDLE_MS); + } else { + logLine("ring health: no RSP for command 0x" + Integer.toHexString(command) + ", moving on"); + } + // Write out any ACK(s) queued by DATA pages that just landed, + // right now rather than after the whole loop - this is the fix + // for the bug the doc above describes. + flushRingOutbound(); + + if (i < commands.length - 1) { + sendRingDevicePing(RING_DEVICE_PING_CMD_LO[i % RING_DEVICE_PING_CMD_LO.length]); + } + } + + // Two more ways to have not really completed, both distinguishable from + // "completed but empty": + // + // - the link dropped while the loop was running, so the later types + // were written into nothing; + // - the ring answered NONE of the five. A type with no backlog still + // RSPs (measured: five REQs, five RSPs, zero DATA), so zero RSPs + // across the whole sequence means the ring was not answering at + // all, not that there was nothing to send. + // + // An RSP with no DATA remains ambiguous per type and is NOT treated as + // a failure here - that is the ordinary "nothing new" case. + boolean stillConnected; + synchronized (lock) { + stillConnected = ringConnected; + } + if (!stillConnected || rspCount == 0) { + logLine("ring health: pull ABORTED - ran all " + commands.length + " types but " + + (stillConnected ? "the ring answered none of them" : "the link dropped")); + return false; + } + logLine("ring health: requested " + commands.length + " record types, " + + rspCount + " answered"); + return true; + } + + /** Block (worker thread) until the health RSP flag is set or the timeout + * elapses. Not correlated to a specific command/seq - like the rest of + * this protocol's request path, it trusts the ring answers in order. */ + private boolean awaitRingHealthRsp(long timeoutMs) { + long deadline = SystemClock.elapsedRealtime() + timeoutMs; + synchronized (lock) { + while (running && ringConnected && !ringHealthRspSeen) { + long remaining = deadline - SystemClock.elapsedRealtime(); + if (remaining <= 0) { + return false; + } + try { + lock.wait(Math.min(remaining, 100)); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + return ringHealthRspSeen; + } + } + return ringHealthRspSeen; + } + } + + /** Block (worker thread) until DATA pages go idle for {@code idleMs}, + * extending the window on every new page so a real multi-page backlog + * transfer isn't cut short. Not filtered by health type - correct given + * the ring only has one type in flight at a time (see the class doc + * above), so any page arriving here belongs to the type just requested. */ + private void awaitRingHealthDataIdle(long idleMs) { + long idleDeadline = SystemClock.elapsedRealtime() + idleMs; + synchronized (lock) { + int lastSeenCounter = ringHealthPageCounter; + while (running && ringConnected) { + long remaining = idleDeadline - SystemClock.elapsedRealtime(); + if (remaining <= 0) { + return; + } + if (ringHealthPageCounter != lastSeenCounter) { + lastSeenCounter = ringHealthPageCounter; + idleDeadline = SystemClock.elapsedRealtime() + idleMs; + remaining = idleMs; + } + try { + lock.wait(Math.min(remaining, 100)); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + return; + } + } + } + } + + /** + * Fire one bare device-channel REQ in the gap between health types, + * matching (without waiting on a response) the cadence a real Even sync + * uses. See {@link #RING_DEVICE_PING_CMD_LO} for provenance and caveats. + */ + private void sendRingDevicePing(int cmdLo) { + byte[] frame; + synchronized (lock) { + int seq = nextRingSeqLocked(); + int nonce = nextRingNonceLocked(); + if (cmdLo == 0x0a) { + // The only one of these four that isn't a bare nonce - it + // carries the same opaque constant blob as the handshake's + // own 0x0a frame (confirmed byte-identical across two + // different nights, see sendRingHandshake()'s comments). + frame = RingProtocol.buildFrame(RingProtocol.CHAN_DEVICE, RingProtocol.KIND_REQ, 0x00, 0x0a, seq, + concatBytes(le16(nonce), parseHex("f8f53d235ac4ceaa073885cc"))); + } else { + frame = RingProtocol.buildRequest(RingProtocol.CHAN_DEVICE, 0x00, cmdLo, seq, nonce); + } + } + writeRingFrame(frame, "device ping 0x" + Integer.toHexString(cmdLo)); + } + + /** Write one already-built ring frame. Worker-thread only (blocking). */ + private boolean writeRingFrame(byte[] frame, String what) { + try { + boolean ok = bleManager.writeFrames( + ringAddress, + BleProtocol.R1_WRITE_CHAR_UUID, + Collections.singletonList(frame), + ConnectionOptions.WRITE_TYPE, + ConnectionOptions.WRITE_TIMEOUT_MS + ); + if (!ok) { + logLine("ring " + what + " write failed"); + } + return ok; + } catch (Throwable t) { + logLine("ring " + what + " write error: " + safeMessage(t)); + return false; + } + } + + /** + * Drain queued ring frames (page ACKs). Worker-thread only. Returns true + * when anything was written. + */ + private boolean flushRingOutbound() { + boolean wroteAny = false; + while (true) { + byte[] frame; + synchronized (lock) { + if (!ringNotificationsReady || ringOutbound.isEmpty()) { + return wroteAny; + } + frame = ringOutbound.poll(); + } + if (frame == null) { + return wroteAny; + } + wroteAny |= writeRingFrame(frame, "page ack"); + } + } + + private int nextRingSeqLocked() { + ringSeq = (ringSeq + 1) & 0xff; + if (ringSeq == 0) { + ringSeq = 1; + } + return ringSeq; + } + + private int nextRingNonceLocked() { + ringNonce = (ringNonce + 1) & 0xffff; + return ringNonce; + } + + /** + * A snapshot of the health buffer together with the watermark identifying + * it. + * + *

The two have to come out under ONE lock. Reading the list and the + * count separately would let a page land in between, and the consumer would + * then clear a record nothing had ingested - the exact failure the + * watermark exists to prevent. + */ + public static final class RingHealthBatch { + private final List records; + private final long watermark; + + RingHealthBatch(List records, long watermark) { + this.records = records; + this.watermark = watermark; + } + + public List getRecords() { + return records; + } + + /** Total-ever-added at the instant of the snapshot. */ + public long getWatermark() { + return watermark; + } + } + + /** + * Snapshot of everything the ring has pushed and not yet been consumed, + * with the watermark needed to hand it back as consumed. + */ + public RingHealthBatch takeRingHealthBatch() { + synchronized (lock) { + return new RingHealthBatch(new ArrayList<>(ringHealthRecords), ringHealthTotalAdded); + } + } + + /** + * Drop every held record whose identity is below {@code watermark} - that + * is, everything the caller has durably stored. + * + *

"Cut and paste instead of copy paste. If you didn't receive the pull + * then it should not delete yet." Call this ONLY after the store write has + * succeeded; a caller that dies before calling it simply sees the same + * records again, which is a no-op at the store. + * + *

Records that arrived after the snapshot sit above the watermark and + * are left alone, so a page landing during an ingest is never lost. If the + * buffer evicted its oldest in the meantime (see + * {@link #RING_HEALTH_MAX_RECORDS}) the arithmetic accounts for it via + * {@code ringHealthTotalAdded} rather than clearing the wrong end. + * + * @return how many records were actually removed. + */ + public int clearRingHealthRecordsBelow(long watermark) { + synchronized (lock) { + long firstHeldIndex = ringHealthTotalAdded - ringHealthRecords.size(); + long toRemove = watermark - firstHeldIndex; + if (toRemove <= 0) { + return 0; + } + if (toRemove > ringHealthRecords.size()) { + toRemove = ringHealthRecords.size(); + } + ringHealthRecords.subList(0, (int) toRemove).clear(); + return (int) toRemove; + } + } + + /** + * Snapshot of everything the ring has pushed this session, WITHOUT + * consuming it. + * + *

Kept for callers that only want to look. The ingest path must use + * {@link #takeRingHealthBatch()} instead - a pure copy is what let the + * buffer grow unbounded and every tick re-process the whole session. + */ + public List getRingHealthRecords() { + synchronized (lock) { + return new ArrayList<>(ringHealthRecords); + } } private boolean enableRingNotification(String characteristicUuid) { diff --git a/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleManager.java b/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleManager.java index b8ecc1df..14a6e52a 100644 --- a/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleManager.java +++ b/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleManager.java @@ -124,6 +124,26 @@ public class FaceclawBleManager { } public boolean connect(String address, int timeoutMs) { + return connect(address, timeoutMs, false); + } + + /** + * EXPERIMENTAL (2026-09-11): the ring specifically needs autoConnect=true. + * Even's own vendor app connects the ring with Android's autoConnect flag + * set (confirmed via its own BLE debug log, "connect() - device: ..., + * auto: true"), while every other faceclaw connection (both glasses arms) + * uses autoConnect=false. Direct connect (false) is faster to establish + * but Android supervises it less patiently; a live test tonight showed + * the ring-only direct connection dying almost exactly 5 seconds in, + * repeatedly, with nothing else competing for it - consistent with a + * companion device Android's stack expects to be babied via autoConnect, + * not direct-connected like the glasses. autoConnect=true can take much + * longer to actually complete (Android manages it as a background + * reconnect, not an immediate attempt), so this needs its own longer + * timeout - do not reuse CONNECT_TIMEOUT_MS/awaitLatch's short window for + * it, that would just trade one spurious failure for another. + */ + public boolean connect(String address, int timeoutMs, boolean autoConnect) { if (address == null || address.trim().isEmpty()) { throw new IllegalArgumentException("address is required"); } @@ -148,7 +168,7 @@ public class FaceclawBleManager { gatt = device.connectGatt( context, - false, + autoConnect, gattCallback, BluetoothDevice.TRANSPORT_LE, BluetoothDevice.PHY_LE_2M|BluetoothDevice.PHY_LE_1M diff --git a/App_Resources/Android/src/main/java/com/faceclaw/app/g2protocol/BleProtocol.java b/App_Resources/Android/src/main/java/com/faceclaw/app/g2protocol/BleProtocol.java index 6031f24d..991c6b84 100644 --- a/App_Resources/Android/src/main/java/com/faceclaw/app/g2protocol/BleProtocol.java +++ b/App_Resources/Android/src/main/java/com/faceclaw/app/g2protocol/BleProtocol.java @@ -23,8 +23,27 @@ public class BleProtocol { public static final String OTA_DATA_WRITE_UUID = "00002760-08c2-11e1-9073-0e8ac72e0001"; public static final String OTA_DATA_NOTIFY_UUID = "00002760-08c2-11e1-9073-0e8ac72e0002"; public static final String RENDER_NOTIFY_UUID = "00002760-08c2-11e1-9073-0e8ac72e6402"; + // R1 ring, vendor service bae80001-4f05-4503-8e65-3af1f7329d1f. The service + // holds two write/notify pairs: bae80010 (write) + bae80011 (notify), and + // bae80012 (write) + bae80013 (notify). The health-data protocol + // (RingProtocol) rides the SECOND pair. public static final String R1_PHONE_NOTIFY_CHAR_UUID = "bae80011-4f05-4503-8e65-3af1f7329d1f"; public static final String R1_NOTIFY_CHAR_UUID = "bae80013-4f05-4503-8e65-3af1f7329d1f"; + /** + * Where health-data requests and page ACKs are written. Properties are + * 0x04 (write without response), so writes use ConnectionOptions.WRITE_TYPE + * (WRITE_TYPE_NO_RESPONSE) — which is also what the reference capture shows + * (ATT opcode 0x52 Write Command, never 0x12 Write Request). + * + * Resolved from the phone's own cached GATT database, not guessed: the + * bugreport taken alongside the capture contains a [gatt_cache_c73eb8f9c7c5] + * block (keyed by the ring's MAC C7:3E:B8:F9:C7:C5) listing + * Characteristic: declaration_handle=0x0014, value_handle=0x0015, + * uuid=bae80012-4f05-4503-8e65-3af1f7329d1f, prop=0x04 + * and 0x0015 is exactly the ATT handle every protocol write in the capture + * targets. See knowledge/staging/faceclaw-ring-protocol-implement-return.md. + */ + public static final String R1_WRITE_CHAR_UUID = "bae80012-4f05-4503-8e65-3af1f7329d1f"; public static final int PRELUDE_ACK_SID = 0x01; public static final int PRELUDE_ACK_MAGIC = 156; diff --git a/App_Resources/Android/src/main/java/com/faceclaw/app/g2protocol/ConnectionOptions.java b/App_Resources/Android/src/main/java/com/faceclaw/app/g2protocol/ConnectionOptions.java index a358dba9..331090e3 100644 --- a/App_Resources/Android/src/main/java/com/faceclaw/app/g2protocol/ConnectionOptions.java +++ b/App_Resources/Android/src/main/java/com/faceclaw/app/g2protocol/ConnectionOptions.java @@ -10,6 +10,11 @@ public class ConnectionOptions { public static final int DESCRIPTOR_TIMEOUT_MS = 5_000; public static final int RING_DESIRED_MTU = 247; public static final int RING_RECONNECT_DELAY_MS = 2_000; + // The ring connects with autoConnect=true (see FaceclawBleManager.connect's + // 3-arg overload) - Android manages that as a background reconnect rather + // than an immediate attempt, so it needs far more room than the glasses' + // direct-connect CONNECT_TIMEOUT_MS. Untuned guess, not measured. + public static final int RING_CONNECT_TIMEOUT_MS = 20_000; public static final int WRITE_TIMEOUT_MS = 2_000; public static final int PRELUDE_TIMEOUT_MS = 2_000; // Application security-auth exchange (sid 0x80). The success notification diff --git a/App_Resources/Android/src/main/java/com/faceclaw/app/g2protocol/RingProtocol.java b/App_Resources/Android/src/main/java/com/faceclaw/app/g2protocol/RingProtocol.java new file mode 100644 index 00000000..bea98611 --- /dev/null +++ b/App_Resources/Android/src/main/java/com/faceclaw/app/g2protocol/RingProtocol.java @@ -0,0 +1,951 @@ +package com.faceclaw.app; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; +import java.util.Locale; + +/** + * RingProtocol: frame build/parse plus per-record decoding for the Even R1 + * ring's health-data channel. Does _not_ include code for actually sending + * anything; for that, see FaceclawBleCommunicator (same split as BleProtocol). + * + *

Deliberately free of Android imports so the whole thing can be exercised + * with plain javac/java — see notes/ring-protocol-selftest/. + * + *

This is a different protocol from BleProtocol's. The glasses speak + * an {@code aa21} envelope with a CRC-16/CCITT; the ring speaks a 15-byte + * {@code 64 .. 64} header with a CRC-32C. Nothing is shared between them, and + * in particular {@link #crc32} must never be pointed at a glasses frame. + * + *

Wire format (offsets from the start of the ATT value): + *

+ *  off size field
+ *   0   1   FLAG      0x00 normally; 0x01 = fragmented, a continuation follows
+ *   1   4   CRC32     little-endian, over bytes [5:] of the *reassembled* frame
+ *   5   1   0x64      constant magic
+ *   6   1   CHAN      0x01 device/system, 0x02 health data
+ *   7   1   0x64      constant magic
+ *   8   1   SEQ       phone-side: one counter shared by both channels
+ *   9   1   0x00      constant
+ *  10   1   KIND      0x00 REQ, 0x01 ACK, 0x02 DATA, 0x03 RSP
+ *  11   1   CMD_HI
+ *  12   1   CMD_LO
+ *  13   2   PLEN      little-endian; equals (total frame length - 5)
+ *  15  ..   PAYLOAD   PLEN - 10 bytes; PAYLOAD[0:2] is a free per-message nonce
+ * 
+ * + *

Protocol spec and its evidence: + * knowledge/staging/faceclaw-ring-protocol-decode-return.md in the TLC + * knowledge base. Everything below is implemented from that document; the + * places where it is explicitly *not* solved are marked UNSOLVED and are + * surfaced raw rather than guessed at. + */ +public final class RingProtocol { + private RingProtocol() { + } + + /** CRC-32C polynomial, MSB-first / non-reflected form. Not CRC-32 (0x04C11DB7). */ + private static final int CRC32C_POLY = 0x1EDC6F41; + + public static final int MAGIC = 0x64; + public static final int HEADER_LEN = 15; + /** A continuation frame is FLAG(1) + CRC32(4) and then raw remainder bytes. */ + public static final int CONTINUATION_PREFIX_LEN = 5; + + public static final int FLAG_PLAIN = 0x00; + public static final int FLAG_FRAGMENTED = 0x01; + + public static final int CHAN_DEVICE = 0x01; + public static final int CHAN_HEALTH = 0x02; + + public static final int KIND_REQ = 0x00; + public static final int KIND_ACK = 0x01; + public static final int KIND_DATA = 0x02; + public static final int KIND_RSP = 0x03; + + /** Every health record type uses CMD_LO = 0x01; the type lives in CMD_HI. */ + public static final int CMD_LO_HEALTH = 0x01; + public static final int CMD_HI_HEART_RATE = 0x01; + public static final int CMD_HI_SPO2 = 0x02; + public static final int CMD_HI_HRV = 0x04; + public static final int CMD_HI_STEPS = 0x05; + public static final int CMD_HI_SLEEP = 0x06; + + /** Device/system channel commands all have CMD_HI = 0x00. */ + public static final int CMD_HI_DEVICE = 0x00; + public static final int CMD_LO_PAGE_ACK = 0x7E; + + /** + * The five health pulls, in the order Even's own app issues them: + * heart rate, HRV, SpO2, sleep, steps. That order is identical in all four + * sync bursts of the reference capture. (It is NOT the order the spec + * document happens to list them in — that is just its presentation order.) + * Whether the order matters to the ring is untested; matching the app is + * the cheapest way not to find out the hard way. + */ + public static final int[] HEALTH_COMMANDS = { + CMD_HI_HEART_RATE, + CMD_HI_HRV, + CMD_HI_SPO2, + CMD_HI_SLEEP, + CMD_HI_STEPS, + }; + + /** Constant terminator on every record body of every type. Meaning unknown. */ + private static final byte[] RECORD_FOOTER = {(byte) 0x94, 0x33, 0x01, 0x00}; + + /** ANCHOR field marker: 0x10 0xFF then a u32 LE Unix timestamp. */ + private static final int ANCHOR_MARK_HI = 0x10; + private static final int ANCHOR_MARK_LO = 0xFF; + + /** Returned by anchor/timestamp accessors when the value is not known. */ + public static final long UNKNOWN_TIME = -1L; + + private static final byte[] EMPTY = new byte[0]; + + // ------------------------------------------------------------------ + // CRC + // ------------------------------------------------------------------ + + /** + * CRC-32C over {@code data[from, to)}: polynomial 0x1EDC6F41, MSB-first, + * init 0, no reflection, no final xor. Verified against 188/188 frames in + * the reference capture. + */ + public static int crc32(byte[] data, int from, int to) { + int crc = 0; + for (int i = from; i < to; i++) { + crc ^= (data[i] & 0xff) << 24; + for (int bit = 0; bit < 8; bit++) { + if ((crc & 0x80000000) != 0) { + crc = (crc << 1) ^ CRC32C_POLY; + } else { + crc = crc << 1; + } + } + } + return crc; + } + + public static int crc32(byte[] data) { + return crc32(data, 0, data == null ? 0 : data.length); + } + + // ------------------------------------------------------------------ + // Frame building + // ------------------------------------------------------------------ + + /** + * Build one complete, CRC-correct frame. Fragmentation is a receive-side + * concern only: nothing we send approaches the 244-byte ATT ceiling. + */ + public static byte[] buildFrame(int chan, int kind, int cmdHi, int cmdLo, int seq, byte[] payload) { + byte[] body = payload == null ? EMPTY : payload; + int total = HEADER_LEN + body.length; + byte[] frame = new byte[total]; + frame[0] = (byte) FLAG_PLAIN; + frame[5] = (byte) MAGIC; + frame[6] = (byte) (chan & 0xff); + frame[7] = (byte) MAGIC; + frame[8] = (byte) (seq & 0xff); + frame[9] = 0x00; + frame[10] = (byte) (kind & 0xff); + frame[11] = (byte) (cmdHi & 0xff); + frame[12] = (byte) (cmdLo & 0xff); + int plen = total - 5; + frame[13] = (byte) (plen & 0xff); + frame[14] = (byte) ((plen >>> 8) & 0xff); + System.arraycopy(body, 0, frame, HEADER_LEN, body.length); + writeIntLe(frame, 1, crc32(frame, 5, total)); + return frame; + } + + /** + * A request frame. Health requests carry no arguments at all: the payload + * is the 2-byte nonce and nothing else. + * + *

The nonce is a free per-message id — it is covered by the frame CRC but + * is not content-derived, so any value works. It is encoded little-endian. + */ + public static byte[] buildRequest(int chan, int cmdHi, int cmdLo, int seq, int nonce) { + return buildFrame(chan, KIND_REQ, cmdHi, cmdLo, seq, nonceBytes(nonce)); + } + + /** One of the five health pulls; see {@link #HEALTH_COMMANDS}. */ + public static byte[] buildHealthRequest(int cmdHi, int seq, int nonce) { + return buildRequest(CHAN_HEALTH, cmdHi, CMD_LO_HEALTH, seq, nonce); + } + + /** + * The per-page acknowledgement: command 00:7E on the DEVICE channel, + * echoing the sequence number of the DATA page being acknowledged. + * + *

Payload is 12 bytes: the usual 2-byte nonce, then + * {@code 02 00 }, then five zero bytes. (Note + * the echoed page seq is at payload offset 6, after the nonce — a spec doc + * that describes the payload as starting at {@code 02} is off by the nonce.) + * + *

The frame's own SEQ is the phone's shared counter, NOT the echoed page + * seq: across 20 ACKs in the reference capture the two are always different, + * and the header SEQ continues the same +1 sequence used by every other + * phone-to-ring write on both channels. + * + *

Whether the ring actually *requires* this is untested — Even's app + * sends one for every page without exception (20/20), but no page has ever + * been deliberately left unacknowledged to see what happens. + */ + public static byte[] buildPageAck(int seq, int nonce, int ackedCmdHi, int ackedCmdLo, int pageSeq) { + byte[] payload = new byte[12]; + payload[0] = (byte) (nonce & 0xff); + payload[1] = (byte) ((nonce >>> 8) & 0xff); + payload[2] = 0x02; + payload[3] = (byte) (ackedCmdHi & 0xff); + payload[4] = (byte) (ackedCmdLo & 0xff); + payload[5] = 0x00; + payload[6] = (byte) (pageSeq & 0xff); + // payload[7..11] stay zero. + return buildFrame(CHAN_DEVICE, KIND_ACK, CMD_HI_DEVICE, CMD_LO_PAGE_ACK, seq, payload); + } + + private static byte[] nonceBytes(int nonce) { + return new byte[] {(byte) (nonce & 0xff), (byte) ((nonce >>> 8) & 0xff)}; + } + + // ------------------------------------------------------------------ + // Frame parsing and fragment reassembly + // ------------------------------------------------------------------ + + /** True when a value could be the start of a frame (magic bytes in place). */ + public static boolean looksLikeHeader(byte[] value) { + return value != null + && value.length >= HEADER_LEN + && (value[5] & 0xff) == MAGIC + && (value[7] & 0xff) == MAGIC; + } + + /** Total frame length declared by PLEN, or -1 when this is not a header. */ + public static int declaredLength(byte[] value) { + if (!looksLikeHeader(value)) { + return -1; + } + int plen = (value[13] & 0xff) | ((value[14] & 0xff) << 8); + int total = plen + 5; + return total < HEADER_LEN ? -1 : total; + } + + /** Parse a complete (already reassembled) frame. Returns null if malformed. */ + public static Frame parse(byte[] frame) { + if (frame == null || frame.length < HEADER_LEN) { + return null; + } + if ((frame[5] & 0xff) != MAGIC || (frame[7] & 0xff) != MAGIC) { + return null; + } + int plen = (frame[13] & 0xff) | ((frame[14] & 0xff) << 8); + if (plen + 5 != frame.length) { + return null; + } + int storedCrc = readIntLe(frame, 1); + int actualCrc = crc32(frame, 5, frame.length); + byte[] payload = Arrays.copyOfRange(frame, HEADER_LEN, frame.length); + return new Frame( + frame[0] & 0xff, + frame[6] & 0xff, + frame[8] & 0xff, + frame[10] & 0xff, + frame[11] & 0xff, + frame[12] & 0xff, + payload, + frame, + storedCrc == actualCrc + ); + } + + /** + * Feeds raw ATT notification values in and produces complete frames, + * rejoining fragmented ones. + * + *

Fragmentation (spec §2.3): when a frame exceeds the 244-byte ATT + * ceiling the ring sets FLAG=0x01, sends the first 244 bytes, and later + * sends a continuation frame in a different, headerless shape — FLAG(1), + * CRC32(4), then the remaining bytes verbatim. + * + *

Two things the spec document does not say, both measured from the + * reference capture and both load-bearing here: + *

    + *
  • The continuation is not adjacent. In one of the six captured + * fragmentations three unrelated complete frames arrive between the + * first fragment and its continuation, so a "next value is the rest" + * rule mis-joins. Complete frames are therefore still parsed normally + * while a fragment is outstanding.
  • + *
  • The continuation's own CRC field is not reliably the reassembled + * CRC. It matched in five of six cases and differed in the sixth + * (whose join is nonetheless byte-exact and CRC-valid), so the + * continuation must not be matched by comparing CRC fields.
  • + *
+ * + *

What is reliable, in all six cases, is length: a continuation carries + * exactly {@code CONTINUATION_PREFIX_LEN + bytesStillNeeded} bytes and does + * not itself look like a header. The reassembled frame's CRC is the real + * validator and is always checked. + */ + public static final class Reassembler { + /** + * Give up on an outstanding fragment after this many intervening + * complete frames. The observed worst case is 3; this is slack, not a + * measured bound. + */ + private static final int MAX_INTERLEAVED_FRAMES = 16; + + private byte[] pending; + private int pendingTotal; + private int interleaved; + + public boolean hasPending() { + return pending != null; + } + + public void reset() { + pending = null; + pendingTotal = 0; + interleaved = 0; + } + + /** + * Offer one ATT notification value. The result says whether the value + * belonged to this protocol at all (so the caller can fall through to + * the gesture decoder) and carries a frame once one is complete. + */ + public Intake accept(byte[] value) { + if (value == null || value.length == 0) { + return Intake.ignored(); + } + + if (pending != null) { + int needed = pendingTotal - pending.length; + if (value.length == CONTINUATION_PREFIX_LEN + needed && !looksLikeHeader(value)) { + byte[] joined = new byte[pendingTotal]; + System.arraycopy(pending, 0, joined, 0, pending.length); + System.arraycopy(value, CONTINUATION_PREFIX_LEN, joined, pending.length, needed); + reset(); + return complete(joined); + } + if (!looksLikeHeader(value)) { + int dropped = pendingTotal; + reset(); + return Intake.consumed(String.format( + Locale.US, + "dropped %d-byte fragment: continuation was %d bytes, expected %d", + dropped, value.length, CONTINUATION_PREFIX_LEN + needed)); + } + if (++interleaved > MAX_INTERLEAVED_FRAMES) { + int dropped = pendingTotal; + reset(); + // Fall through and parse this value as a fresh frame. + Intake result = acceptFresh(value); + return result.withNote(String.format( + Locale.US, "dropped %d-byte fragment: continuation never arrived", dropped)); + } + } + + return acceptFresh(value); + } + + private Intake acceptFresh(byte[] value) { + int total = declaredLength(value); + if (total < 0) { + return Intake.ignored(); + } + if (value.length >= total) { + return complete(Arrays.copyOf(value, total)); + } + // Only one fragment is ever outstanding in the reference capture, + // but never silently clobber one if that assumption breaks. + String clobbered = pending == null ? null : String.format( + Locale.US, "dropped %d-byte fragment: a new fragment started", pendingTotal); + pending = Arrays.copyOf(value, value.length); + pendingTotal = total; + interleaved = 0; + return Intake.consumed(String.format( + Locale.US, "fragment start, %d of %d bytes", value.length, total)).withNote(clobbered); + } + + private Intake complete(byte[] raw) { + Frame frame = parse(raw); + if (frame == null) { + return Intake.consumed("malformed frame, " + raw.length + " bytes"); + } + return Intake.frame(frame); + } + } + + /** The outcome of offering one ATT value to a {@link Reassembler}. */ + public static final class Intake { + /** True when the value belonged to this protocol and must not be re-handled. */ + public final boolean consumed; + /** Non-null once a complete frame is available. Check {@link Frame#crcOk}. */ + public final Frame frame; + /** Human-readable detail for logging, or null. */ + public final String note; + + private Intake(boolean consumed, Frame frame, String note) { + this.consumed = consumed; + this.frame = frame; + this.note = note; + } + + static Intake ignored() { + return new Intake(false, null, null); + } + + static Intake consumed(String note) { + return new Intake(true, null, note); + } + + static Intake frame(Frame frame) { + return new Intake(true, frame, null); + } + + Intake withNote(String extra) { + if (extra == null) { + return this; + } + return new Intake(consumed, frame, note == null ? extra : note + "; " + extra); + } + } + + /** One complete frame. */ + public static final class Frame { + public final int flag; + public final int chan; + public final int seq; + public final int kind; + public final int cmdHi; + public final int cmdLo; + /** PLEN - 10 bytes. payload[0:2] is the sender's nonce. */ + public final byte[] payload; + public final byte[] raw; + public final boolean crcOk; + + Frame(int flag, int chan, int seq, int kind, int cmdHi, int cmdLo, + byte[] payload, byte[] raw, boolean crcOk) { + this.flag = flag; + this.chan = chan; + this.seq = seq; + this.kind = kind; + this.cmdHi = cmdHi; + this.cmdLo = cmdLo; + this.payload = payload; + this.raw = raw; + this.crcOk = crcOk; + } + + public boolean isHealth() { + return chan == CHAN_HEALTH; + } + + public String commandLabel() { + return String.format(Locale.US, "%02x:%02x", cmdHi, cmdLo); + } + + public String describe() { + return String.format( + Locale.US, + "chan=%02x kind=%02x cmd=%s seq=%02x len=%d", + chan, kind, commandLabel(), seq, raw.length); + } + } + + // ------------------------------------------------------------------ + // Record decoding + // ------------------------------------------------------------------ + + /** + * Decode a health DATA page. Returns null when the frame is not a health + * DATA page or its body does not match the layout for its type. + */ + public static HealthRecord decode(Frame frame, long receivedAtMs) { + if (frame == null || !frame.crcOk || !frame.isHealth() || frame.kind != KIND_DATA) { + return null; + } + if (frame.cmdLo != CMD_LO_HEALTH) { + return null; + } + switch (frame.cmdHi) { + case CMD_HI_HEART_RATE: + case CMD_HI_SPO2: + case CMD_HI_HRV: + return decodeHourly(frame, receivedAtMs); + case CMD_HI_STEPS: + return decodeSteps(frame, receivedAtMs); + case CMD_HI_SLEEP: + return decodeSleep(frame, receivedAtMs); + default: + return null; + } + } + + /** + * Heart rate / SpO2 / HRV: an hourly {@code [index][avg][max][min]} series. + * + *

The value width W is not guessed — it is resolved from the body length + * by {@code len == W + COUNT * (1 + 3W)}, which has a unique solution for + * every frame in the reference capture (W=1 for HR and SpO2, W=2 for HRV). + */ + public static HourlyRecord decodeHourly(Frame frame, long receivedAtMs) { + byte[] pay = frame.payload; + if (pay.length < 13 + RECORD_FOOTER.length) { + return null; + } + int count = pay[2] & 0xff; + long anchor = anchorUnixSeconds(pay); + long tag = readUInt32Le(pay, 9); + + int bodyLen = pay.length - 13 - RECORD_FOOTER.length; + int width; + if (bodyLen == 1 + count * 4) { + width = 1; + } else if (bodyLen == 2 + count * 7) { + width = 2; + } else { + return null; + } + + int current = readUIntLe(pay, 13, width); + int offset = 13 + width; + HourlyGroup[] groups = new HourlyGroup[count]; + for (int i = 0; i < count; i++) { + int hourIndex = pay[offset] & 0xff; + offset++; + int avg = readUIntLe(pay, offset, width); + offset += width; + int max = readUIntLe(pay, offset, width); + offset += width; + int min = readUIntLe(pay, offset, width); + offset += width; + long unix = anchor == UNKNOWN_TIME ? UNKNOWN_TIME : anchor + hourIndex * 3600L; + groups[i] = new HourlyGroup(hourIndex, avg, max, min, unix); + } + return new HourlyRecord(frame.cmdHi, receivedAtMs, anchor, tag, current, width, groups); + } + + /** + * Steps / activity buckets: {@code [index][v1][v2][v3]} after the record + * prefix. v1 (steps) is proven against a full-day total; v2 and v3 are + * calorie-shaped but unconfirmed, and the bucket index does NOT map to a + * known wall-clock time (see {@link StepsBucket}). + */ + public static StepsRecord decodeSteps(Frame frame, long receivedAtMs) { + byte[] pay = frame.payload; + if (pay.length < 9 + RECORD_FOOTER.length) { + return null; + } + int count = pay[2] & 0xff; + if (pay.length != 9 + count * 7 + RECORD_FOOTER.length) { + return null; + } + long anchor = anchorUnixSeconds(pay); + int offset = 9; + StepsBucket[] buckets = new StepsBucket[count]; + for (int i = 0; i < count; i++) { + int index = pay[offset] & 0xff; + int steps = readUInt16Le(pay, offset + 1); + int v2 = readUInt16Le(pay, offset + 3); + int v3 = readUInt16Le(pay, offset + 5); + offset += 7; + buckets[i] = new StepsBucket(index, steps, v2, v3); + } + return new StepsRecord(receivedAtMs, anchor, buckets); + } + + /** + * A sleep session. The ring transmits pre-classified stages, per-stage + * totals and the session boundaries; nothing is computed phone-side. + * + *

{@code startTs}/{@code endTs} are ring-relative seconds, NOT Unix + * timestamps — see {@link SleepRecord}. + */ + public static SleepRecord decodeSleep(Frame frame, long receivedAtMs) { + byte[] pay = frame.payload; + if (pay.length < 3) { + return null; + } + int recordState = pay[2] & 0xff; + byte[] unknownA = safeRange(pay, 3, 9); + long unknownTag = pay.length >= 13 ? readUInt32Le(pay, 9) : UNKNOWN_TIME; + if (recordState != 1 || pay.length < 34 + RECORD_FOOTER.length) { + // RECSTATE 2 is the empty / end-of-list marker. + return new SleepRecord( + receivedAtMs, recordState, unknownA, unknownTag, + 0, 0, 0, 0, 0, 0, 0, new SleepSegment[0]); + } + + long startTs = readUInt32Le(pay, 14); + long endTs = readUInt32Le(pay, 18); + int totalTime = readUInt16Le(pay, 22); + int wakeTime = readUInt16Le(pay, 24); + int remTime = readUInt16Le(pay, 26); + int lightTime = readUInt16Le(pay, 28); + int deepTime = readUInt16Le(pay, 30); + int segmentCount = pay[32] & 0xff; + if (pay.length != 34 + segmentCount * 3 + RECORD_FOOTER.length) { + return null; + } + SleepSegment[] segments = new SleepSegment[segmentCount]; + int offset = 34; + for (int i = 0; i < segmentCount; i++) { + int stage = pay[offset] & 0xff; + int halfMinutes = readUInt16Le(pay, offset + 1); + offset += 3; + segments[i] = new SleepSegment(stage, halfMinutes); + } + return new SleepRecord( + receivedAtMs, recordState, unknownA, unknownTag, + startTs, endTs, totalTime, wakeTime, remTime, lightTime, deepTime, segments); + } + + /** + * The record's day anchor as Unix epoch seconds, or {@link #UNKNOWN_TIME} + * when the anchor field is the six-zero-byte "backlog page" form. + * + *

UNSOLVED: a backlog page's true base is not understood as a + * general rule. One capture's backlog base landed at 2026-09-08 23:48:49 + * local, which is the moment that sync ran plus a per-type offset — it is + * not a fixed offset from midnight and must not be hardcoded. Callers get + * {@link #UNKNOWN_TIME} and the raw hour index instead of an invented + * absolute time. + */ + public static long anchorUnixSeconds(byte[] payload) { + if (payload == null || payload.length < 9) { + return UNKNOWN_TIME; + } + if ((payload[3] & 0xff) == ANCHOR_MARK_HI && (payload[4] & 0xff) == ANCHOR_MARK_LO) { + return readUInt32Le(payload, 5); + } + return UNKNOWN_TIME; + } + + // ------------------------------------------------------------------ + // Decoded record types + // ------------------------------------------------------------------ + + /** Common supertype so one store can hold every decoded page. */ + public abstract static class HealthRecord { + public final int cmdHi; + public final long receivedAtMs; + + HealthRecord(int cmdHi, long receivedAtMs) { + this.cmdHi = cmdHi; + this.receivedAtMs = receivedAtMs; + } + + /** The metric name, for logs. */ + public String metric() { + switch (cmdHi) { + case CMD_HI_HEART_RATE: return "heart_rate"; + case CMD_HI_SPO2: return "spo2"; + case CMD_HI_HRV: return "hrv"; + case CMD_HI_STEPS: return "steps"; + case CMD_HI_SLEEP: return "sleep"; + default: return String.format(Locale.US, "cmd%02x", cmdHi); + } + } + + /** A one-line summary safe to put in a log. */ + public abstract String summary(); + } + + /** Heart rate, SpO2 or HRV: one page of hourly buckets. */ + public static final class HourlyRecord extends HealthRecord { + /** Day anchor in Unix seconds, or {@link #UNKNOWN_TIME} on a backlog page. */ + public final long anchorUnixSeconds; + /** Per-metric "last measured at". See the 4-hour skew note in the spec. */ + public final long tagRaw; + /** The metric's latest value. */ + public final int current; + /** 1 byte for HR/SpO2, 2 for HRV; resolved from the body length. */ + public final int valueWidth; + public final HourlyGroup[] groups; + + HourlyRecord(int cmdHi, long receivedAtMs, long anchorUnixSeconds, long tagRaw, + int current, int valueWidth, HourlyGroup[] groups) { + super(cmdHi, receivedAtMs); + this.anchorUnixSeconds = anchorUnixSeconds; + this.tagRaw = tagRaw; + this.current = current; + this.valueWidth = valueWidth; + this.groups = groups; + } + + /** True when this page has no anchor, i.e. it is a backlog page. */ + public boolean isBacklog() { + return anchorUnixSeconds == UNKNOWN_TIME; + } + + @Override public String summary() { + return String.format( + Locale.US, + "%s groups=%d width=%d current=%d anchor=%s tag=%d", + metric(), groups.length, valueWidth, current, + isBacklog() ? "backlog(unanchored)" : Long.toString(anchorUnixSeconds), + tagRaw); + } + } + + /** One hourly bucket. */ + public static final class HourlyGroup { + /** Raw index as sent. On an anchored page this is hours since the anchor. */ + public final int hourIndex; + public final int avg; + public final int max; + public final int min; + /** + * Absolute Unix seconds for this bucket, or {@link #UNKNOWN_TIME} on a + * backlog page — where the base is UNSOLVED and deliberately not guessed. + */ + public final long unixSeconds; + + HourlyGroup(int hourIndex, int avg, int max, int min, long unixSeconds) { + this.hourIndex = hourIndex; + this.avg = avg; + this.max = max; + this.min = min; + this.unixSeconds = unixSeconds; + } + } + + /** One page of activity buckets. */ + public static final class StepsRecord extends HealthRecord { + public final long anchorUnixSeconds; + public final StepsBucket[] buckets; + + StepsRecord(long receivedAtMs, long anchorUnixSeconds, StepsBucket[] buckets) { + super(CMD_HI_STEPS, receivedAtMs); + this.anchorUnixSeconds = anchorUnixSeconds; + this.buckets = buckets; + } + + public int totalSteps() { + int total = 0; + for (StepsBucket bucket : buckets) { + total += bucket.steps; + } + return total; + } + + @Override public String summary() { + return String.format( + Locale.US, + "steps buckets=%d total=%d anchor=%s", + buckets.length, totalSteps(), + anchorUnixSeconds == UNKNOWN_TIME ? "none" : Long.toString(anchorUnixSeconds)); + } + } + + /** + * One activity bucket. + * + *

UNSOLVED: {@link #index} does not map to a known wall-clock + * time. It runs 0-7, 10, 11, 13-34 and then jumps to 130+, and no bucket + * width at any base reproduces the app's own per-bucket distribution — even + * though the steps total across all buckets is exactly right. The raw index + * is stored as sent; no time-of-day mapping is invented. + */ + public static final class StepsBucket { + public final int index; + /** Confirmed: summed over a page this equals the app's daily step total. */ + public final int steps; + /** UNCONFIRMED: calorie-shaped (v3 - v2 tracks per-bucket resting kcal). */ + public final int calorieLike2; + /** UNCONFIRMED: calorie-shaped. */ + public final int calorieLike3; + + StepsBucket(int index, int steps, int calorieLike2, int calorieLike3) { + this.index = index; + this.steps = steps; + this.calorieLike2 = calorieLike2; + this.calorieLike3 = calorieLike3; + } + } + + /** + * One sleep session. + * + *

{@link #startTs} and {@link #endTs} are ring-relative seconds, not + * Unix time. Even's own app gets this wrong and stamps live-pushed + * sessions with timestamps in 1979. Do not feed them to a date formatter. + * + *

UNSOLVED: {@link #unknownPrefix} (6 bytes) and + * {@link #unknownTag} (u32) are not decoded; one of them probably carries + * the session date, which would remove the anchoring problem. They are + * stored raw rather than interpreted. + */ + public static final class SleepRecord extends HealthRecord { + /** 1 = a real record, 2 = the empty / end-of-list marker. */ + public final int recordState; + /** UNSOLVED per-record 6-byte field (payload[3:9]). Stored raw. */ + public final byte[] unknownPrefix; + /** UNSOLVED u32 tag (payload[9:13]). Stored raw. */ + public final long unknownTag; + /** Ring-relative seconds, NOT Unix. */ + public final long startTs; + /** Ring-relative seconds, NOT Unix. */ + public final long endTs; + public final int totalTime; + public final int wakeTime; + public final int remTime; + public final int lightTime; + public final int deepTime; + /** + * The stage series. Stage ids are the same 0-3 encoding the app's own + * export uses, but which id means wake/rem/light/deep is NOT stated by + * the spec and is deliberately not guessed here — see + * {@link #halfMinutesForStage}. + */ + public final SleepSegment[] segments; + + SleepRecord(long receivedAtMs, int recordState, byte[] unknownPrefix, long unknownTag, + long startTs, long endTs, int totalTime, int wakeTime, int remTime, + int lightTime, int deepTime, SleepSegment[] segments) { + super(CMD_HI_SLEEP, receivedAtMs); + this.recordState = recordState; + this.unknownPrefix = unknownPrefix; + this.unknownTag = unknownTag; + this.startTs = startTs; + this.endTs = endTs; + this.totalTime = totalTime; + this.wakeTime = wakeTime; + this.remTime = remTime; + this.lightTime = lightTime; + this.deepTime = deepTime; + this.segments = segments; + } + + public boolean isRealRecord() { + return recordState == 1; + } + + public int totalHalfMinutes() { + int total = 0; + for (SleepSegment segment : segments) { + total += segment.halfMinutes; + } + return total; + } + + public int halfMinutesForStage(int stage) { + int total = 0; + for (SleepSegment segment : segments) { + if (segment.stage == stage) { + total += segment.halfMinutes; + } + } + return total; + } + + /** + * The two whole-record arithmetic identities from the spec, which held + * exactly for all ten real records in the reference capture. A false + * result means the body was mis-parsed. + */ + public boolean identitiesHold() { + if (!isRealRecord()) { + return true; + } + int seconds = totalHalfMinutes() * 30; + return seconds == totalTime + wakeTime && seconds == (int) (endTs - startTs); + } + + @Override public String summary() { + if (!isRealRecord()) { + return String.format(Locale.US, "sleep marker state=%d", recordState); + } + return String.format( + Locale.US, + "sleep segments=%d total=%ds wake=%d rem=%d light=%d deep=%d relStart=%d relEnd=%d identities=%s", + segments.length, totalTime, wakeTime, remTime, lightTime, deepTime, + startTs, endTs, identitiesHold()); + } + } + + /** One stage run: a stage id and a duration in half-minutes (30 s units). */ + public static final class SleepSegment { + public final int stage; + public final int halfMinutes; + + SleepSegment(int stage, int halfMinutes) { + this.stage = stage; + this.halfMinutes = halfMinutes; + } + } + + // ------------------------------------------------------------------ + // Little-endian helpers + // ------------------------------------------------------------------ + + private static void writeIntLe(byte[] out, int offset, int value) { + out[offset] = (byte) (value & 0xff); + out[offset + 1] = (byte) ((value >>> 8) & 0xff); + out[offset + 2] = (byte) ((value >>> 16) & 0xff); + out[offset + 3] = (byte) ((value >>> 24) & 0xff); + } + + private static int readIntLe(byte[] data, int offset) { + return (data[offset] & 0xff) + | ((data[offset + 1] & 0xff) << 8) + | ((data[offset + 2] & 0xff) << 16) + | ((data[offset + 3] & 0xff) << 24); + } + + private static long readUInt32Le(byte[] data, int offset) { + return readIntLe(data, offset) & 0xffffffffL; + } + + private static int readUInt16Le(byte[] data, int offset) { + return (data[offset] & 0xff) | ((data[offset + 1] & 0xff) << 8); + } + + private static int readUIntLe(byte[] data, int offset, int width) { + int value = 0; + for (int i = 0; i < width; i++) { + value |= (data[offset + i] & 0xff) << (8 * i); + } + return value; + } + + private static byte[] safeRange(byte[] data, int from, int to) { + if (data == null || from >= data.length) { + return EMPTY; + } + return Arrays.copyOfRange(data, from, Math.min(to, data.length)); + } + + /** Hex, for logs. Mirrors FaceclawBleCommunicator.hex(). */ + public static String hex(byte[] data) { + if (data == null || data.length == 0) { + return ""; + } + char[] digits = "0123456789abcdef".toCharArray(); + char[] out = new char[data.length * 2]; + for (int i = 0; i < data.length; i++) { + int value = data[i] & 0xff; + out[i * 2] = digits[value >>> 4]; + out[i * 2 + 1] = digits[value & 0x0f]; + } + return new String(out); + } + + /** The five health requests, ready to write, sharing one ascending seq run. */ + public static List buildHealthRequestBurst(int firstSeq, int firstNonce) { + List frames = new ArrayList<>(HEALTH_COMMANDS.length); + int seq = firstSeq; + int nonce = firstNonce; + for (int cmdHi : HEALTH_COMMANDS) { + frames.add(buildHealthRequest(cmdHi, seq, nonce)); + seq = (seq + 1) & 0xff; + nonce = (nonce + 1) & 0xffff; + } + return frames; + } +} diff --git a/notes/ring-protocol-selftest/RingProtocolSelfTest.java b/notes/ring-protocol-selftest/RingProtocolSelfTest.java new file mode 100644 index 00000000..dc20116b --- /dev/null +++ b/notes/ring-protocol-selftest/RingProtocolSelfTest.java @@ -0,0 +1,483 @@ +package com.faceclaw.app; + +import java.util.Arrays; +import java.util.List; + +/** + * Standalone self-test for {@link RingProtocol}. No Android APIs and no + * hardware: every byte-manipulation path is exercised against either frames + * copied from the reference capture or synthetic bodies built from the spec's + * field layout. + * + *

+ *   javac -d /tmp/rpt App_Resources/Android/src/main/java/com/faceclaw/app/g2protocol/RingProtocol.java \
+ *                     notes/ring-protocol-selftest/RingProtocolSelfTest.java
+ *   java -cp /tmp/rpt com.faceclaw.app.RingProtocolSelfTest
+ * 
+ * + *

The captured frames reproduced below are requests and page-ACKs only. + * Those carry a nonce, a command id and a sequence number — no biometric + * values. No captured DATA page appears here, deliberately. + */ +public final class RingProtocolSelfTest { + private static int checks; + private static int failures; + + public static void main(String[] args) { + testCrcAndRequestRoundTrip(); + testFiveHealthRequests(); + testPageAckAgainstCapture(); + testParseRejectsGarbage(); + testFragmentReassembly(); + testHourlyDecode(); + testStepsDecode(); + testSleepDecodeAndIdentities(); + + System.out.println(); + System.out.println(failures == 0 + ? "PASS: all " + checks + " checks" + : "FAIL: " + failures + " of " + checks + " checks"); + if (failures != 0) { + System.exit(1); + } + } + + // ------------------------------------------------------------------ + + /** + * Rebuild captured request pkt 9166 from its decoded fields alone. If the + * CRC-32C parameters or the header layout are wrong by even one bit this + * cannot reproduce the captured bytes. + */ + private static void testCrcAndRequestRoundTrip() { + section("CRC + request round-trip (captured pkt 9166)"); + byte[] built = RingProtocol.buildRequest( + RingProtocol.CHAN_HEALTH, + RingProtocol.CMD_HI_HEART_RATE, + RingProtocol.CMD_LO_HEALTH, + 0x06, + 0x08ca); + expectHex("pkt 9166", "00db64265a64026406000001010c00ca08", built); + + RingProtocol.Frame frame = RingProtocol.parse(built); + expect("parses back", frame != null && frame.crcOk); + expect("chan", frame.chan == RingProtocol.CHAN_HEALTH); + expect("kind REQ", frame.kind == RingProtocol.KIND_REQ); + expect("seq", frame.seq == 0x06); + expect("cmd 01:01", frame.cmdHi == 0x01 && frame.cmdLo == 0x01); + expect("payload is the 2-byte nonce", frame.payload.length == 2); + + // A single flipped payload bit must invalidate the CRC. + byte[] tampered = built.clone(); + tampered[15] ^= 0x01; + RingProtocol.Frame bad = RingProtocol.parse(tampered); + expect("tampered frame fails CRC", bad != null && !bad.crcOk); + } + + /** The five ready-to-send health requests, seq=1, nonce=0. */ + private static void testFiveHealthRequests() { + section("five health requests (spec section 9)"); + String[][] expected = { + {"heart rate", "00450fe48f64026401000001010c000000"}, + {"SpO2", "000d3fd33364026401000002010c000000"}, + {"HRV", "00dc30615564026401000004010c000000"}, + {"steps", "00e4208c3e64026401000005010c000000"}, + {"sleep", "00ac10bb8264026401000006010c000000"}, + }; + int[] commands = { + RingProtocol.CMD_HI_HEART_RATE, + RingProtocol.CMD_HI_SPO2, + RingProtocol.CMD_HI_HRV, + RingProtocol.CMD_HI_STEPS, + RingProtocol.CMD_HI_SLEEP, + }; + for (int i = 0; i < commands.length; i++) { + byte[] built = RingProtocol.buildHealthRequest(commands[i], 0x01, 0x0000); + expectHex(expected[i][0], expected[i][1], built); + } + + // The convenience burst builder must produce the same first frame and + // then advance the shared sequence counter by one per frame. + List burst = RingProtocol.buildHealthRequestBurst(0x01, 0x0000); + expect("burst has five frames", burst.size() == 5); + expectHex("burst[0] == heart rate", expected[0][1], burst.get(0)); + boolean seqRuns = true; + for (int i = 0; i < burst.size(); i++) { + RingProtocol.Frame f = RingProtocol.parse(burst.get(i)); + if (f == null || !f.crcOk || f.seq != 0x01 + i) { + seqRuns = false; + } + } + expect("burst sequence numbers run 1..5 and all CRCs are valid", seqRuns); + } + + /** + * Rebuild real captured page-ACKs. This is what pins down the two things + * the prose spec got wrong: the payload begins with the usual nonce (so the + * echoed page seq is at offset 6, not 4), and the frame's own SEQ is the + * phone's shared counter rather than the echoed page seq. + */ + private static void testPageAckAgainstCapture() { + section("page ACK 00:7E rebuilt from captured frames"); + // seq, nonce, ackedCmdHi, ackedCmdLo, pageSeq, expected hex + Object[][] cases = { + {0x0d, 0x5f49, 0x01, 0x01, 0x03, "005e55d80b6401640d0001007e1600495f02010100030000000000"}, + {0x13, 0xdc10, 0x04, 0x01, 0x07, "00a2bae3c4640164130001007e160010dc02040100070000000000"}, + {0x17, 0x86e9, 0x02, 0x01, 0x09, "002c006c61640164170001007e1600e98602020100090000000000"}, + {0x23, 0x634c, 0x06, 0x01, 0x13, "00b96c8823640164230001007e16004c6302060100130000000000"}, + {0x25, 0x46f2, 0x05, 0x01, 0x14, "00474ee8b8640164250001007e1600f24602050100140000000000"}, + {0x14, 0x7bc3, 0x05, 0x01, 0x3b, "00f3a5a917640164140001007e1600c37b020501003b0000000000"}, + }; + for (Object[] c : cases) { + byte[] built = RingProtocol.buildPageAck( + (Integer) c[0], (Integer) c[1], (Integer) c[2], (Integer) c[3], (Integer) c[4]); + expectHex("ack for cmd " + hex2((Integer) c[2]) + ":" + hex2((Integer) c[3]) + + " page seq " + hex2((Integer) c[4]), (String) c[5], built); + } + + RingProtocol.Frame f = RingProtocol.parse(RingProtocol.buildPageAck(0x0d, 0x5f49, 0x01, 0x01, 0x03)); + expect("ack rides the DEVICE channel", f.chan == RingProtocol.CHAN_DEVICE); + expect("ack kind is ACK", f.kind == RingProtocol.KIND_ACK); + expect("ack command is 00:7e", f.cmdHi == 0x00 && f.cmdLo == 0x7e); + expect("ack header seq differs from echoed page seq", f.seq != (f.payload[6] & 0xff)); + expect("echoed page seq is at payload[6]", (f.payload[6] & 0xff) == 0x03); + } + + private static void testParseRejectsGarbage() { + section("parser rejects non-frames"); + expect("null", RingProtocol.parse(null) == null); + expect("too short", RingProtocol.parse(new byte[8]) == null); + expect("no magic", RingProtocol.parse(new byte[20]) == null); + // A 3-byte ring gesture frame must not look like a header. + expect("gesture frame is not a header", + !RingProtocol.looksLikeHeader(new byte[] {(byte) 0xff, 0x04, 0x01})); + // A frame whose PLEN disagrees with its actual length is rejected. + byte[] frame = RingProtocol.buildHealthRequest(RingProtocol.CMD_HI_HRV, 1, 0); + byte[] truncated = Arrays.copyOf(frame, frame.length - 1); + expect("length/PLEN mismatch rejected", RingProtocol.parse(truncated) == null); + } + + /** + * Fragmentation, reproducing the shape the capture actually shows: an + * oversized frame split into a 244-byte FLAG=0x01 head and a headerless + * continuation, with an unrelated complete frame arriving in between. + */ + private static void testFragmentReassembly() { + section("fragment reassembly"); + // Build a 252-byte steps-shaped frame: 15 header + 237 payload. + byte[] payload = new byte[237]; + for (int i = 0; i < payload.length; i++) { + payload[i] = (byte) (i * 7 + 3); + } + byte[] whole = RingProtocol.buildFrame( + RingProtocol.CHAN_HEALTH, RingProtocol.KIND_DATA, + RingProtocol.CMD_HI_STEPS, RingProtocol.CMD_LO_HEALTH, 0x15, payload); + expect("test frame is 252 bytes", whole.length == 252); + + byte[] head = Arrays.copyOf(whole, 244); + head[0] = (byte) RingProtocol.FLAG_FRAGMENTED; + byte[] continuation = new byte[RingProtocol.CONTINUATION_PREFIX_LEN + (whole.length - 244)]; + System.arraycopy(whole, 244, continuation, RingProtocol.CONTINUATION_PREFIX_LEN, whole.length - 244); + expect("continuation is 5 + remaining bytes", continuation.length == 13); + + byte[] interleaved = RingProtocol.buildFrame( + RingProtocol.CHAN_DEVICE, RingProtocol.KIND_DATA, 0x00, 0x01, 0x16, new byte[9]); + + RingProtocol.Reassembler reassembler = new RingProtocol.Reassembler(); + + RingProtocol.Intake first = reassembler.accept(head); + expect("head consumed", first.consumed && first.frame == null); + expect("fragment outstanding", reassembler.hasPending()); + + RingProtocol.Intake middle = reassembler.accept(interleaved); + expect("interleaved frame still parses while a fragment is pending", + middle.consumed && middle.frame != null && middle.frame.crcOk); + expect("fragment survives the interleaved frame", reassembler.hasPending()); + + RingProtocol.Intake done = reassembler.accept(continuation); + expect("continuation completes the frame", done.consumed && done.frame != null); + expect("reassembled frame passes CRC", done.frame.crcOk); + expect("reassembled bytes are exact", + Arrays.equals(done.frame.raw, headJoined(head, whole))); + expect("no fragment left outstanding", !reassembler.hasPending()); + expect("reassembled payload is intact", Arrays.equals(done.frame.payload, payload)); + + // Non-protocol traffic must pass straight through untouched. + RingProtocol.Intake gesture = reassembler.accept(new byte[] {(byte) 0xff, 0x04, 0x01}); + expect("gesture frame is not consumed", !gesture.consumed); + } + + private static byte[] headJoined(byte[] head, byte[] whole) { + byte[] expected = whole.clone(); + expected[0] = head[0]; + return expected; + } + + // ------------------------------------------------------------------ + // Synthetic record bodies, built directly from the spec's field layout. + // ------------------------------------------------------------------ + + private static void testHourlyDecode() { + section("hourly decode (heart rate W=1, HRV W=2, backlog page)"); + + // Anchored heart-rate page, W=1, three groups. + long anchor = 1788926400L; // 2026-09-09 00:00 local, the capture's anchor + int[][] groups = {{0, 61, 88, 55}, {1, 58, 71, 52}, {2, 63, 90, 57}}; + byte[] body = hourlyBody(3, anchor, 12345L, 64, 1, groups); + RingProtocol.Frame frame = dataFrame(RingProtocol.CMD_HI_HEART_RATE, body); + RingProtocol.HourlyRecord hr = RingProtocol.decodeHourly(frame, 0L); + expect("HR decodes", hr != null); + expect("HR width resolved to 1", hr.valueWidth == 1); + expect("HR group count", hr.groups.length == 3); + expect("HR anchor", hr.anchorUnixSeconds == anchor); + expect("HR not backlog", !hr.isBacklog()); + expect("HR current", hr.current == 64); + boolean values = true; + for (int i = 0; i < groups.length; i++) { + RingProtocol.HourlyGroup g = hr.groups[i]; + values &= g.hourIndex == groups[i][0] && g.avg == groups[i][1] + && g.max == groups[i][2] && g.min == groups[i][3] + && g.unixSeconds == anchor + groups[i][0] * 3600L; + } + expect("HR values and hour timestamps round-trip", values); + + // HRV uses two-byte values; the width must be resolved, not assumed. + int[][] hrvGroups = {{8, 300, 420, 210}, {9, 275, 380, 190}, {10, 512, 640, 400}}; + byte[] hrvBody = hourlyBody(3, anchor, 22222L, 333, 2, hrvGroups); + RingProtocol.HourlyRecord hrv = + RingProtocol.decodeHourly(dataFrame(RingProtocol.CMD_HI_HRV, hrvBody), 0L); + expect("HRV decodes", hrv != null); + expect("HRV width resolved to 2", hrv.valueWidth == 2); + expect("HRV current", hrv.current == 333); + expect("HRV holds values above 255", hrv.groups[2].max == 640); + + // Backlog page: anchor absent. The hour index must survive; the absolute + // time must NOT be invented. + byte[] backlogBody = hourlyBody(3, RingProtocol.UNKNOWN_TIME, 77777L, 60, 1, groups); + RingProtocol.HourlyRecord backlog = + RingProtocol.decodeHourly(dataFrame(RingProtocol.CMD_HI_HEART_RATE, backlogBody), 0L); + expect("backlog decodes", backlog != null); + expect("backlog flagged", backlog.isBacklog()); + expect("backlog anchor unknown", backlog.anchorUnixSeconds == RingProtocol.UNKNOWN_TIME); + boolean noInventedTime = true; + for (RingProtocol.HourlyGroup g : backlog.groups) { + noInventedTime &= g.unixSeconds == RingProtocol.UNKNOWN_TIME; + } + expect("backlog groups carry no invented absolute time", noInventedTime); + expect("backlog keeps raw hour indices", + backlog.groups[0].hourIndex == 0 && backlog.groups[2].hourIndex == 2); + expect("backlog still decodes values", backlog.groups[1].avg == 58); + } + + private static void testStepsDecode() { + section("steps decode"); + long anchor = 1788926400L; + int[][] buckets = {{0, 120, 4, 16}, {3, 0, 0, 12}, {130, 45, 2, 14}}; + byte[] body = stepsBody(anchor, buckets); + RingProtocol.StepsRecord steps = + RingProtocol.decodeSteps(dataFrame(RingProtocol.CMD_HI_STEPS, body), 0L); + expect("steps decode", steps != null); + expect("bucket count", steps.buckets.length == 3); + expect("total steps", steps.totalSteps() == 165); + expect("raw index preserved, including the 130+ jump", + steps.buckets[2].index == 130); + expect("v2/v3 kept as unconfirmed calorie-shaped fields", + steps.buckets[0].calorieLike2 == 4 && steps.buckets[0].calorieLike3 == 16); + expect("steps anchor", steps.anchorUnixSeconds == anchor); + // Length must be exact: a truncated body is a decode failure, not a guess. + byte[] shortBody = Arrays.copyOf(body, body.length - 1); + expect("truncated steps body rejected", + RingProtocol.decodeSteps(dataFrame(RingProtocol.CMD_HI_STEPS, shortBody), 0L) == null); + } + + private static void testSleepDecodeAndIdentities() { + section("sleep decode + the spec's arithmetic identities"); + // segments: (stage, halfMinutes). Stage sums: 0->10, 1->20, 2->70, 3->25. + int[][] segments = {{0, 4}, {1, 20}, {2, 40}, {0, 6}, {2, 30}, {3, 25}}; + int totalHalfMinutes = 125; + int seconds = totalHalfMinutes * 30; // 3750 + int wake = 10 * 30; // 300, stage 0 + int rem = 20 * 30; // 600, stage 1 + int light = 70 * 30; // 2100, stage 2 + int deep = 25 * 30; // 750, stage 3 + int total = seconds - wake; // 3450 + long start = 100000L; + long end = start + seconds; + + byte[] body = sleepBody(1, start, end, total, wake, rem, light, deep, segments); + RingProtocol.SleepRecord sleep = + RingProtocol.decodeSleep(dataFrame(RingProtocol.CMD_HI_SLEEP, body), 0L); + expect("sleep decodes", sleep != null); + expect("real record", sleep.isRealRecord()); + expect("segment count", sleep.segments.length == segments.length); + expect("segment stages and durations round-trip", + sleep.segments[2].stage == 2 && sleep.segments[2].halfMinutes == 40); + + expect("identity: sum(half_minutes) x 30 == total_time + wake_time", + sleep.totalHalfMinutes() * 30 == sleep.totalTime + sleep.wakeTime); + expect("identity: sum(half_minutes) x 30 == end_ts - start_ts", + sleep.totalHalfMinutes() * 30 == (int) (sleep.endTs - sleep.startTs)); + expect("identity: per-stage sums match the four stage totals", + sleep.halfMinutesForStage(0) * 30 == wake + && sleep.halfMinutesForStage(1) * 30 == rem + && sleep.halfMinutesForStage(2) * 30 == light + && sleep.halfMinutesForStage(3) * 30 == deep); + expect("identitiesHold() agrees", sleep.identitiesHold()); + + expect("uncracked 6-byte field stored raw, not interpreted", + sleep.unknownPrefix.length == 6); + expect("relative timestamps kept as sent", + sleep.startTs == start && sleep.endTs == end); + + // The empty end-of-list marker must decode without inventing a session. + byte[] marker = new byte[] {0x11, 0x22, 0x02}; + RingProtocol.SleepRecord empty = + RingProtocol.decodeSleep(dataFrame(RingProtocol.CMD_HI_SLEEP, marker), 0L); + expect("RECSTATE=2 marker decodes", empty != null && !empty.isRealRecord()); + expect("marker has no segments", empty.segments.length == 0); + + // A declared segment count that does not fill the body is a parse failure. + byte[] broken = body.clone(); + broken[32] = (byte) (segments.length + 1); + expect("segment-count mismatch rejected", + RingProtocol.decodeSleep(dataFrame(RingProtocol.CMD_HI_SLEEP, broken), 0L) == null); + } + + // ------------------------------------------------------------------ + // Synthetic body builders (mirror the spec layout, used only by the tests) + // ------------------------------------------------------------------ + + private static byte[] hourlyBody(int count, long anchor, long tag, int current, + int width, int[][] groups) { + byte[] body = new byte[13 + width + count * (1 + 3 * width) + 4]; + body[0] = 0x11; + body[1] = 0x22; + body[2] = (byte) count; + writeAnchor(body, anchor); + putLe(body, 9, tag, 4); + putLe(body, 13, current, width); + int offset = 13 + width; + for (int[] g : groups) { + body[offset++] = (byte) g[0]; + putLe(body, offset, g[1], width); + offset += width; + putLe(body, offset, g[2], width); + offset += width; + putLe(body, offset, g[3], width); + offset += width; + } + putFooter(body); + return body; + } + + private static byte[] stepsBody(long anchor, int[][] buckets) { + byte[] body = new byte[9 + buckets.length * 7 + 4]; + body[0] = 0x33; + body[1] = 0x44; + body[2] = (byte) buckets.length; + writeAnchor(body, anchor); + int offset = 9; + for (int[] b : buckets) { + body[offset] = (byte) b[0]; + putLe(body, offset + 1, b[1], 2); + putLe(body, offset + 3, b[2], 2); + putLe(body, offset + 5, b[3], 2); + offset += 7; + } + putFooter(body); + return body; + } + + private static byte[] sleepBody(int recordState, long start, long end, int total, int wake, + int rem, int light, int deep, int[][] segments) { + byte[] body = new byte[34 + segments.length * 3 + 4]; + body[0] = 0x55; + body[1] = 0x66; + body[2] = (byte) recordState; + for (int i = 3; i < 9; i++) { + body[i] = (byte) (0xA0 + i); // the uncracked 6-byte field + } + putLe(body, 9, 90210L, 4); // the uncracked u32 tag + body[13] = 0x00; + putLe(body, 14, start, 4); + putLe(body, 18, end, 4); + putLe(body, 22, total, 2); + putLe(body, 24, wake, 2); + putLe(body, 26, rem, 2); + putLe(body, 28, light, 2); + putLe(body, 30, deep, 2); + body[32] = (byte) segments.length; + body[33] = 0x00; + int offset = 34; + for (int[] s : segments) { + body[offset] = (byte) s[0]; + putLe(body, offset + 1, s[1], 2); + offset += 3; + } + putFooter(body); + return body; + } + + private static void writeAnchor(byte[] body, long anchor) { + if (anchor == RingProtocol.UNKNOWN_TIME) { + return; // six zero bytes = backlog page + } + body[3] = 0x10; + body[4] = (byte) 0xFF; + putLe(body, 5, anchor, 4); + } + + private static void putFooter(byte[] body) { + int offset = body.length - 4; + body[offset] = (byte) 0x94; + body[offset + 1] = 0x33; + body[offset + 2] = 0x01; + body[offset + 3] = 0x00; + } + + private static void putLe(byte[] out, int offset, long value, int width) { + for (int i = 0; i < width; i++) { + out[offset + i] = (byte) ((value >>> (8 * i)) & 0xff); + } + } + + private static RingProtocol.Frame dataFrame(int cmdHi, byte[] body) { + byte[] frame = RingProtocol.buildFrame( + RingProtocol.CHAN_HEALTH, RingProtocol.KIND_DATA, cmdHi, + RingProtocol.CMD_LO_HEALTH, 0x20, body); + return RingProtocol.parse(frame); + } + + // ------------------------------------------------------------------ + + private static void section(String name) { + System.out.println(); + System.out.println("-- " + name); + } + + private static void expect(String what, boolean ok) { + checks++; + if (!ok) { + failures++; + } + System.out.println(" " + (ok ? "ok " : "FAIL") + " " + what); + } + + private static void expectHex(String what, String expectedHex, byte[] actual) { + String actualHex = RingProtocol.hex(actual); + boolean ok = expectedHex.equals(actualHex); + checks++; + if (!ok) { + failures++; + System.out.println(" FAIL " + what); + System.out.println(" expected " + expectedHex); + System.out.println(" actual " + actualHex); + return; + } + System.out.println(" ok " + what + " " + actualHex); + } + + private static String hex2(int value) { + return String.format(java.util.Locale.US, "%02x", value & 0xff); + } +}