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 3d731043..89df17ff 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 @@ -15,6 +15,8 @@ import android.os.SystemClock; import android.util.Log; import java.io.ByteArrayOutputStream; +import java.io.File; +import java.io.FileOutputStream; import java.io.PrintWriter; import java.io.StringWriter; import java.nio.charset.StandardCharsets; @@ -245,6 +247,8 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { private int headsetCharging = -1; private int ringBattery = -1; private int ringCharging = -1; + private int directRingBattery = -1; + private int directRingCharging = -1; // Silent mode: 1 = on, 0 = off, -1 = not yet known. See updateSilentModeLocked. private int silentMode = -1; private int wearState = -1; @@ -2052,8 +2056,23 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { return true; } + // Keep the original bytes before acknowledging them. Ring firmware + // variants can have layouts we cannot decode yet, and the ring may + // never deliver an acknowledged page again. This private journal also + // lets us diagnose a new device without repeatedly draining its data. + if (!journalRingFrame(frame)) return true; + // Route on the CHAN byte, not on the shape of the payload. if (frame.chan != RingProtocol.CHAN_HEALTH) { + RingProtocol.DeviceStatus status = RingProtocol.decodeDeviceStatus(frame); + if (status != null) { + synchronized (lock) { + directRingBattery = status.battery; + directRingCharging = status.charging; + emitBatteryState(headsetBattery, headsetCharging); + } + logLine("direct ring battery " + status.battery + "% charging=" + status.charging); + } Log.d(TAG, "ring device frame " + frame.describe()); return true; } @@ -2126,6 +2145,25 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { interruptibleSleep.interrupt(); } + private boolean journalRingFrame(RingProtocol.Frame frame) { + File folder = new File(appContext.getFilesDir(), "health"); + try { + if (!folder.isDirectory() && !folder.mkdirs()) { + throw new java.io.IOException("cannot create health folder"); + } + String line = "\n{\"receivedAtMs\":" + System.currentTimeMillis() + + ",\"raw\":\"" + hex(frame.raw) + "\"}\n"; + try (FileOutputStream out = new FileOutputStream(new File(folder, "ring-frames.jsonl"), true)) { + out.write(line.getBytes(StandardCharsets.UTF_8)); + out.getFD().sync(); + } + return true; + } catch (Exception error) { + logLine("ring frame persistence failed; page not acknowledged: " + safeMessage(error)); + return false; + } + } + private void handleRenderNotification(String address, byte[] data) { FaceclawAudioPacketListener listenerToCall; long arrivalMs = SystemClock.elapsedRealtime(); @@ -2158,6 +2196,9 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { // link; the sequence counter restarts on the next connect. ringReassembler.reset(); ringOutbound.clear(); + directRingBattery = -1; + directRingCharging = -1; + emitBatteryState(headsetBattery, headsetCharging); } logLine(connected ? "direct ring BLE connected" : "direct ring BLE disconnected"); return; @@ -2749,7 +2790,8 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { 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)), + concatBytes(le16(nonce3), + le16(TimeZone.getDefault().getOffset(nowMs) / 60000), 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, @@ -4792,6 +4834,8 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { private void resetSessionStateLocked() { ringBattery = -1; ringCharging = -1; + directRingBattery = -1; + directRingCharging = -1; sessionReady = false; shutdownRequested = false; fixedLayoutCreated = false; @@ -4952,8 +4996,11 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { } private void emitBatteryState(int headsetBattery, int headsetCharging) { - final int reportedRingBattery = ringBattery; - final int reportedRingCharging = ringCharging; + // A missing glasses-side report must not erase a verified direct + // reading. Fall back to the glasses cache when the direct link drops. + final boolean useDirect = ringConnected && directRingBattery >= 0; + final int reportedRingBattery = useDirect ? directRingBattery : ringBattery; + final int reportedRingCharging = useDirect ? directRingCharging : ringCharging; final FaceclawBleCommunicatorListener current = listener; if (current == null) { return; 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 index bea98611..04b04cfd 100644 --- 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 @@ -92,13 +92,6 @@ public final class RingProtocol { 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; @@ -489,34 +482,31 @@ public final class RingProtocol { /** * 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). + *

Layout follows openR1 r1_health_encode_daily_u8/u16 in r1_health.c: + * count, signed timezone minutes, day start, optional latest timestamp/value, + * then count groups. There is no footer. HR/SpO2 values are one byte; HRV + * values are two. Subtracting a supposed four-byte footer misdecoded a + * one-group HRV page as one-byte values and rejected real HR/SpO2 pages. */ public static HourlyRecord decodeHourly(Frame frame, long receivedAtMs) { byte[] pay = frame.payload; - if (pay.length < 13 + RECORD_FOOTER.length) { + if (pay.length < 9) { 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; + int width = frame.cmdHi == CMD_HI_HRV ? 2 : 1; + int groupBytes = count * (1 + 3 * width); + int prefixLength = pay.length - groupBytes; + boolean hasLatest = prefixLength == 13 + width; + if (count > 24 || (!hasLatest && prefixLength != 9)) return null; + long tag = hasLatest ? readUInt32Le(pay, 9) : UNKNOWN_TIME; + int current = hasLatest ? readUIntLe(pay, 13, width) : -1; + int offset = prefixLength; HourlyGroup[] groups = new HourlyGroup[count]; for (int i = 0; i < count; i++) { int hourIndex = pay[offset] & 0xff; + if (hourIndex >= 24) return null; offset++; int avg = readUIntLe(pay, offset, width); offset += width; @@ -538,11 +528,11 @@ public final class RingProtocol { */ public static StepsRecord decodeSteps(Frame frame, long receivedAtMs) { byte[] pay = frame.payload; - if (pay.length < 9 + RECORD_FOOTER.length) { + if (pay.length < 9) { return null; } int count = pay[2] & 0xff; - if (pay.length != 9 + count * 7 + RECORD_FOOTER.length) { + if (count > 144 || pay.length != 9 + count * 7) { return null; } long anchor = anchorUnixSeconds(pay); @@ -550,6 +540,7 @@ public final class RingProtocol { StepsBucket[] buckets = new StepsBucket[count]; for (int i = 0; i < count; i++) { int index = pay[offset] & 0xff; + if (index >= 144) return null; int steps = readUInt16Le(pay, offset + 1); int v2 = readUInt16Le(pay, offset + 3); int v3 = readUInt16Le(pay, offset + 5); @@ -574,12 +565,13 @@ public final class RingProtocol { 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) { + if (recordState != 1) { // 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]); } + if (pay.length < 34) return null; long startTs = readUInt32Le(pay, 14); long endTs = readUInt32Le(pay, 18); @@ -588,8 +580,8 @@ public final class RingProtocol { 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) { + int segmentCount = readUInt16Le(pay, 32); + if (pay.length != 34 + segmentCount * 3) { return null; } SleepSegment[] segments = new SleepSegment[segmentCount]; @@ -607,7 +599,7 @@ public final class RingProtocol { /** * 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. + * when the day timestamp is zero or the timezone offset is invalid. * *

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 @@ -620,10 +612,32 @@ public final class RingProtocol { 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); + // These two bytes are an int16 timezone offset, not magic. 10 ff is + // -240 minutes (EDT); Pacific time, UTC and eastern zones differ. + int timezoneMinutes = (short) readUInt16Le(payload, 3); + long anchor = readUInt32Le(payload, 5); + return timezoneMinutes >= -840 && timezoneMinutes <= 840 && anchor != 0 + ? anchor : UNKNOWN_TIME; + } + + /** Device-channel 00:01 response, matching openR1 get_device_status(). */ + public static DeviceStatus decodeDeviceStatus(Frame frame) { + if (frame == null || !frame.crcOk || frame.chan != CHAN_DEVICE + || frame.kind != KIND_RSP || frame.cmdHi != 0 || frame.cmdLo != 1 + || frame.payload.length != 9) return null; + int battery = frame.payload[2] & 0xff; + int charge = frame.payload[3] & 0xff; + if (battery > 100 || charge > 3) return null; + return new DeviceStatus(battery, charge == 0 ? -1 : charge == 2 ? 0 : 1); + } + + public static final class DeviceStatus { + public final int battery; + public final int charging; + DeviceStatus(int battery, int charging) { + this.battery = battery; + this.charging = charging; } - return UNKNOWN_TIME; } // ------------------------------------------------------------------ @@ -664,7 +678,7 @@ public final class RingProtocol { 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. */ + /** 1 byte for HR/SpO2, 2 for HRV, as defined by the metric serializer. */ public final int valueWidth; public final HourlyGroup[] groups; diff --git a/notes/ring-health-live-validation.md b/notes/ring-health-live-validation.md new file mode 100644 index 00000000..afffeb3b --- /dev/null +++ b/notes/ring-health-live-validation.md @@ -0,0 +1,57 @@ +# R1 live sync, 2026-09-17 + +Validated on the connected Pixel 7a and an R1 reporting firmware `2.0.7.0003`. + +## Connection and decoding + +Direct mode was effective. The first connection attempt timed out after 20 seconds; +the retry connected, subscribed to both notify characteristics, completed the +handshake, and received responses to all five health requests. Pairing was not the +reason health measurements were absent. + +The incoming daily records do not have the four-byte footer assumed by PR #26. +The rejected HR, SpO2 and activity frame lengths were respectively 37, 33 and 80 +bytes, matching two one-byte hourly groups, one one-byte hourly group, and eight +activity buckets without a footer. Subtracting four bytes also made a one-group +HRV page appear to contain one-byte values instead of the actual two-byte values. + +Payload bytes 3–4 are a signed timezone offset in minutes. `10 ff` is EDT's +offset of -240; it is not a magic marker. This R1 reports `5c fe`, or -420. +The handshake's timezone field now also uses the phone's actual offset. + +The corrected serializers are corroborated by the sibling openCFW checkout at +commit `fc1040f1`, particularly `r1_health_encode_daily_u8`, +`r1_health_encode_daily_u16`, `r1_activity_encode_daily`, and `r1_sleep_encode` +in `r1/src/r1_health.c`. Regression tests use synthetic records matching those +layouts rather than checking private biometric captures into the repository. + +After installing the fixes, a live sync decoded four pages and stored 31 samples +across heart rate, HRV, SpO2, steps and calories. The fixture files and marker were +removed, and `live-marker.json` was present. There was no sleep DATA page in that +sync; sleep has not been validated on this ring. + +## Battery + +Device-channel `00:01` returns seven status bytes after the two-byte prefix. +The first is battery percentage; the next is the charge-state enum. This matches +openCFW's `get_device_status` and `r1_charge_state`. The captured percentage was +85%, independently confirmed by the user in the Even app. + +Faceclaw now uses the direct status while the ring link is connected, falling +back to the glasses report on disconnect. This does not repair the separate +stock ring-to-glasses connection or its cached battery reading. + +## Remaining clock validation + +Successful decoding does not establish correct chart timestamps. This ring's +reported day anchor had nonzero hour/minute/second components; the inherited +`anchor + index * interval - clock correction` conversion produced hourly bucket +starts at `:47:44`. The relationship between that anchor, current ring time, and +the clock changes made by Faceclaw and Even remains unverified. Do not normalize +these to midnight or change the clock corrections without further evidence. + +CRC-valid frames are now retained before acknowledgement in the app-private +`files/health/ring-frames.jsonl`, with reception time and original bytes. This +preserves evidence and permits later reprocessing; it is not yet an automatic +replay/import path. The earlier rejected pages were not journaled by the old +build, and re-delivery of them is not guaranteed. diff --git a/notes/ring-protocol-selftest/RingProtocolSelfTest.java b/notes/ring-protocol-selftest/RingProtocolSelfTest.java index dc20116b..17aa7383 100644 --- a/notes/ring-protocol-selftest/RingProtocolSelfTest.java +++ b/notes/ring-protocol-selftest/RingProtocolSelfTest.java @@ -32,6 +32,8 @@ public final class RingProtocolSelfTest { testHourlyDecode(); testStepsDecode(); testSleepDecodeAndIdentities(); + testDailyWireLayouts(); + testDeviceStatus(); System.out.println(); System.out.println(failures == 0 @@ -344,12 +346,70 @@ public final class RingProtocolSelfTest { } // ------------------------------------------------------------------ - // Synthetic body builders (mirror the spec layout, used only by the tests) + private static void testDailyWireLayouts() { + section("footer-free daily layouts and timezone anchors"); + long anchor = 1789700400L; + byte[] hr = hourlyBody(2, anchor, anchor + 3600, 70, 1, + new int[][] {{0, 70, 80, 60}, {1, 72, 82, 62}}); + expect("two-hour HR frame is 37 bytes", dataFrame(1, hr).raw.length == 37); + for (int timezone : new int[] {-420, -240, 0, 330, 840}) { + putLe(hr, 3, timezone, 2); + RingProtocol.HourlyRecord decoded = RingProtocol.decodeHourly(dataFrame(1, hr), 0); + expect("anchor works at timezone " + timezone, + decoded != null && decoded.anchorUnixSeconds == anchor && decoded.groups.length == 2); + } + byte[] spo2 = hourlyBody(1, anchor, anchor, 98, 1, new int[][] {{0, 98, 99, 97}}); + expect("one-hour SpO2 frame is 33 bytes", dataFrame(2, spo2).raw.length == 33); + expect("SpO2 decodes without footer", RingProtocol.decodeHourly(dataFrame(2, spo2), 0).groups[0].avg == 98); + byte[] hrv = hourlyBody(1, anchor, anchor, 51, 2, new int[][] {{3, 51, 300, 40}}); + RingProtocol.HourlyRecord variability = RingProtocol.decodeHourly(dataFrame(4, hrv), 0); + expect("one-hour HRV retains two-byte values", variability.valueWidth == 2 + && variability.groups[0].hourIndex == 3 && variability.groups[0].max == 300); + + // Offline daily pages omit the five-byte latest-reading prefix. + byte[] offline = new byte[9 + 8]; + System.arraycopy(hr, 0, offline, 0, 9); + System.arraycopy(hr, 14, offline, 9, 8); + RingProtocol.HourlyRecord past = RingProtocol.decodeHourly(dataFrame(1, offline), 0); + expect("daily page without latest sample decodes", past != null + && past.current == -1 && past.groups[1].avg == 72); + putLe(offline, 5, 0, 4); + expect("zero day remains unresolved", RingProtocol.anchorUnixSeconds(offline) == RingProtocol.UNKNOWN_TIME); + + int[][] buckets = new int[8][4]; + for (int i = 0; i < buckets.length; i++) buckets[i] = new int[] {i, i * 10, 1, 2}; + byte[] activity = stepsBody(anchor, buckets); + expect("eight-bucket activity frame is 80 bytes", dataFrame(5, activity).raw.length == 80); + expect("activity decodes without footer", RingProtocol.decodeSteps(dataFrame(5, activity), 0).buckets.length == 8); + expect("trailing garbage rejected", RingProtocol.decodeSteps(dataFrame(5, + Arrays.copyOf(activity, activity.length + 4)), 0) == null); + } + + private static void testDeviceStatus() { + section("direct device status battery"); + byte[] payload = {0x11, 0x22, 82, 2, 1, 0, 0, 0, 0}; + for (int charge = 0; charge <= 3; charge++) { + payload[3] = (byte) charge; + RingProtocol.Frame frame = RingProtocol.parse(RingProtocol.buildFrame( + RingProtocol.CHAN_DEVICE, RingProtocol.KIND_RSP, 0, 1, 1, payload)); + RingProtocol.DeviceStatus status = RingProtocol.decodeDeviceStatus(frame); + expect("battery and charge enum " + charge, status != null && status.battery == 82 + && status.charging == (charge == 0 ? -1 : charge == 2 ? 0 : 1)); + } + payload[2] = (byte) 255; + expect("invalid battery rejected", RingProtocol.decodeDeviceStatus(RingProtocol.parse( + RingProtocol.buildFrame(1, 3, 0, 1, 1, payload))) == null); + expect("wrong channel rejected", RingProtocol.decodeDeviceStatus(dataFrame(1, payload)) == null); + expect("short response rejected", RingProtocol.decodeDeviceStatus(RingProtocol.parse( + RingProtocol.buildFrame(1, 3, 0, 1, 1, new byte[2]))) == null); + } + + // Synthetic body builders matching the recovered R1 serializers. // ------------------------------------------------------------------ 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]; + byte[] body = new byte[13 + width + count * (1 + 3 * width)]; body[0] = 0x11; body[1] = 0x22; body[2] = (byte) count; @@ -366,12 +426,11 @@ public final class RingProtocolSelfTest { 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]; + byte[] body = new byte[9 + buckets.length * 7]; body[0] = 0x33; body[1] = 0x44; body[2] = (byte) buckets.length; @@ -384,13 +443,12 @@ public final class RingProtocolSelfTest { 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]; + byte[] body = new byte[34 + segments.length * 3]; body[0] = 0x55; body[1] = 0x66; body[2] = (byte) recordState; @@ -414,7 +472,6 @@ public final class RingProtocolSelfTest { putLe(body, offset + 1, s[1], 2); offset += 3; } - putFooter(body); return body; } @@ -427,14 +484,6 @@ public final class RingProtocolSelfTest { 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);