Decode R1 daily health pages and direct battery status

This commit is contained in:
James Babcock committed 2026-09-17 20:58:35 -07:00
1 parent 41ff1f1a8e
commit 7677dd254e
4 files changed
+220 -53

No files matched your search

@@ -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;
@@ -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.
*
* <p>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).
* <p>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.
*
* <p><b>UNSOLVED:</b> 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;
+57
View File
@@ -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.
@@ -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);