R1 ring: Debug health-data sync

This commit is contained in:
James Babcock committed 2026-11-01 12:19:46 -08:00
1 parent fcea0b369a
commit 7289496c09
14 files changed
+705 -194

No files matched your search

@@ -107,6 +107,20 @@ class RingProtocol private constructor() {
/** Returned by anchor/timestamp accessors when the value is not known. */
const val UNKNOWN_TIME: Long = -1L
/**
* Bytes R1 firmware 2.3.x appends to every health DATA page, after the
* last group/bucket. Seen on 2.3.0.0005 and 2.3.2.0008: every one of
* the 30 hourly and activity pages journaled 2026-10-06..11-01 carries
* it (values `6e050000`, `00000000`, `ad5e0000`; meaning unknown).
* Firmware 2.0.7.0003 sent none (notes/ring-health-live-validation.md),
* so the decoders accept a page with or without it. The group or
* bucket count is explicit, so the two lengths cannot be confused.
*/
const val HEALTH_PAGE_TRAILER_LEN: Int = 4
private val JOURNAL_RECEIVED_AT = Regex("\"receivedAtMs\":(\\d+)")
private val JOURNAL_RAW = Regex("\"raw\":\"([0-9a-fA-F]+)\"")
private val EMPTY = ByteArray(0)
// ------------------------------------------------------------------
@@ -432,14 +446,42 @@ class RingProtocol private constructor() {
}
}
/**
* Decode the health DATA pages in a ring frame journal - the JSON lines
* `{"receivedAtMs":N,"raw":"<hex>"}` the session writes before
* acknowledging each frame - received after [afterReceivedAtMs], in
* file order. Anything that is not a decodable health DATA page is
* skipped. Lets pages the ring will never send again (it counts an
* acknowledged page as synced) be stored after a decoder fix.
*/
@JvmStatic
fun decodeFrameJournal(text: String, afterReceivedAtMs: Long): List<HealthRecord> {
val records = ArrayList<HealthRecord>()
for (line in text.lineSequence()) {
val receivedAtMs = JOURNAL_RECEIVED_AT.find(line)?.groupValues?.get(1)?.toLongOrNull() ?: continue
if (receivedAtMs <= afterReceivedAtMs) continue
val raw = JOURNAL_RAW.find(line)?.groupValues?.get(1) ?: continue
if (raw.length % 2 != 0) continue
val bytes = ByteArray(raw.length / 2) { raw.substring(it * 2, it * 2 + 2).toInt(16).toByte() }
val record = try {
decode(parse(bytes), receivedAtMs)
} catch (_: Throwable) {
null
} ?: continue
records.add(record)
}
return records
}
/**
* Heart rate / SpO2 / HRV: an hourly `[index][avg][max][min]` series.
*
* 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.
* then count groups, then (firmware 2.3.x only) [HEALTH_PAGE_TRAILER_LEN]
* trailing bytes. HR/SpO2 values are one byte; HRV values are two; the
* width comes from the command, never from the length, which is what
* once misdecoded a one-group HRV page as one-byte values.
*/
@JvmStatic
fun decodeHourly(frame: Frame, receivedAtMs: Long): HourlyRecord? {
@@ -451,7 +493,11 @@ class RingProtocol private constructor() {
val anchor = anchorUnixSeconds(pay)
val width = if (frame.cmdHi == CMD_HI_HRV) 2 else 1
val groupBytes = count * (1 + 3 * width)
val prefixLength = pay.size - groupBytes
val nonGroupBytes = pay.size - groupBytes
// 9 or 13+width without the trailer; 13 or 17+width with it. All distinct.
val trailer = if (nonGroupBytes == 9 + HEALTH_PAGE_TRAILER_LEN
|| nonGroupBytes == 13 + width + HEALTH_PAGE_TRAILER_LEN) HEALTH_PAGE_TRAILER_LEN else 0
val prefixLength = nonGroupBytes - trailer
val hasLatest = prefixLength == 13 + width
if (count > 24 || (!hasLatest && prefixLength != 9)) return null
val tag = if (hasLatest) readUInt32Le(pay, 9) else UNKNOWN_TIME
@@ -488,7 +534,8 @@ class RingProtocol private constructor() {
return null
}
val count = pay[2].toInt() and 0xff
if (count > 144 || pay.size != 9 + count * 7) {
val bucketsEnd = 9 + count * 7
if (count > 144 || (pay.size != bucketsEnd && pay.size != bucketsEnd + HEALTH_PAGE_TRAILER_LEN)) {
return null
}
val anchor = anchorUnixSeconds(pay)
@@ -539,7 +586,10 @@ class RingProtocol private constructor() {
val lightTime = readUInt16Le(pay, 28)
val deepTime = readUInt16Le(pay, 30)
val segmentCount = readUInt16Le(pay, 32)
if (pay.size != 34 + segmentCount * 3) {
// The 2.3.x trailer is assumed here too: no sleep DATA page has been
// seen from that firmware yet.
val segmentsEnd = 34 + segmentCount * 3
if (pay.size != segmentsEnd && pay.size != segmentsEnd + HEALTH_PAGE_TRAILER_LEN) {
return null
}
var offset = 34
@@ -226,6 +226,18 @@ class GlassesSessionCore(
* sequence. Guarded by `monitor`. See RING_HEALTH_ABORTED_RETRY_LIMIT.
*/
internal var ringHealthAbortedRetries = 0
/**
* Direct mode (configured role "glasses") only: the direct link has been
* handed to the phone role for one health pull, and returns to the glasses
* role when that pull ends, or at [ringHealthWindowDeadlineMs] if the
* phone-role link never comes up. See beginRingHealthWindowLocked.
* Guarded by `monitor`.
*/
internal var ringHealthWindowActive = false
internal var ringHealthWindowDeadlineMs = 0L
/** Outcome of the last health pull, for the Ring status page. Guarded by `monitor`. */
internal var lastRingHealthPullResult = ""
internal var lastRingHealthPullAtMs = 0L
/**
* Timeout waiting for a health REQ's own RSP. In the reference capture
* (a real successful Even sync) RSPs land within ~150ms; this only needs
@@ -1021,6 +1033,10 @@ class GlassesSessionCore(
status["lastCommandResultR"] = lastRingLinkResultR
status["lastCommandResultL"] = lastRingLinkResultL
status["directRole"] = directRingRole
status["healthWindowActive"] = ringHealthWindowActive
status["lastHealthPull"] = lastRingHealthPullResult
status["lastHealthPullAgeMs"] = age(lastRingHealthPullAtMs)
status["heldHealthRecords"] = ringHealthRecords.size
status["directGlassesAuth"] = directGlassesAuth
status["directGlassesAuthAgeMs"] = age(directGlassesAuthAtMs)
status["lastRingCommand"] = lastRingConfigCommand
@@ -1040,8 +1056,10 @@ class GlassesSessionCore(
* with only the data CCCD, like Even's app. The glasses keep the ring.
* - "glasses": act as the ring's glasses (legacy CCCD, legacy pair-auth,
* touch source on; see runRingGlassesSetup) and take the ring over from
* the glasses when they still hold it. No health sync: the ring answers
* system requests only on a phone-role link.
* the glasses when they still hold it. The ring answers system requests
* (health included) only on a phone-role link, so each health pull
* briefly reconnects the link in the phone role and then returns it
* (see beginRingHealthWindowLocked).
* Asking for both on one link (the old behavior) made the ring drop the
* link every ~6 s while the glasses held it. A change while the direct
* link is up reconnects it.
@@ -1051,6 +1069,8 @@ class GlassesSessionCore(
monitor.withLock {
if (normalized == directRingRole) return
directRingRole = normalized
// A health window only exists to borrow the phone role from the glasses role.
ringHealthWindowActive = false
if (ringConnected || ringNotificationsReady) {
ringRoleReconnectPending = true
monitor.signalAll()
@@ -2406,7 +2426,11 @@ class GlassesSessionCore(
// service events 6/7), and the ring sends gestures (00 09 61 00 ...)
// only to that role. The direct ring
// role setting decides which CCCDs we enable; see setDirectRingRole.
val role = monitor.withLock { directRingRole }
val configuredRole: String
val role = monitor.withLock {
configuredRole = directRingRole
effectiveRingRoleLocked()
}
val legacyNotify = role == DIRECT_RING_ROLE_GLASSES
&& enableRingNotification(BleProtocol.R1_LEGACY_NOTIFY_CHAR_UUID)
val dataNotify = enableRingNotification(BleProtocol.R1_NOTIFY_CHAR_UUID)
@@ -2433,10 +2457,13 @@ class GlassesSessionCore(
directGlassesAuthAtMs = 0L
directGlassesAuthRetried = false
}
logLine("direct ring ready role=$role legacyNotify=$legacyNotify dataNotify=$dataNotify")
logLine("direct ring ready role=$role legacyNotify=$legacyNotify dataNotify=$dataNotify"
+ (if (role != configuredRole) " (health window; configured role $configuredRole)" else ""))
// The glasses role means no pairAuth (it would ask for the phone role
// on the same link) and therefore no health sync.
// on the same link) and therefore no health sync. Direct mode gets its
// health through a temporary phone-role connection instead (see
// beginRingHealthWindowLocked), which takes this branch.
if (dataNotify && host.supportsRingHealth() && role == DIRECT_RING_ROLE_PHONE) {
onRingDataChannelReady()
}
@@ -87,6 +87,39 @@ private const val RING_HEALTH_ABORTED_RETRY_LIMIT = 2
*/
private const val RING_HEALTH_ABORTED_RETRY_GAP_MS = 60L * 1000L
/**
* Direct mode: floor between health windows (see beginRingHealthWindowLocked).
* A window costs the user ring gestures for the length of two reconnects and a
* pull, so opening and closing the Health app must not keep bouncing the link.
* The aligned :01/:31 pulls are well outside it.
*/
private const val RING_HEALTH_WINDOW_MIN_INTERVAL_MS = 5L * 60L * 1000L
/**
* Direct mode: how long a health window waits for its phone-role link to be
* up before giving up and handing the link back to the glasses role. Bounds
* only the connect; a pull that has started runs to completion on the ring
* worker before the deadline is looked at again.
*/
private const val RING_HEALTH_WINDOW_CONNECT_TIMEOUT_MS = 60_000L
/**
* Direct mode: a requested health window waits until the ring has been idle
* this long, so it does not take the ring away in the middle of a gesture
* sequence. The request stays pending meanwhile.
*/
private const val RING_HEALTH_WINDOW_INPUT_IDLE_MS = 5_000L
/**
* Pause between dropping the direct link and reconnecting it in another role.
* The ring frees a role when the connection ends, but Android keeps the LE
* link up for a moment after the last client closes, and a new client
* registered in that moment reuses it - the ring would then see the old
* role's handle ask for the other role, which stock firmware treats as a
* fatal assertion (openCFW CONNECTION-ROLE-ASSIGNMENT-CORRELATION.md).
*/
private const val RING_ROLE_SWITCH_SETTLE_MS = 3_000L
/** First pause after a failed ring write; doubles per consecutive failure. See [writeRingFrame]. */
private const val RING_WRITE_BACKOFF_MS = 1_000L
private const val RING_WRITE_BACKOFF_MAX_MS = 15_000L
@@ -130,6 +163,7 @@ class RingHealthBatch internal constructor(
internal fun GlassesSessionCore.runRingWorker() {
while (running) {
try {
expireRingHealthWindow()
restartRingLinkForRoleChange()
if (shouldAttemptRingConnect()) tryConnectRing("ring worker")
if (!running) break
@@ -314,27 +348,143 @@ internal fun GlassesSessionCore.journalRingFrame(frame: RingProtocol.Frame): Boo
* Ring worker only (blocking).
*/
internal fun GlassesSessionCore.onRingDataChannelReady() {
// 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()
val now = now()
val dueForHealthPull: Boolean
val lastRequestedAtMs: Long
monitor.withLock {
lastRequestedAtMs = ringHealthLastRequestedAtMs
dueForHealthPull = ringHealthPullDueLocked(now)
if (dueForHealthPull) {
ringHealthLastRequestedAtMs = now
try {
// 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()
val now = now()
val dueForHealthPull: Boolean
val lastRequestedAtMs: Long
monitor.withLock {
lastRequestedAtMs = ringHealthLastRequestedAtMs
// A health window was opened for exactly this pull, and its own
// floor was applied when it opened.
dueForHealthPull = ringHealthWindowActive || ringHealthPullDueLocked(now)
if (dueForHealthPull) {
ringHealthLastRequestedAtMs = now
}
}
if (dueForHealthPull) {
runRingHealthPull()
} else {
logLine("ring health: pull skipped, last one was " + ((now - lastRequestedAtMs) / 1000) + "s ago")
}
} finally {
// Completed, aborted or threw: either way the link goes back to the
// glasses role, so a failed pull never costs the user gestures for
// longer than the attempt.
monitor.withLock { endRingHealthWindowLocked("pull finished") }
}
if (dueForHealthPull) {
runRingHealthPull()
} else {
logLine("ring health: pull skipped, last one was " + ((now - lastRequestedAtMs) / 1000) + "s ago")
}
/**
* The direct link's role for its next setup: the configured one, except the
* phone role while a health window is open. Caller holds `monitor`.
*/
internal fun GlassesSessionCore.effectiveRingRoleLocked(): String =
if (ringHealthWindowActive) DIRECT_RING_ROLE_PHONE else directRingRole
/**
* Direct mode's health sync. Caller holds `monitor`.
*
* In Direct mode the direct link holds the ring's glasses role (gestures,
* battery), and the ring answers system requests - health included - only to
* its phone role. One link cannot hold both: the stock role setter treats the
* same connection asking for the second role as a fatal assertion, and live
* "both" links died every ~6 s (notes/ring-link-control.md). So a pull borrows
* the phone role: drop the link, reconnect it with only the data CCCD (the
* health-mode setup, which runs the handshake and the pull), then drop it
* again and reconnect in the glasses role. Ring gestures stop for that long,
* typically well under a minute; the glasses' own touch input is unaffected.
*
* Every exit returns the link to the glasses role: the pull finishing
* ([onRingDataChannelReady]), the connect deadline ([expireRingHealthWindow]),
* or a role change ([GlassesSessionCore.setDirectRingRole]).
*
* Not yet hardware-tested: whether the ring restores the bonded peer's legacy
* CCCD on the phone-role reconnect and assigns the glasses role from it. If it
* does, the phone-role pairAuth would be refused or the link dropped, the pull
* would abort, and the window would close; look for "health window" in the log.
*/
internal fun GlassesSessionCore.beginRingHealthWindowLocked(now: Long, reason: String) {
ringHealthWindowActive = true
ringHealthWindowDeadlineMs = now + RING_HEALTH_WINDOW_CONNECT_TIMEOUT_MS
// Counts as the attempt for the window floor whether or not it succeeds,
// so a ring that never comes up in the phone role is retried at most
// once per floor.
ringHealthLastRequestedAtMs = now
// A link already set up in the glasses role has to be dropped. One that
// is still connecting sets up in the phone role when it lands.
if (ringNotificationsReady) {
ringRoleReconnectPending = true
}
monitor.signalAll()
logLine("ring health: opening a health window ($reason): direct link to the phone role for one pull")
}
/** Close a health window and put the link back in the glasses role. Caller holds `monitor`. */
internal fun GlassesSessionCore.endRingHealthWindowLocked(reason: String) {
if (!ringHealthWindowActive) return
ringHealthWindowActive = false
ringHealthWindowDeadlineMs = 0L
// Only a link that finished its phone-role setup has to be dropped; one
// still connecting picks up the glasses role when it sets up.
if (directRingRole == DIRECT_RING_ROLE_GLASSES && ringNotificationsReady) {
ringRoleReconnectPending = true
}
monitor.signalAll()
logLine("ring health: closing the health window ($reason); direct link back to the glasses role")
}
/** Ring-worker tick: give up on a health window whose phone-role link never came up. */
internal fun GlassesSessionCore.expireRingHealthWindow() {
monitor.withLock {
if (!ringHealthWindowActive || now() < ringHealthWindowDeadlineMs) return
lastRingHealthPullResult = "not run: phone-role link did not come up"
lastRingHealthPullAtMs = now()
endRingHealthWindowLocked("phone-role link not up after "
+ (RING_HEALTH_WINDOW_CONNECT_TIMEOUT_MS / 1000L) + "s")
}
}
/**
* Direct mode's on-demand pull: open a health window for an explicit request
* (Health app opened, aligned :01/:31 tick), and once per session without one
* so the first pull does not wait for the next aligned tick. Ring worker only.
*/
private fun GlassesSessionCore.startRequestedRingHealthWindow() {
val now = now()
monitor.withLock {
if (!host.supportsRingHealth()) {
ringHealthPullRequested = false
return
}
if (ringHealthWindowActive) {
// The open window pulls as soon as its link is up.
ringHealthPullRequested = false
return
}
val firstThisSession = ringHealthLastRequestedAtMs == 0L
if (!ringHealthPullRequested && !firstThisSession) return
// The ring is only dialed once the glasses session is up
// (shouldAttemptRingConnect); opening sooner would spend the
// window's connect deadline waiting on the glasses.
if (!running || !sessionReady) return
if (!firstThisSession && now - ringHealthLastRequestedAtMs < RING_HEALTH_WINDOW_MIN_INTERVAL_MS) {
ringHealthPullRequested = false
logLine("ring health: health window skipped, last pull attempt was "
+ ((now - ringHealthLastRequestedAtMs) / 1000) + "s ago")
return
}
if (lastDirectRingInputAtMs != 0L && now - lastDirectRingInputAtMs < RING_HEALTH_WINDOW_INPUT_IDLE_MS) {
return // the ring is in use; try again on a later tick
}
ringHealthPullRequested = false
beginRingHealthWindowLocked(now, if (firstThisSession) "first pull this session" else "requested")
}
}
@@ -362,8 +512,12 @@ internal fun GlassesSessionCore.ringHealthPullDueLocked(now: Long): Boolean {
* definition of "aborted".
*/
internal fun GlassesSessionCore.runRingHealthPull() {
val pagesBefore = monitor.withLock { ringHealthPageCounter }
val completed = requestRingHealth()
monitor.withLock {
val pages = ringHealthPageCounter - pagesBefore
lastRingHealthPullResult = (if (completed) "completed" else "aborted") + ", $pages pages"
lastRingHealthPullAtMs = now()
if (completed) {
ringHealthAbortedRetries = 0
} else if (ringHealthAbortedRetries < RING_HEALTH_ABORTED_RETRY_LIMIT) {
@@ -393,6 +547,8 @@ internal fun GlassesSessionCore.resumeAbortedRingHealthPull() {
if (ringHealthAbortedRetries == 0) {
return
}
// Direct mode does not resume here: a retry would mean another pair
// of role switches, so the next requested or aligned window retries.
if (!ringConnected || !ringNotificationsReady || directRingRole == DIRECT_RING_ROLE_GLASSES) {
return
}
@@ -407,6 +563,12 @@ internal fun GlassesSessionCore.resumeAbortedRingHealthPull() {
/** Ring-worker side of [GlassesSessionCore.requestRingHealthNow]. */
internal fun GlassesSessionCore.runRequestedRingHealthPull() {
if (monitor.withLock { directRingRole == DIRECT_RING_ROLE_GLASSES }) {
// Direct mode used to drop every request here, so the Health app
// never got data; the pull has to borrow the phone role instead.
startRequestedRingHealthWindow()
return
}
val now = now()
monitor.withLock {
if (!ringHealthPullRequested) {
@@ -417,10 +579,6 @@ internal fun GlassesSessionCore.runRequestedRingHealthPull() {
logLine("ring health: on-demand pull skipped, ring not ready")
return
}
if (directRingRole == DIRECT_RING_ROLE_GLASSES) {
logLine("ring health: on-demand pull skipped, direct link holds the glasses role")
return
}
if (ringHealthLastRequestedAtMs != 0L
&& now - ringHealthLastRequestedAtMs < RING_HEALTH_ON_DEMAND_MIN_INTERVAL_MS) {
logLine("ring health: on-demand pull skipped, last one was "
@@ -1033,17 +1191,22 @@ internal fun GlassesSessionCore.recordRingConfigResponse(frame: RingProtocol.Fra
logLine("ring command $label answered: $result " + frame.describe())
}
/** Apply a [GlassesSessionCore.setDirectRingRole] change by reconnecting the direct link. Ring worker only. */
/**
* Apply a role change (a [GlassesSessionCore.setDirectRingRole] change, or a
* health window opening or closing) by reconnecting the direct link. Ring
* worker only.
*/
internal fun GlassesSessionCore.restartRingLinkForRoleChange() {
val role = monitor.withLock {
if (!ringRoleReconnectPending) return
ringRoleReconnectPending = false
ringConnected = false
ringNotificationsReady = false
ringReconnectAfterMs = 0
// Let the old connection end before dialing again; see RING_ROLE_SWITCH_SETTLE_MS.
ringReconnectAfterMs = now() + RING_ROLE_SWITCH_SETTLE_MS
ringOutbound.clear()
dropRingConfigCommandsLocked("role change")
directRingRole
effectiveRingRoleLocked()
}
logLine("direct ring: reconnecting to take the $role role")
link.disconnect(ringAddress)