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: + *

+ * + *

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); + } +}