Merge branch 'main' of https://github.com/jimrandomh/faceclaw into ring-health-fixes

This commit is contained in:
James Babcock committed 2026-11-01 11:00:38 -08:00
commit fcea0b369a
218 files changed
+14438 -2259

No files matched your search

@@ -1,70 +0,0 @@
package com.faceclaw.app
/** Shared on-disk settings format. Native adapters own locking and atomic IO. */
class SettingsDocument private constructor(private val settings: Map<String, Any?>) {
fun containsString(key: String, value: String): Boolean = settings[key] == structuredValue(key, value)
fun getString(key: String, fallback: String): String = when (val value = settings[key]) {
is String -> value
is Map<*, *>, is List<*> -> Json.write(value)
else -> fallback
}
fun getBoolean(key: String, fallback: Boolean): Boolean = settings[key] as? Boolean ?: fallback
fun getNumber(key: String, fallback: Double): Double = (settings[key] as? JsonNumber)?.text?.toDoubleOrNull() ?: fallback
fun replacingNumber(key: String, value: Double): SettingsDocument =
SettingsDocument(settings + (key to JsonNumber(value.toString())))
fun removing(key: String): SettingsDocument = SettingsDocument(settings - key)
fun replacingString(key: String, value: String): SettingsDocument =
SettingsDocument(settings + (key to structuredValue(key, value)))
fun replacingBoolean(key: String, value: Boolean): SettingsDocument = SettingsDocument(settings + (key to value))
fun merged(other: SettingsDocument): SettingsDocument = SettingsDocument(settings + other.settings)
fun encode(): String = Json.write(mapOf("schema" to JsonNumber(CURRENT_SCHEMA.toString()), "settings" to settings), pretty = true) + "\n"
// A mutation/merge must never commit a document that the next launch rejects.
fun encodeForStorage(): String? {
val text = encode()
return if (runCatching { decode(text) }.isSuccess) text else null
}
companion object {
const val CURRENT_SCHEMA = 2
// Explicit keys avoid interpreting arbitrary text (prompts, passwords, drafts) as JSON.
private val structuredKeys = setOf(
"terminal.connections", "teleprompter.recents", "launcher.folders", "notifications.sources",
"files.bookmarks", "music.apps", "microphones.array-config", "display.uiFont2", "terminal.font",
"navigate.savedDestinations", "navigate.recentDestinations", "evenhub.installedApps.v1", "timers.state", "assistant.conversations"
)
private fun structuredValue(key: String, value: Any?): Any? {
if ((key !in structuredKeys && !key.startsWith("ios.ble.peripheral.")) || value !is String) return value
// Preserve empty/invalid old values: callers already provide their own fallback.
val parsed = runCatching { Json.parse(value) }.getOrNull()
return if (parsed is Map<*, *> || parsed is List<*>) parsed else value
}
// Each entry migrates version N to N+1. Never rewrite unknown future schemas.
private val migrations: Map<Int, (Map<String, Any?>) -> Map<String, Any?>> = mapOf(
1 to { old -> old.mapValues { (key, value) -> structuredValue(key, value) } }
)
internal fun decode(text: String): SettingsDocument {
require(text.encodeToByteArray().size <= 2 * 1024 * 1024) { "Config exceeds 2 MiB" }
val root = Json.parse(text) as? Map<*, *> ?: error("Expected config object")
var schema = (root["schema"] as? JsonNumber)?.text?.toIntOrNull() ?: error("Missing schema")
require(schema in 1..CURRENT_SCHEMA) { "Unsupported settings schema" }
val raw = root["settings"] as? Map<*, *> ?: error("Missing settings")
require(raw.size <= 4096)
var values: Map<String, Any?> = raw.entries.associate { (key, value) ->
require(key is String && key.isNotEmpty() && key.length <= 512)
require(value != null) { "Null setting" }
key to value
}
while (schema < CURRENT_SCHEMA) values = migrations.getValue(schema++)(values)
return SettingsDocument(values)
}
}
}
/** Nullable decode keeps invalid files recoverable across Objective-C/JVM bridges. */
class SettingsCodec {
fun needsMigration(text: String): Boolean = runCatching {
((Json.parse(text) as Map<*, *>)["schema"] as JsonNumber).text != SettingsDocument.CURRENT_SCHEMA.toString()
}.getOrDefault(false)
fun decode(text: String): SettingsDocument? = runCatching { SettingsDocument.decode(text) }.getOrNull()
}
@@ -0,0 +1,9 @@
package com.faceclaw.app
interface FaceclawWebSignInListener {
/**
* The sign-in ended: the redirect URL (query included), or null with why
* not ("cancelled" when it was cancelled or replaced by another sign-in).
*/
fun onFinished(redirectUrl: String?, error: String?): Unit
}
@@ -208,6 +208,9 @@ class BleProtocol {
/** CFW's SysEvent for an R1 wire type it has no mapping for; diagnostics only. */
const val EVENT_RING_UNKNOWN: Int = 127
/** Faceclaw/38: IMU head-down (the head returning after a lift), forwarded while a page is up. */
const val EVENT_HEAD_DOWN: Int = 15
const val EVENT_SOURCE_GLASSES_R: Int = 1
const val EVENT_SOURCE_RING: Int = 2
@@ -1141,6 +1141,8 @@ class GlassesSessionCore(
status["payloadBytesAcked"] = benchmarkPayloadBytesAcked
status["wireBytesAcked"] = benchmarkWireBytesAcked
status["aborted"] = benchmarkAborted
status["leftPhy"] = link.describePhy(leftAddress)
status["rightPhy"] = link.describePhy(rightAddress)
return Json.write(status)
} catch (e: Exception) {
return "{\"state\":\"idle\"}"
@@ -1940,6 +1942,14 @@ class GlassesSessionCore(
// deferred head-up wake produces from a dark display.
decoded = G2Event("display-wake", "", BleProtocol.EVENT_HEAD_UP, decoded.eventSource, 0)
logLine("head-up forwarded by CFW while page on screen")
} else if (decoded != null
&& "sys-event" == decoded.kind
&& decoded.eventType == BleProtocol.EVENT_HEAD_DOWN) {
// Faceclaw/38 also forwards the head coming back down. Nothing
// uses it yet; as an unknown input it would count as activity
// and keep the screen awake, so drop it here.
logLine("head-down forwarded by CFW (ignored)")
decoded = null
}
event = decoded
if (decoded != null) {
@@ -2285,6 +2295,10 @@ class GlassesSessionCore(
if (enableRenderNotify) {
link.enableNotifications(address, BleProtocol.RENDER_NOTIFY_UUID, true, ConnectionOptions.DESCRIPTOR_TIMEOUT_MS)
}
// The connectGatt PHY preference only covers the connection's establishment, so every
// connection comes up on 1M and has to ask for 2M (which the CFW enables). Asked last,
// once the stack has the glasses' feature bits; the link keeps retrying on its own.
link.requestLe2mPhy(address)
monitor.withLock {
if (address.equals(rightAddress, ignoreCase = true)) {
rightConnected = true
@@ -36,6 +36,15 @@ interface SessionLink {
/** Best effort; no completion point (see connectArm). */
fun requestHighPriority(address: String)
/**
* Get the link onto the LE 2M PHY, re-asking in the background until it lands; returns
* without waiting. A no-op where the OS negotiates the PHY itself (CoreBluetooth).
*/
fun requestLe2mPhy(address: String) {}
/** The link's current PHY for diagnostics ("2M", "1M", ...), or null when unknown. */
fun describePhy(address: String): String? = null
fun requestMtu(address: String, mtu: Int, timeoutMs: Int): Boolean
fun negotiatedMtu(address: String): Int
@@ -91,6 +91,63 @@ object GrayPacket {
return best >= BACKGROUND_MIN_SHARE * count && bestStart + BACKGROUND_SPAN / 2 >= LIGHT_BACKGROUND_MIN_GRAY
}
/** Pixels at least this opaque count as drawn, for inkBounds. */
private const val INK_MIN_ALPHA = 16
/**
* The bounds of what translucent artwork draws (pixels at least INK_MIN_ALPHA opaque), as
* [left, top, right, bottom] with right and bottom exclusive; null when nothing is drawn.
* Used to trim a rendered layout's empty margins.
*/
@JvmStatic
fun inkBounds(pixels: IntArray, width: Int, height: Int): IntArray? {
var left = width
var top = height
var right = 0
var bottom = 0
for (y in 0 until height) {
val row = y * width
for (x in 0 until width) {
if (alpha(pixels[row + x]) >= INK_MIN_ALPHA) {
if (x < left) left = x
if (x >= right) right = x + 1
if (y < top) top = y
bottom = y + 1
}
}
}
return if (right > left && bottom > top) intArrayOf(left, top, right, bottom) else null
}
/**
* Turns dark ink light, in place, for translucent artwork drawn with no background of its
* own (a notification's custom layout): returns whether it did. Ink whose average gray,
* weighted by alpha, is below mid-gray was drawn for a light background, like Dexcom's
* dark-gray text for a light-theme shade, and would vanish against the glasses' black;
* inverting its colors (not its alpha) shows it as it would look on white, as a negative.
* That is what invertLightBackground would make of the artwork composited on white, but
* it doesn't depend on the background covering enough of the picture to be detected.
*/
@JvmStatic
fun lightenDarkInk(pixels: IntArray, width: Int, height: Int): Boolean {
val count = width * height
var weight = 0L
var sum = 0L
for (i in 0 until count) {
val p = pixels[i]
val a = alpha(p)
weight += a
sum += luma(p).toLong() * a
}
if (weight == 0L || sum * 2 >= weight * 255) {
return false
}
for (i in 0 until count) {
pixels[i] = pixels[i] xor 0x00ffffff
}
return true
}
private fun luma(p: Int): Int {
val r = (p shr 16) and 0xff
val g = (p shr 8) and 0xff
@@ -0,0 +1,179 @@
package com.faceclaw.app
/**
* What an import will store: the values to merge into the phone's settings, plus the
* platform-local keys left out because the document was exported on another platform.
*/
class SettingsImportPlan internal constructor(
/** String, Boolean or JsonNumber. Objects/arrays in the document arrive as compact JSON strings. */
val values: Map<String, Any>,
val skipped: List<String>,
/** The platform that exported the document, or null when it doesn't say. */
val sourcePlatform: String?,
)
/**
* The settings export/import document shared by Android and iOS (scripts/config-transfer.md).
* Only the transfer format is shared: each platform keeps storing settings natively
* (SharedPreferences / NSUserDefaults), and its config port converts with this codec.
*
* ```
* {
* "schema": 2,
* "platform": "android", // the exporting platform
* "appVersion": "0.8.3", // informational
* "settings": { ... }, // imported on any platform
* "platformSettings": { ... } // imported only when "platform" matches the importer
* }
* ```
*
* Values are strings, booleans and numbers, as stored. A string holding a JSON object or array
* is written as that object/array when doing so is lossless (re-serializing it reproduces the
* stored text exactly), so structured settings are readable and editable; any object/array value
* is stored back as its compact JSON text. No setting is stored as a native object, so this never
* changes a setting's type.
*
* Schema 1 (flat `settings`, strings only; written by older iOS builds and by the scripts'
* conversion of Android shared-preferences XML) is still accepted: its keys are classified with
* [isPlatformLocal] at import time instead.
*/
object SettingsTransfer {
private const val SCHEMA = 2
private const val MAX_BYTES = 2 * 1024 * 1024
private const val MAX_ENTRIES = 4096
private const val MAX_KEY_CHARS = 512
/** Bookkeeping that is never exported or imported. */
private val internalKeys = setOf("ios.settings.changeToken")
// Platform-local: values that would be wrong, or would clobber something correct, on another
// phone. Everything else is portable, including settings only one platform currently uses,
// so that they survive an Android -> iOS -> Android round trip. Enum values a platform doesn't
// offer need no entry here: each setting falls back to its default when read.
private val platformLocalPrefixes = listOf(
"ios.", "android.", // platform internals, e.g. CoreBluetooth peripheral identifiers
"deviceAddress.", "deviceIdentity.", // glasses and ring paired with this phone (bonds are per phone)
"onboarding.", // whether this phone has been set up: pairing, permissions, firmware
)
private val platformLocalKeys = setOf(
"notifications.sources", // Android package names vs iOS bundle identifiers
"music.apps", "music.lastApp", // Android media-browser packages
"files.bookmarks", "teleprompter.recents", // paths in this phone's storage
"evenhub.installedApps.v1", // packages unpacked into this phone's storage
"integrations.evenhub.terminalId", "integrations.evenhub.openUdid", // per-phone EvenHub device IDs
)
fun isPlatformLocal(key: String): Boolean =
key in platformLocalKeys || platformLocalPrefixes.any { key.startsWith(it) }
/**
* Encode a phone's settings as a document. [values] holds String, Boolean and numeric
* (JsonNumber, Int, Long, Float, Double) values; other types are rejected.
*/
fun export(values: Map<String, Any?>, platform: String, appVersion: String? = null): String {
val settings = linkedMapOf<String, Any?>()
val local = linkedMapOf<String, Any?>()
for (key in values.keys.sorted()) {
if (key in internalKeys) continue
val value = values[key]
requireKey(key)
val encoded = when (value) {
is String -> structured(value) ?: value
is Boolean, is JsonNumber -> value
is Int, is Long -> JsonNumber(value.toString())
is Float -> JsonNumber.of(value.toDouble())
is Double -> JsonNumber.of(value)
else -> throw IllegalArgumentException("Unsupported value type for setting $key")
}
(if (isPlatformLocal(key)) local else settings)[key] = encoded
}
require(settings.size + local.size <= MAX_ENTRIES) { "Too many settings" }
val document = linkedMapOf<String, Any?>("schema" to JsonNumber.of(SCHEMA), "platform" to platform)
if (!appVersion.isNullOrEmpty()) document["appVersion"] = appVersion
document["settings"] = settings
document["platformSettings"] = local
val text = Json.write(document, pretty = true) + "\n"
require(text.encodeToByteArray().size <= MAX_BYTES) { "Config exceeds 2 MiB" }
return text
}
/** Validate a document and work out what importing it on [platform] stores. */
fun planImport(text: String, platform: String): SettingsImportPlan {
require(text.encodeToByteArray().size <= MAX_BYTES) { "Config exceeds 2 MiB" }
val root = runCatching { Json.parse(text) }.getOrElse { throw IllegalArgumentException("Config is not valid JSON: ${it.message}") }
.asObject() ?: throw IllegalArgumentException("Expected a Faceclaw config object")
val schema = (root["schema"] as? JsonNumber)?.text
val source = root["platform"]?.let { it as? String ?: throw IllegalArgumentException("\"platform\" must be a string") }
val portable = section(root, "settings") ?: throw IllegalArgumentException("Missing \"settings\" object")
val values = linkedMapOf<String, Any>()
val skipped = ArrayList<String>()
val seen = HashSet<String>()
fun add(key: String, value: Any?, include: Boolean) {
requireKey(key)
require(seen.add(key)) { "Setting $key appears more than once" }
require(seen.size <= MAX_ENTRIES) { "Too many settings" }
val stored = storedValue(key, value)
if (key in internalKeys) return
if (include) values[key] = stored else skipped.add(key)
}
val from = when (schema) {
"1" -> {
// Old builds exported iOS settings only; the scripts tag converted Android XML.
val from = source ?: "ios"
for ((key, value) in portable) add(key, value, from == platform || !isPlatformLocal(key))
from
}
"2" -> {
for ((key, value) in portable) add(key, value, true)
section(root, "platformSettings")?.forEach { (key, value) -> add(key, value, source == platform) }
source
}
else -> throw IllegalArgumentException(if (schema == null) "Missing \"schema\"" else "Unsupported config schema $schema")
}
return SettingsImportPlan(values, skipped, from)
}
/**
* Objective-C bridge (FaceclawConfigPort.m, `exportValuesJson:platform:appVersion:`): [json]
* is a JSON object of the phone's settings. Returns the document, or null when the values
* can't be exported.
*/
fun exportValues(json: String, platform: String, appVersion: String?): String? = runCatching {
export(Json.parseObject(json), platform, appVersion)
}.onFailure { PlatformLog.w("SettingsTransfer", "export failed: ${it.message}") }.getOrNull()
/**
* Objective-C bridge (`importPlanDocument:platform:`): never throws. Returns a JSON object, either
* `{"ok":true,"settings":{...},"skipped":[...],"sourcePlatform":...}` or `{"ok":false,"message":...}`.
*/
fun importPlan(document: String, platform: String): String = try {
val plan = planImport(document, platform)
Json.write(linkedMapOf("ok" to true, "settings" to plan.values, "skipped" to plan.skipped, "sourcePlatform" to plan.sourcePlatform))
} catch (error: Exception) {
Json.write(mapOf("ok" to false, "message" to (error.message ?: "Invalid config")))
}
private fun section(root: Map<String, Any?>, name: String): Map<String, Any?>? {
val value = root[name] ?: return null
return value.asObject() ?: throw IllegalArgumentException("\"$name\" must be an object")
}
private fun requireKey(key: String) {
require(key.isNotEmpty() && key.length <= MAX_KEY_CHARS) { "Invalid setting name" }
}
private fun storedValue(key: String, value: Any?): Any = when (value) {
is String, is Boolean, is JsonNumber -> value
is Map<*, *>, is List<*> -> Json.write(value)
null -> throw IllegalArgumentException("Setting $key is null; supply an empty value to clear it")
else -> throw IllegalArgumentException("Unsupported value for setting $key")
}
/** The object/array a string holds, when writing it back reproduces the string exactly. */
private fun structured(text: String): Any? {
if (text.isEmpty() || (text[0] != '{' && text[0] != '[')) return null
val parsed = runCatching { Json.parse(text) }.getOrNull()
if (parsed !is Map<*, *> && parsed !is List<*>) return null
return parsed.takeIf { Json.write(it) == text }
}
}
@@ -24,6 +24,16 @@ interface IosAudioPacketListener {
fun onNsDataAudioPacket(data: NSData, arm: String, arrivalMs: Long)
}
/** CFW ambient-light reports (the raw field-105 record) as NSData. Main queue. Named apart like [IosAudioPacketListener]. */
interface IosAmbientLightListener {
fun onNsDataAmbientLight(body: NSData)
}
/** CFW mic_control status records (the raw field-104 record) as NSData, with the temple: "L", "R" or "?". Main queue. */
interface IosMicStatusListener {
fun onNsDataMicStatus(body: NSData, arm: String)
}
/**
* ObjC-facing facade over the shared [GlassesSessionCore] for the NativeScript app: the iOS
* counterpart of Android's FaceclawBleCommunicator with the same method names. GATT goes
@@ -194,6 +204,39 @@ class IosGlassesSession internal constructor(
fun sendFaceclawMicControl(record: NSData?, label: String, rightTemple: Boolean, leftTemple: Boolean): Boolean =
core.sendFaceclawMicControl(record?.byteArray(), label, rightTemple, leftTemple)
// NSData twins of the ByteArray listeners above (a Kotlin ByteArray crosses into JavaScript one
// byte per call). The core already delivers these on the main queue. Each returns the adapter it
// registered: pass that to the matching remove* method to unsubscribe.
fun addAmbientLightListenerNsData(listener: IosAmbientLightListener): FaceclawAmbientLightListener {
val adapter = object : FaceclawAmbientLightListener {
override fun onAmbientLight(body: ByteArray?) = listener.onNsDataAmbientLight((body ?: ByteArray(0)).data())
}
core.addAmbientLightListener(adapter)
return adapter
}
fun addMicStatusListenerNsData(listener: IosMicStatusListener): FaceclawMicStatusListener {
val adapter = object : FaceclawMicStatusListener {
override fun onMicStatus(body: ByteArray?, arm: String?) =
listener.onNsDataMicStatus((body ?: ByteArray(0)).data(), arm ?: "?")
}
core.addMicStatusListener(adapter)
return adapter
}
/** Every audio-characteristic packet, whether or not a capture is active (passive; sends nothing). */
fun addAudioMonitorListenerNsData(listener: IosAudioPacketListener): FaceclawAudioPacketListener {
val adapter = object : FaceclawAudioPacketListener {
override fun onAudioPacket(data: ByteArray?, arm: String?, arrivalMs: Long) =
listener.onNsDataAudioPacket((data ?: ByteArray(0)).data(), arm ?: "?", arrivalMs)
}
core.addAudioMonitorListener(adapter)
return adapter
}
fun removeAudioMonitorListener(listener: FaceclawAudioPacketListener?) = core.removeAudioMonitorListener(listener)
fun startG2AudioForwarding(listener: FaceclawAudioPacketListener?): Boolean =
core.startG2AudioForwarding(listener?.let { MainQueueAudioListener(it) })