Convert most Android-specific kotlin to shared or shareable

This commit is contained in:
James Babcock committed 2026-09-22 18:43:55 -07:00
1 parent f9724ddcab
commit 587364e5e6
92 files changed
+14347 -9193

No files matched your search

+18 -2
View File
@@ -8,7 +8,21 @@ local `@faceclaw/kotlin` plugin. Generated binaries and Gradle caches are ignore
- `commonMain/kotlin`: wire protocol, fragmentation/reassembly, event decoding,
image/RLE/texture planning, retained surface composition, glyph/image atlases,
LVGL font parsing, spectral noise suppression, PNG/GIF/WAV encodings and
callback interfaces.
callback interfaces. Since 2026-09-22 also the platform-neutral cores behind
the Android adapters: `util/` (Json codec, FrameTimingsCore, concurrency
primitives, sha256/clock/log/file expects), `g2protocol/FirmwareImage`,
`audio/` (Lc3PacketFramer, AudioSegmentation, VoicePrint, WavPcmReader),
`graphics/` (GrayPacket, PreviewPalette, StatusIconArt, GlyphPacket,
OpenTypeNames, SvgIconSource), `net/` (HttpIdentity, SseStream,
ResumableDownload, RemoteInputSession), `evenhub/EvenHubAssetServer`,
`alarms/` (AlarmSchedule, AlarmRingingPolicy), `settings/SettingsChangeHub`,
the stock-firmware flows over a `StockLink` GATT port (`g2protocol/StockLinkSession`,
`DeviceInfoProbeFlow`, `FlashPromptFlow`, `OtaFlashFlow`), the full glasses session
(`g2protocol/session/GlassesSessionCore` over `SessionLink`/`SessionHost`) and the
voice/caption pipelines (`audio/VoiceCaptureSession`, `CaptionEngineCore`).
Cores take port interfaces (GATT link, storage, transport, dispatcher) and call
listeners synchronously; the Android adapters in `App_Resources` own threads,
Handler marshalling and OS APIs. See `notes/stage2-shared-kotlin-plan.md`.
- `androidMain/kotlin`: monotonic clock, reentrant locks, JVM zlib and file I/O,
zero-copy `ByteBuffer` readers, firmware hashing/file writes and WAV file storage.
- `iosMain/kotlin`: monotonic clock, recursive locks, native zlib and POSIX file
@@ -22,7 +36,9 @@ bulk buffer crossing without putting Java APIs in common code. iOS uses
## Platform boundaries
`ProtocolPlatform` supplies clocks, locks and persistent deflaters. `expect` /
`ProtocolPlatform` supplies clocks, locks, persistent deflaters and condition
variables (`ProtocolCondition`, NOT reentrant on iOS: NSCondition). `InterruptibleSleep`,
`Latch` and `BlockingQueue` in commonMain build on it. `expect` /
`actual` functions select default platform services at compilation. Stateful
transports and caches retain reentrant locking; callbacks still run on their
caller's thread. The migration does not introduce implicit UI-thread dispatch.
+1 -1
View File
@@ -409,6 +409,6 @@
},
{
"java": "com/faceclaw/app/util/InterruptibleSleep.java",
"kotlin": "App_Resources/Android/src/main/java/com/faceclaw/app/util/InterruptibleSleep.kt"
"kotlin": "native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/util/Concurrency.kt"
}
]
@@ -0,0 +1,57 @@
package com.faceclaw.app
import java.security.MessageDigest
import java.text.SimpleDateFormat
import java.util.Date
import java.util.Locale
actual class Sha256Digest actual constructor() {
private val digest = MessageDigest.getInstance("SHA-256")
actual fun update(bytes: ByteArray, offset: Int, length: Int) = digest.update(bytes, offset, length)
actual fun digest(): ByteArray = digest.digest()
}
actual fun currentTimeMillis(): Long = System.currentTimeMillis()
actual fun formatLocalTime(epochMs: Long, pattern: String): String =
SimpleDateFormat(pattern, Locale.US).format(Date(epochMs))
actual object PlatformLog {
actual fun i(tag: String, message: String) {
android.util.Log.i(tag, message)
}
actual fun w(tag: String, message: String) {
android.util.Log.w(tag, message)
}
actual fun e(tag: String, message: String, error: Throwable?) {
if (error != null) android.util.Log.e(tag, message, error) else android.util.Log.e(tag, message)
}
}
actual fun startThread(name: String, daemon: Boolean, body: () -> Unit) {
val thread = Thread(body, name)
thread.isDaemon = daemon
thread.start()
}
actual fun sleepMs(ms: Long) {
try {
Thread.sleep(ms)
} catch (ignored: InterruptedException) {
Thread.currentThread().interrupt()
}
}
actual fun writeFileData(path: String, bytes: ByteArray) = java.io.File(path).writeBytes(bytes)
actual fun fileExists(path: String): Boolean = java.io.File(path).exists()
actual fun fileLength(path: String): Long = java.io.File(path).let { if (it.exists()) it.length() else -1L }
actual fun deleteFile(path: String): Boolean = java.io.File(path).delete()
actual fun renameFile(from: String, to: String): Boolean = java.io.File(from).renameTo(java.io.File(to))
@@ -20,6 +20,22 @@ object AndroidProtocolPlatform : ProtocolPlatform {
override fun createDeflater(): ProtocolDeflater = AndroidDeflater()
override fun createCondition(): ProtocolCondition =
object : ProtocolCondition {
private val lock = ReentrantLock()
private val condition = lock.newCondition()
override fun lock() = lock.lock()
override fun unlock() = lock.unlock()
override fun awaitMs(timeoutMs: Long) {
if (timeoutMs > 0) condition.await(timeoutMs, java.util.concurrent.TimeUnit.MILLISECONDS)
}
override fun signalAll() = condition.signalAll()
}
@JvmStatic
fun writeType(mode: GattWriteMode): Int =
when (mode) {
@@ -8,3 +8,15 @@ internal expect fun deflateData(bytes: ByteArray): ByteArray
internal expect fun inflateData(bytes: ByteArray, size: Int): ByteArray
internal expect fun readFileData(path: String): ByteArray
/** Whole-file write (truncating); parent directories must exist. */
expect fun writeFileData(path: String, bytes: ByteArray)
expect fun fileExists(path: String): Boolean
/** Size in bytes, or -1 when the file does not exist. */
expect fun fileLength(path: String): Long
expect fun deleteFile(path: String): Boolean
expect fun renameFile(from: String, to: String): Boolean
@@ -5,7 +5,7 @@ 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<*> -> SettingsJson.write(value)
is Map<*, *>, is List<*> -> Json.write(value)
else -> fallback
}
fun getBoolean(key: String, fallback: Boolean): Boolean = settings[key] as? Boolean ?: fallback
@@ -17,7 +17,7 @@ class SettingsDocument private constructor(private val settings: Map<String, Any
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 = SettingsJson.write(mapOf("schema" to JsonNumber(CURRENT_SCHEMA.toString()), "settings" to settings), pretty = true) + "\n"
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? {
@@ -36,7 +36,7 @@ class SettingsDocument private constructor(private val settings: Map<String, Any
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 { SettingsJson.parse(value) }.getOrNull()
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.
@@ -45,7 +45,7 @@ class SettingsDocument private constructor(private val settings: Map<String, Any
)
internal fun decode(text: String): SettingsDocument {
require(text.encodeToByteArray().size <= 2 * 1024 * 1024) { "Config exceeds 2 MiB" }
val root = SettingsJson.parse(text) as? Map<*, *> ?: error("Expected config object")
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")
@@ -64,103 +64,7 @@ class SettingsDocument private constructor(private val settings: Map<String, Any
/** Nullable decode keeps invalid files recoverable across Objective-C/JVM bridges. */
class SettingsCodec {
fun needsMigration(text: String): Boolean = runCatching {
((SettingsJson.parse(text) as Map<*, *>)["schema"] as JsonNumber).text != SettingsDocument.CURRENT_SCHEMA.toString()
((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()
}
private data class JsonNumber(val text: String)
/** Strict JSON plus // and block comments and trailing commas, on both platforms. */
private object SettingsJson {
private val numberPattern = Regex("-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?(?:[eE][+-]?[0-9]+)?")
fun parse(text: String): Any? = Parser(text).parse()
fun write(value: Any?, pretty: Boolean = false, depth: Int = 0): String {
fun quoted(text: String): String = buildString {
append('"')
for (c in text) when (c) {
'"' -> append("\\\""); '\\' -> append("\\\\"); '\n' -> append("\\n"); '\r' -> append("\\r"); '\t' -> append("\\t")
else -> if (c < ' ') append("\\u" + c.code.toString(16).padStart(4, '0')) else append(c)
}
append('"')
}
fun collection(open: String, close: String, entries: List<String>): String {
if (entries.isEmpty()) return open + close
return if (pretty) open + "\n" + entries.joinToString(",\n") { " ".repeat(depth + 1) + it } + "\n" + " ".repeat(depth) + close
else open + entries.joinToString(",") + close
}
return when (value) {
null -> "null"
is String -> quoted(value)
is Boolean -> value.toString()
is JsonNumber -> value.text
is List<*> -> collection("[", "]", value.map { write(it, pretty, depth + 1) })
is Map<*, *> -> collection("{", "}", value.entries.map { quoted(it.key as String) + (if (pretty) ": " else ":") + write(it.value, pretty, depth + 1) })
else -> error("Unsupported JSON value")
}
}
private class Parser(val text: String) {
var i = 0
fun parse(): Any? { val result = value(0); space(); require(i == text.length); return result }
fun space() {
while (i < text.length) {
if (text[i] in " \r\n\t\uFEFF") { i++; continue }
if (text.startsWith("//", i)) { while (i < text.length && text[i] != '\n' && text[i] != '\r') i++; continue }
if (text.startsWith("/*", i)) { val end = text.indexOf("*/", i + 2); require(end >= 0); i = end + 2; continue }
break
}
}
fun take(c: Char): Boolean { space(); return if (i < text.length && text[i] == c) { i++; true } else false }
fun value(depth: Int): Any? {
require(depth < 64); space(); require(i < text.length)
return when (text[i]) {
'"' -> string()
'{' -> {
i++; val result = linkedMapOf<String, Any?>()
if (!take('}')) while (true) {
space(); val key = string(); require(!result.containsKey(key)); require(take(':'))
result[key] = value(depth + 1)
if (take('}')) break
require(take(',')); if (take('}')) break
}
result
}
'[' -> {
i++; val result = mutableListOf<Any?>()
if (!take(']')) while (true) {
result.add(value(depth + 1)); if (take(']')) break
require(take(',')); if (take(']')) break
}
result
}
't' -> literal("true", true)
'f' -> literal("false", false)
'n' -> literal("null", null)
else -> {
val match = numberPattern.find(text, i)
require(match != null && match.range.first == i)
require(match.value.toDouble().isFinite()); i += match.value.length; JsonNumber(match.value)
}
}
}
fun literal(word: String, result: Any?): Any? { require(text.startsWith(word, i)); i += word.length; return result }
fun string(): String {
require(i < text.length && text[i++] == '"')
return buildString {
while (true) {
require(i < text.length); val c = text[i++]
if (c == '"') break
require(c >= ' ')
if (c != '\\') { append(c); continue }
require(i < text.length)
append(when (val escaped = text[i++]) {
'"', '\\', '/' -> escaped
'b' -> '\b'; 'f' -> '\u000c'; 'n' -> '\n'; 'r' -> '\r'; 't' -> '\t'
'u' -> { require(i + 4 <= text.length); val hex = text.substring(i, i + 4); require(hex.all { it in "0123456789abcdefABCDEF" }); val code = hex.toInt(16); i += 4; code.toChar() }
else -> error("Invalid escape")
})
}
}
}
}
}
@@ -0,0 +1,275 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
/** One item currently ringing. Subclassed by the Android service for its own bookkeeping. */
open class RingingItem(
@JvmField val id: Long,
title: String?,
text: String?,
kind: String?,
snoozeMinutes: Int,
@JvmField val ringAtMs: Long,
) {
@JvmField val title: String = if (title == null || title.trim().isEmpty()) "Alarm" else title
@JvmField val text: String = text ?: ""
@JvmField val kind: String = kind ?: AlarmSchedule.KIND_ALARM
@JvmField val snoozeMinutes: Int = maxOf(1, snoozeMinutes)
@JvmField var deliveredAtMs: Long = 0
@JvmField var escalated: Boolean = false
@JvmField var silenced: Boolean = false
}
/** Delayed callbacks for the escalation timers; the owner's main thread on Android. */
interface AlarmScheduler {
fun postDelayed(token: Any, delayMs: Long, action: () -> Unit)
fun cancel(token: Any)
fun cancelAll()
}
/** Platform effects of ringing: notifications, sound, the schedule, and the journal. */
interface RingingSink {
/** Show or refresh the item's notification (title/status wording comes from the item). */
fun showNotification(item: RingingItem)
/** The item is gone: drop its notification and any per-item resources. */
fun itemRemoved(item: RingingItem)
/** Something started ringing: keep the device awake for the escalation window. */
fun ringingStarted()
fun startSound()
fun stopSound()
/** Re-arm the item (a snooze) at [atMs]. */
fun reschedule(item: RingingItem, atMs: Long, minutes: Int)
/** Forget the item's schedule entry (a dismiss). */
fun cancelSchedule(id: Long)
fun recordPhoneAction(id: Long, action: String, minutes: Int)
fun log(line: String)
}
/**
* Ringing escalation. Each item starts silent on the phone (a notification only, the glasses do
* the ringing) and escalates to phone sound when the glasses cannot carry it: not connected,
* not on a head, charging, no delivery confirmation from the JS side within [DELIVERY_WAIT_MS],
* or no acknowledgement within [ACK_WAIT_MS] of delivery. Sound stops after [AUTO_SILENCE_MS]
* while the notification stays. The policy is process-wide; the platform host (a service on
* Android) attaches its scheduler and sink while it is alive.
*/
class AlarmRingingPolicy(
private val gate: GlassesStatusGate,
private val clock: () -> Long = ::currentTimeMillis,
platform: ProtocolPlatform = protocolPlatform(),
) {
private val lock = platform.createLock()
/** Ringing items, oldest first. */
private val ringing = LinkedHashMap<Long, RingingItem>()
/**
* Signals that arrived before the ring request was processed (the JS engine fires, launches
* its window and reports delivery on the same thread the host queues behind), keyed by id
* with their arrival time. Consumed by [ring].
*/
private val deliveredEarly = LinkedHashMap<Long, Long>()
private val stoppedEarly = LinkedHashMap<Long, Long>()
private var scheduler: AlarmScheduler? = null
private var sink: RingingSink? = null
fun attach(scheduler: AlarmScheduler, sink: RingingSink) {
lock.withLock {
this.scheduler = scheduler
this.sink = sink
}
}
fun detach() {
lock.withLock {
scheduler?.cancelAll()
scheduler = null
sink = null
}
}
fun isRinging(id: Long): Boolean = lock.withLock { ringing.containsKey(id) }
fun isAnythingRinging(): Boolean = lock.withLock { ringing.isNotEmpty() }
fun snapshot(): List<RingingItem> = lock.withLock { ArrayList(ringing.values) }
/**
* The glasses report showing [id]. True when the item is ringing (the host should process
* the delivery); false when it is not yet known, in which case the signal is kept for a
* ring request that follows within [EARLY_SIGNAL_MAX_AGE_MS].
*/
fun deliveredOrDefer(id: Long): Boolean =
lock.withLock {
if (ringing.containsKey(id)) true
else {
deliveredEarly[id] = clock()
false
}
}
/** As [deliveredOrDefer], for an acknowledgement / cancellation. */
fun stopOrDefer(id: Long): Boolean =
lock.withLock {
if (ringing.containsKey(id)) true
else {
stoppedEarly[id] = clock()
false
}
}
/** An item came due (idempotent per id: a duplicate ring only refreshes the notification). */
fun ring(item: RingingItem) {
if (item.id == 0L) return
lock.withLock {
val sink = sink ?: return
val existing = ringing[item.id]
if (existing != null) {
// The engine's JS timeout and the platform alarm both fired: one ring.
sink.showNotification(existing)
return
}
if (takeEarlySignal(stoppedEarly, item.id)) {
// Acknowledged or cancelled before this request was processed.
sink.log("ring " + item.id + " already acknowledged")
return
}
ringing[item.id] = item
sink.log("ring " + item.kind + " " + item.id + " (" + gate.description() + ")")
sink.ringingStarted()
sink.showNotification(item)
if (!gate.canCarryAlarm()) {
escalate(item, gate.description())
return
}
if (takeEarlySignal(deliveredEarly, item.id)) {
markDelivered(item.id)
return
}
// The glasses could carry it: give the JS side a moment to confirm they are
// actually showing it, then hold for the acknowledgement.
scheduler?.postDelayed("delivery:" + item.id, DELIVERY_WAIT_MS) {
lock.withLock {
val current = ringing[item.id]
if (current != null && !current.escalated && current.deliveredAtMs == 0L) {
escalate(current, "not delivered to the glasses")
}
}
}
}
}
fun markDelivered(id: Long) {
lock.withLock {
val item = ringing[id]
if (item == null || item.deliveredAtMs != 0L) return
item.deliveredAtMs = clock()
sink?.log("delivered $id to glasses")
scheduler?.postDelayed("ack:$id", ACK_WAIT_MS) {
lock.withLock {
val current = ringing[id]
if (current != null && !current.escalated) {
escalate(current, "not acknowledged on the glasses")
}
}
}
}
}
private fun escalate(item: RingingItem, reason: String) {
if (item.escalated) return
item.escalated = true
val sink = sink ?: return
sink.log("phone sound for " + item.id + ": " + reason)
sink.showNotification(item)
sink.startSound()
scheduler?.postDelayed("silence:" + item.id, AUTO_SILENCE_MS) {
lock.withLock {
val current = ringing[item.id]
if (current != null && current.escalated && !current.silenced) {
current.silenced = true
this.sink?.log("auto-silenced " + current.id)
this.sink?.showNotification(current)
syncSound()
}
}
}
}
/** Dismissed on the phone: journal it, stop it, and drop the schedule entry. */
fun dismiss(id: Long) {
lock.withLock {
val item = ringing[id] ?: return
val sink = sink ?: return
sink.recordPhoneAction(id, "dismiss", 0)
removeItem(item)
// A one-off is over; the engine re-arms repeats.
sink.cancelSchedule(id)
}
}
/** Snoozed on the phone: journal it, stop it, and re-arm on the phone directly so the snooze holds even with the JS side gone. */
fun snooze(id: Long) {
lock.withLock {
val item = ringing[id] ?: return
val sink = sink ?: return
val minutes = item.snoozeMinutes
sink.recordPhoneAction(id, "snooze", minutes)
removeItem(item)
sink.reschedule(item, clock() + minutes * 60_000L, minutes)
}
}
/** Stop an item without a phone action (acknowledged on the glasses / cancelled by the engine). */
fun stopQuietly(id: Long, reason: String) {
lock.withLock {
val item = ringing[id] ?: return
sink?.log("$reason $id")
removeItem(item)
}
}
/** Start or stop the sound to match whether any escalated, not-yet-silenced item exists. */
fun syncSound() {
lock.withLock {
val sink = sink ?: return
if (ringing.values.any { it.escalated && !it.silenced }) sink.startSound() else sink.stopSound()
}
}
fun cancelTimers() {
lock.withLock { scheduler?.cancelAll() }
}
private fun removeItem(item: RingingItem) {
ringing.remove(item.id)
sink?.itemRemoved(item)
syncSound()
}
/** Consume an early signal for the id; stale entries are dropped. */
private fun takeEarlySignal(signals: MutableMap<Long, Long>, id: Long): Boolean {
val at = signals.remove(id)
val now = clock()
signals.entries.removeAll { now - it.value > EARLY_SIGNAL_MAX_AGE_MS }
return at != null && now - at <= EARLY_SIGNAL_MAX_AGE_MS
}
companion object {
/** How long to wait for the JS side to confirm the glasses are showing the item. */
const val DELIVERY_WAIT_MS = 5_000L
/** How long after delivery to the glasses before the phone joins in. */
const val ACK_WAIT_MS = 30_000L
/** Sound and vibration stop after this; the notification stays. */
const val AUTO_SILENCE_MS = 10 * 60_000L
const val EARLY_SIGNAL_MAX_AGE_MS = 15_000L
}
}
@@ -0,0 +1,235 @@
package com.faceclaw.app
import kotlin.concurrent.Volatile
import kotlin.jvm.JvmField
import kotlin.jvm.JvmStatic
/** Key/value persistence for the alarm schedule, journal and log (device-protected prefs on Android). */
interface AlarmStore {
fun read(key: String): String?
fun write(key: String, value: String?)
}
/** One scheduled item: the JS engine's item id, its wall-clock trigger time, and what to show. */
class AlarmEntry(
@JvmField val id: Long,
@JvmField val at: Long,
title: String?,
text: String?,
kind: String?,
@JvmField val snoozeMinutes: Int,
) {
@JvmField val title: String = title ?: ""
@JvmField val text: String = text ?: ""
@JvmField val kind: String = kind ?: AlarmSchedule.KIND_ALARM
fun toJson(): Map<String, Any?> =
linkedMapOf(
"id" to JsonNumber.of(id),
"at" to JsonNumber.of(at),
"title" to title,
"text" to text,
"kind" to kind,
"snoozeMinutes" to JsonNumber.of(snoozeMinutes),
)
companion object {
@JvmStatic
fun fromJson(value: Any?): AlarmEntry? {
val map = value.asObject() ?: return null
return AlarmEntry(
map["id"].asLong() ?: 0L,
map["at"].asLong() ?: 0L,
map["title"].asString() ?: "",
map["text"].asString() ?: "",
map["kind"].asString() ?: AlarmSchedule.KIND_ALARM,
map["snoozeMinutes"].asInt() ?: 10,
)
}
}
}
/**
* The persisted alarm schedule, the phone-action journal and the diagnostics log, plus the
* replay / staleness policies. Everything the platform's alarm clock API does not own.
* Compound read-modify-write operations are serialized on one lock; the store itself only
* needs to be atomic per key.
*/
class AlarmSchedule(
private val store: AlarmStore,
private val clock: () -> Long = ::currentTimeMillis,
platform: ProtocolPlatform = protocolPlatform(),
) {
private val lock = platform.createLock()
/** All entries, in stored order. */
fun entries(): List<AlarmEntry> = lock.withLock { readEntries() }
fun find(id: Long): AlarmEntry? = lock.withLock { readEntries().firstOrNull { it.id == id } }
/** Add or replace the entry with the same id (moved to the end). */
fun put(entry: AlarmEntry) {
lock.withLock {
val next = readEntries().filter { it.id != entry.id } + entry
writeEntries(next)
}
}
fun remove(id: Long) {
lock.withLock { writeEntries(readEntries().filter { it.id != id }) }
}
/**
* Replay the schedule after a reboot, package update or clock change: entries already due
* ring now if inside the grace window, older ones are dropped as missed (and logged), the
* rest are handed to [arm]. Logs the outcome.
*/
fun replay(reason: String?, ring: (AlarmEntry) -> Unit, arm: (AlarmEntry) -> Unit) {
val scheduled = entries()
val now = clock()
var armed = 0
for (entry in scheduled) {
if (entry.at <= now) {
if (now - entry.at <= LATE_GRACE_MS) {
ring(entry)
} else {
log("missed " + entry.kind + " " + entry.id + " (" + reason + ")")
remove(entry.id)
}
continue
}
arm(entry)
armed++
}
log("rescheduled $armed ($reason)")
}
/** The soonest future trigger time, or null when nothing is pending. */
fun soonestPendingAt(now: Long = clock()): Long? =
entries().filter { it.at > now }.minOfOrNull { it.at }
/**
* The schedule and the system alarm clock can disagree (a force-stop clears alarms but not
* the file). True when the soonest stored entry is not what the system reports as its next
* alarm clock; another app's sooner alarm is fine, only a later (or absent) one proves ours
* is missing. [systemNextAlarmAt] is null when the system has no alarm clock set.
*/
fun looksStale(systemNextAlarmAt: Long?, now: Long = clock()): Boolean {
val soonest = soonestPendingAt(now) ?: return false
return systemNextAlarmAt == null || systemNextAlarmAt > soonest + 1000
}
// ------------------------------------------------------------------
// Phone-action journal (dismiss / snooze done on the phone, replayed by the JS engine)
fun appendJournal(id: Long, action: String, minutes: Int) {
val event = linkedMapOf<String, Any?>(
"id" to JsonNumber.of(id),
"action" to action,
"minutes" to JsonNumber.of(minutes),
"at" to JsonNumber.of(clock()),
)
lock.withLock {
val journal = readArray(KEY_JOURNAL) + event
store.write(KEY_JOURNAL, Json.write(journal))
}
log("phone " + action + " " + id + (if (minutes > 0) " ($minutes min)" else ""))
}
/** Hand the journal over as a JSON array and clear it. */
fun drainJournal(): String =
lock.withLock {
val text = Json.write(readArray(KEY_JOURNAL))
store.write(KEY_JOURNAL, "[]")
text
}
// ------------------------------------------------------------------
// Diagnostics log (bounded, newest last)
fun log(line: String) {
lock.withLock {
val existing = readArray(KEY_LOG).map { it.asString() ?: it?.toString() ?: "" }
val kept = existing.drop(maxOf(0, existing.size - (LOG_LINES - 1)))
store.write(KEY_LOG, Json.write(kept + (clock().toString() + " " + line)))
}
}
fun readLog(): String =
lock.withLock { readArray(KEY_LOG).joinToString("\n") { it.asString() ?: it?.toString() ?: "" } }
// ------------------------------------------------------------------
private fun readArray(key: String): List<Any?> {
val raw = store.read(key) ?: return emptyList()
return runCatching { Json.parseArray(raw) }.getOrDefault(emptyList())
}
private fun readEntries(): List<AlarmEntry> = readArray(KEY_SCHEDULED).mapNotNull { AlarmEntry.fromJson(it) }
private fun writeEntries(entries: List<AlarmEntry>) {
store.write(KEY_SCHEDULED, Json.write(entries.map { it.toJson() }))
}
companion object {
const val KIND_TIMER = "timer"
const val KIND_ALARM = "alarm"
const val KEY_SCHEDULED = "scheduled"
const val KEY_JOURNAL = "journal"
const val KEY_LOG = "log"
const val LOG_LINES = 60
/**
* A schedule entry found already past due (after a reboot, or when the process was
* asleep) rings if it is at most this late; older ones are dropped as missed. Matches
* the JS engine's grace window.
*/
const val LATE_GRACE_MS = 5 * 60_000L
/** A stable per-item request code for platform alarm/notification identities. */
@JvmStatic
fun requestCode(id: Long): Int = (id xor (id ushr 32)).toInt() and 0x7fffffff
}
}
/**
* The last glasses status report pushed by the JS side. In memory only, so a dead process
* reads as "no glasses"; a report older than [MAX_AGE_MS] is not trusted either.
*/
class GlassesStatusGate(private val clock: () -> Long = ::currentTimeMillis) {
@Volatile private var connected = false
@Volatile private var worn = false
@Volatile private var charging = false
@Volatile private var statusAtMs = 0L
fun set(connected: Boolean, worn: Boolean, charging: Boolean) {
this.connected = connected
this.worn = worn
this.charging = charging
statusAtMs = clock()
}
/** True only when a fresh report says the glasses are connected, on a head, and not charging. */
fun canCarryAlarm(): Boolean {
val at = statusAtMs
if (at == 0L || clock() - at > MAX_AGE_MS) return false
return connected && worn && !charging
}
fun description(): String {
val at = statusAtMs
if (at == 0L) return "no glasses status"
if (clock() - at > MAX_AGE_MS) return "glasses status stale"
if (!connected) return "glasses not connected"
if (charging) return "glasses charging"
if (!worn) return "glasses not worn"
return "glasses worn"
}
companion object {
/** A glasses status report older than this is not trusted (the JS side is probably gone). */
const val MAX_AGE_MS = 3 * 60_000L
}
}
@@ -0,0 +1,127 @@
package com.faceclaw.app
import kotlin.jvm.JvmStatic
import kotlin.math.abs
import kotlin.math.min
import kotlin.math.sqrt
/**
* Sample-level helpers shared by the push-to-talk voice controller and the caption engine
* (previously two private copies each). All PCM is 16 kHz mono S16LE unless stated.
*/
object AudioSegmentation {
/**
* Where to end a decode segment: the center of the quietest [windowSamples]-long window
* within the last [searchSamples] of `samples[offset until offset + length]`, so the cut
* lands between words rather than splitting one. Returns [length] when the region is
* too short to search.
*/
@JvmStatic
fun quietestCutPoint(samples: FloatArray, length: Int, searchSamples: Int, windowSamples: Int): Int =
quietestCutPoint(length, searchSamples, windowSamples) { samples[it].toDouble() }
@JvmStatic
fun quietestCutPoint(samples: ShortArray, offset: Int, length: Int, searchSamples: Int, windowSamples: Int): Int =
quietestCutPoint(length, searchSamples, windowSamples) { samples[offset + it].toDouble() }
private inline fun quietestCutPoint(length: Int, searchSamples: Int, windowSamples: Int, sample: (Int) -> Double): Int {
val searchStart = maxOf(0, length - searchSamples)
val win = windowSamples
if (length - searchStart <= win) return length
var sum = 0.0
for (i in searchStart until searchStart + win) {
val s = sample(i)
sum += s * s
}
var best = sum
var bestStart = searchStart
var start = searchStart + 1
while (start + win <= length) {
val dropped = sample(start - 1)
val added = sample(start + win - 1)
sum += added * added - dropped * dropped
if (sum < best) {
best = sum
bestStart = start
}
start++
}
return bestStart + win / 2
}
@JvmStatic
fun peakAmplitude(samples: FloatArray): Float = peakAmplitude(samples, samples.size)
@JvmStatic
fun peakAmplitude(samples: FloatArray, count: Int): Float {
var peak = 0f
for (i in 0 until count) {
val a = abs(samples[i])
if (a > peak) peak = a
}
return peak
}
/**
* Scales [samples] in place so the peak reaches [targetPeak], with the gain capped at
* [maxGain]; audio already at or above the target is left untouched.
*/
@JvmStatic
fun normalizePeak(samples: FloatArray, targetPeak: Float, maxGain: Float) {
val peak = peakAmplitude(samples)
if (peak <= 0f) return
val gain = min(targetPeak / peak, maxGain)
if (gain <= 1f) return
for (i in samples.indices) samples[i] *= gain
}
/** S16 samples to [-1, 1] floats. */
@JvmStatic
fun pcm16ToFloat(samples: ShortArray, offset: Int, count: Int): FloatArray {
val out = FloatArray(count)
for (i in 0 until count) out[i] = samples[offset + i] / 32768.0f
return out
}
/** S16LE bytes to [-1, 1] floats (an odd trailing byte is ignored). */
@JvmStatic
fun pcm16leToFloat(bytes: ByteArray, offset: Int, byteCount: Int): FloatArray {
val count = byteCount / 2
val out = FloatArray(count)
for (i in 0 until count) {
val base = offset + i * 2
out[i] = pcm16le(bytes[base], bytes[base + 1]) / 32768.0f
}
return out
}
@JvmStatic
fun pcm16leToFloat(bytes: ByteArray): FloatArray = pcm16leToFloat(bytes, 0, bytes.size)
/** One little-endian S16 sample from its two bytes. */
@JvmStatic
fun pcm16le(low: Byte, high: Byte): Short = ((low.toInt() and 0xff) or (high.toInt() shl 8)).toShort()
/** S16 samples to S16LE bytes. */
@JvmStatic
fun pcm16ToLittleEndian(samples: ShortArray, offset: Int, count: Int): ByteArray {
val le = ByteArray(count * 2)
for (i in 0 until count) {
val s = samples[offset + i].toInt()
le[i * 2] = (s and 0xff).toByte()
le[i * 2 + 1] = ((s shr 8) and 0xff).toByte()
}
return le
}
/** Root-mean-square of `samples[offset until offset + count]` in S16 units. */
@JvmStatic
fun rms(samples: ShortArray, offset: Int, count: Int): Double {
var sumSquares = 0.0
for (i in 0 until count) {
val s = samples[offset + i].toDouble()
sumSquares += s * s
}
return sqrt(sumSquares / maxOf(1, count))
}
}
@@ -0,0 +1,380 @@
package com.faceclaw.app
import kotlin.concurrent.Volatile
import kotlin.math.max
import kotlin.math.min
import kotlin.math.sqrt
/** Receives segmenter events synchronously on the thread feeding [CaptionSegmenter.processChunk]. */
interface CaptionSegmentSink {
fun onSpeechStart(startMs: Long)
/** [samples] is the segmenter's own buffer, valid only for the duration of the call. */
fun onUtterance(samples: ShortArray, length: Int, startMs: Long, endMs: Long, peakRms: Double)
}
/**
* Splits decoded mic PCM into utterances with an adaptive energy gate: the noise floor is a
* rolling mean tracked while idle, onset fires at ONSET_FACTOR above it (keeping PRE_ROLL_MS of
* idle audio so leading consonants survive), and the utterance ends after [silenceMs] below
* RELEASE_FACTOR or at MAX_UTTERANCE_MS. Boundaries are measured on the 16 kHz sample clock,
* not the wall clock: BLE delivers mic packets in bursts.
*/
class CaptionSegmenter(private val sink: CaptionSegmentSink) {
companion object {
const val SAMPLE_RATE = 16000
const val ONSET_FACTOR = 3.0
const val RELEASE_FACTOR = 1.8
const val MIN_RMS = 220.0
const val NOISE_EMA_ALPHA = 0.05
const val PRE_ROLL_MS = 400
const val DEFAULT_SILENCE_MS = 800
const val MIN_SILENCE_MS = 200
const val MAX_SILENCE_MS = 3000
const val MIN_UTTERANCE_MS = 350
const val MAX_UTTERANCE_MS = 15000
}
@Volatile
var silenceMs = DEFAULT_SILENCE_MS
set(value) {
field = max(MIN_SILENCE_MS, min(MAX_SILENCE_MS, value))
}
private var totalSamples: Long = 0
private var noiseFloor = 0.0
private var inUtterance = false
private var utteranceStartSample: Long = 0
private var silenceRunSamples: Long = 0
private var utterancePeakRms = 0.0
private val utterance = ShortArray(SAMPLE_RATE * (MAX_UTTERANCE_MS / 1000))
private var utteranceLength = 0
private val preRoll = ShortArray(SAMPLE_RATE * PRE_ROLL_MS / 1000)
private var preRollLength = 0
val isInUtterance: Boolean
get() = inUtterance
fun reset() {
totalSamples = 0
noiseFloor = 0.0
inUtterance = false
utteranceLength = 0
preRollLength = 0
silenceRunSamples = 0
utterancePeakRms = 0.0
}
/** Feeds one chunk of S16LE PCM bytes (any chunking). */
fun processChunk(chunk: ByteArray) {
val count = chunk.size / 2
val pcm = ShortArray(count)
for (i in 0 until count) {
pcm[i] = AudioSegmentation.pcm16le(chunk[i * 2], chunk[i * 2 + 1])
}
processChunk(pcm, count)
}
fun processChunk(pcm: ShortArray, count: Int) {
var sumSquares = 0.0
for (i in 0 until count) {
val s = pcm[i].toDouble()
sumSquares += s * s
}
val rms = sqrt(sumSquares / max(1, count))
totalSamples += count.toLong()
if (!inUtterance) {
// Track the noise floor only while idle so speech doesn't raise it.
noiseFloor = if (noiseFloor == 0.0) rms else noiseFloor * (1 - NOISE_EMA_ALPHA) + rms * NOISE_EMA_ALPHA
val threshold = max(noiseFloor, MIN_RMS)
if (rms >= threshold * ONSET_FACTOR) {
inUtterance = true
utteranceLength = 0
silenceRunSamples = 0
utterancePeakRms = rms
appendUtterance(preRoll, preRollLength)
utteranceStartSample = max(0L, totalSamples - count - preRollLength)
appendUtterance(pcm, count)
sink.onSpeechStart(utteranceStartSample * 1000 / SAMPLE_RATE)
} else {
appendPreRoll(pcm, count)
}
return
}
appendUtterance(pcm, count)
utterancePeakRms = max(utterancePeakRms, rms)
val threshold = max(noiseFloor, MIN_RMS)
if (rms < threshold * RELEASE_FACTOR) {
silenceRunSamples += count.toLong()
} else {
silenceRunSamples = 0
}
val utteranceMs = utteranceLength.toLong() * 1000 / SAMPLE_RATE
val silenceEnded = silenceRunSamples * 1000L / SAMPLE_RATE >= silenceMs
if (silenceEnded || utteranceMs >= MAX_UTTERANCE_MS) {
finalizeUtterance()
inUtterance = false
preRollLength = 0
}
}
/** Emits a trailing utterance (if any) so its text isn't lost on stop. */
fun flush() {
if (inUtterance && utteranceLength > 0) {
finalizeUtterance()
}
inUtterance = false
preRollLength = 0
}
private fun appendPreRoll(pcm: ShortArray, count: Int) {
// Keep the last PRE_ROLL_MS of idle audio so onset consonants survive.
if (count >= preRoll.size) {
pcm.copyInto(preRoll, 0, count - preRoll.size, count)
preRollLength = preRoll.size
return
}
val keep = min(preRollLength, preRoll.size - count)
preRoll.copyInto(preRoll, 0, preRollLength - keep, preRollLength)
pcm.copyInto(preRoll, keep, 0, count)
preRollLength = keep + count
}
private fun appendUtterance(pcm: ShortArray, count: Int) {
val room = utterance.size - utteranceLength
val copied = min(room, count)
if (copied > 0) {
pcm.copyInto(utterance, utteranceLength, 0, copied)
utteranceLength += copied
}
}
private fun finalizeUtterance() {
val length = utteranceLength
val startMs = utteranceStartSample * 1000 / SAMPLE_RATE
val endMs = (utteranceStartSample + length) * 1000 / SAMPLE_RATE
if (endMs - startMs < MIN_UTTERANCE_MS) {
return
}
sink.onUtterance(utterance, length, startMs, endMs, utterancePeakRms)
}
}
/**
* Transcribes one utterance in model-safe segments cut at the quietest window (Moonshine v2
* fails past ~9.1 s of input) and attaches a voice-print from at most its first 10 s.
*/
class UtteranceDecoder(private val transcriber: OfflineTranscriber?, private val embedder: SpeakerEmbedder?) {
companion object {
const val SAMPLE_RATE = 16000
const val DECODE_SEGMENT_MAX_SAMPLES = SAMPLE_RATE * 8
const val CUT_SEARCH_SAMPLES = SAMPLE_RATE * 2
const val CUT_WINDOW_SAMPLES = SAMPLE_RATE * 30 / 1000
const val NORMALIZE_TARGET_PEAK = 0.9f
const val NORMALIZE_MAX_GAIN = 30f
// Voice-prints degrade on very long inputs; embed at most the first 10 s.
const val EMBED_MAX_SAMPLES = SAMPLE_RATE * 10
}
val hasTranscriber: Boolean
get() = transcriber != null
fun recognize(utterance: ShortArray, length: Int): String {
val recognizer = transcriber
if (recognizer == null || length <= 0) {
return ""
}
val joined = StringBuilder()
var offset = 0
while (offset < length) {
val remaining = length - offset
var segment = min(remaining, DECODE_SEGMENT_MAX_SAMPLES)
if (remaining > DECODE_SEGMENT_MAX_SAMPLES) {
segment = AudioSegmentation.quietestCutPoint(utterance, offset, segment, CUT_SEARCH_SAMPLES, CUT_WINDOW_SAMPLES)
}
val samples = AudioSegmentation.pcm16ToFloat(utterance, offset, segment)
AudioSegmentation.normalizePeak(samples, NORMALIZE_TARGET_PEAK, NORMALIZE_MAX_GAIN)
val part = recognizer.recognize(samples, samples.size).trim()
if (part.isNotEmpty()) {
if (joined.isNotEmpty() && ".,!?;:%)]}".indexOf(part[0]) < 0) {
joined.append(' ')
}
joined.append(part)
}
offset += segment
}
return joined.toString().trim()
}
fun embed(utterance: ShortArray, length: Int): FloatArray? {
val currentEmbedder = embedder
if (currentEmbedder == null || length <= 0) {
return null
}
val count = min(length, EMBED_MAX_SAMPLES)
return currentEmbedder.embed(AudioSegmentation.pcm16ToLittleEndian(utterance, 0, count), SAMPLE_RATE)
}
fun release() {
transcriber?.release()
embedder?.release()
}
}
/** Platform services for [CaptionSession]. */
interface CaptionHost {
val dispatcher: CallbackDispatcher
/** Loads the caption recognizer from [modelDir], or null when the model files are absent. */
fun loadTranscriber(modelDir: String): OfflineTranscriber?
/** Loads the speaker-embedding model, or null when the file is absent. */
fun loadEmbedder(modelPath: String): SpeakerEmbedder?
}
/**
* Continuous captioning over pushed mic PCM: queue, worker thread (owned here, via the shared
* [startThread]), model lifecycle, segmentation and per-utterance decode/embedding, with
* listener callbacks marshalled through the host dispatcher.
*/
class CaptionSession(
private val host: CaptionHost,
private val platform: ProtocolPlatform = protocolPlatform(),
private val threadName: String = "FaceclawCaptionEngine",
private val logError: (String, Throwable) -> Unit = { message, error -> PlatformLog.e(TAG, message, error) },
) : CaptionSegmentSink {
companion object {
const val TAG = "FaceclawCaptions"
const val MAX_QUEUE_PACKETS = 200
}
private val lock = platform.createLock()
private val queue = DroppingPacketQueue<ByteArray>(MAX_QUEUE_PACKETS, platform)
private val segmenter = CaptionSegmenter(this)
@Volatile
private var listener: FaceclawCaptionEngineListener? = null
@Volatile
private var asrModelDir: String? = null
@Volatile
private var speakerModelPath: String? = null
@Volatile
private var started = false
private var workerFinished: Latch? = null
@Volatile
private var workerThreadName: String? = null
private var decoder: UtteranceDecoder? = null
fun setListener(listener: FaceclawCaptionEngineListener?) {
this.listener = listener
}
fun setAsrModelDir(dir: String?) {
this.asrModelDir = dir
}
fun setSpeakerModelPath(path: String?) {
this.speakerModelPath = path
}
fun setSilenceMs(ms: Int) {
segmenter.silenceMs = ms
}
fun start() {
lock.withLock {
if (started) {
return
}
started = true
val finished = Latch(1, platform)
workerFinished = finished
startThread(threadName, true) { runLoop(finished) }
}
}
/** Stops and waits up to 2 s for the worker unless called from it. */
fun stop() {
var finished: Latch? = null
var workerName: String? = null
lock.withLock {
if (!started) {
return
}
started = false
finished = workerFinished
workerName = workerThreadName
}
queue.wake()
if (finished != null && (workerName == null || currentThreadName() != workerName)) {
finished.await(2000)
}
}
/** Push decoded 16 kHz mono S16LE PCM (any chunking). */
fun acceptPcm(pcm16le: ByteArray?) {
if (!started || pcm16le == null || pcm16le.size < 2) {
return
}
queue.put(pcm16le)
}
private fun runLoop(finished: Latch) {
workerThreadName = currentThreadName()
try {
loadModels()
segmenter.reset()
while (started) {
val chunk = queue.take(250) { started } ?: continue
segmenter.processChunk(chunk)
}
// Flush a trailing utterance so its text isn't lost on stop.
segmenter.flush()
} catch (t: Throwable) {
logError("caption engine failed", t)
emitStatus("Captions failed: " + t.message)
} finally {
decoder?.release()
decoder = null
lock.withLock {
workerFinished = null
workerThreadName = null
}
finished.countDown()
}
}
private fun loadModels() {
val modelDir = asrModelDir
val transcriber = if (modelDir != null) {
emitStatus("Loading caption model...")
host.loadTranscriber(modelDir)
} else {
null
}
val embedModel = speakerModelPath
val embedder = if (embedModel != null) host.loadEmbedder(embedModel) else null
decoder = UtteranceDecoder(transcriber, embedder)
emitStatus(if (transcriber != null) "Captions listening..." else "Captions listening (no ASR model)...")
}
override fun onSpeechStart(startMs: Long) {
val currentListener = listener ?: return
host.dispatcher.post { currentListener.onSpeechStart(startMs) }
}
override fun onUtterance(samples: ShortArray, length: Int, startMs: Long, endMs: Long, peakRms: Double) {
val currentDecoder = decoder ?: return
val text = currentDecoder.recognize(samples, length)
val embedding = currentDecoder.embed(samples, length)
val currentListener = listener ?: return
val embeddingCopy = embedding?.copyOf()
host.dispatcher.post { currentListener.onUtterance(text, embeddingCopy, startMs, endMs, peakRms) }
}
private fun emitStatus(status: String?) {
val currentListener = listener ?: return
host.dispatcher.post { currentListener.onStatus(status) }
}
}
@@ -0,0 +1,93 @@
package com.faceclaw.app
import kotlin.jvm.JvmStatic
/** Decodes the LC3 frames of one G2 packet into [pcmOut]; returns samples written, <= 0 on error. */
interface Lc3Codec {
fun decodeFrames(packet: ByteArray, offset: Int, length: Int, pcmOut: ShortArray): Int
}
/**
* G2 microphone packet framing shared by the Android JNI decoder and the iOS port: length
* check, counter-based duplicate/late/missing accounting, trailer parsing and statistics.
* The codec itself (liblc3) is injected.
*
* Both arms may relay the same packet, so a counter gap of 0 or >= 128 (a late copy, including
* across the 255 -> 0 wrap) is dropped before it can disturb the decoder's history. The
* former Android decoder only dropped gap == 0; this adopts the wrap-safe rule the iOS
* decoder already used.
*/
class Lc3PacketFramer(private val codec: Lc3Codec) {
companion object {
const val SAMPLE_RATE = 16000
const val FRAME_US = 10000
const val FRAME_BYTES = 40
const val FRAMES_PER_PACKET = 5
const val PACKET_BYTES = 205
const val COUNTER_OFFSET = 204
const val SAMPLES_PER_FRAME = 160
const val SAMPLES_PER_PACKET = FRAMES_PER_PACKET * SAMPLES_PER_FRAME
const val LC3_BYTES = FRAME_BYTES * FRAMES_PER_PACKET
// Trailer layout (firmware service_audio.c): after the 200 LC3 bytes the
// glasses DSP appends two signed 16-bit LE values computed on the raw
// stereo capture before the mono downmix — a signal-strength ratio and the
// asin-derived direction-of-arrival in degrees — then the packet counter.
const val SSR_OFFSET = 200
const val ANGLE_OFFSET = 202
/** Counter gaps at or beyond this are late copies, not losses. */
const val LATE_GAP = 128
@JvmStatic
fun readTrailerS16(packet: ByteArray, offset: Int): Int =
((packet[offset].toInt() and 0xff) or (packet[offset + 1].toInt() shl 8)).toShort().toInt()
}
private var lastCounter = -1
var realPackets: Long = 0
private set
var duplicatePackets: Long = 0
private set
var missingPackets: Long = 0
private set
var decodeErrors: Long = 0
private set
/** Firmware signal-strength ratio from the most recent decoded packet. */
var lastSsr: Int = 0
private set
/** Firmware direction-of-arrival (signed degrees) from the most recent decoded packet. */
var lastAngleDegrees: Int = 0
private set
/**
* Returns the number of PCM samples written to [pcmOut], or 0 when the packet was dropped
* (wrong length, duplicate/late, or codec failure; see the counters).
*/
fun decodePacket(packet: ByteArray?, pcmOut: ShortArray?): Int {
if (packet == null || packet.size != PACKET_BYTES) {
decodeErrors++
return 0
}
if (pcmOut == null || pcmOut.size < SAMPLES_PER_PACKET) {
throw IllegalArgumentException("pcmOut must hold $SAMPLES_PER_PACKET samples")
}
val counter = packet[COUNTER_OFFSET].toInt() and 0xff
if (lastCounter >= 0) {
val gap = (counter - lastCounter) and 0xff
if (gap == 0 || gap >= LATE_GAP) {
duplicatePackets++
return 0
}
missingPackets += (gap - 1).toLong()
}
val decoded = codec.decodeFrames(packet, 0, LC3_BYTES, pcmOut)
if (decoded <= 0) {
decodeErrors++
return 0
}
realPackets++
lastCounter = counter
lastSsr = readTrailerS16(packet, SSR_OFFSET)
lastAngleDegrees = readTrailerS16(packet, ANGLE_OFFSET)
return decoded
}
}
@@ -0,0 +1,833 @@
package com.faceclaw.app
import kotlin.concurrent.Volatile
import kotlin.jvm.JvmStatic
import kotlin.math.abs
import kotlin.math.max
import kotlin.math.min
/** Platform services the voice-capture session needs; supplied by the Android/iOS adapter. */
interface VoiceCaptureHost {
val dispatcher: CallbackDispatcher
/** Runs first on the worker thread of every session (Android deletes legacy model files here). */
fun onSessionStarting()
/** True when a glasses session can carry microphone packets (false when no communicator is set). */
fun isG2SessionReady(): Boolean
/** Whether the glasses are still delivering packets; see [VoiceCaptureSession.isCapturing]. */
fun isG2AudioCaptureActive(): Boolean
/** The glasses packet source, or null when no communicator is available. */
fun g2AudioSource(): PacketAudioSource?
fun createPacketDecoder(): AudioPacketDecoder
/** Opens the phone microphone at 16 kHz mono PCM16, or null when it cannot start. */
fun openPhoneMic(): PcmAudioSource?
/** Whether the on-device model files for [kind] are present (downloaded). */
fun hasTranscriberModel(kind: VoiceModelKind): Boolean
/** Loads the recognizer for [kind]; throws when the model cannot be loaded. */
fun loadTranscriber(kind: VoiceModelKind): OfflineTranscriber
/** The speaker-embedding model at [modelPath] (may be shared/cached across sessions). */
fun speakerEmbedder(modelPath: String): SpeakerEmbedder
/** Where a saved recording goes, or null when recordings cannot be stored. */
fun recordingSink(): RecordingSink?
}
/**
* Voice-input capture pipeline shared by both platforms: LC3 packet queue with drop/late
* accounting, firmware-DoA beam gate, per-chunk processing (suppression, recording, speaker
* verification buffer, endpointing, PCM emit), the segmented on-device transcript machine with
* REPLACE-semantics partials, and speaker verification at session end. The session owns its
* worker thread (started through the shared [startThread]); listener callbacks go through the
* host's [CallbackDispatcher] so the adapter decides the delivery thread.
*/
class VoiceCaptureSession(
private val host: VoiceCaptureHost,
private val platform: ProtocolPlatform = protocolPlatform(),
private val threadName: String = "FaceclawVoiceController",
private val logInfo: (String) -> Unit = { PlatformLog.i(TAG, it) },
private val logWarn: (String) -> Unit = { PlatformLog.w(TAG, it) },
private val logError: (String, Throwable) -> Unit = { message, error -> PlatformLog.e(TAG, message, error) },
) {
companion object {
const val TAG = "FaceclawVoice"
const val SAMPLE_RATE = 16000
const val MAX_AUDIO_QUEUE_PACKETS = 80
const val EXPECTED_PACKET_INTERVAL_MS = 50
const val LATE_PACKET_INTERVAL_MS = 90
const val STATS_INTERVAL_MS = 5_000
// Push-to-talk utterance boundaries come from the button. We re-decode the
// current audio segment in full for each live partial and emit the complete
// utterance text (REPLACE, never a delta). The sherpa Moonshine v2 decoder
// used here fails once a single input grows past roughly 9.1 seconds, so
// longer utterances are committed in model-safe segments.
const val TRANSCRIPT_DECODE_INTERVAL_MS = 700
const val TRANSCRIPT_MIN_SAMPLES = SAMPLE_RATE / 3
const val TRANSCRIPT_SEGMENT_MAX_SAMPLES = SAMPLE_RATE * 8
// When a segment fills, cut at the quietest window within the last
// TRANSCRIPT_CUT_SEARCH_SAMPLES rather than mid-word at the 8s mark; the
// audio after the cut carries over into the next segment.
const val TRANSCRIPT_CUT_SEARCH_SAMPLES = SAMPLE_RATE * 2
const val TRANSCRIPT_CUT_WINDOW_SAMPLES = SAMPLE_RATE * 30 / 1000
// Glasses-mic PCM peaks around 0.1 full scale, and at that level the
// quantized Moonshine model often returns empty or garbled text. Boost
// each decode window toward this peak, with a gain cap so near-silent
// buffers aren't amplified into pure noise.
const val TRANSCRIPT_NORMALIZE_TARGET_PEAK = 0.9f
const val TRANSCRIPT_NORMALIZE_MAX_GAIN = 30f
const val TRANSCRIPT_LOG_PREVIEW_CHARS = 80
// Below this peak amplitude (pre-normalization, of a full-scale +/-1.0f
// buffer) a segment is treated as silence and never reaches the Whisper
// recognizer at all, rather than risking a hallucinated non-answer. Picked
// conservatively low (well under typical mic noise floor already seen in
// this pipeline's normalization target) -- UNTESTED on real hardware, tune
// against real glasses captures rather than trusting this number.
const val WHISPER_SILENCE_PEAK_THRESHOLD = 0.01f
// Speaker verification against the enrolled wearer voice-print ("my voice
// only" command gating). Configured before start(); the utterance PCM is
// buffered (capped) and verified once at session end.
const val VERIFY_MAX_SAMPLES = SAMPLE_RATE * 10
const val VERIFY_MIN_SAMPLES = SAMPLE_RATE
const val DEFAULT_VERIFY_THRESHOLD = 0.8f
/** Samples per G2 packet; the decode buffer the worker reuses. */
const val PACKET_SAMPLES = Lc3PacketFramer.SAMPLES_PER_PACKET
/** Joins transcript pieces, attaching leading punctuation to the previous text. */
@JvmStatic
fun joinTranscript(prefix: String?, suffix: String?): String {
if (prefix.isNullOrEmpty()) {
return suffix ?: ""
}
if (suffix.isNullOrEmpty()) {
return prefix
}
val first = suffix[0]
val attachesToPrevious = ".,!?;:%)]}".indexOf(first) >= 0
return prefix + (if (attachesToPrevious) "" else " ") + suffix
}
@JvmStatic
fun parseModelKind(kind: String?): VoiceModelKind =
if ("whisper" == kind) VoiceModelKind.WHISPER else VoiceModelKind.MOONSHINE
}
enum class Mode {
ONBOARD, // on-phone transcription (Moonshine or Whisper; see onboardModelKind)
CLOUD, // decode locally, emit PCM for a cloud recognizer on the TS side
}
private class AudioPacket(val data: ByteArray, arm: String?, val arrivalMs: Long) {
val arm: String = arm ?: "?"
}
private val lock = platform.createLock()
private val audioQueue = DroppingPacketQueue<AudioPacket>(MAX_AUDIO_QUEUE_PACKETS, platform)
@Volatile
private var listener: FaceclawVoiceControllerListener? = null
@Volatile
private var started = false
// Set once the worker has the mic enabled for this session. Read and
// written under `lock`, so it flips with `started` atomically.
private var audioStarted = false
private var workerFinished: Latch? = null
@Volatile
private var workerThreadName: String? = null
// Capture from the phone's own microphone instead of the G2 over BLE
// (preview-only mode). Latched into activePhoneMic at start() (under `lock`)
// so a mid-session setter call can't switch pipelines underneath the worker.
@Volatile
private var usePhoneMic = false
private var activePhoneMic = false
private var mode = Mode.CLOUD
@Volatile
private var onboardModelKind = VoiceModelKind.MOONSHINE
private var recognizer: OfflineTranscriber? = null
private var packetDecoder: AudioPacketDecoder? = null
private val transcriptSamples = FloatArray(TRANSCRIPT_SEGMENT_MAX_SAMPLES)
private var transcriptSampleCount = 0
private var committedTranscriptSampleCount: Long = 0
private var committedTranscript = ""
private var currentSegmentTranscript = ""
private var lastTranscriptDecodeAtMs: Long = 0
private var lastTranscript = ""
@Volatile
private var saveRecordings = false
@Volatile
private var endpointing = false
private val endpointDetector = VoiceEndpointDetector()
private var recordingPcm: ByteSink? = null
@Volatile
private var verifySpeakerModelPath: String? = null
@Volatile
private var verifyWearerEmbedding: FloatArray? = null
@Volatile
private var verifyThreshold = DEFAULT_VERIFY_THRESHOLD
private var verifyBuffer: ShortArray? = null
private var verifyCount = 0
// Global mic processing (Microphones app config): spectral noise
// suppression and firmware-DoA beam gating, applied to every capture
// session that opts in. The raw tap opts out.
@Volatile
private var suppressionEnabled = false
@Volatile
private var beamFilterEnabled = false
@Volatile
private var beamCenterDeg = 0
@Volatile
private var beamHalfWidthDeg = 180
private var suppressor: FaceclawNoiseSuppressor? = null
private var queuedPackets: Long = 0
private var decodedSamples: Long = 0
private var latePackets: Long = 0
private var wrongArmPackets: Long = 0
private var lastPacketArrivalMs: Long = 0
private var maxInterPacketMs: Long = 0
private var lastStatsAtMs: Long = 0
fun setListener(listener: FaceclawVoiceControllerListener?) {
this.listener = listener
}
fun setUsePhoneMic(usePhoneMic: Boolean) {
this.usePhoneMic = usePhoneMic
}
fun setSaveRecordings(saveRecordings: Boolean) {
this.saveRecordings = saveRecordings
}
fun setOnboardModelKind(kind: String?) {
this.onboardModelKind = parseModelKind(kind)
}
fun setEndpointing(endpointing: Boolean) {
this.endpointing = endpointing
}
fun setSpeakerVerification(speakerModelPath: String?, wearerEmbedding: FloatArray?, threshold: Float) {
this.verifySpeakerModelPath = speakerModelPath
this.verifyWearerEmbedding = wearerEmbedding
this.verifyThreshold = if (threshold > 0) threshold else DEFAULT_VERIFY_THRESHOLD
}
fun clearSpeakerVerification() {
this.verifySpeakerModelPath = null
this.verifyWearerEmbedding = null
}
fun setNoiseSuppression(enabled: Boolean) {
this.suppressionEnabled = enabled
}
fun setBeamFilter(enabled: Boolean, centerDeg: Int, halfWidthDeg: Int) {
this.beamFilterEnabled = enabled
this.beamCenterDeg = centerDeg
this.beamHalfWidthDeg = max(5, min(180, halfWidthDeg))
}
/** Direction gating: true when [angleDegrees] lies within centerDeg ± halfWidthDeg (wrap-safe). */
fun withinBeam(angleDegrees: Int): Boolean {
var delta = angleDegrees - beamCenterDeg
while (delta > 180) delta -= 360
while (delta < -180) delta += 360
return abs(delta) <= beamHalfWidthDeg
}
private fun applySuppression(pcm: ShortArray, count: Int) {
try {
if (suppressor == null) {
suppressor = FaceclawNoiseSuppressor(SAMPLE_RATE)
}
val le = AudioSegmentation.pcm16ToLittleEndian(pcm, 0, count)
val cleaned = suppressor!!.process(le)!!
val cleanedCount = min(count, cleaned.size / 2)
for (i in 0 until cleanedCount) {
pcm[i] = AudioSegmentation.pcm16le(cleaned[i * 2], cleaned[i * 2 + 1])
}
} catch (t: Throwable) {
logWarn("noise suppression failed; passing audio through (${t.message})")
suppressionEnabled = false
}
}
fun start(requestedMode: String?) {
start(requestedMode, 0)
}
fun start(requestedMode: String?, captureId: Int) {
lock.withLock {
if (started) {
emitStatus("Voice control is already listening.")
emitStopped(captureId)
return
}
if (!usePhoneMic && !host.isG2SessionReady()) {
emitStatus("Voice control needs an active G2 connection.")
emitStopped(captureId)
return
}
mode = parseMode(requestedMode)
activePhoneMic = usePhoneMic
started = true
audioStarted = false
val finished = Latch(1, platform)
workerFinished = finished
startThread(threadName, true) { runLoop(captureId, finished) }
}
}
/**
* Whether mic audio is actually flowing. start() only records intent: the
* enable lives in the glasses' EvenHub session, so a transport drop or a
* session suspend can leave this session started with a worker that will
* never see another packet.
*/
fun isCapturing(): Boolean {
var audioUp = false
var phoneMic = false
lock.withLock {
if (!started) {
return false
}
audioUp = audioStarted
phoneMic = activePhoneMic
}
if (!audioUp) {
// The worker is still bringing the mic up; report it as running so
// a concurrent request shares it instead of restarting it.
return true
}
if (phoneMic) {
// The phone mic has no session to lose the enable to; it runs until stop().
return true
}
return host.isG2AudioCaptureActive()
}
/**
* Stops the session and waits up to 1.5 s for the worker to finish unless
* called from the worker itself. The worker checks the stop flag between
* packets (every packet or 250 ms wait) and between phone-mic reads (50 ms).
*/
fun stop() {
var finished: Latch? = null
var workerName: String? = null
lock.withLock {
if (!started) {
return
}
started = false
finished = workerFinished
workerName = workerThreadName
}
stopG2Audio()
audioQueue.wake()
if (finished != null && (workerName == null || currentThreadName() != workerName)) {
finished.await(1500)
}
}
fun close() {
stop()
}
private fun parseMode(requestedMode: String?): Mode {
if ("cloud" == requestedMode) {
return Mode.CLOUD
}
return Mode.ONBOARD
}
private fun runLoop(captureId: Int, finished: Latch) {
workerThreadName = currentThreadName()
try {
host.onSessionStarting()
val currentMode = mode
val currentOnboardKind = onboardModelKind
if (currentMode == Mode.ONBOARD) {
if (!host.hasTranscriberModel(currentOnboardKind)) {
emitStatus("Voice model not downloaded (see Settings > Voice).")
return
}
emitStatus("Loading transcription model...")
recognizer = host.loadTranscriber(currentOnboardKind)
resetTranscriptState()
lastTranscript = ""
}
endpointDetector.reset()
suppressor?.reset()
recordingPcm = if (saveRecordings) ByteSink(SAMPLE_RATE * 2 * 4) else null
val verifying = verifySpeakerModelPath != null && verifyWearerEmbedding != null
verifyBuffer = if (verifying) ShortArray(VERIFY_MAX_SAMPLES) else null
verifyCount = 0
if (activePhoneMic) {
val record = host.openPhoneMic()
if (record == null) {
emitStatus("Could not start the phone microphone.")
return
}
lock.withLock { audioStarted = true }
emitStatus(if (currentMode == Mode.CLOUD) "Listening (cloud)..." else "Listening...")
try {
processPhoneAudio(record)
} finally {
record.close()
}
} else {
packetDecoder = host.createPacketDecoder()
if (!startG2Audio()) {
emitStatus("Could not start G2 microphone input.")
return
}
lock.withLock { audioStarted = true }
emitStatus(if (currentMode == Mode.CLOUD) "Listening (cloud)..." else "Listening...")
processG2Audio()
}
// Verification result must precede the final transcript so the
// TS bridge can suppress a non-wearer command before it is acted
// on (the callbacks are posted in order to the dispatcher).
runSpeakerVerification()
// Button released / stop requested: emit one final full-utterance
// transcript so the UI can freeze it.
if (currentMode == Mode.ONBOARD) {
decodeTranscript(true)
}
} catch (error: Throwable) {
logError("Voice control failed", error)
emitStatus("Voice control failed: " + error.message)
} finally {
stopG2Audio()
writeRecordingIfAny()
releaseRecognizer()
releaseDecoder()
lock.withLock {
started = false
audioStarted = false
workerFinished = null
workerThreadName = null
}
emitStopped(captureId)
finished.countDown()
}
}
private fun appendRecording(pcm: ShortArray, count: Int) {
val out = recordingPcm ?: return
out.write(AudioSegmentation.pcm16ToLittleEndian(pcm, 0, count))
}
private fun writeRecordingIfAny() {
val out = recordingPcm
recordingPcm = null
if (out == null || out.size() == 0) {
return
}
val sink = host.recordingSink() ?: return
try {
sink.save(out.toByteArray(), SAMPLE_RATE)
} catch (t: Throwable) {
logWarn("failed to save voice recording (${t.message})")
}
}
private fun startG2Audio(): Boolean {
val source = host.g2AudioSource() ?: return false
resetAudioStats()
audioQueue.clear()
return source.start(object : FaceclawAudioPacketListener {
override fun onAudioPacket(data: ByteArray?, arm: String?, arrivalMs: Long) {
queueAudioPacket(data, arm, arrivalMs)
}
})
}
private fun processG2Audio() {
val pcm = ShortArray(PACKET_SAMPLES)
while (started) {
val currentDecoder = packetDecoder ?: return
val packet = takeAudioPacket()
if (packet == null) {
continue
}
val count = currentDecoder.decodePacket(packet.data, pcm)
if (count <= 0) {
maybeEmitAudioStats(false)
continue
}
decodedSamples += count.toLong()
// The beam filter drops packets whose firmware direction-of-arrival
// falls outside the listening wedge (isolating the aimed talker for
// every consumer, recognition included); the spectral noise
// suppressor then cleans what remains before it reaches the
// recognizer, cloud PCM, endpointing, or speaker verification.
val angleDegrees = currentDecoder.lastAngleDegrees
val ssr = currentDecoder.lastSsr
if (beamFilterEnabled && ssr > 0 && !withinBeam(angleDegrees)) {
emitFrameMeta(angleDegrees, ssr)
maybeEmitAudioStats(false)
continue
}
processPcmChunk(pcm, count, angleDegrees, ssr, true)
maybeEmitAudioStats(false)
}
}
/**
* Per-chunk processing shared by the G2 and phone-mic paths, downstream of
* decode and the beam filter. hasFrameMeta is false for the phone mic,
* which has no firmware DSP metadata to report.
*/
internal fun processPcmChunk(pcm: ShortArray, count: Int, angleDegrees: Int, ssr: Int, hasFrameMeta: Boolean) {
if (suppressionEnabled) {
applySuppression(pcm, count)
}
if (recordingPcm != null) {
appendRecording(pcm, count)
}
val verifyBuffer = this.verifyBuffer
if (verifyBuffer != null && verifyCount < VERIFY_MAX_SAMPLES) {
val copied = min(count, VERIFY_MAX_SAMPLES - verifyCount)
pcm.copyInto(verifyBuffer, verifyCount, 0, copied)
verifyCount += copied
}
if (endpointing && endpointDetector.accept(pcm, count)) {
emitSpeechEnd()
}
// PCM and frame metadata flow in every mode so levels, recording,
// and the Microphones radar keep working alongside onboard ASR.
emitPcm(pcm, count)
if (hasFrameMeta) {
emitFrameMeta(angleDegrees, ssr)
}
if (mode != Mode.CLOUD) {
processRecognizer(AudioSegmentation.pcm16ToFloat(pcm, 0, count))
}
}
/**
* Phone-mic capture loop: no LC3 decode, no arm bookkeeping, no frame
* metadata. The blocking read returns every chunk (50 ms), which bounds how
* long a stop() waits for the loop to notice `started` dropped.
*/
private fun processPhoneAudio(record: PcmAudioSource) {
val pcm = ShortArray(SAMPLE_RATE / 20)
while (started) {
val read = record.read(pcm)
if (read < 0) {
logWarn("phone mic read failed: $read")
return
}
if (read == 0) {
continue
}
decodedSamples += read.toLong()
processPcmChunk(pcm, read, 0, 0, false)
}
}
private fun processRecognizer(samples: FloatArray) {
appendTranscriptSamples(samples)
// Each Whisper call re-encodes the whole buffer plus ~10s of tail padding,
// so it skips the live-partial redecode Moonshine does on this interval and
// only decodes when a segment commits (8s buffer fill) or the utterance ends
// (decodeTranscript(true) in runLoop()). No live preview text in Whisper
// mode -- status stays "Listening..." until release. Deliberate tradeoff.
if (onboardModelKind == VoiceModelKind.WHISPER) {
return
}
val now = platform.elapsedRealtimeMs()
if (transcriptSampleCount >= TRANSCRIPT_MIN_SAMPLES &&
now - lastTranscriptDecodeAtMs >= TRANSCRIPT_DECODE_INTERVAL_MS
) {
decodeTranscript(false)
lastTranscriptDecodeAtMs = now
}
}
private fun appendTranscriptSamples(samples: FloatArray) {
var sourceOffset = 0
while (sourceOffset < samples.size) {
val available = TRANSCRIPT_SEGMENT_MAX_SAMPLES - transcriptSampleCount
val count = min(available, samples.size - sourceOffset)
samples.copyInto(transcriptSamples, transcriptSampleCount, sourceOffset, sourceOffset + count)
transcriptSampleCount += count
sourceOffset += count
if (transcriptSampleCount == TRANSCRIPT_SEGMENT_MAX_SAMPLES) {
commitTranscriptSegment()
}
}
}
/**
* Decode the current model-safe segment and emit the best transcript of the
* complete utterance (REPLACE semantics — the caller displays it as-is).
*/
private fun decodeTranscript(isFinal: Boolean) {
if (recognizer == null || transcriptSampleCount <= 0) {
if (isFinal) {
emitTranscript(lastTranscript, true)
}
return
}
val segmentSampleCount = transcriptSampleCount
var segmentText = recognizeTranscriptSegment(segmentSampleCount)
if (segmentText.isNotEmpty()) {
currentSegmentTranscript = segmentText
} else {
segmentText = currentSegmentTranscript
}
val text = joinTranscript(committedTranscript, segmentText)
lastTranscript = text
logTranscriptDecode(isFinal, segmentSampleCount, text)
emitTranscript(text, isFinal)
}
/**
* Finalize a full segment before accepting more audio. This keeps every
* Moonshine invocation below its failing sequence length while retaining
* all earlier text in the replace-semantics preview.
*/
private fun commitTranscriptSegment() {
val cut = AudioSegmentation.quietestCutPoint(
transcriptSamples, transcriptSampleCount, TRANSCRIPT_CUT_SEARCH_SAMPLES, TRANSCRIPT_CUT_WINDOW_SAMPLES,
)
var segmentText = recognizeTranscriptSegment(cut)
if (segmentText.isEmpty()) {
// Fallback text came from partial decodes of the full buffer, so it
// may include words from the carried-over tail; rare now that decode
// windows are peak-normalized.
segmentText = currentSegmentTranscript
}
committedTranscript = joinTranscript(committedTranscript, segmentText)
currentSegmentTranscript = ""
committedTranscriptSampleCount += cut.toLong()
val tail = transcriptSampleCount - cut
transcriptSamples.copyInto(transcriptSamples, 0, cut, cut + tail)
transcriptSampleCount = tail
lastTranscript = committedTranscript
lastTranscriptDecodeAtMs = platform.elapsedRealtimeMs()
logTranscriptDecode(false, cut, committedTranscript)
emitTranscript(committedTranscript, false)
}
private fun recognizeTranscriptSegment(sampleCount: Int): String {
val currentRecognizer = recognizer
if (currentRecognizer == null || sampleCount <= 0) {
return ""
}
val segment = transcriptSamples.copyOf(sampleCount)
// Whisper hallucinates text on near-silent input; gate it on the
// PRE-normalization peak, since normalizePeak() below would otherwise
// amplify true silence right up to the target level. Moonshine does not
// share this failure mode in practice, so it is left unchanged.
if (onboardModelKind == VoiceModelKind.WHISPER &&
AudioSegmentation.peakAmplitude(segment) < WHISPER_SILENCE_PEAK_THRESHOLD
) {
return ""
}
AudioSegmentation.normalizePeak(segment, TRANSCRIPT_NORMALIZE_TARGET_PEAK, TRANSCRIPT_NORMALIZE_MAX_GAIN)
return currentRecognizer.recognize(segment, segment.size).trim()
}
private fun logTranscriptDecode(isFinal: Boolean, segmentSampleCount: Int, text: String) {
val totalAudioSec = (committedTranscriptSampleCount + transcriptSampleCount) / SAMPLE_RATE.toDouble()
val preview = if (text.length <= TRANSCRIPT_LOG_PREVIEW_CHARS) text
else text.substring(0, TRANSCRIPT_LOG_PREVIEW_CHARS) + "..."
logInfo(
(if (onboardModelKind == VoiceModelKind.WHISPER) "Whisper" else "Moonshine") + " decode final=" + isFinal +
" audioSec=" + formatFixed(totalAudioSec, 2) +
" segmentAudioSec=" + formatFixed(segmentSampleCount / SAMPLE_RATE.toDouble(), 2) +
" textLen=" + text.length + " text=\"" + preview + "\"",
)
}
private fun resetTranscriptState() {
transcriptSampleCount = 0
committedTranscriptSampleCount = 0
committedTranscript = ""
currentSegmentTranscript = ""
lastTranscriptDecodeAtMs = 0
}
private fun emitPcm(pcm: ShortArray, count: Int) {
val currentListener = listener
if (currentListener == null || count <= 0) {
return
}
val le = AudioSegmentation.pcm16ToLittleEndian(pcm, 0, count)
host.dispatcher.post { currentListener.onPcm(le) }
}
/**
* Embed the session's buffered utterance and compare it to the enrolled
* wearer voice-print. Fails open: a session too short to verify, or a
* model that will not load, counts as the wearer rather than silencing
* every command.
*/
private fun runSpeakerVerification() {
val buffer = verifyBuffer
val wearer = verifyWearerEmbedding
val modelPath = verifySpeakerModelPath
verifyBuffer = null
if (buffer == null || wearer == null || modelPath == null) {
return
}
if (verifyCount < VERIFY_MIN_SAMPLES) {
emitSpeakerVerified(true, 0f)
return
}
try {
val embedder = host.speakerEmbedder(modelPath)
val le = AudioSegmentation.pcm16ToLittleEndian(buffer, 0, verifyCount)
val embedding = embedder.embed(le, SAMPLE_RATE)
if (embedding == null || embedding.size != wearer.size) {
emitSpeakerVerified(true, 0f)
return
}
val dot = VoicePrint.dot(embedding, wearer)
val isWearer = dot >= verifyThreshold
logInfo(
"speaker verification similarity=" + formatFixed(dot, 3) +
" threshold=" + verifyThreshold + " isWearer=" + isWearer,
)
emitSpeakerVerified(isWearer, dot.toFloat())
} catch (t: Throwable) {
logWarn("speaker verification failed (${t.message})")
emitSpeakerVerified(true, 0f)
}
}
private fun emitSpeakerVerified(isWearer: Boolean, similarity: Float) {
val currentListener = listener ?: return
host.dispatcher.post { currentListener.onSpeakerVerified(isWearer, similarity) }
}
private fun emitFrameMeta(angleDegrees: Int, ssr: Int) {
val currentListener = listener ?: return
host.dispatcher.post { currentListener.onFrameMeta(angleDegrees, ssr) }
}
private fun emitSpeechEnd() {
val currentListener = listener ?: return
host.dispatcher.post { currentListener.onSpeechEnd() }
}
private fun emitStopped(captureId: Int) {
val currentListener = listener ?: return
host.dispatcher.post { currentListener.onStopped(captureId) }
}
private fun stopG2Audio() {
host.g2AudioSource()?.stop()
maybeEmitAudioStats(true)
}
private fun releaseRecognizer() {
recognizer?.release()
recognizer = null
}
private fun releaseDecoder() {
packetDecoder?.close()
packetDecoder = null
}
/** Called from the BLE notification thread for every glasses mic packet. */
fun queueAudioPacket(data: ByteArray?, arm: String?, arrivalMs: Long) {
if (!started || data == null) {
return
}
if ("L" != arm) {
wrongArmPackets++
}
audioQueue.put(AudioPacket(data, arm, arrivalMs)) {
queuedPackets++
if (lastPacketArrivalMs > 0) {
val delta = arrivalMs - lastPacketArrivalMs
if (delta > maxInterPacketMs) {
maxInterPacketMs = delta
}
if (delta > LATE_PACKET_INTERVAL_MS) {
latePackets++
}
}
lastPacketArrivalMs = arrivalMs
}
}
private fun takeAudioPacket(): AudioPacket? {
val packet = audioQueue.take(250) { started }
if (packet == null) {
maybeEmitAudioStats(false)
}
return packet
}
private fun resetAudioStats() {
queuedPackets = 0
decodedSamples = 0
latePackets = 0
wrongArmPackets = 0
lastPacketArrivalMs = 0
maxInterPacketMs = 0
lastStatsAtMs = platform.elapsedRealtimeMs()
}
/** Diagnostic packet accounting for tests and adapters. */
class AudioStats(
val queuedPackets: Long,
val queueDroppedPackets: Long,
val latePackets: Long,
val wrongArmPackets: Long,
val maxInterPacketMs: Long,
val decodedSamples: Long,
)
fun audioStats(): AudioStats = AudioStats(
queuedPackets, audioQueue.droppedCount, latePackets, wrongArmPackets, maxInterPacketMs, decodedSamples,
)
private fun maybeEmitAudioStats(force: Boolean) {
val now = platform.elapsedRealtimeMs()
if (!force && now - lastStatsAtMs < STATS_INTERVAL_MS) {
return
}
lastStatsAtMs = now
val currentDecoder = packetDecoder
val real = currentDecoder?.realPackets ?: 0L
val duplicate = currentDecoder?.duplicatePackets ?: 0L
val missing = currentDecoder?.missingPackets ?: 0L
val decodeErrors = currentDecoder?.decodeErrors ?: 0L
val status = "G2 mic packets=" + queuedPackets +
" decoded=" + real +
" missing=" + missing +
" duplicate=" + duplicate +
" late=" + latePackets +
" maxGapMs=" + maxInterPacketMs +
" queueDrop=" + audioQueue.droppedCount +
" decodeErrors=" + decodeErrors +
" wrongArm=" + wrongArmPackets +
" audioSec=" + formatFixed(decodedSamples / SAMPLE_RATE.toDouble(), 1)
// Audio-pipeline stats are diagnostic; keep them in the log only, out of
// the on-glasses voice UI.
logInfo(status + " expectedIntervalMs=" + EXPECTED_PACKET_INTERVAL_MS)
}
private fun emitStatus(status: String?) {
val currentListener = listener ?: return
host.dispatcher.post { currentListener.onStatus(status) }
}
private fun emitTranscript(text: String?, isFinal: Boolean) {
val currentListener = listener ?: return
logInfo("Emit transcript final=" + isFinal + " textLen=" + (text?.trim()?.length ?: 0))
host.dispatcher.post { currentListener.onTranscript(text, isFinal) }
}
}
@@ -0,0 +1,137 @@
package com.faceclaw.app
import kotlin.math.abs
import kotlin.math.round
/** Which on-device model ONBOARD voice input loads. */
enum class VoiceModelKind {
MOONSHINE,
WHISPER,
}
/**
* Whole-utterance (offline) recognizer: each call decodes one complete buffer. The Android
* implementation wraps sherpa-onnx; a streaming recognizer (Apple Speech) could satisfy this
* by buffering and re-running, but the session's REPLACE-semantics partials assume re-decoding
* the same buffer is cheap enough on the MOONSHINE cadence.
*/
interface OfflineTranscriber {
/** Returns the trimmed text for [count] float samples at 16 kHz, or "" when nothing was recognized. */
fun recognize(samples: FloatArray, count: Int): String
fun release()
}
/** Speaker voice-print extraction over 16 kHz mono S16LE PCM; null when unavailable or too short. */
interface SpeakerEmbedder {
fun embed(pcm16le: ByteArray, sampleRate: Int): FloatArray?
fun release()
}
/** Marshals listener callbacks to the platform's UI/JS thread (Android: the main Handler). */
fun interface CallbackDispatcher {
fun post(action: () -> Unit)
}
/** Receives the session's decoded PCM once capture ends (Android saves a WAV file). */
fun interface RecordingSink {
fun save(pcm16le: ByteArray, sampleRate: Int)
}
/** A G2 microphone packet decoder (the shared [Lc3PacketFramer] over a platform LC3 codec). */
interface AudioPacketDecoder {
fun decodePacket(packet: ByteArray?, pcmOut: ShortArray?): Int
val lastAngleDegrees: Int
val lastSsr: Int
val realPackets: Long
val duplicatePackets: Long
val missingPackets: Long
val decodeErrors: Long
fun close()
}
/** Glasses microphone packets over BLE (Android: FaceclawBleCommunicator's capture API). */
interface PacketAudioSource {
fun start(listener: FaceclawAudioPacketListener): Boolean
fun stop()
/** Whether the glasses are still delivering packets for this capture. */
fun isActive(): Boolean
}
/** The phone's own microphone delivering 16 kHz mono PCM16 in blocking reads. */
interface PcmAudioSource {
/** Blocking read into [pcm]; returns samples read, 0 to retry, or a negative error. */
fun read(pcm: ShortArray): Int
fun close()
}
/** Formats [value] with exactly [decimals] fraction digits (the shared stand-in for %.Nf). */
fun formatFixed(value: Double, decimals: Int): String {
var scale = 1L
repeat(decimals) { scale *= 10 }
val scaled = round(abs(value) * scale).toLong()
val whole = scaled / scale
val fraction = scaled % scale
val sign = if (value < 0 && scaled != 0L) "-" else ""
return if (decimals == 0) "$sign$whole" else "$sign$whole." + fraction.toString().padStart(decimals, '0')
}
/**
* Bounded FIFO between a producer thread and one consumer: when full the oldest item is
* dropped (counted). [take] waits up to [waitMs] and returns null on timeout or when [open] is
* false, so the consumer can poll a stop flag and emit periodic diagnostics.
*/
class DroppingPacketQueue<T : Any>(private val capacity: Int, platform: ProtocolPlatform = protocolPlatform()) {
private val condition = platform.createCondition()
private val items = ArrayDeque<T>()
var droppedCount: Long = 0
private set
fun put(item: T) {
condition.withLock {
if (items.size >= capacity) {
items.removeFirst()
droppedCount++
}
items.addLast(item)
condition.signalAll()
}
}
/** Runs [action] while holding the queue lock, after enqueuing (used to update stats atomically). */
fun put(item: T, action: () -> Unit) {
condition.withLock {
if (items.size >= capacity) {
items.removeFirst()
droppedCount++
}
items.addLast(item)
action()
condition.signalAll()
}
}
fun take(waitMs: Long, open: () -> Boolean): T? {
condition.withLock {
if (items.isEmpty() && open()) condition.awaitMs(waitMs)
return items.removeFirstOrNull()
}
}
fun clear() {
condition.withLock {
items.clear()
droppedCount = 0
}
}
fun wake() {
condition.withLock { condition.signalAll() }
}
}
@@ -0,0 +1,104 @@
package com.faceclaw.app
import kotlin.jvm.JvmStatic
import kotlin.math.sqrt
/** Voice-print (speaker embedding) vector math shared by extraction, verification and storage. */
object VoicePrint {
/** L2-normalizes [v] in place and returns it; a null or zero vector is returned unchanged. */
@JvmStatic
fun l2Normalize(v: FloatArray?): FloatArray? {
if (v == null) return null
var sum = 0.0
for (x in v) sum += x.toDouble() * x
val norm = sqrt(sum)
if (norm <= 0) return v
for (i in v.indices) v[i] = (v[i] / norm).toFloat()
return v
}
/** Dot product; on L2-normalized vectors this is the cosine similarity. */
@JvmStatic
fun dot(a: FloatArray, b: FloatArray): Double {
require(a.size == b.size) { "embedding sizes differ: ${a.size} vs ${b.size}" }
var sum = 0.0
for (i in a.indices) sum += a[i].toDouble() * b[i]
return sum
}
/** Utterances shorter than this (~0.5 s of S16 mono at [sampleRate]) produce unreliable prints. */
@JvmStatic
fun isLongEnoughToEmbed(pcm16leBytes: Int, sampleRate: Int): Boolean = pcm16leBytes >= sampleRate
}
/** Persistence-side voice-print math: float32-LE blobs and centroid updates. */
object SpeakerEmbeddings {
/** Decodes a float32-LE blob; null for a null, empty or misaligned blob. */
@JvmStatic
fun blobToFloats(blob: ByteArray?): FloatArray? {
if (blob == null || blob.size < 4 || blob.size % 4 != 0) return null
val out = FloatArray(blob.size / 4)
for (i in out.indices) {
val base = i * 4
val bits = (blob[base].toInt() and 0xff) or
((blob[base + 1].toInt() and 0xff) shl 8) or
((blob[base + 2].toInt() and 0xff) shl 16) or
((blob[base + 3].toInt() and 0xff) shl 24)
out[i] = Float.fromBits(bits)
}
return out
}
@JvmStatic
fun floatsToBlob(values: FloatArray): ByteArray {
val out = ByteArray(values.size * 4)
for (i in values.indices) {
val bits = values[i].toRawBits()
val base = i * 4
out[base] = (bits and 0xff).toByte()
out[base + 1] = ((bits shr 8) and 0xff).toByte()
out[base + 2] = ((bits shr 16) and 0xff).toByte()
out[base + 3] = ((bits shr 24) and 0xff).toByte()
}
return out
}
class Centroid(val embedding: FloatArray, val count: Int)
/**
* Running-mean update of a speaker's centroid with one new print, with the existing
* weight capped at [maxCount] so a long session cannot drown the enrolled voice. A
* missing or differently sized current centroid is replaced by [update] (count 1).
*/
@JvmStatic
fun runningMean(current: FloatArray?, currentCount: Int, update: FloatArray, maxCount: Int): Centroid {
if (current == null || current.size != update.size) return Centroid(update, 1)
val effective = minOf(currentCount, maxOf(1, maxCount))
val merged = FloatArray(current.size)
for (i in merged.indices) merged[i] = (current[i] * effective + update[i]) / (effective + 1)
VoicePrint.l2Normalize(merged)
return Centroid(merged, currentCount + 1)
}
/**
* Blends two centroids weighted by their sample counts when both exist with the same
* size; otherwise keeps [into], falling back to [from] when [into] is missing. Null when
* neither exists.
*/
@JvmStatic
fun blend(from: FloatArray?, fromCount: Int, into: FloatArray?, intoCount: Int): FloatArray? {
if (from != null && into != null && from.size == into.size) {
val blended = FloatArray(into.size)
val total = maxOf(1, fromCount + intoCount)
for (i in blended.indices) blended[i] = (into[i] * intoCount + from[i] * fromCount) / total
VoicePrint.l2Normalize(blended)
return blended
}
return into ?: from
}
/** When merging speakers, the target keeps its conversation insights; it adopts the source's only when it has none. */
@JvmStatic
fun shouldAdoptInsights(targetHasInsights: Boolean, sourceHasInsights: Boolean): Boolean =
!targetHasInsights && sourceHasInsights
}
@@ -0,0 +1,66 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
import kotlin.jvm.JvmStatic
/** RIFF/WAVE header walk shared by the AAC transcoder and the diarizer (16-bit PCM only). */
object WavPcmReader {
/** Bytes of a WAV file the header walk needs at most; chunk payloads beyond it are skipped by offset. */
const val HEADER_PREFIX_BYTES = 65536
class WavInfo(
@JvmField val sampleRate: Int,
@JvmField val channels: Int,
@JvmField val bitsPerSample: Int,
/** Byte offset of the first PCM sample. */
@JvmField val dataOffset: Long,
/** PCM byte count; a zero-length data chunk (header never patched after a crash) is recovered from the file length. */
@JvmField val dataBytes: Long,
)
/**
* Parses the fmt/data chunks from [prefix], the first bytes of a WAV file of [fileLength]
* bytes. Throws IllegalArgumentException for anything that is not 16-bit PCM WAV or whose
* data chunk header lies beyond the prefix.
*/
@JvmStatic
fun parseHeader(prefix: ByteArray, fileLength: Long): WavInfo {
require(prefix.size >= 12 && prefix[0] == 'R'.code.toByte() && prefix[1] == 'I'.code.toByte() &&
prefix[2] == 'F'.code.toByte() && prefix[3] == 'F'.code.toByte() &&
prefix[8] == 'W'.code.toByte() && prefix[9] == 'A'.code.toByte()) { "not a WAV file" }
var sampleRate = 0
var channels = 0
var bits = 0
var offset = 12L
while (offset + 8 <= prefix.size) {
val at = offset.toInt()
val id = u32(prefix, at)
val size = u32(prefix, at + 4).toLong() and 0xffffffffL
offset += 8
when (id) {
0x20746d66 -> { // "fmt "
val available = minOf(size, 16L).toInt()
require(offset + available <= prefix.size) { "truncated fmt chunk" }
val f = offset.toInt()
val audioFormat = u16(prefix, f)
channels = u16(prefix, f + 2)
sampleRate = u32(prefix, f + 4)
bits = u16(prefix, f + 14)
require(audioFormat == 1 && bits == 16) { "only 16-bit PCM WAV is supported" }
offset += size
}
0x61746164 -> { // "data"
require(sampleRate != 0) { "missing fmt or data chunk" }
val dataBytes = if (size > 0) size else fileLength - offset
return WavInfo(sampleRate, channels, bits, offset, maxOf(0L, dataBytes))
}
else -> offset += size
}
}
throw IllegalArgumentException("missing fmt or data chunk")
}
private fun u16(bytes: ByteArray, at: Int): Int = (bytes[at].toInt() and 0xff) or ((bytes[at + 1].toInt() and 0xff) shl 8)
private fun u32(bytes: ByteArray, at: Int): Int = u16(bytes, at) or (u16(bytes, at + 2) shl 16)
}
@@ -0,0 +1,94 @@
package com.faceclaw.app
import kotlin.jvm.JvmStatic
/**
* Offline asset resolution for an unpacked EvenHub app served from a fake per-app origin.
* Shared by the Android WebViewClient interceptor and the iOS WKURLSchemeHandler so both apply
* the same path rules, MIME table and bridge-shim injection.
*/
object EvenHubAssetServer {
/** A resolved request: [relativePath] is root-relative with no leading slash. */
data class Asset(val relativePath: String, val mime: String) {
val isHtml: Boolean
get() = mime == "text/html"
}
/** A loaded response body. */
class Response(val mime: String, val bytes: ByteArray)
/**
* Maps a decoded URL path to a root-relative file path, or null when it escapes the root.
* Empty and "/" paths serve index.html. Segments are normalised lexically ("." and "..");
* platform adapters must still canonicalise the final file to defeat symlinks.
*/
@JvmStatic
fun resolve(urlPath: String?): Asset? {
val path = if (urlPath.isNullOrEmpty() || urlPath == "/") "/index.html" else urlPath
val segments = ArrayList<String>()
for (segment in path.split('/')) {
when (segment) {
"", "." -> continue
".." -> if (segments.isEmpty()) return null else segments.removeAt(segments.size - 1)
else -> segments.add(segment)
}
}
if (segments.isEmpty()) return null
val relative = segments.joinToString("/")
return Asset(relative, mimeTypeFor(segments.last()))
}
/** True when [canonicalFile] lies inside [canonicalRoot] (both already canonicalised, no trailing slash). */
@JvmStatic
fun isInsideRoot(canonicalRoot: String, canonicalFile: String): Boolean =
canonicalFile == canonicalRoot || canonicalFile.startsWith(canonicalRoot.trimEnd('/') + "/")
/**
* Inserts the bridge shim right after `<head...>` when present, else before everything, so
* window.flutter_inappwebview exists before any app script runs.
*/
@JvmStatic
fun injectIntoHtml(html: String, injectScript: String): String {
val tag = "<script>$injectScript</script>"
val headIndex = html.lowercase().indexOf("<head")
if (headIndex >= 0) {
val close = html.indexOf('>', headIndex)
if (close >= 0) return html.substring(0, close + 1) + tag + html.substring(close + 1)
}
return tag + html
}
/** Loads [asset] under [rootDir] with the shim spliced into HTML; null when the file is unreadable. */
@JvmStatic
fun load(rootDir: String, asset: Asset, injectScript: String): Response? {
val path = rootDir.trimEnd('/') + "/" + asset.relativePath
if (!fileExists(path)) return null
val bytes = try { readFileData(path) } catch (e: Exception) { return null }
if (!asset.isHtml) return Response(asset.mime, bytes)
return Response(asset.mime, injectIntoHtml(bytes.decodeToString(), injectScript).encodeToByteArray())
}
/** Extension-based MIME lookup (the union of the Android and iOS tables). */
@JvmStatic
fun mimeTypeFor(name: String): String {
val lower = name.lowercase()
val dot = lower.lastIndexOf('.')
val ext = if (dot >= 0) lower.substring(dot + 1) else ""
return MIME_TYPES[ext] ?: "application/octet-stream"
}
private val MIME_TYPES = mapOf(
"html" to "text/html", "htm" to "text/html",
"js" to "text/javascript", "mjs" to "text/javascript",
"css" to "text/css",
"json" to "application/json",
"wasm" to "application/wasm",
"svg" to "image/svg+xml",
"png" to "image/png", "jpg" to "image/jpeg", "jpeg" to "image/jpeg", "gif" to "image/gif",
"webp" to "image/webp", "ico" to "image/x-icon",
"woff" to "font/woff", "woff2" to "font/woff2", "ttf" to "font/ttf", "otf" to "font/otf",
"txt" to "text/plain", "map" to "text/plain",
"xml" to "application/xml", "mp3" to "audio/mpeg", "wav" to "audio/wav", "ogg" to "audio/ogg",
"mp4" to "video/mp4", "webm" to "video/webm",
)
}
@@ -0,0 +1,219 @@
package com.faceclaw.app
/**
* Connects to the glasses (stock-firmware compatible), reads the device-info / settings
* response, and reports the firmware versions plus the firmware-extension string (empty on
* stock firmware). Used by onboarding to decide whether to flash. Owns its own [StockLink] and
* runs [run] on the caller's worker thread; listener callbacks are synchronous on that thread
* (the platform adapter marshals them). Shows nothing on the lens.
*/
class DeviceInfoProbeFlow(
link: StockLink,
rightAddress: String,
leftAddress: String,
private val listener: FaceclawDeviceInfoProbeListener,
private val timings: StockFlowTimings = StockFlowTimings(),
platform: ProtocolPlatform = protocolPlatform(),
) {
companion object {
const val TAG = "FaceclawDeviceInfo"
/** Connect + auth attempts per arm; a link that drops mid-pairing is retried once the bond settles. */
const val ARM_ATTEMPTS = 3
}
private val rightAddress = rightAddress.trim()
private val leftAddress = leftAddress.trim()
private val sleeper = InterruptibleSleep(platform)
private val session = StockLinkSession(link, ::emitLog, timings, traceFrames = true, platform = platform)
val cancelled: Boolean
get() = session.cancelled
fun cancel() {
session.cancel()
sleeper.interrupt()
}
fun run() {
try {
if (rightAddress.isEmpty()) {
emitError("No right-arm address configured.")
return
}
val haveLeft = leftAddress.isNotEmpty() && !leftAddress.equals(rightAddress, ignoreCase = true)
// Bring up and authenticate BOTH arms before asking for versions. Each arm is its
// own peripheral with its own bond, so on a fresh phone each raises its own pairing
// prompt; completing both here means the flash step (and the app proper) find both
// bonds in place. Strictly one arm at a time: Android pairs with one device at a
// time, and a second arm connected while the first was still pairing has been seen
// to drop within a second and never pair (2026-09-11 logcat).
var rightAuthenticated = bringUpArm(rightAddress, "right")
var leftAuthenticated = false
if (haveLeft && !cancelled) {
leftAuthenticated = bringUpArm(leftAddress, "left")
}
if (cancelled) {
emitError("Cancelled.")
return
}
if (!session.isConnected(rightAddress)) {
// The right lens may have dropped while the left one paired; it is bonded by
// now, so this comes back quickly.
emitLog("right lens disconnected while the left lens was set up; reconnecting")
rightAuthenticated = bringUpArm(rightAddress, "right")
if (cancelled) {
emitError("Cancelled.")
return
}
}
var ack: ByteArray? = null
var rightFailure: String? = null
try {
ack = queryArm(rightAddress, "right", rightAuthenticated)
} catch (e: IllegalStateException) {
rightFailure = StockLinkSession.messageOf(e)
emitLog("right-lens query failed: $rightFailure")
}
// The right lens is the documented control endpoint, but a silent right lens has
// been observed on stock 2.2.9 even after a successful security auth — run the same
// probe against the left lens rather than giving up, and log which lens answered.
if (ack == null && !cancelled && haveLeft) {
emitLog("right lens did not answer the settings query; probing the left lens")
try {
ack = queryArm(leftAddress, "left", leftAuthenticated)
} catch (e: Exception) {
emitLog("left-lens probe failed: " + StockLinkSession.messageOf(e))
}
}
if (cancelled) {
emitError("Cancelled.")
return
}
if (ack == null) {
throw IllegalStateException(
rightFailure
?: ("no response to the device-info query on either lens — check `adb logcat -s " + TAG + "` for the frame trace")
)
}
val info = BleProtocol.parseSettingsFirmwareInfo(ack)
val left = info?.leftVersion ?: ""
val right = info?.rightVersion ?: ""
val extension = info?.extension ?: ""
emitLog("device-info: L=$left R=$right ext=[$extension]")
listener.onResult(left, right, extension)
} catch (e: Exception) {
emitError(if (cancelled) "Cancelled." else StockLinkSession.messageOf(e))
} finally {
session.closeQuietly()
}
}
/**
* Connect to one arm and complete its security-auth exchange, retrying when the link drops
* mid-pairing. Returns whether the auth success was seen (false = connected but
* unconfirmed, tolerated because the custom firmware's response to the exchange is not yet
* hardware-verified); throws when the arm cannot be brought up at all.
*/
private fun bringUpArm(address: String, label: String): Boolean {
var lastFailure: String? = null
var attempt = 1
while (attempt <= ARM_ATTEMPTS && !cancelled) {
if (attempt > 1) {
// A link the OS dropped while it was still pairing comes back once the bond
// settles; reconnecting sooner just fails again.
session.waitForBondToSettle(address, label, sleeper)
if (cancelled) {
break
}
emitLog("retrying the $label lens (attempt $attempt/$ARM_ATTEMPTS): $lastFailure")
sleeper.sleep(timings.armRetryDelayMs.toLong())
}
listener.onState("connecting", label)
try {
session.bringUp(address)
} catch (e: IllegalStateException) {
lastFailure = StockLinkSession.messageOf(e)
emitLog("$label lens: $lastFailure")
attempt++
continue
}
if (cancelled) {
break
}
// Firmware 2.2.9 answers no queries until the security-auth exchange completes over
// an encrypted link; on a phone with no existing bond this is also what triggers SMP
// pairing (and its OS prompt), so it must come before the prelude and query.
listener.onState("authenticating", label)
when (session.authenticate(address, label)) {
StockLinkSession.AuthResult.SUCCESS -> return true
StockLinkSession.AuthResult.UNCONFIRMED -> return false
StockLinkSession.AuthResult.LINK_DROPPED -> {
lastFailure = "link dropped during authentication"
attempt++
}
}
}
if (cancelled) {
return false
}
throw IllegalStateException(
"could not connect to the $label lens ($address): " + lastFailure +
" — if the phone showed a Bluetooth pairing request, accept it and try again"
)
}
/**
* Prelude + settings read on an already connected/authenticated lens. Returns the settings
* ack protobuf, an unsolicited settings push that carried firmware versions, or null when
* the lens never answered the read. Throws on prelude failure; the caller wraps the fallback
* lens's attempt so its failure cannot mask the primary lens's outcome.
*/
private fun queryArm(address: String, label: String, authenticated: Boolean): ByteArray? {
if (cancelled) {
return null
}
listener.onState("querying", label)
// Session prelude, then a settings/device-info read (both arms' versions and the
// firmware-extension string ride back in one response).
session.sendPrelude(
address,
" ($label lens)" +
(if (authenticated) "" else "; authentication did not complete — if the phone shows a Bluetooth pairing request, accept it and try again"),
)
// Two attempts: the first read straight after a fresh pairing has been seen to go
// unanswered while a later one succeeds.
var attempt = 0
while (attempt < 2 && !cancelled) {
val ack = session.readSettings(address, timings.queryTimeoutMs)
if (ack != null) {
return ack
}
// A push with the firmware versions on the device's own magic is as good as the
// ack we asked for.
val pushed = session.unsolicitedSettingsPb
if (pushed != null) {
emitLog("using unsolicited settings push instead of the read ack ($label lens)")
return pushed
}
emitLog("settings query attempt " + (attempt + 1) + " unanswered (" + label + " lens)")
attempt++
}
return null
}
// Log lines reach the platform log through the adapter's onLog (Android: logcat under TAG).
private fun emitLog(line: String) {
listener.onLog(line)
}
private fun emitError(message: String) {
listener.onError(message)
}
}
@@ -0,0 +1,167 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
import kotlin.jvm.JvmStatic
/**
* Stock EVENOTA container layout, validation and CRC-32C, shared by the Android flasher and
* (via stage 3) the iOS port of app/g2/firmware-ota.ts. Mirrors g2flash.py: a 0x40-byte
* header (component count at +8), a 16-byte table-of-contents entry per component
* (offset at +4, CRC at +12), and per component a 128-byte subheader (payload size at +8,
* CRC at +12, NUL-terminated name at +48) followed by the payload.
*
* Validation takes the stricter of the two former implementations: the Android checks
* (component count, CRC in both TOC and subheader, main-app preamble/MRAM ceiling) plus the
* TypeScript ones (TOC/subheader/payload bounds, no overlapping components).
*/
object FirmwareImage {
const val HEADER_SIZE = 0x40
const val TOC_ENTRY_SIZE = 16
const val SUBHEADER_SIZE = 128
const val NAME_OFFSET = 48
const val NAME_MAX = 80
// Firmware 2.2.4 has 5 components; 2.2.6 has 6.
const val MIN_SEGMENTS = 5
const val MAX_SEGMENTS = 6
const val REQUIRED_SEGMENT = "ota/s200_firmware_ota.bin"
const val APP_LOAD_ADDR = 0x00438000L
const val APP_MAX_END = 0x007F0000L
const val APP_PREAMBLE = 0x20
class Segment(
/** Offset of the 128-byte subheader within the image. */
@JvmField val off: Int,
/** Payload size in bytes (payload starts at off + SUBHEADER_SIZE). */
@JvmField val ps: Int,
/** CRC-32C recorded in the table of contents. */
@JvmField val crc: Long,
@JvmField val name: String,
) {
val payloadStart: Int get() = off + SUBHEADER_SIZE
val end: Int get() = payloadStart + ps
}
private val CRC32C_TABLE: IntArray = IntArray(256).also { table ->
for (b in 0 until 256) {
var c = b shl 24
for (i in 0 until 8) {
c = if ((c and 0x80000000.toInt()) != 0) (c shl 1) xor 0x1edc6f41 else c shl 1
}
table[b] = c
}
}
/** CRC-32C, MSB-first, init 0, no final xor (matches g2flash.py crc32c_msb). */
@JvmStatic
fun crc32cMsb(data: ByteArray, offset: Int = 0, length: Int = data.size - offset): Int {
require(offset >= 0 && length >= 0 && offset + length <= data.size)
var crc = 0
for (i in offset until offset + length) {
crc = (crc shl 8) xor CRC32C_TABLE[((crc ushr 24) xor (data[i].toInt() and 0xff)) and 0xff]
}
return crc
}
/** Unsigned CRC-32C as a Long, for comparison with recorded values. */
@JvmStatic
fun crc32cUnsigned(data: ByteArray, offset: Int = 0, length: Int = data.size - offset): Long =
crc32cMsb(data, offset, length).toLong() and 0xffffffffL
@JvmStatic
fun readU32(buf: ByteArray, offset: Int): Long {
if (offset < 0 || offset + 4 > buf.size) throw IllegalStateException("firmware header is truncated")
return (buf[offset].toLong() and 0xffL) or
((buf[offset + 1].toLong() and 0xffL) shl 8) or
((buf[offset + 2].toLong() and 0xffL) shl 16) or
((buf[offset + 3].toLong() and 0xffL) shl 24)
}
@JvmStatic
fun readCString(buf: ByteArray, offset: Int, maxLen: Int): String {
var end = offset
val limit = minOf(buf.size, offset + maxLen)
while (end < limit && buf[end].toInt() != 0) end++
return buildString(end - offset) { for (i in offset until end) append((buf[i].toInt() and 0xff).toChar()) }
}
/** Parses the table of contents without checking CRCs; throws on bounds violations. */
@JvmStatic
fun parseSegments(img: ByteArray): List<Segment> {
if (img.size < HEADER_SIZE) throw IllegalStateException("file is too small to be a firmware image")
val n = readU32(img, 8)
if (n <= 0 || n > 64) throw IllegalStateException("implausible component count $n (corrupt image?)")
val count = n.toInt()
val tocEnd = HEADER_SIZE + count * TOC_ENTRY_SIZE
if (tocEnd > img.size) throw IllegalStateException("table of contents runs past end of file")
val segs = ArrayList<Segment>(count)
for (i in 0 until count) {
val base = HEADER_SIZE + i * TOC_ENTRY_SIZE
val crc = readU32(img, base + 12)
val offLong = readU32(img, base + 4)
if (offLong < tocEnd || offLong + SUBHEADER_SIZE > img.size) {
throw IllegalStateException("segment $i subheader is out of bounds")
}
val off = offLong.toInt()
val psLong = readU32(img, off + 8)
if (psLong <= 0 || off + SUBHEADER_SIZE + psLong > img.size) {
throw IllegalStateException("segment $i payload is truncated")
}
val name = readCString(img, off + NAME_OFFSET, NAME_MAX)
val seg = Segment(off, psLong.toInt(), crc, name)
for (other in segs) {
if (seg.off < other.end && other.off < seg.end) {
throw IllegalStateException("components ${other.name} and ${seg.name} overlap")
}
}
segs.add(seg)
}
return segs
}
/** Full validation: layout, component count, CRCs, and the main-app preamble/MRAM check. */
@JvmStatic
fun validate(img: ByteArray): List<Segment> {
val segs = parseSegments(img)
if (segs.size < MIN_SEGMENTS || segs.size > MAX_SEGMENTS) {
throw IllegalStateException("expected $MIN_SEGMENTS-$MAX_SEGMENTS components, found ${segs.size}")
}
var main: Segment? = null
for (s in segs) {
val calc = crc32cUnsigned(img, s.payloadStart, s.ps)
val subCrc = readU32(img, s.off + 12)
if (calc != s.crc || calc != subCrc) {
throw IllegalStateException("component ${s.name} CRC32C is stale (image not checksum-fixed)")
}
if (REQUIRED_SEGMENT == s.name) {
if (main != null) throw IllegalStateException("required component $REQUIRED_SEGMENT is duplicated")
main = s
}
}
if (main == null) throw IllegalStateException("required component $REQUIRED_SEGMENT not found")
checkMainAppFitsMram(img, main)
return segs
}
@JvmStatic
fun checkMainAppFitsMram(img: ByteArray, main: Segment) {
if (main.ps < APP_PREAMBLE) throw IllegalStateException("main-app payload is smaller than its preamble")
val loadAddr = readU32(img, main.payloadStart + 0x14)
val preLen = readU32(img, main.payloadStart) and 0xFFFFFFL
if (loadAddr != APP_LOAD_ADDR) {
throw IllegalStateException(
"main-app preamble load address is 0x" + loadAddr.toString(16) +
", expected 0x" + APP_LOAD_ADDR.toString(16))
}
if (preLen != main.ps.toLong()) {
throw IllegalStateException("main-app preamble length ($preLen) != staged payload size (${main.ps})")
}
val progEnd = APP_LOAD_ADDR + main.ps - APP_PREAMBLE
if (progEnd > APP_MAX_END) {
val over = progEnd - APP_MAX_END
throw IllegalStateException(
"main-app is too large: programmed region ends at 0x" + progEnd.toString(16) +
", " + over + " bytes past the safe MRAM ceiling — refusing to flash (brick risk)")
}
}
}
@@ -0,0 +1,353 @@
package com.faceclaw.app
import kotlin.concurrent.Volatile
/**
* A minimal, stock-firmware-compatible flow used only to show the pre-flash confirmation
* prompt on the glasses and read back the user's Yes/No choice. It speaks only the stock subset
* — session prelude, a text container, a list container, and heartbeats. No images.
*
* Both arms are connected and security-authenticated up front, even though the prompt itself
* only needs the right arm (the lenses relay messages to each other, and acks/events only ever
* come from the right arm): on an unbonded phone the auth exchange is what raises the OS
* pairing prompt, and doing both here means both prompts appear at the start rather than one
* popping up half way through flashing the second lens. While connected, each arm's battery
* level is read (they are independent batteries) so the caller can refuse to flash on a low
* charge.
*
* With `skipPrompt` the on-glasses confirmation is not shown: the flow is just connect + auth +
* battery read + result(approved). Used to re-check the battery after the user has already
* confirmed once. [run] executes on the caller's worker thread; the heartbeat runs on its own
* thread while the prompt is up.
*/
class FlashPromptFlow(
link: StockLink,
rightAddress: String,
leftAddress: String,
warningText: String,
private val skipPrompt: Boolean,
private val listener: FaceclawFlashPromptListener,
private val timings: StockFlowTimings = StockFlowTimings(),
platform: ProtocolPlatform = protocolPlatform(),
) {
companion object {
const val TAG = "FaceclawFlashPrompt"
const val TEXT_NAME = "flashwarn"
const val LIST_NAME = "flashmenu"
const val TEXT_CONTAINER_ID = 1
const val LIST_CONTAINER_ID = 2
// Index 0 = decline, index 1 = approve. Kept short for the ~50-col grid.
val ITEMS = arrayOf("No, cancel", "Yes, flash")
}
private val rightAddress = rightAddress.trim()
private val leftAddress = leftAddress.trim()
private val warningText = warningText
private val platform = platform
private val lock = platform.createLock()
private val sleeper = InterruptibleSleep(platform)
private val selectionLatch = Latch(1, platform)
private val session = StockLinkSession(link, ::emitLog, timings, platform = platform)
@Volatile
private var finished = false
@Volatile
private var rightConnected = false
@Volatile
private var leftConnected = false
@Volatile
private var rightLost = false
@Volatile
private var approved: Boolean? = null
/** The running heartbeat's sleeper; interrupting it ends that thread. */
@Volatile
private var heartbeat: InterruptibleSleep? = null
val cancelled: Boolean
get() = session.cancelled
init {
session.onEvent = { _, frame -> handleEvent(frame) }
session.onDisconnected = ::handleDisconnected
}
/** Abort the prompt (e.g. the user backed out on the phone). */
fun cancel() {
session.cancel()
selectionLatch.countDown()
sleeper.interrupt()
stopHeartbeat()
}
fun run() {
try {
if (rightAddress.isEmpty()) {
listener.onState("error", "No right-arm address configured.")
return
}
listener.onState("connecting", "")
connectArm(rightAddress, "right")
rightConnected = true
if (cancelled) {
teardown()
return
}
if (leftAddress.isNotEmpty()) {
connectArm(leftAddress, "left")
leftConnected = true
if (cancelled) {
teardown()
return
}
}
listener.onState("connected", "")
// Auth both arms now (pairing prompts, if any, happen here) before anything else,
// so both bonds exist by the time flashing starts.
authenticateArm(rightAddress, "right")
if (leftConnected) {
authenticateArm(leftAddress, "left")
}
if (cancelled) {
teardown()
return
}
session.sendPrelude(rightAddress, ": $rightAddress")
if (!skipPrompt) {
showPrompt(rightAddress)
startHeartbeat()
listener.onState("prompting", "")
selectionLatch.await(timings.selectionTimeoutMs.toLong())
stopHeartbeat()
if (cancelled) {
listener.onState("cancelled", "")
teardown()
return
}
if (approved == null) {
if (rightLost) {
listener.onState("disconnected", "Lost connection to the glasses.")
} else {
listener.onState("timeout", "No response from the glasses.")
}
teardown()
return
}
try {
sendShutdown()
} catch (ignored: Exception) {
}
if (approved != true) {
listener.onResult(false)
listener.onState("result", "declined")
teardown()
return
}
}
// Approved (or prompt skipped): read each arm's battery while the links are still
// up, then report the result.
listener.onState("battery", "")
readBatteries()
if (cancelled) {
listener.onState("cancelled", "")
teardown()
return
}
if (rightLost) {
listener.onState("disconnected", "Lost connection to the glasses.")
teardown()
return
}
finished = true
listener.onResult(true)
listener.onState("result", "approved")
teardown()
} catch (e: Exception) {
stopHeartbeat()
if (!cancelled) {
listener.onState("error", StockLinkSession.messageOf(e))
}
teardown()
}
}
private fun connectArm(address: String, arm: String) {
try {
session.bringUp(address)
} catch (e: IllegalStateException) {
throw IllegalStateException(StockLinkSession.messageOf(e) + ": $arm arm ($address)")
}
emitLog("connected $arm arm")
}
/**
* Security-auth exchange on sid=0x80: firmware 2.2.9 will not run a session (and closes
* the link after ~30 s) without it, and on an unbonded phone this is what triggers SMP
* pairing, so it may sit waiting on an OS pairing prompt.
*/
private fun authenticateArm(address: String, arm: String) {
if (session.authenticate(address, arm) != StockLinkSession.AuthResult.SUCCESS) {
throw IllegalStateException(
"could not authenticate with the $arm arm ($address" +
") — if the phone shows a Bluetooth pairing request, accept it and try again"
)
}
emitLog("security auth complete: $arm arm")
}
private fun showPrompt(address: String) {
// Create the prompt page (warning text + No/Yes list) on sid=0xe0 Cmd=0. Two attempts:
// on 2.2.9 the first request sent right after the prelude can be dropped while the lens
// emits its own sid-0x80 notifications (observed with the device-info settings read).
var pageAck: ByteArray? = null
var attempt = 0
while (attempt < 2 && pageAck == null && !cancelled) {
val magic = session.allocMagic()
val page = BleProtocol.buildCreatePromptPage(magic, TEXT_NAME, TEXT_CONTAINER_ID, warningText, LIST_NAME, LIST_CONTAINER_ID, ITEMS)
pageAck = session.writeAndAwaitAck(address, BleProtocol.SID_EVENHUB, BleProtocol.FLAG_REQUEST, magic, page, timings.createAckTimeoutMs)
if (pageAck == null) {
emitLog("prompt page attempt " + (attempt + 1) + " unacked: " + address)
}
attempt++
}
if (pageAck == null) {
throw IllegalStateException("prompt page not acked: $address")
}
emitLog("prompt page shown on $address")
}
/**
* Read each arm's battery via a sid-0x09 settings read on that arm's own link (the arms
* have independent batteries and each answers with its own). An arm that does not answer
* reports -1; the caller decides what to do with a partial reading.
*/
private fun readBatteries() {
val right = if (rightConnected) readBattery(rightAddress, "right") else -1
val left = if (leftConnected) readBattery(leftAddress, "left") else -1
emitLog("battery R=" + (if (right < 0) "?" else "$right%") + " L=" + (if (left < 0) "?" else "$left%"))
listener.onBattery(right, left)
}
private fun readBattery(address: String, arm: String): Int {
var attempt = 0
while (attempt < 2 && !cancelled) {
val ack = session.readSettings(address, timings.batteryAckTimeoutMs)
if (ack == null) {
emitLog("battery read attempt " + (attempt + 1) + " unacked: " + arm + " arm")
attempt++
continue
}
val snapshot = BleProtocol.parseSettingsBattery(ack)
if (snapshot != null) {
return snapshot.battery
}
emitLog("battery read ack had no battery field: $arm arm")
attempt++
}
return -1
}
private fun startHeartbeat() {
stopHeartbeat()
val ticker = InterruptibleSleep(platform)
heartbeat = ticker
startThread("faceclaw-flash-hb", true) {
while (heartbeat === ticker && ticker.sleep(timings.heartbeatIntervalMs.toLong())) {
if (heartbeat !== ticker) break
sendHeartbeat()
}
}
}
private fun sendHeartbeat() {
if (finished || cancelled) {
return
}
try {
val heartbeat = BleProtocol.buildHeartbeat(session.allocMagic())
if (rightConnected) {
session.writeFrame(rightAddress, BleProtocol.SID_EVENHUB, BleProtocol.FLAG_REQUEST, heartbeat)
}
} catch (e: Exception) {
emitLog("heartbeat failed: " + e.message)
}
}
private fun stopHeartbeat() {
val ticker = heartbeat ?: return
heartbeat = null
ticker.interrupt()
}
private fun sendShutdown() {
val shutdown = BleProtocol.buildShutdown(session.allocMagic(), 0)
if (rightConnected) {
session.writeFrame(rightAddress, BleProtocol.SID_EVENHUB, BleProtocol.FLAG_REQUEST, shutdown)
}
}
private fun teardown() {
finished = true
stopHeartbeat()
session.closeQuietly()
rightConnected = false
leftConnected = false
}
private fun handleEvent(frame: BleProtocol.ParsedFrame) {
val selection = BleProtocol.parseListSelection(frame) ?: return
if (LIST_NAME != selection.containerName) {
return
}
// Only a confirmed click is a decision; scroll/highlight changes are ignored.
if (selection.eventType != BleProtocol.EVENT_CLICK) {
return
}
val itemName = selection.itemName
val yes = selection.itemIndex == 1 || (itemName != null && itemName.lowercase().startsWith("yes"))
lock.withLock {
if (finished) {
return
}
finished = true
approved = yes
}
emitLog("selection: " + (if (yes) "flash" else "cancel") + " (index " + selection.itemIndex + ")")
selectionLatch.countDown()
}
private fun handleDisconnected(address: String) {
if (address.equals(leftAddress, ignoreCase = true)) {
// The prompt itself only needs the right arm; a dropped left link just means no
// left battery reading.
leftConnected = false
emitLog("left arm disconnected")
return
}
if (address.equals(rightAddress, ignoreCase = true)) {
rightConnected = false
lock.withLock {
if (!finished && !cancelled) {
rightLost = true
finished = true
selectionLatch.countDown()
}
}
}
}
// Log lines reach the platform log through the adapter's onLog (Android: logcat under TAG).
private fun emitLog(line: String) {
listener.onLog(line)
}
}
@@ -0,0 +1,312 @@
package com.faceclaw.app
/**
* Ports g2flash.py's OTA flash procedure. Streams the EVENOTA firmware container to each lens
* over the firmware-data service using the aa21 envelope (BleProtocol.framePb) and the c0/c1
* control/data protocol.
*
* Each lens connection completes the sid-0x80 security-auth exchange before OTA BEGIN —
* firmware 2.2.9 closes unauthenticated links ~30 s in, killing the transfer mid-component. No
* control-channel traffic is injected during the transfer itself: official OTA captures show
* none between BEGIN and the final END, heartbeats demonstrably do not satisfy the 2.2.9
* deadline, and a concurrent control writer would interleave with the marker/data
* transactions. (See notes/ble-connections-2.2.9.md.)
*
* Lenses are flashed one at a time (left, then right). Finishing either lens reboots BOTH
* lenses, so the second lens is briefly unreachable — the reconnect for it uses a generous
* window rather than failing fast. [run] executes on the caller's worker thread.
*/
class OtaFlashFlow(
link: StockLink,
rightAddress: String,
leftAddress: String,
private val firmwarePath: String,
private val listener: FaceclawFirmwareFlasherListener,
private val timings: StockFlowTimings = StockFlowTimings(),
platform: ProtocolPlatform = protocolPlatform(),
/** Test seam: the firmware container bytes; defaults to reading [firmwarePath]. */
private val readImage: (String) -> ByteArray = ::readFirmwareFile,
) {
companion object {
const val TAG = "FaceclawFlasher"
// OTA message types (envelope sid byte) and control opcodes.
const val SID_CTRL = 0xc0
const val SID_DATA = 0xc1
const val FLAG_OTA = 0x00
const val OP_BEGIN = 0x00
const val OP_FILE_CHECK = 0x01
const val OP_BLOCK = 0x02
const val OP_END = 0x03
const val BLOCK_SIZE = 4096
const val BLOCK_NAK_RETRIES = 3
const val COMPONENT_RETRIES = 3
// END ack statuses that mean "component accepted": SUCCESS, UPDATING, SYS_RESTART.
private val END_OK = intArrayOf(0, 8, 9)
private val EMPTY = ByteArray(0)
fun isEndOk(status: Int): Boolean = END_OK.contains(status)
private fun readFirmwareFile(path: String): ByteArray =
try {
readFileData(path)
} catch (e: Exception) {
throw IllegalStateException("could not read firmware: " + e.message, e)
}
}
private val rightAddress = rightAddress.trim()
private val leftAddress = leftAddress.trim()
private val sleeper = InterruptibleSleep(platform)
// The auth exchange uses its own magic range (0x60..0x7f) and the OTA envelope counter
// starts at 1, mirroring the stock sequence.
private val session = StockLinkSession(link, ::emitLog, timings, magicStart = 0x60, magicEnd = 0x7f, seqStart = 1, platform = platform)
val cancelled: Boolean
get() = session.cancelled
fun cancel() {
session.cancel()
sleeper.interrupt()
}
fun run() {
try {
if (leftAddress.isEmpty() || rightAddress.isEmpty()) {
throw IllegalStateException("Both lens addresses are required to flash.")
}
listener.onState("validating", "")
val img = readImage(firmwarePath)
val segs = FirmwareImage.validate(img)
emitLog("firmware validated: " + segs.size + " components, " + img.size + " bytes")
flashLens("left", leftAddress, img, segs, timings.firstLensConnectWindowMs)
if (cancelled) {
listener.onState("error", "Cancelled.")
listener.onComplete(false, "Cancelled after the left lens.")
return
}
listener.onState("rebooting", "Left lens done. Both lenses reboot briefly; reconnecting for the right lens.")
sleeper.sleep(timings.rebootSettleMs.toLong())
flashLens("right", rightAddress, img, segs, timings.secondLensConnectWindowMs)
listener.onState("done", "")
listener.onComplete(true, "Both lenses flashed. The glasses are rebooting into the custom firmware.")
} catch (e: Exception) {
val message = if (cancelled) "Cancelled." else StockLinkSession.messageOf(e)
listener.onState("error", message)
listener.onComplete(false, message)
} finally {
session.closeQuietly()
}
}
private fun flashLens(lens: String, address: String, img: ByteArray, segs: List<FirmwareImage.Segment>, connectWindowMs: Int) {
listener.onState("connecting", lens)
connectLensResilient(lens, address, connectWindowMs)
sleeper.sleep(timings.notifySettleMs.toLong())
session.otaAcks.clear()
// Fresh envelope counter for the OTA stream (the auth exchange during bring-up used its
// own); mirrors the stock sequence.
session.resetSeq(1)
listener.onState("flashing", lens)
val beginStatus = sendCtrlAndWait(address, OP_BEGIN, EMPTY, timings.ctrlAckTimeoutMs)
if (!isEndOk(beginStatus)) {
emitLog("warning: unexpected begin status $beginStatus; continuing")
}
// Progress is reported in bytes across the whole image: the segments are one large
// firmware blob plus several small ones, so a bar stepped per segment would sit still
// through the big one and then sprint through the rest.
var totalBytes = 0L
for (seg in segs) {
totalBytes += seg.ps
}
var bytesBefore = 0L
for (i in segs.indices) {
if (cancelled) {
throw IllegalStateException("Cancelled.")
}
flashComponentWithRetry(lens, address, i, segs.size, segs[i], img, bytesBefore, totalBytes)
bytesBefore += segs[i].ps
}
emitLog("$lens lens: all components verified")
session.disconnectQuietly(address)
}
private fun flashComponentWithRetry(
lens: String,
address: String,
index: Int,
count: Int,
seg: FirmwareImage.Segment,
img: ByteArray,
bytesBefore: Long,
totalBytes: Long,
) {
for (attempt in 0 until COMPONENT_RETRIES) {
if (attempt > 0) {
emitLog(seg.name + ": re-flash attempt " + (attempt + 1) + "/" + COMPONENT_RETRIES)
}
var endStatus: Int
try {
endStatus = flashComponent(lens, address, index, count, seg, img, bytesBefore, totalBytes)
} catch (e: StockTimeoutException) {
emitLog(seg.name + ": block phase failed: " + e.message)
endStatus = -1
} catch (e: RuntimeException) {
emitLog(seg.name + ": block phase failed: " + e.message)
endStatus = -1
}
if (isEndOk(endStatus)) {
emitLog(seg.name + ": END verify OK (status " + endStatus + ")")
return
}
if (endStatus >= 0) {
emitLog(seg.name + ": END verify FAILED (status " + endStatus + ")")
}
session.otaAcks.clear()
sleeper.sleep(timings.componentRetryDelayMs.toLong())
}
throw IllegalStateException("component " + seg.name + " failed after " + COMPONENT_RETRIES + " attempts")
}
private fun flashComponent(
lens: String,
address: String,
index: Int,
count: Int,
seg: FirmwareImage.Segment,
img: ByteArray,
bytesBefore: Long,
totalBytes: Long,
): Int {
val sub = img.copyOfRange(seg.off, seg.off + FirmwareImage.SUBHEADER_SIZE)
val ps = seg.ps
val payloadStart = seg.off + FirmwareImage.SUBHEADER_SIZE
val checkStatus = sendCtrlAndWait(address, OP_FILE_CHECK, sub, timings.ctrlAckTimeoutMs)
if (checkStatus != 0) {
throw IllegalStateException("FILE_CHECK rejected status=$checkStatus")
}
val blockCount = (ps + BLOCK_SIZE - 1) / BLOCK_SIZE
for (b in 0 until blockCount) {
if (cancelled) {
throw IllegalStateException("Cancelled.")
}
val start = payloadStart + b * BLOCK_SIZE
val end = minOf(start + BLOCK_SIZE, payloadStart + ps)
val block = img.copyOfRange(start, end)
var accepted = false
for (tries in 0 until BLOCK_NAK_RETRIES) {
val status = sendBlock(address, block) // throws StockTimeoutException -> component re-flash
if (status == 0) {
accepted = true
break
}
emitLog(seg.name + ": block " + b + "/" + blockCount + " NAK=" + status + " resend " + (tries + 1) + "/" + BLOCK_NAK_RETRIES)
}
if (!accepted) {
throw IllegalStateException("block " + b + " NAK'd " + BLOCK_NAK_RETRIES + " times")
}
if (b % 20 == 0 || b == blockCount - 1) {
val bytesSent = bytesBefore + minOf((b + 1).toLong() * BLOCK_SIZE, ps.toLong())
listener.onProgress(lens, index + 1, count, b + 1, blockCount, bytesSent, totalBytes)
}
}
emitLog(seg.name + ": data phase done; sending END")
return sendCtrlAndWait(address, OP_END, EMPTY, timings.ctrlAckTimeoutMs)
}
/** Send one 4 KB block as a marker + data pair sharing one envelope seq. */
private fun sendBlock(address: String, block: ByteArray): Int {
val seq = session.nextSeq()
session.otaAcks.clear()
writeOta(address, SID_CTRL, byteArrayOf(OP_BLOCK.toByte()), seq)
writeOta(address, SID_DATA, block, seq)
return waitAck(OP_BLOCK, timings.blockAckTimeoutMs)
}
private fun sendCtrlAndWait(address: String, op: Int, data: ByteArray, timeoutMs: Int): Int {
val seq = session.nextSeq()
session.otaAcks.clear()
val payload = ByteArray(1 + data.size)
payload[0] = op.toByte()
data.copyInto(payload, 1)
writeOta(address, SID_CTRL, payload, seq)
return waitAck(op, timeoutMs)
}
private fun writeOta(address: String, sid: Int, payload: ByteArray, seq: Int): Boolean =
session.writeFrame(address, BleProtocol.OTA_DATA_WRITE_UUID, sid, FLAG_OTA, payload, seq)
private fun waitAck(wantOp: Int, timeoutMs: Int): Int {
val deadline = session.now() + timeoutMs
while (true) {
val remaining = deadline - session.now()
if (remaining <= 0 || cancelled) {
break
}
val pb = session.otaAcks.poll(remaining) ?: break
if (pb.size >= 2 && (pb[0].toInt() and 0xff) == wantOp) {
return pb[1].toInt() and 0xff
}
// Different opcode (e.g. a late ack from a prior stage) — ignore, keep waiting.
}
throw StockTimeoutException("no ack op=0x" + wantOp.toString(16) + " within " + timeoutMs + "ms")
}
// ---- connection ----------------------------------------------------------
private fun connectLensResilient(lens: String, address: String, windowMs: Int) {
val deadline = session.now() + windowMs
var lastError: String? = "unknown"
var attempt = 0
while (session.now() < deadline && !cancelled) {
attempt++
try {
if (bringUpLens(address)) {
emitLog("connected $lens lens (attempt $attempt)")
return
}
lastError = "connect/discover incomplete"
} catch (e: Exception) {
lastError = StockLinkSession.messageOf(e)
}
emitLog("$lens connect attempt $attempt failed ($lastError); retrying...")
session.disconnectQuietly(address)
sleeper.sleep(timings.otaRetryDelayMs.toLong())
}
if (cancelled) {
throw IllegalStateException("Cancelled.")
}
throw IllegalStateException("could not reach $lens lens: $lastError")
}
private fun bringUpLens(address: String): Boolean {
try {
// Control-channel notify carries the auth response; the OTA notify carries the acks.
session.bringUp(address, otaChannel = true)
} catch (e: IllegalStateException) {
return false
}
// Complete the sid-0x80 security-auth exchange on this connection. On an unbonded
// phone this triggers SMP pairing (possibly with an OS prompt), so the wait is
// generous. Must succeed before any OTA traffic.
if (session.authenticate(address, "ota") != StockLinkSession.AuthResult.SUCCESS) {
throw IllegalStateException("security auth not acknowledged — if the phone shows a Bluetooth pairing request, accept it")
}
return true
}
// Log lines reach the platform log through the adapter's onLog (Android: logcat under TAG).
private fun emitLog(line: String) {
listener.onLog(line)
}
}
@@ -8,6 +8,34 @@ interface ProtocolPlatform {
fun createLock(): ProtocolLock
fun createDeflater(): ProtocolDeflater
/** A mutex plus condition variable for blocking waits (see [ProtocolCondition]). */
fun createCondition(): ProtocolCondition
}
/**
* Mutex + condition variable. NOT reentrant: iOS backs it with NSCondition, so a thread that
* already holds the lock must not lock it again (Android's implementation would tolerate it
* and hide the bug). Hold the lock while calling [awaitMs] and [signalAll].
*/
interface ProtocolCondition {
fun lock()
fun unlock()
/** Waits up to [timeoutMs] (spurious wake-ups possible); the lock is held again on return. */
fun awaitMs(timeoutMs: Long)
fun signalAll()
}
inline fun <T> ProtocolCondition.withLock(action: () -> T): T {
lock()
try {
return action()
} finally {
unlock()
}
}
/** Must be reentrant: transport encoding can reset its history under the lock. */
@@ -0,0 +1,91 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
/** Android bond state of a peripheral; iOS reports UNKNOWN (pairing is invisible to the app). */
enum class BondState {
NONE,
BONDING,
BONDED,
UNKNOWN,
}
/** Inbound side of a [StockLink]; called on whatever thread the platform stack delivers on. */
interface StockLinkListener {
fun onNotification(address: String, characteristicUuid: String, data: ByteArray)
fun onConnectionStateChange(address: String, connected: Boolean)
}
/**
* The GATT boundary used by the stock-firmware flows (device-info probe, flash prompt, OTA
* flasher). Calls block on the caller's thread with explicit timeouts; addresses are opaque
* strings (Android MAC, iOS peripheral identifier). Android wraps FaceclawBleManager; an iOS
* implementation sits on CoreBluetooth. Methods other than [isConnected]/[bondState]/
* [disconnect]/[close] may throw IllegalStateException when the link is not connected.
*/
interface StockLink {
fun setListener(listener: StockLinkListener?)
fun connect(address: String, timeoutMs: Int): Boolean
/** Best-effort link tuning after connect (connection priority, MTU). */
fun prepareLink(address: String, desiredMtu: Int, timeoutMs: Int)
fun discoverServices(address: String, timeoutMs: Int): Boolean
fun enableNotifications(address: String, characteristicUuid: String, timeoutMs: Int): Boolean
fun writeFrames(
address: String,
characteristicUuid: String,
frames: List<ByteArray>,
mode: GattWriteMode,
timeoutMs: Int,
): Boolean
fun isConnected(address: String): Boolean
fun bondState(address: String): BondState
fun disconnect(address: String)
fun close()
}
/** A wait for a lens reply expired. */
class StockTimeoutException(message: String) : Exception(message)
/**
* Timeouts and pacing shared by the stock flows. Production uses the defaults; tests shrink
* them. Values are milliseconds unless named otherwise.
*/
class StockFlowTimings(
@JvmField val connectTimeoutMs: Int = ConnectionOptions.CONNECT_TIMEOUT_MS,
@JvmField val servicesTimeoutMs: Int = ConnectionOptions.SERVICES_TIMEOUT_MS,
@JvmField val descriptorTimeoutMs: Int = ConnectionOptions.DESCRIPTOR_TIMEOUT_MS,
@JvmField val writeTimeoutMs: Int = ConnectionOptions.WRITE_TIMEOUT_MS,
@JvmField val preludeTimeoutMs: Int = ConnectionOptions.PRELUDE_TIMEOUT_MS,
@JvmField val securityAuthTimeoutMs: Int = ConnectionOptions.SECURITY_AUTH_TIMEOUT_MS,
@JvmField val securityAuthSoftTimeoutMs: Int = ConnectionOptions.SECURITY_AUTH_SOFT_TIMEOUT_MS,
/** Upper bound on waiting while the OS reports pairing in progress (a dialog may be up). */
@JvmField val pairingWaitCapMs: Int = 90_000,
/** After a fresh bond, how long the firmware gets to notify success before the auth request is re-sent. */
@JvmField val postBondGraceMs: Int = 2_000,
@JvmField val pollMs: Int = 250,
/** Delay between connect/auth attempts on one arm and between auth re-sends. */
@JvmField val armRetryDelayMs: Int = 1_000,
@JvmField val queryTimeoutMs: Int = 4_000,
@JvmField val heartbeatIntervalMs: Int = 4_000,
@JvmField val selectionTimeoutMs: Int = 120_000,
@JvmField val createAckTimeoutMs: Int = 3_000,
@JvmField val batteryAckTimeoutMs: Int = 3_000,
@JvmField val blockAckTimeoutMs: Int = 4_000,
@JvmField val ctrlAckTimeoutMs: Int = 8_000,
@JvmField val firstLensConnectWindowMs: Int = 30_000,
@JvmField val secondLensConnectWindowMs: Int = 120_000,
@JvmField val rebootSettleMs: Int = 5_000,
@JvmField val notifySettleMs: Int = 2_500,
@JvmField val otaRetryDelayMs: Int = 2_500,
@JvmField val componentRetryDelayMs: Int = 1_500,
)
@@ -0,0 +1,443 @@
package com.faceclaw.app
import kotlin.concurrent.Volatile
/**
* The stock-firmware request/reply plumbing that the device-info probe, the flash prompt and
* the OTA flasher all need on top of a [StockLink]: connect + subscribe, envelope sequence and
* magic allocation, frame demux, ack matching keyed by (sid, magic), the bond-aware security
* auth exchange (only the firmware's SUCCESS satisfies it), the unsolicited settings capture,
* async-event and disconnect hooks, and the OTA ack queue. Blocking calls run on the owning
* flow's worker thread; notifications arrive on the platform's callback thread.
*/
class StockLinkSession(
private val link: StockLink,
private val log: (String) -> Unit,
private val timings: StockFlowTimings = StockFlowTimings(),
magicStart: Int = 100,
private val magicEnd: Int = 255,
seqStart: Int = 0x40,
/** Log every parsed control frame with a payload prefix (the probe's 2.2.9 diagnostics). */
private val traceFrames: Boolean = false,
private val platform: ProtocolPlatform = protocolPlatform(),
) : StockLinkListener {
enum class AuthResult {
SUCCESS,
UNCONFIRMED,
LINK_DROPPED,
}
private val lock = platform.createLock()
private val magicStart = magicStart
private var nextMagic = magicStart
private var nextSeq = seqStart
private val pendingAcks = HashMap<String, Latch>()
private val ackPayloads = HashMap<String, ByteArray>()
private val authMagics = HashSet<Int>()
private var authLatch: Latch? = null
/** Latest sid-0x09 frame carrying firmware versions, whatever magic it came with. */
@Volatile
var unsolicitedSettingsPb: ByteArray? = null
private set
/** OTA acks (first two payload bytes: opcode, status) from the data-notify characteristic. */
val otaAcks = BlockingQueue<ByteArray>(platform)
/** Async events (flag 0x01/0x06) on the control characteristic, e.g. list selections. */
@Volatile
var onEvent: ((address: String, frame: BleProtocol.ParsedFrame) -> Unit)? = null
@Volatile
var onDisconnected: ((address: String) -> Unit)? = null
@Volatile
var cancelled = false
private set
init {
link.setListener(this)
}
val platformServices: ProtocolPlatform
get() = platform
fun now(): Long = platform.elapsedRealtimeMs()
/** Wake every pending wait; subsequent waits return immediately as timeouts. */
fun cancel() {
cancelled = true
lock.withLock {
for (latch in pendingAcks.values) latch.countDown()
authLatch?.countDown()
}
}
fun allocMagic(): Int =
lock.withLock {
val magic = nextMagic
nextMagic = if (nextMagic >= magicEnd) magicStart else nextMagic + 1
magic
}
fun nextSeq(): Int =
lock.withLock {
val seq = nextSeq and 0xff
nextSeq = (nextSeq + 1) and 0xff
seq
}
fun resetSeq(value: Int) {
lock.withLock { nextSeq = value and 0xff }
}
/** Connect, tune, discover and subscribe to the control notify (plus the OTA notify when asked). Throws on failure. */
fun bringUp(address: String, otaChannel: Boolean = false) {
if (!link.connect(address, timings.connectTimeoutMs)) {
throw IllegalStateException("connect failed")
}
link.prepareLink(address, ConnectionOptions.DESIRED_MTU, timings.connectTimeoutMs)
if (!link.discoverServices(address, timings.servicesTimeoutMs)) {
throw IllegalStateException("service discovery failed")
}
if (!link.enableNotifications(address, BleProtocol.NOTIFY_CHAR_UUID, timings.descriptorTimeoutMs)) {
throw IllegalStateException("could not subscribe to notifications")
}
if (otaChannel && !link.enableNotifications(address, BleProtocol.OTA_DATA_NOTIFY_UUID, timings.descriptorTimeoutMs)) {
throw IllegalStateException("could not subscribe to OTA notifications")
}
}
fun isConnected(address: String): Boolean = link.isConnected(address)
fun disconnectQuietly(address: String) {
try {
link.disconnect(address)
} catch (ignored: Exception) {
}
}
fun closeQuietly() {
try {
link.close()
} catch (ignored: Exception) {
}
}
/** Frame and write one message on the control characteristic; false when the write failed. */
fun writeFrame(address: String, sid: Int, flag: Int, payload: ByteArray): Boolean =
writeFrame(address, BleProtocol.WRITE_CHAR_UUID, sid, flag, payload, nextSeq())
/** @throws IllegalStateException when the link reports "not connected". */
fun writeFrame(address: String, characteristicUuid: String, sid: Int, flag: Int, payload: ByteArray, seq: Int): Boolean {
val frames = BleProtocol.framePb(payload, sid, flag, seq)
return link.writeFrames(address, characteristicUuid, frames, ConnectionOptions.WRITE_MODE, timings.writeTimeoutMs)
}
/**
* Write a request and wait for the ack carrying the same sid and magic. Returns the ack's
* protobuf (possibly empty), or null on write failure / timeout / cancel.
*/
fun writeAndAwaitAck(address: String, sid: Int, flag: Int, magic: Int, payload: ByteArray, timeoutMs: Int): ByteArray? {
val key = ackKey(sid, magic)
val latch = Latch(1, platform)
lock.withLock {
pendingAcks[key] = latch
ackPayloads.remove(key)
}
try {
val seq = nextSeq()
log(
"tx " + address + " sid=0x" + hex2(sid) + " flag=0x" + hex2(flag) + " magic=" + magic +
" seq=0x" + hex2(seq) + " len=" + payload.size
)
val written =
try {
writeFrame(address, BleProtocol.WRITE_CHAR_UUID, sid, flag, payload, seq)
} catch (e: IllegalStateException) {
// "Not connected" — the link went away underneath us.
false
}
if (!written) {
log("tx write FAILED sid=0x" + sid.toString(16) + " (" + address + ")")
return null
}
if (!latch.await(timeoutMs.toLong()) || cancelled) {
return null
}
return lock.withLock { ackPayloads[key] ?: ByteArray(0) }
} finally {
lock.withLock {
if (pendingAcks[key] === latch) pendingAcks.remove(key)
ackPayloads.remove(key)
}
}
}
/** Mandatory session prelude on sid=0x01; throws when it is not acked. */
fun sendPrelude(address: String, failureDetail: String = "") {
if (writeAndAwaitAck(
address,
BleProtocol.PRELUDE_ACK_SID,
BleProtocol.FLAG_REQUEST,
BleProtocol.PRELUDE_ACK_MAGIC,
BleProtocol.PRELUDE_F5872_PAYLOAD,
timings.preludeTimeoutMs,
) == null
) {
throw IllegalStateException("session prelude not acked$failureDetail")
}
}
/** One sid-0x09 settings read; the ack protobuf or null when unanswered. */
fun readSettings(address: String, timeoutMs: Int): ByteArray? {
val magic = allocMagic()
return writeAndAwaitAck(address, BleProtocol.SID_UI_SETTING, BleProtocol.FLAG_REQUEST, magic, BleProtocol.buildSettingsQuery(magic), timeoutMs)
}
/**
* Send the sid-0x80 authentication request and wait for the firmware's SUCCESS notification,
* which only arrives once the link is encrypted. On an unbonded phone that means waiting
* through the OS pairing flow (BOND_BONDING, possibly with a dialog up), so the wait is
* extended while the OS reports pairing in progress and the request is re-sent once after a
* fresh bond in case the pre-pairing write was dropped. Bond state is polled; 250 ms
* granularity is plenty here. Platforms that cannot see bonding (UNKNOWN) get the plain
* timeout. The first reply with a non-success result is expected before encryption and does
* not satisfy the wait.
*/
fun authenticate(address: String, label: String): AuthResult {
val start = now()
var deadline = start + timings.securityAuthTimeoutMs
val hardDeadline = start + timings.pairingWaitCapMs
val latch = Latch(1, platform)
lock.withLock {
authMagics.clear()
authLatch = latch
}
val initialBond = link.bondState(address)
log("security auth: $label lens, bond state " + bondStateName(initialBond))
try {
var sends = 0
var lastSendFailed = false
var nextSendAt = start
var bondedAt = -1L
var resentAfterBond = false
var loggedBonding = false
while (!cancelled) {
val now = now()
val bond = link.bondState(address)
if (bond == BondState.BONDING) {
// OS pairing in progress — the firmware will answer once the link is
// encrypted. Don't write, don't give up, don't move on to the other arm.
if (!loggedBonding) {
log("the OS is pairing with the $label lens; waiting for the user to accept")
loggedBonding = true
}
if (now >= hardDeadline) {
break
}
} else {
if (bond == BondState.BONDED && initialBond != BondState.BONDED && bondedAt < 0) {
bondedAt = now
log("bond established with the $label lens; waiting for the auth success")
deadline = maxOf(deadline, now + timings.securityAuthSoftTimeoutMs)
}
val wantSend = sends == 0 ||
(lastSendFailed && sends < 3 && now >= nextSendAt) ||
(bondedAt >= 0 && !resentAfterBond && now - bondedAt >= timings.postBondGraceMs)
if (wantSend) {
if (bondedAt >= 0) {
resentAfterBond = true
if (sends > 0) {
log("re-sending the auth request after pairing ($label lens)")
}
}
lastSendFailed = !sendAuthRequest(address)
sends++
nextSendAt = now() + timings.armRetryDelayMs
if (lastSendFailed && !link.isConnected(address)) {
return AuthResult.LINK_DROPPED
}
}
if (now >= deadline) {
break
}
}
if (latch.await(timings.pollMs.toLong()) && !cancelled) {
log("security auth complete: $label lens ($address)")
return AuthResult.SUCCESS
}
if (!link.isConnected(address)) {
log(
"security auth: $label lens disconnected while waiting" +
(if (bond == BondState.BONDING) " (the OS was still pairing)" else "")
)
return AuthResult.LINK_DROPPED
}
}
if (cancelled) {
return AuthResult.UNCONFIRMED
}
log("security auth unconfirmed: $label lens ($address), bond state " + bondStateName(link.bondState(address)))
return AuthResult.UNCONFIRMED
} finally {
lock.withLock {
authLatch = null
authMagics.clear()
}
}
}
private fun sendAuthRequest(address: String): Boolean {
val magic = allocMagic()
lock.withLock { authMagics.add(magic) }
val seq = nextSeq()
val payload = BleProtocol.buildAuthenticationRequest(magic)
log(
"tx " + address + " sid=0x" + hex2(BleProtocol.SID_SECURITY_AUTH) + " flag=0x" + hex2(BleProtocol.FLAG_SECURITY_AUTH) +
" magic=" + magic + " seq=0x" + hex2(seq) + " len=" + payload.size
)
val written =
try {
writeFrame(address, BleProtocol.WRITE_CHAR_UUID, BleProtocol.SID_SECURITY_AUTH, BleProtocol.FLAG_SECURITY_AUTH, payload, seq)
} catch (e: IllegalStateException) {
false
}
if (!written) {
log("tx write FAILED sid=0x80 ($address)")
}
return written
}
/** Block while the OS reports this arm as BONDING (pairing dialog up / SMP in flight). */
fun waitForBondToSettle(address: String, label: String, sleeper: InterruptibleSleep) {
val cap = now() + timings.pairingWaitCapMs
var logged = false
while (!cancelled && link.bondState(address) == BondState.BONDING && now() < cap) {
if (!logged) {
log("waiting for the OS to finish pairing with the $label lens before reconnecting")
logged = true
}
sleeper.sleep(timings.pollMs.toLong())
}
}
// ---- inbound --------------------------------------------------------------
override fun onNotification(address: String, characteristicUuid: String, data: ByteArray) {
if (BleProtocol.OTA_DATA_NOTIFY_UUID.equals(characteristicUuid, ignoreCase = true)) {
val frame = BleProtocol.parseFrame(data)
if (frame.ok && frame.pb.size >= 2) {
otaAcks.put(frame.pb.copyOf(minOf(frame.pb.size, 2)))
}
return
}
if (!BleProtocol.NOTIFY_CHAR_UUID.equals(characteristicUuid, ignoreCase = true)) {
return
}
// One notification value can carry several envelope frames back to back; reading only
// the first would silently drop the rest.
val frames = BleProtocol.splitFrames(data)
if (traceFrames && frames.size > 1) {
log("rx " + address + " value carries " + frames.size + " frames (raw " + data.size + " bytes)")
}
for (buf in frames) {
handleFrame(address, buf, data.size)
}
}
private fun handleFrame(address: String, buf: ByteArray, rawValueLength: Int) {
val frame = BleProtocol.parseFrame(buf)
if (!frame.ok) {
if (traceFrames) {
log(
"rx " + address + " unparseable frame len=" + buf.size + " (raw value " + rawValueLength + ")" +
" head=" + BinaryEncoding.bytesToHex(buf.copyOf(minOf(16, buf.size)))
)
}
return
}
if (traceFrames) {
// Log every control frame while diagnosing 2.2.9: sid/flag/type/magic plus a
// payload prefix is enough to reconstruct what the lens said.
val declared = if (buf.size > 3) buf[3].toInt() and 0xff else 0
val truncated = if (buf.size < 8 + declared) " TRUNCATED(declared=$declared)" else ""
log(
"rx " + address + " sid=0x" + hex2(frame.sid) + " flag=0x" + hex2(frame.flag) + " type=" + frame.msgType +
" magic=" + frame.msgSeq + " frag=" + (if (buf.size > 5) buf[5].toInt() and 0xff else 0) + "/" +
(if (buf.size > 4) buf[4].toInt() and 0xff else 0) + " len=" + frame.pb.size + truncated +
" pb=" + BinaryEncoding.bytesToHex(frame.pb.copyOf(minOf(48, frame.pb.size)))
)
}
if (frame.sid == BleProtocol.SID_UI_SETTING && BleProtocol.parseSettingsFirmwareInfo(frame.pb) != null) {
// Any settings frame carrying firmware versions answers the probe's question,
// whether or not it matches the magic we asked with.
unsolicitedSettingsPb = frame.pb
}
if (frame.flag == BleProtocol.FLAG_NOTIFY || frame.flag == BleProtocol.FLAG_NOTIFY_ALT) {
// Async event, not an ack. This includes the lens's own periodic sid-0x80 notifies
// (device-chosen magic, non-empty result).
onEvent?.invoke(address, frame)
return
}
if (frame.sid == BleProtocol.SID_SECURITY_AUTH) {
var success = false
var ours = false
lock.withLock {
val currentLatch = authLatch
if (currentLatch != null) {
ours = authMagics.contains(frame.msgSeq)
for (magic in authMagics) {
if (BleProtocol.isAuthenticationSuccess(frame.pb, magic)) {
success = true
currentLatch.countDown()
break
}
}
}
}
if (ours && !success) {
// Expected before the link is encrypted: the firmware answers the request
// straight away with a non-success result and sends the real success once
// pairing/encryption completes.
log("auth reply for magic " + frame.msgSeq + " is not the success result; still waiting")
}
return
}
if (frame.msgSeq >= 0) {
val key = ackKey(frame.sid, frame.msgSeq)
lock.withLock {
val latch = pendingAcks[key]
if (latch != null) {
ackPayloads[key] = frame.pb
latch.countDown()
}
}
}
}
override fun onConnectionStateChange(address: String, connected: Boolean) {
if (!connected) {
log("disconnected: $address")
onDisconnected?.invoke(address)
}
}
companion object {
private fun ackKey(sid: Int, magic: Int): String = "$sid:$magic"
internal fun hex2(value: Int): String = (value and 0xff).toString(16).padStart(2, '0')
internal fun bondStateName(state: BondState): String =
when (state) {
BondState.NONE -> "none"
BondState.BONDING -> "bonding"
BondState.BONDED -> "bonded"
BondState.UNKNOWN -> "unknown"
}
internal fun messageOf(e: Throwable): String = e.message ?: e.toString()
}
}
@@ -0,0 +1,695 @@
package com.faceclaw.app
import com.faceclaw.app.GlassesSessionCore.Companion.DASHBOARD_TILE
import com.faceclaw.app.GlassesSessionCore.Companion.FACECLAW_WAKE_CONTROL_WAIT_MS
import com.faceclaw.app.GlassesSessionCore.Companion.TAG
/*
* GlassesSessionCore, part 3: CFW lease controls, EvenHub shutdown, the bandwidth
* benchmark stream, transport-failure handling and the listener emits (all
* marshalled through SessionHost.postToMain, or a subscriber's own dispatcher
* for compass events).
*/
// ---------------------------------------------------------------------------
// Bandwidth benchmark
/** Pending + in-flight benchmark no-op messages. */
internal fun GlassesSessionCore.benchmarkOutstandingLocked(): Int {
var count = 0
for (message in pendingMessages) {
if ("bandwidth" == message.kind) count++
}
for (message in inFlightMessages) {
if ("bandwidth" == message.kind) count++
}
return count
}
/**
* Keep the benchmark stream fed: top the pending queue up so the send
* window never starves, stop enqueueing once the run expires (or a message
* times out), and finish the run when the last outstanding message drains.
*/
internal fun GlassesSessionCore.maintainBenchmarkLocked(now: Long) {
if (!sessionReady || !fixedLayoutCreated || shutdownRequested) {
finishBenchmarkLocked(true, "session no longer ready")
return
}
if (benchmarkLinkPending || now < benchmarkReadyAtMs) {
return
}
if (benchmarkAborted || now >= benchmarkDeadlineAtMs) {
// The run is over: drop queued-but-unsent no-ops (sending them
// would stretch the run past its deadline) and finish once the
// in-flight tail has acked or timed out.
val pendingIterator = pendingMessages.iterator()
while (pendingIterator.hasNext()) {
val queued = pendingIterator.next()
if ("bandwidth" == queued.kind) {
pendingIterator.remove()
magicPool.release(queued.sid, queued.magic, queued.label, "benchmark over")
}
}
if (benchmarkOutstandingLocked() == 0) {
finishBenchmarkLocked(false, "complete")
}
return
}
// One more than the window so a fresh message is always ready to write
// the moment an ack frees a slot.
var outstanding = benchmarkOutstandingLocked()
while (outstanding <= benchmarkWindowSize) {
enqueueBenchmarkMessageLocked()
outstanding++
}
}
internal fun GlassesSessionCore.finishBenchmarkLocked(aborted: Boolean, reason: String) {
if (!benchmarkActive) {
return
}
benchmarkActive = false
benchmarkAborted = benchmarkAborted or aborted
// Prefer the last ack as the end time so drain lag after the deadline
// doesn't dilute the throughput figure.
benchmarkEndAtMs = if (benchmarkLastAckAtMs != 0L) benchmarkLastAckAtMs else now()
logLine("bandwidth benchmark " + (if (benchmarkAborted) "aborted" else "finished") + " (" + reason + "): "
+ benchmarkMessagesAcked + "/" + benchmarkMessagesSent + " acked, "
+ benchmarkPayloadBytesAcked + "B payload, " + benchmarkTimeouts + " timeouts")
}
internal fun GlassesSessionCore.enqueueBenchmarkMessageLocked() {
// Fresh bytes per message: the transport's persistent compression history
// would compress even a random payload if we reused it across the run.
val payload = ByteArray(benchmarkMessageSize)
kotlin.random.Random.nextBytes(payload)
payload[0] = CFW_MSG_DIAGNOSTICS.toByte() // CFW diagnostic-control mode...
payload[1] = 0x7f.toByte() // ...with an unused sub-op: acked, no effect
val message = messageBuilder.imagePayload(
"bandwidth",
DASHBOARD_TILE,
nextMapSessionId(),
payload,
"bandwidth no-op " + payload.size + "B",
connectionOptions.sendImagesToLeft)
val payloadBytes = payload.size
// Logical custom-message bytes; excludes length tag and packet framing.
val wireBytes = message.message.size
message.onSent = MessageCallback {
benchmarkMessagesSent++
if (benchmarkStartAtMs == 0L) {
benchmarkStartAtMs = now()
benchmarkDeadlineAtMs = benchmarkStartAtMs + benchmarkDurationMs
}
}
message.onAck = MessageCallback {
val ackedAtMs = now()
benchmarkMessagesAcked++
benchmarkPayloadBytesAcked += payloadBytes
benchmarkWireBytesAcked += wireBytes
benchmarkLastAckAtMs = ackedAtMs
// No-op payloads ride the image path, so the firmware resets its
// heartbeat timer on them just like real image messages.
lastHeartbeatAckedAtMs = ackedAtMs
}
message.onTimeout = MessageCallback {
benchmarkTimeouts++
benchmarkAborted = true
logLine("bandwidth benchmark ack timeout")
}
pendingMessages.addLast(message)
}
// ---------------------------------------------------------------------------
// EvenHub shutdown and audio control waits
internal fun GlassesSessionCore.sendShutdownInternal(exitMode: Int, reconnectOnTimeout: Boolean): Boolean {
val magic: Int
val startedAtMs = now()
monitor.withLock {
if (!running || !sessionReady) {
logLine("skip shutdown; session not ready")
return false
}
if (shutdownRequested) {
return true
}
shutdownRequested = true
// Magic values wrap, so an ACK from a much older suspend must not
// satisfy this request after enough sleep/wake cycles.
lastShutdownAckMagic = 0
clearPendingMessagesLocked("shutdown requested")
val message = messageBuilder.shutdown(exitMode)
magic = message.magic
message.onAck = MessageCallback {
lastShutdownAckMagic = message.magic
fixedLayoutCreated = false
displayedFingerprint = ""
}
message.onTimeout = MessageCallback {
if (reconnectOnTimeout) {
handleTransportFailure("shutdown ack timeout")
} else {
logLine("EvenHub shutdown ack timeout; keeping BLE connected")
}
}
pendingMessages.addFirst(message)
logLine("queue shutdown")
// The stock compass keeps the magnetometer sampling independently of
// the plugin task, so ending the page does not stop it. Force a
// disable ahead of the shutdown command whenever it may be running:
// this also covers a disable that was wiped by the queue flush above
// or whose ack was lost, and the charging-mode/exit paths where the
// Compass window never got a chance to release it.
if (compassMaybeOn && fixedLayoutCreated) {
enqueueCompassControlLocked(true, false)
}
}
interruptibleSleep.interrupt()
val ackDeadline = now() + ConnectionOptions.ACK_TIMEOUT_MS + 500
monitor.withLock {
while (running
&& sessionReady
&& lastShutdownAckMagic != magic
&& lastShutdownExitAtMs < startedAtMs
&& hasPendingOrInflightMagicLocked(magic)) {
val remaining = ackDeadline - now()
if (remaining <= 0) {
break
}
monitor.awaitMs(minOf(remaining, 100L))
}
val acked = lastShutdownAckMagic == magic
if (acked) {
val exitDeadline = now() + ConnectionOptions.ACK_TIMEOUT_MS + 500
while (running && sessionReady && lastShutdownExitAtMs < startedAtMs) {
val remaining = exitDeadline - now()
if (remaining <= 0) {
break
}
monitor.awaitMs(minOf(remaining, 100L))
}
}
return acked || lastShutdownExitAtMs >= startedAtMs
}
}
internal fun GlassesSessionCore.waitForAudioControlAck(magic: Int, operation: String): Boolean {
val deadline = now() + ConnectionOptions.ACK_TIMEOUT_MS + ConnectionOptions.WRITE_TIMEOUT_MS + 500
monitor.withLock {
while (running && sessionReady && lastAudioControlAckMagic != magic && hasPendingOrInflightMagicLocked(magic)) {
val remaining = deadline - now()
if (remaining <= 0) {
break
}
monitor.awaitMs(minOf(remaining, 100L))
}
val acked = lastAudioControlAckMagic == magic
if (!acked) {
if ("enable" == operation) {
audioPacketListener = null
audioCaptureActive = false
}
logLine("G2 mic $operation ack timeout")
}
return acked
}
}
// ---------------------------------------------------------------------------
// CFW wake and framebuffer leases
/**
* Replace any stale lease control with one right-arm and one left-arm
* fire-and-forget write. With priority=true the right arm is sent first so
* CLAIM reaches the lens that originated the deferred wake immediately.
*/
internal fun GlassesSessionCore.enqueueFaceclawWakeControlLocked(operation: Int, nonce: Int, priority: Boolean): Int {
clearMessagesOfKindLocked("wake-lease-control")
val generation = ++faceclawWakeControlGeneration
faceclawWakeControlSentCount = 0
if (operation == BleProtocol.FACECLAW_WAKE_OP_ACQUIRE) {
lastFaceclawWakeLeaseQueuedAtMs = now()
}
val onSent = MessageCallback {
if (faceclawWakeControlGeneration == generation) {
faceclawWakeControlSentCount += 1
}
}
val right = messageBuilder.faceclawWakeControl(operation, nonce, false)
val left = messageBuilder.faceclawWakeControl(operation, nonce, true)
right.onSent = onSent
left.onSent = onSent
if (priority) {
pendingMessages.addFirst(left)
pendingMessages.addFirst(right)
} else {
pendingMessages.addLast(right)
pendingMessages.addLast(left)
}
logLine("queue " + right.label + " + L")
return generation
}
internal fun GlassesSessionCore.waitForFaceclawWakeControlDelivery(generation: Int, timeoutMs: Long): Boolean {
val deadline = now() + maxOf(0L, timeoutMs)
monitor.withLock {
while (running
&& sessionReady
&& faceclawWakeControlGeneration == generation
&& faceclawWakeControlSentCount < 2) {
val remaining = deadline - now()
if (remaining <= 0) {
break
}
monitor.awaitMs(minOf(remaining, 100L))
}
return faceclawWakeControlGeneration == generation
&& faceclawWakeControlSentCount >= 2
}
}
/**
* Acquire/renew or release CFW's independent direct-framebuffer repaint
* guard on both arms. It is separate from the optional idle-wake lease:
* every Faceclaw display session needs this guard while its EvenHub layout
* contains swipe-capturing stock widgets.
*/
internal fun GlassesSessionCore.enqueueFaceclawFramebufferControlLocked(operation: Int, priority: Boolean): Int {
clearMessagesOfKindLocked("framebuffer-lease-control")
val generation = ++faceclawFramebufferControlGeneration
faceclawFramebufferControlSentCount = 0
if (operation == BleProtocol.FACECLAW_FB_OP_ACQUIRE) {
lastFaceclawFramebufferLeaseQueuedAtMs = now()
}
val onSent = MessageCallback {
if (faceclawFramebufferControlGeneration == generation) {
faceclawFramebufferControlSentCount += 1
}
}
val right = messageBuilder.faceclawFramebufferControl(operation, false)
val left = messageBuilder.faceclawFramebufferControl(operation, true)
right.onSent = onSent
left.onSent = onSent
if (priority) {
pendingMessages.addFirst(left)
pendingMessages.addFirst(right)
} else {
pendingMessages.addLast(right)
pendingMessages.addLast(left)
}
logLine("queue " + right.label + " + L")
return generation
}
internal fun GlassesSessionCore.waitForFaceclawFramebufferControlDelivery(generation: Int, timeoutMs: Long): Boolean {
val deadline = now() + maxOf(0L, timeoutMs)
monitor.withLock {
while (running
&& sessionReady
&& faceclawFramebufferControlGeneration == generation
&& faceclawFramebufferControlSentCount < 2) {
val remaining = deadline - now()
if (remaining <= 0) {
break
}
monitor.awaitMs(minOf(remaining, 100L))
}
return faceclawFramebufferControlGeneration == generation
&& faceclawFramebufferControlSentCount >= 2
}
}
internal fun GlassesSessionCore.releaseFaceclawFramebufferLease(): Boolean {
val generation: Int
monitor.withLock {
if (!running || !sessionReady) {
return true
}
generation = enqueueFaceclawFramebufferControlLocked(
BleProtocol.FACECLAW_FB_OP_RELEASE,
true
)
}
interruptibleSleep.interrupt()
return waitForFaceclawFramebufferControlDelivery(
generation,
FACECLAW_WAKE_CONTROL_WAIT_MS
)
}
// ---------------------------------------------------------------------------
// Failure handling
/** The address of a configured arm the OS no longer holds a bond for, or null. */
internal fun GlassesSessionCore.firstUnpairedArm(): String? {
if (!link.isBonded(rightAddress)) return rightAddress
if (!link.isBonded(leftAddress)) return leftAddress
return null
}
/**
* A connect failure while an arm's bond is missing (the pairing was
* forgotten in the OS settings, or the address was typed in by hand and
* never paired) will repeat forever, so instead of scheduling a retry,
* park the worker loop and tell the user to re-pair. Only an explicit
* connect (which builds a fresh communicator) starts a new attempt.
*/
internal fun GlassesSessionCore.handleUnpairedFailure(address: String) {
logError("Connect failed and $address is not paired; suspending reconnect")
monitor.withLock {
reconnectHalted = true
sessionReady = false
fixedLayoutCreated = false
startupProbePending = false
shutdownRequested = false
chargingMode = false
imageRetryAfterMs = 0
displayedFingerprint = ""
faceclawWakePendingNonce = -1
lastFaceclawWakeLeaseQueuedAtMs = 0
faceclawWakeControlSentCount = 0
clearAllMessagesLocked("arm not paired: $address")
reconnectAfterMs = Long.MAX_VALUE
link.disconnect(rightAddress)
link.disconnect(leftAddress)
}
if (!userDisconnectRequested) {
setStateDisplay(
"unpaired",
"The glasses (" + address + ") are not paired with this phone."
+ " Use \"Pair glasses\" to pair them again, then connect."
)
}
interruptibleSleep.interrupt()
}
internal fun GlassesSessionCore.handleTransportFailure(reason: String?) {
logError("Transport failure: $reason")
monitor.withLock {
maybeEmitEvenAppConflictLocked(reason)
finishBenchmarkLocked(true, "transport failure")
sessionReady = false
fixedLayoutCreated = false
startupProbePending = false
shutdownRequested = false
chargingMode = false
imageRetryAfterMs = 0
displayedFingerprint = ""
faceclawWakePendingNonce = -1
lastFaceclawWakeLeaseQueuedAtMs = 0
faceclawWakeControlSentCount = 0
clearAllMessagesLocked("transport failure: $reason")
reconnectAfterMs = now() + ConnectionOptions.RECONNECT_DELAY_MS
link.disconnect(rightAddress)
link.disconnect(leftAddress)
}
if (!userDisconnectRequested) {
setStateDisplay("retrying", if (reason == null || reason.isEmpty()) "Reconnecting..." else "Reconnecting after $reason")
}
interruptibleSleep.interrupt()
}
internal fun GlassesSessionCore.resetSessionStateLocked() {
ringBattery = -1
ringCharging = -1
sessionReady = false
shutdownRequested = false
fixedLayoutCreated = false
chargingMode = false
rightConnected = false
leftConnected = false
ringConnected = false
ringNotificationsReady = false
reconnectAfterMs = 0
reconnectHalted = false
ringReconnectAfterMs = 0
lastAckAtMs = 0
lastIncomingAtMs = 0
lastHeartbeatSentAtMs = 0
lastSessionReadyAtMs = 0
consecutiveAckTimeouts = 0
lastAudioControlAckMagic = 0
audioCaptureActive = false
audioPacketListener = null
compassControlLastSent = -1
// A dead transport orphans any glasses-side compass state; the fresh
// session re-asserts the desired state once its layout is ready.
compassMaybeOn = false
faceclawWakePendingNonce = -1
lastFaceclawWakeLeaseQueuedAtMs = 0
faceclawWakeControlSentCount = 0
cfwCleanupDelivered = false
for (transport in cfwTransports) transport.reset()
lastCfwCleanupAckMagic = 0
wearState = -1
displayedFingerprint = ""
// Deliberately not clearing silentMode: it is a property of the glasses,
// not of our session, and silent mode blocks app launches, so it can be
// the very cause of the session teardown that got us here.
}
// ---------------------------------------------------------------------------
// Listener emits (main thread via the host)
internal fun GlassesSessionCore.emitAmbientLight(body: ByteArray) {
if (ambientLightListeners.isEmpty()) {
return
}
val copy = body.copyOf()
host.postToMain {
for (alsListener in ambientLightListeners) {
try {
alsListener.onAmbientLight(copy)
} catch (t: Throwable) {
logWarn("ambient light listener failed", t)
}
}
}
}
internal fun GlassesSessionCore.emitMicStatus(body: ByteArray, address: String) {
if (micStatusListeners.isEmpty()) {
return
}
val arm = if (address.equals(leftAddress, ignoreCase = true)) "L"
else if (address.equals(rightAddress, ignoreCase = true)) "R" else "?"
val copy = body.copyOf()
host.postToMain {
for (micListener in micStatusListeners) {
try {
micListener.onMicStatus(copy, arm)
} catch (t: Throwable) {
logWarn("mic status listener failed", t)
}
}
}
}
internal fun GlassesSessionCore.emitRingEvent(event: G2Event, frameId: Int) {
val current = listener
if (current == null) {
frameTimings.finishFrame(frameId, "discarded: no listener attached")
return
}
val containerNameSnapshot = event.containerName
host.postToMain {
frameTimings.log(frameId, "dispatching input event on main thread")
try {
current.onRingEvent(event.kind, containerNameSnapshot, event.eventType, event.eventSource, event.systemExitReasonCode, frameId,
event.ringTick, event.ringType, event.ringAux, event.ringSpeed)
} catch (t: Throwable) {
logWarn("listener onRingEvent failed", t)
frameTimings.finishFrame(frameId, "discarded: listener onRingEvent failed")
}
}
}
/** Finish a frame owned by the communicator and tell the TS side, which may be awaiting it. */
internal fun GlassesSessionCore.finishFrame(frameId: Int, outcome: String) {
if (frameId <= 0) {
return
}
frameTimings.finishFrame(frameId, outcome)
val current = listener ?: return
host.postToMain {
try {
current.onFrameFinished(frameId, outcome)
} catch (t: Throwable) {
logWarn("listener onFrameFinished failed", t)
}
}
}
internal fun GlassesSessionCore.emitImuData(x: Double, y: Double, z: Double, eventSource: Int) {
if (imuListeners.isEmpty()) {
return
}
host.postToMain {
for (imuListener in imuListeners) {
try {
imuListener.onImuData(x, y, z, eventSource)
} catch (t: Throwable) {
logWarn("listener onImuData failed", t)
}
}
}
}
internal fun GlassesSessionCore.emitCompassEvent(event: BleProtocol.CompassEvent) {
if (event.diagnosticFlags >= 0) {
val sources = arrayOf("unknown", "GRV", "GMRV", "RV")
host.log(SessionLogLevel.INFO, "FaceclawCompass", "heading=" + event.headingDegrees
+ " magneticAccuracy=" + event.magneticAccuracy
+ " magneticAnomalies=" + event.magneticAnomalies
+ " orientationSource=" + sources[event.orientationSource]
+ " flags=0x" + event.diagnosticFlags.toString(16)
+ " sampleTimeMs=" + event.sampleTimeMs, null)
}
for (subscription in compassSubscriptions) {
subscription.dispatcher.post {
try {
subscription.listener.onCompassEvent(event.command, event.headingDegrees,
event.magneticAccuracy, event.magneticAnomalies, event.orientationSource,
event.diagnosticFlags, event.sampleTimeMs)
} catch (t: Throwable) {
logWarn("listener onCompassEvent failed", t)
}
}
}
}
internal fun GlassesSessionCore.emitSilentMode(silent: Boolean) {
val current = listener ?: return
host.postToMain {
try {
current.onSilentMode(silent)
} catch (t: Throwable) {
logWarn("listener onSilentMode failed", t)
}
}
}
internal fun GlassesSessionCore.emitWearState(wearing: Boolean) {
val current = listener ?: return
host.postToMain {
try {
current.onWearState(wearing)
} catch (t: Throwable) {
logWarn("listener onWearState failed", t)
}
}
}
internal fun GlassesSessionCore.emitPhoneLockStateIfChanged(force: Boolean) {
val locked: Boolean
monitor.withLock {
val now = now()
if (!force && now - lastPhoneLockCheckAtMs < 1_000) return
lastPhoneLockCheckAtMs = now
locked = host.isPhoneLocked()
val value = if (locked) 1 else 0
if (!force && value == phoneLockState) return
phoneLockState = value
}
val current = listener ?: return
host.postToMain {
try {
current.onPhoneLockState(locked)
} catch (t: Throwable) {
logWarn("listener onPhoneLockState failed", t)
}
}
}
internal fun GlassesSessionCore.emitBatteryState(headsetBattery: Int, headsetCharging: Int) {
val reportedRingBattery = ringBattery
val reportedRingCharging = ringCharging
val current = listener ?: return
host.postToMain {
try {
current.onBatteryState(headsetBattery, headsetCharging, reportedRingBattery, reportedRingCharging)
} catch (t: Throwable) {
logWarn("listener onBatteryState failed", t)
}
}
}
internal fun GlassesSessionCore.emitFirmwareInfo(info: BleProtocol.FirmwareInfo) {
val current = listener ?: return
host.postToMain {
try {
current.onFirmwareInfo(info.leftVersion, info.rightVersion, info.extension)
} catch (t: Throwable) {
logWarn("listener onFirmwareInfo failed", t)
}
}
}
internal fun GlassesSessionCore.emitFrameMetrics(paintMs: Int, transmitMs: Int, tileCount: Int) {
val current = listener ?: return
host.postToMain {
try {
current.onFrameMetrics(paintMs, transmitMs, tileCount)
} catch (t: Throwable) {
logWarn("listener onFrameMetrics failed", t)
}
}
}
internal fun GlassesSessionCore.maybeEmitEvenAppConflictLocked(reason: String?) {
if ("write failed" != reason) {
return
}
val now = now()
if (lastSessionReadyAtMs <= 0 || now - lastSessionReadyAtMs > ConnectionOptions.EVEN_APP_WRITE_FAILURE_WINDOW_MS) {
return
}
if (lastEvenAppConflictAtMs > 0 && now - lastEvenAppConflictAtMs < 60_000) {
return
}
if (!host.isEvenAppActive()) {
return
}
lastEvenAppConflictAtMs = now
emitEvenAppConflict("The Even Realities app still appears to be running. It can hold the glasses BLE link and cause Faceclaw write failures. Open its app settings and force stop it, then reconnect Faceclaw.")
}
internal fun GlassesSessionCore.emitEvenAppConflict(message: String?) {
val current = listener ?: return
val messageSnapshot = message ?: ""
host.postToMain {
try {
current.onEvenAppConflict(messageSnapshot)
} catch (t: Throwable) {
logWarn("listener onEvenAppConflict failed", t)
}
}
}
internal fun GlassesSessionCore.setStateDisplay(nextPhase: String, nextStatus: String) {
monitor.withLock {
phase = nextPhase
status = nextStatus
}
emitState()
}
internal fun GlassesSessionCore.emitState() {
val current = listener ?: return
val phaseSnapshot: String
val statusSnapshot: String
monitor.withLock {
phaseSnapshot = phase
statusSnapshot = status
}
host.postToMain {
try {
current.onStateChange(phaseSnapshot, statusSnapshot)
} catch (t: Throwable) {
logWarn("listener onStateChange failed", t)
}
}
}
@@ -0,0 +1,165 @@
package com.faceclaw.app
import kotlin.concurrent.Volatile
import kotlin.contracts.ExperimentalContracts
import kotlin.contracts.InvocationKind
import kotlin.contracts.contract
/**
* GATT transport used by [GlassesSessionCore]. Addresses are opaque strings (Android MAC
* addresses, CoreBluetooth identifiers on iOS); every call blocks the calling thread until the
* operation completes or [timeoutMs] elapses, exactly like Android's FaceclawBleManager. Inbound
* traffic reaches the core through its FaceclawBleListener methods, which the implementation
* must call from whatever thread the platform stack delivers on.
*/
interface SessionLink {
fun connect(address: String, timeoutMs: Int): Boolean
/** Best effort; no completion point (see connectArm). */
fun requestHighPriority(address: String)
fun requestMtu(address: String, mtu: Int, timeoutMs: Int): Boolean
fun negotiatedMtu(address: String): Int
fun discoverServices(address: String, timeoutMs: Int): Boolean
fun enableNotifications(address: String, characteristicUuid: String, enable: Boolean, timeoutMs: Int): Boolean
fun writeFrames(
address: String,
characteristicUuid: String,
frames: List<ByteArray>,
mode: GattWriteMode,
timeoutMs: Int,
): Boolean
fun disconnect(address: String)
fun close()
/** Whether the OS still holds a pairing bond for the address (iOS: always true). */
fun isBonded(address: String): Boolean
/** Bandwidth-benchmark link tuning; 0: current link, 1: HIGH priority, 2: 2M PHY, 3: both. */
fun prepareBenchmarkLink(address: String, mode: Int)
/** Traffic counter hook: one display frame fully acknowledged. */
fun recordDisplayFrameSent()
}
/** Delivers an action on a specific thread (a Looper, a dispatch queue, ...). */
fun interface SessionDispatcher {
fun post(action: () -> Unit)
}
enum class SessionLogLevel {
DEBUG,
INFO,
WARN,
ERROR,
}
/**
* Platform side effects the session core needs. Listener callbacks are marshalled through
* [postToMain]; everything else is a synchronous query or command on the calling thread.
*/
interface SessionHost {
fun postToMain(action: () -> Unit)
/** A dispatcher for the calling thread (its Looper/queue), falling back to the main thread. */
fun currentThreadDispatcher(): SessionDispatcher
fun isPhoneLocked(): Boolean
/** Hold (true) or release (false) the "glasses screen on" wake lock; idempotent. */
fun setScreenWakeLock(on: Boolean)
/** Whether the stock Even app appears active (it can hold the BLE link). */
fun isEvenAppActive(): Boolean
/** Start the worker thread that runs [body] (the core's run loop) once. */
fun startWorker(body: () -> Unit)
/** Interrupt (where supported) and wait up to [timeoutMs] for the worker started by [startWorker]. */
fun joinWorker(timeoutMs: Long)
fun log(level: SessionLogLevel, tag: String, message: String, error: Throwable?)
}
/**
* Java-monitor replacement: a reentrant state lock plus a separate condition used only at the
* blocking wait sites. Waiters must hold [lock] exactly once when calling [awaitMs]; notifiers
* may hold it (they normally do). Ordering is always lock -> signal, and the waiter never holds
* the signal while acquiring the lock, so the pair cannot deadlock and cannot lose a wake-up:
* the predicate is checked under [lock], the signal is taken before [lock] is released, and
* [ProtocolCondition.awaitMs] releases the signal atomically.
*/
internal class SessionMonitor(platform: ProtocolPlatform) {
val lock: ProtocolLock = platform.createLock()
private val signal: ProtocolCondition = platform.createCondition()
fun signalAll() {
signal.lock()
try {
signal.signalAll()
} finally {
signal.unlock()
}
}
/** Caller holds [lock] once; returns with it held again. Spurious wake-ups are possible. */
fun awaitMs(timeoutMs: Long) {
signal.lock()
lock.unlock()
try {
signal.awaitMs(timeoutMs)
} finally {
signal.unlock()
}
lock.lock()
}
}
/** Snapshot-iterated listener list (java.util.concurrent.CopyOnWriteArrayList stand-in). */
internal class CopyOnWriteList<T>(platform: ProtocolPlatform) : Iterable<T> {
private val lock = platform.createLock()
@Volatile private var items: List<T> = emptyList()
fun add(item: T) {
lock.withLock { items = items + item }
}
fun remove(item: T) {
lock.withLock { items = items - item }
}
fun isEmpty(): Boolean = items.isEmpty()
override fun iterator(): Iterator<T> = items.iterator()
}
/** Runs [action] under the monitor's state lock; the contract lets `val`s be assigned inside, like `synchronized`. */
@OptIn(ExperimentalContracts::class)
internal inline fun <T> SessionMonitor.withLock(action: () -> T): T {
contract { callsInPlace(action, InvocationKind.EXACTLY_ONCE) }
lock.lock()
try {
return action()
} finally {
lock.unlock()
}
}
/** [ProtocolLock.withLock] with a call-in-place contract. */
@OptIn(ExperimentalContracts::class)
internal inline fun <T> ProtocolLock.locked(action: () -> T): T {
contract { callsInPlace(action, InvocationKind.EXACTLY_ONCE) }
lock()
try {
return action()
} finally {
unlock()
}
}
@@ -0,0 +1,168 @@
package com.faceclaw.app
import kotlin.jvm.JvmStatic
import kotlin.math.pow
import kotlin.math.roundToInt
/**
* Wire packets produced by the platform text rasterizers (Android FontFileRenderer over
* minikin/HarfBuzz, iOS over CoreText) and consumed by the TypeScript side
* (app/native/font-files.ts, app/graphics/ttf-font.ts). Rasterization stays per platform;
* the packet layouts, gamma mapping and ink-box cropping live here so both platforms agree.
*
* Image packet (renderText / renderWrapped): [widthLo, widthHi, heightLo, heightHi, pixels...],
* one gamma-mapped coverage byte per pixel, row-major.
*
* Glyph-cell packet (renderGlyphCell), little-endian:
* [advance u16, 26.6 fixed point]
* [bearingX s16] ink left relative to the pen position
* [inkTop s16] ink top relative to the line top (ascent above baseline)
* [width u16][height u16]
* [width*height coverage bytes, gamma-mapped]
* An ink-free glyph (space) has width = height = 0 but a valid advance.
*/
object GlyphPacket {
const val IMAGE_HEADER_BYTES = 4
const val GLYPH_CELL_HEADER_BYTES = 10
/** out = 255 * (coverage/255)^gamma; non-positive gamma means linear. */
@JvmStatic
fun gammaLut(gammaIn: Double): ByteArray {
val gamma = if (gammaIn > 0 && gammaIn.isFinite()) gammaIn else 1.0
val lut = ByteArray(256)
for (i in 0 until 256) {
lut[i] = (255.0 * (i / 255.0).pow(gamma)).roundToInt().coerceIn(0, 255).toByte()
}
return lut
}
/** [first, last] painted (nonzero) column indexes, or null if blank. */
@JvmStatic
fun paintedColumnRange(pixels: ByteArray, width: Int, height: Int): IntArray? {
var first = width
var last = -1
for (y in 0 until height) {
val row = y * width
var x = 0
while (x < first) {
if (pixels[row + x].toInt() != 0) {
first = x
break
}
x++
}
x = width - 1
while (x > last) {
if (pixels[row + x].toInt() != 0) {
last = x
break
}
x--
}
}
return if (last >= first) intArrayOf(first, last) else null
}
/** Tight [x0, y0, x1, y1] (inclusive) box of nonzero pixels, or null if blank. */
@JvmStatic
fun inkBounds(pixels: ByteArray, width: Int, height: Int): IntArray? {
var x0 = width
var x1 = -1
var y0 = height
var y1 = -1
for (y in 0 until height) {
val row = y * width
for (x in 0 until width) {
if (pixels[row + x].toInt() != 0) {
if (x < x0) x0 = x
if (x > x1) x1 = x
if (y < y0) y0 = y
if (y > y1) y1 = y
}
}
}
return if (x1 >= x0) intArrayOf(x0, y0, x1, y1) else null
}
/** Image packet of the whole width*height alpha raster. */
@JvmStatic
fun packImage(alpha8: ByteArray, width: Int, height: Int, gamma: Double): ByteArray =
packImageRegion(alpha8, width, 0, 0, width, height, gamma)
/** Image packet of the [x, y, width, height] region of a raster with row [stride]. */
@JvmStatic
fun packImageRegion(alpha8: ByteArray, stride: Int, x: Int, y: Int, width: Int, height: Int, gamma: Double): ByteArray {
require(width >= 0 && height >= 0 && x >= 0 && y >= 0 && x + width <= stride)
val lut = gammaLut(gamma)
val out = ByteArray(IMAGE_HEADER_BYTES + width * height)
putU16(out, 0, width)
putU16(out, 2, height)
for (row in 0 until height) {
val src = (y + row) * stride + x
val dst = IMAGE_HEADER_BYTES + row * width
for (col in 0 until width) {
out[dst + col] = lut[alpha8[src + col].toInt() and 0xff]
}
}
return out
}
/** 26.6 fixed-point advance clamped to u16. */
@JvmStatic
fun advanceFixed(advancePx: Double): Int = (advancePx * 64.0).roundToInt().coerceIn(0, 0xffff)
/** Glyph cell with no ink (space): valid advance, zero-size box. */
@JvmStatic
fun emptyGlyphCell(advanceFixed: Int): ByteArray = glyphCellPacket(advanceFixed, 0, 0, 0, 0, null)
/** Glyph cell from already gamma-mapped coverage. */
@JvmStatic
fun glyphCellPacket(advanceFixed: Int, bearingX: Int, inkTop: Int, width: Int, height: Int, coverage: ByteArray?): ByteArray {
val out = ByteArray(GLYPH_CELL_HEADER_BYTES + (coverage?.size ?: 0))
putU16(out, 0, advanceFixed)
putU16(out, 2, bearingX)
putU16(out, 4, inkTop)
putU16(out, 6, width)
putU16(out, 8, height)
coverage?.copyInto(out, GLYPH_CELL_HEADER_BYTES)
return out
}
/**
* Glyph cell cropped to the tight ink box of a padded raster. [penX]/[baselineY] are the
* pen position inside the raster and [ascent] the font ascent above the baseline; the
* returned bearing/inkTop are relative to those, as the wire format requires.
*/
@JvmStatic
fun packGlyphCell(
advanceFixed: Int,
alpha8: ByteArray,
rasterWidth: Int,
rasterHeight: Int,
penX: Int,
baselineY: Int,
ascent: Int,
gamma: Double,
): ByteArray {
val box = inkBounds(alpha8, rasterWidth, rasterHeight) ?: return emptyGlyphCell(advanceFixed)
val x0 = box[0]
val y0 = box[1]
val width = box[2] - x0 + 1
val height = box[3] - y0 + 1
val lut = gammaLut(gamma)
val coverage = ByteArray(width * height)
for (y in 0 until height) {
val src = (y0 + y) * rasterWidth + x0
val dst = y * width
for (x in 0 until width) {
coverage[dst + x] = lut[alpha8[src + x].toInt() and 0xff]
}
}
return glyphCellPacket(advanceFixed, x0 - penX, ascent + (y0 - baselineY), width, height, coverage)
}
private fun putU16(out: ByteArray, offset: Int, value: Int) {
out[offset] = (value and 0xff).toByte()
out[offset + 1] = ((value shr 8) and 0xff).toByte()
}
}
@@ -0,0 +1,117 @@
package com.faceclaw.app
import kotlin.jvm.JvmStatic
import kotlin.math.pow
import kotlin.math.roundToInt
/**
* Converts ARGB pixels to the grayscale packet format used across the TS bridge:
* [widthLo, widthHi, heightLo, heightHi, pixels...] with one byte per pixel, row-major.
* Transparent pixels darken toward black (the on-glasses background). Platform code owns
* decoding and scaling (Bitmap / ImageIO); this object owns the pixel math so both platforms
* produce identical tone and dither.
*/
object GrayPacket {
const val HEADER_SIZE = 4
/**
* gamma > 1 darkens midtones (out = 255 * (in/255)^gamma). Source pixels are sRGB-encoded
* but the G2 drives its 16 levels roughly linearly, so mid-gray otherwise displays far
* brighter than intended; 2.2 undoes the sRGB encoding outright.
*
* dither error-diffuses against the 16 levels the frame is eventually packed to
* (BmpUtil.GRAY_TO_NIBBLE) instead of leaving each pixel to round on its own, which turns
* smooth gradients into visible bands. Dithered output is already quantized: every byte is
* a level times 16, which BmpUtil re-quantizes back to exactly that level.
*/
@JvmStatic
fun fromArgb(pixels: IntArray, width: Int, height: Int, gamma: Float, dither: Boolean): ByteArray {
require(width > 0 && height > 0 && pixels.size >= width * height) { "bad pixel plane" }
val out = ByteArray(HEADER_SIZE + width * height)
writeHeader(out, width, height)
val tone = toneCurve(gamma)
for (i in 0 until width * height) {
val p = pixels[i]
val a = (p ushr 24) and 0xff
val r = (p shr 16) and 0xff
val g = (p shr 8) and 0xff
val b = p and 0xff
out[HEADER_SIZE + i] = tone[((r * 299 + g * 587 + b * 114) / 1000) * a / 255].toByte()
}
if (dither) {
ditherToDisplayLevels(out, HEADER_SIZE, width, height)
}
return out
}
@JvmStatic
fun writeHeader(out: ByteArray, width: Int, height: Int) {
out[0] = (width and 0xff).toByte()
out[1] = ((width shr 8) and 0xff).toByte()
out[2] = (height and 0xff).toByte()
out[3] = ((height shr 8) and 0xff).toByte()
}
/** 256-entry map of source gray to displayed gray for out = in^gamma. */
@JvmStatic
fun toneCurve(gamma: Float): IntArray {
val curve = IntArray(256)
for (v in 0 until 256) {
curve[v] = if (gamma == 1f) v else (255f * (v / 255f).pow(gamma)).roundToInt()
}
return curve
}
/**
* Floyd-Steinberg error diffusion onto the display's 16 gray levels, in place over an 8bpp
* plane. Serpentine scanning keeps the diffusion from building up a directional texture
* across wide flat areas.
*
* Level n is written back as n * 16 rather than the n * 17 it stands for so that BmpUtil's
* (v + 8) >> 4 reproduces n exactly; level 0 is written as 1, not 0, because 0 is the shell's
* color-key for transparent.
*/
@JvmStatic
fun ditherToDisplayLevels(plane: ByteArray, offset: Int, width: Int, height: Int) {
var curr = FloatArray(width)
var next = FloatArray(width)
for (x in 0 until width) {
curr[x] = (plane[offset + x].toInt() and 0xff).toFloat()
}
for (y in 0 until height) {
val rowStart = offset + y * width
val nextStart = rowStart + width
val hasNext = y + 1 < height
for (x in 0 until width) {
next[x] = if (hasNext) (plane[nextStart + x].toInt() and 0xff).toFloat() else 0f
}
val leftToRight = (y and 1) == 0
val start = if (leftToRight) 0 else width - 1
val step = if (leftToRight) 1 else -1
for (i in 0 until width) {
val x = start + i * step
val wanted = curr[x]
val level = (minOf(255f, maxOf(0f, wanted)) / 17f).roundToInt()
val error = wanted - level * 17f
plane[rowStart + x] = (if (level == 0) 1 else level * 16).toByte()
val ahead = x + step
if (ahead >= 0 && ahead < width) {
curr[ahead] += error * (7f / 16f)
}
if (hasNext) {
if (ahead >= 0 && ahead < width) {
next[ahead] += error * (1f / 16f)
}
next[x] += error * (5f / 16f)
val behind = x - step
if (behind >= 0 && behind < width) {
next[behind] += error * (3f / 16f)
}
}
}
val swap = curr
curr = next
next = swap
}
}
}
@@ -0,0 +1,110 @@
package com.faceclaw.app
import kotlin.jvm.JvmStatic
/** Random access over font bytes, so large files are not read whole just for a name. */
interface RandomAccessBytes {
val length: Long
/** Reads exactly [count] bytes at [offset] into [into]; throws when out of range. */
fun read(offset: Long, into: ByteArray, count: Int)
}
class ArrayRandomAccessBytes(private val bytes: ByteArray) : RandomAccessBytes {
override val length: Long
get() = bytes.size.toLong()
override fun read(offset: Long, into: ByteArray, count: Int) {
require(offset >= 0 && count >= 0 && offset + count <= bytes.size) { "read out of range" }
bytes.copyInto(into, 0, offset.toInt(), offset.toInt() + count)
}
}
/**
* Minimal OpenType 'name' table reader (TTF/OTF/TTC, first face) for font titles.
* Returns "Family\nStyle" ("Style" may be empty), preferring the typographic names
* (ids 16/17) over the legacy ones (1/2), or "" when the table cannot be parsed.
*/
object OpenTypeNames {
private const val TTCF = 0x74746366
private const val NAME = 0x6e616d65
@JvmStatic
fun parseFile(path: String): String = parse(ArrayRandomAccessBytes(readFileData(path)))
@JvmStatic
fun parse(bytes: ByteArray): String = parse(ArrayRandomAccessBytes(bytes))
@JvmStatic
fun parse(source: RandomAccessBytes): String {
val fileSize = source.length
if (fileSize < 12) return ""
var offset = 0L
if (readU32(source, 0) == TTCF) { // 'ttcf': use the first face
if (readU32(source, 8) < 1) return ""
offset = readU32(source, 12).toLong() and 0xffffffffL
}
val numTables = readU16(source, offset + 4)
var nameOffset = -1L
for (i in 0 until numTables) {
val rec = offset + 12 + i * 16L
if (rec + 16 > fileSize) return ""
if (readU32(source, rec) == NAME) {
nameOffset = readU32(source, rec + 8).toLong() and 0xffffffffL
break
}
}
if (nameOffset < 0 || nameOffset + 6 > fileSize) return ""
val count = readU16(source, nameOffset + 2)
val stringStorage = nameOffset + readU16(source, nameOffset + 4)
var family: String? = null
var style: String? = null
var preferredFamily: String? = null
var preferredStyle: String? = null
for (i in 0 until count) {
val rec = nameOffset + 6 + i * 12L
if (rec + 12 > fileSize) break
val platform = readU16(source, rec)
val nameId = readU16(source, rec + 6)
if (nameId != 1 && nameId != 2 && nameId != 16 && nameId != 17) continue
val length = readU16(source, rec + 8)
val strOffset = stringStorage + readU16(source, rec + 10)
if (strOffset + length > fileSize || length <= 0 || length > 512) continue
val data = ByteArray(length)
source.read(strOffset, data, length)
// Platform 0 (Unicode) and 3 (Windows) store UTF-16BE;
// platform 1 (Mac) is close enough to Latin-1 for names.
val value = (if (platform == 1) latin1(data) else utf16be(data)).trim()
if (value.isEmpty()) continue
if (nameId == 1 && family == null) family = value
if (nameId == 2 && style == null) style = value
if (nameId == 16 && preferredFamily == null) preferredFamily = value
if (nameId == 17 && preferredStyle == null) preferredStyle = value
}
val outFamily = preferredFamily ?: family ?: return ""
return outFamily + "\n" + (preferredStyle ?: style ?: "")
}
private fun latin1(data: ByteArray): String =
CharArray(data.size) { (data[it].toInt() and 0xff).toChar() }.concatToString()
private fun utf16be(data: ByteArray): String {
val chars = CharArray(data.size / 2) {
(((data[2 * it].toInt() and 0xff) shl 8) or (data[2 * it + 1].toInt() and 0xff)).toChar()
}
return chars.concatToString()
}
private fun readU16(source: RandomAccessBytes, offset: Long): Int {
val b = ByteArray(2)
source.read(offset, b, 2)
return ((b[0].toInt() and 0xff) shl 8) or (b[1].toInt() and 0xff)
}
private fun readU32(source: RandomAccessBytes, offset: Long): Int {
val b = ByteArray(4)
source.read(offset, b, 4)
return ((b[0].toInt() and 0xff) shl 24) or ((b[1].toInt() and 0xff) shl 16) or
((b[2].toInt() and 0xff) shl 8) or (b[3].toInt() and 0xff)
}
}
@@ -0,0 +1,52 @@
package com.faceclaw.app
import kotlin.jvm.JvmStatic
import kotlin.math.pow
import kotlin.math.roundToLong
/**
* Palette for the phone-UI preview of an 8bpp grayscale frame: gray -> ARGB with a brightening
* gamma, either grayscale or green-on-black (matching the physical glasses). Both platforms
* should build their preview images from this table so they brighten identically.
*/
object PreviewPalette {
private var cachedLut: IntArray? = null
private var cachedGammaBits: Long = 0
private var cachedGreen: Boolean = false
private val lock = protocolPlatform().createLock()
/** ARGB value for [gray] under [brightenGamma]: 255 * (gray/255)^gamma per channel. */
@JvmStatic
fun argb(gray: Int, brightenGamma: Double, green: Boolean): Int {
val v = (255 * (gray / 255.0).pow(brightenGamma)).roundToLong().coerceIn(0L, 255L).toInt()
return if (green) (0xff000000.toInt() or (v shl 8)) else (0xff000000.toInt() or (v shl 16) or (v shl 8) or v)
}
/** Reuse the current preview palette; rebuild only when gamma or color changes. */
@JvmStatic
fun lookupTable(brightenGamma: Double, green: Boolean): IntArray {
val gammaBits = brightenGamma.toBits()
lock.withLock {
val cached = cachedLut
if (cached != null && cachedGammaBits == gammaBits && cachedGreen == green) {
return cached
}
val lut = IntArray(256) { argb(it, brightenGamma, green) }
cachedGammaBits = gammaBits
cachedGreen = green
cachedLut = lut
return lut
}
}
/** Expands [count] gray bytes starting at [offset] to ARGB pixels through the palette. */
@JvmStatic
fun expand(gray: ByteArray, offset: Int, count: Int, brightenGamma: Double, green: Boolean): IntArray {
val lut = lookupTable(brightenGamma, green)
val colors = IntArray(count)
for (i in 0 until count) {
colors[i] = lut[gray[offset + i].toInt() and 0xff]
}
return colors
}
}
@@ -0,0 +1,98 @@
package com.faceclaw.app
import kotlin.jvm.JvmStatic
import kotlin.math.abs
/**
* Pure 24x24 8bpp icons for the system status strip (Wi-Fi level, cellular level, hotspot).
* Platform code reads the levels; this object only draws, so both platforms render the same
* artwork.
*/
object StatusIconArt {
const val ICON_SIZE = 24
@JvmStatic
fun wifi(level: Int): ByteArray {
val icon = ByteArray(ICON_SIZE * ICON_SIZE)
val cx = 12
val cy = 18
fillRect(icon, cx - 1, cy - 1, 3, 3, 230)
val radii = intArrayOf(5, 9, 13, 17)
for (index in radii.indices) {
if (level <= index) {
continue
}
drawWifiArc(icon, cx, cy, radii[index], 210)
}
return icon
}
@JvmStatic
fun cell(level: Int): ByteArray {
val icon = ByteArray(ICON_SIZE * ICON_SIZE)
for (bar in 0 until 4) {
val x = 5 + bar * 4
val height = 5 + bar * 4
val value = if (level > bar) 220 else 55
fillRect(icon, x, 20 - height, 3, height, value)
}
return icon
}
@JvmStatic
fun hotspot(): ByteArray {
val icon = ByteArray(ICON_SIZE * ICON_SIZE)
fillRect(icon, 11, 17, 3, 3, 230)
drawWifiArc(icon, 12, 19, 7, 210)
drawWifiArc(icon, 12, 19, 12, 210)
fillRect(icon, 6, 5, 12, 2, 170)
return icon
}
/** Nearest-neighbour resample of a 24x24 icon to size x size. */
@JvmStatic
fun scale(source: ByteArray, size: Int): ByteArray {
if (size == ICON_SIZE) {
return source
}
val scaled = ByteArray(size * size)
for (y in 0 until size) {
val sy = minOf(ICON_SIZE - 1, (y * ICON_SIZE) / size)
for (x in 0 until size) {
val sx = minOf(ICON_SIZE - 1, (x * ICON_SIZE) / size)
scaled[y * size + x] = source[sy * ICON_SIZE + sx]
}
}
return scaled
}
private fun drawWifiArc(icon: ByteArray, cx: Int, cy: Int, radius: Int, value: Int) {
val inner = (radius - 1) * (radius - 1)
val outer = (radius + 1) * (radius + 1)
for (y in 0 until ICON_SIZE) {
for (x in 0 until ICON_SIZE) {
val dx = x - cx
val dy = y - cy
val dist = dx * dx + dy * dy
if (dy <= 0 && dist >= inner && dist <= outer && abs(dx) <= radius) {
setPixel(icon, x, y, value)
}
}
}
}
private fun fillRect(icon: ByteArray, x: Int, y: Int, width: Int, height: Int, value: Int) {
for (row in y until y + height) {
for (col in x until x + width) {
setPixel(icon, col, row, value)
}
}
}
private fun setPixel(icon: ByteArray, x: Int, y: Int, value: Int) {
if (x < 0 || y < 0 || x >= ICON_SIZE || y >= ICON_SIZE) {
return
}
icon[y * ICON_SIZE + x] = value.coerceIn(0, 255).toByte()
}
}
@@ -0,0 +1,150 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
import kotlin.jvm.JvmStatic
import kotlin.math.min
/** One drawable element of a parsed icon; coordinates are in viewBox units. */
sealed class SvgShape {
class PathData(@JvmField val d: String) : SvgShape()
class Circle(@JvmField val cx: Float, @JvmField val cy: Float, @JvmField val r: Float) : SvgShape()
class Ellipse(@JvmField val cx: Float, @JvmField val cy: Float, @JvmField val rx: Float, @JvmField val ry: Float) : SvgShape()
/** rx/ry are both 0 for a sharp rectangle, otherwise both positive. */
class Rect(
@JvmField val x: Float,
@JvmField val y: Float,
@JvmField val width: Float,
@JvmField val height: Float,
@JvmField val rx: Float,
@JvmField val ry: Float,
) : SvgShape()
class Line(@JvmField val x1: Float, @JvmField val y1: Float, @JvmField val x2: Float, @JvmField val y2: Float) : SvgShape()
/** [points] is x0,y0,x1,y1,... with at least one pair; [closed] for polygon. */
class Polyline(@JvmField val points: FloatArray, @JvmField val closed: Boolean) : SvgShape()
}
class SvgIcon(
@JvmField val minX: Float,
@JvmField val minY: Float,
@JvmField val viewWidth: Float,
@JvmField val viewHeight: Float,
/** Lucide-style outline icons (fill="none") are stroked; everything else is filled. */
@JvmField val stroked: Boolean,
@JvmField val shapes: List<SvgShape>,
) {
/**
* Mapping from viewBox to a size*size raster: [translateX, translateY, scale]. Apply as
* translate(tx, ty), scale(s), translate(-minX, -minY), i.e. the viewBox centered in the box.
*/
fun placement(size: Int): FloatArray {
val scale = min(size / viewWidth, size / viewHeight)
return floatArrayOf((size - viewWidth * scale) / 2f, (size - viewHeight * scale) / 2f, scale)
}
}
/**
* Parses the small subset of SVG used by Lucide / simple Noun Project icons (path, circle,
* ellipse, rect, line, polyline, polygon) into shapes the platform path builders draw.
* Also owns the 3-level coverage quantization applied after rasterization on both platforms.
*/
object SvgIconSource {
private val TAG_RE = Regex("<(path|circle|ellipse|rect|line|polyline|polygon)\\b([^>]*)>")
private val VIEWBOX_RE = Regex("viewBox\\s*=\\s*\"([^\"]*)\"")
private val SEPARATOR_RE = Regex("[\\s,]+")
/** Null when nothing drawable was found. */
@JvmStatic
fun parse(svg: String): SvgIcon? {
var minX = 0f
var minY = 0f
var viewW = 24f
var viewH = 24f
val vb = VIEWBOX_RE.find(svg)
if (vb != null) {
val parts = SEPARATOR_RE.split(vb.groupValues[1].trim())
if (parts.size == 4) {
minX = parts[0].toFloat()
minY = parts[1].toFloat()
viewW = parts[2].toFloat()
viewH = parts[3].toFloat()
}
}
val stroked = svg.contains("fill=\"none\"")
val shapes = ArrayList<SvgShape>()
for (m in TAG_RE.findAll(svg)) {
parseElement(m.groupValues[1], m.groupValues[2])?.let { shapes.add(it) }
}
if (shapes.isEmpty()) return null
return SvgIcon(minX, minY, viewW, viewH, stroked, shapes)
}
/**
* Snap antialiased coverage toward hard edges so the 4bpp frames sent over BLE deflate
* better: mostly-transparent and mostly-opaque pixels become exactly 0/255 (long runs, and
* 0 stays color-key transparent for bitBlt), and only genuinely half-covered edge pixels
* keep one mid gray. At icon sizes this is visually near-identical.
*/
@JvmStatic
fun quantizeCoverage(alpha: Int): Int {
if (alpha < 64) return 0
if (alpha >= 192) return 255
return 128
}
/** Quantized coverage bytes from ARGB pixels (alpha channel = coverage). */
@JvmStatic
fun quantizeArgb(pixels: IntArray): ByteArray {
val gray = ByteArray(pixels.size)
for (i in pixels.indices) gray[i] = quantizeCoverage((pixels[i] ushr 24) and 0xff).toByte()
return gray
}
private fun parseElement(tag: String, attrs: String): SvgShape? =
when (tag) {
"path" -> attr(attrs, "d")?.let { SvgShape.PathData(it) }
"circle" -> {
val r = num(attrs, "r", 0f)
if (r > 0) SvgShape.Circle(num(attrs, "cx", 0f), num(attrs, "cy", 0f), r) else null
}
"ellipse" -> {
val rx = num(attrs, "rx", 0f)
val ry = num(attrs, "ry", 0f)
if (rx > 0 && ry > 0) SvgShape.Ellipse(num(attrs, "cx", 0f), num(attrs, "cy", 0f), rx, ry) else null
}
"rect" -> {
val w = num(attrs, "width", 0f)
val h = num(attrs, "height", 0f)
var rx = num(attrs, "rx", 0f)
var ry = num(attrs, "ry", if (rx > 0) rx else 0f)
if (rx <= 0) rx = ry
if (ry <= 0) ry = rx
if (w > 0 && h > 0) {
val rounded = rx > 0 || ry > 0
SvgShape.Rect(num(attrs, "x", 0f), num(attrs, "y", 0f), w, h, if (rounded) rx else 0f, if (rounded) ry else 0f)
} else null
}
"line" -> SvgShape.Line(num(attrs, "x1", 0f), num(attrs, "y1", 0f), num(attrs, "x2", 0f), num(attrs, "y2", 0f))
"polyline", "polygon" -> {
val points = attr(attrs, "points") ?: return null
val nums = SEPARATOR_RE.split(points.trim())
val pairs = nums.size / 2
if (pairs == 0) return null
val values = FloatArray(pairs * 2) { nums[it].toFloat() }
SvgShape.Polyline(values, tag == "polygon")
}
else -> null
}
private fun attr(attrs: String, name: String): String? =
Regex("\\b" + name + "\\s*=\\s*\"([^\"]*)\"").find(attrs)?.groupValues?.get(1)
private fun num(attrs: String, name: String, fallback: Float): Float {
val value = attr(attrs, name) ?: return fallback
return value.trim().toFloatOrNull() ?: fallback
}
}
@@ -0,0 +1,26 @@
package com.faceclaw.app
import kotlin.concurrent.Volatile
import kotlin.jvm.JvmStatic
/**
* Shared HTTP identity for the native networking helpers on both platforms. The version
* lives in app/version.ts, so the TypeScript side pushes the real string in at startup
* (see installNativeUserAgent in app/util/http.ts); the default is only a fallback for
* requests that somehow beat that call.
*/
object HttpIdentity {
const val DEFAULT_USER_AGENT = "Faceclaw"
@Volatile
private var userAgent = DEFAULT_USER_AGENT
@JvmStatic
fun setUserAgent(value: String?) {
val trimmed = value?.trim()
if (!trimmed.isNullOrEmpty()) userAgent = trimmed
}
@JvmStatic
fun getUserAgent(): String = userAgent
}
@@ -0,0 +1,229 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
import kotlin.jvm.JvmStatic
/** One accepted client connection of the local input port. */
interface RemoteInputConnection {
/** Reads one byte, blocking at most [timeoutMs]; returns -1 on end of stream, timeout or error. */
fun readByte(timeoutMs: Long): Int
fun write(bytes: ByteArray)
fun close()
}
/** A bound, listening socket. */
interface RemoteInputListener {
/** Blocks for the next client; returns null when the listener is closed or accept fails. */
fun accept(): RemoteInputConnection?
val isClosed: Boolean
fun close()
}
/** OS socket access for [RemoteInputSession]; a POSIX actual is the iOS counterpart. */
interface LocalServerPort {
/** True when [address] is a unicast address assigned to a local interface (not any/multicast). */
fun isLocalUnicastAddress(address: String): Boolean
/** Binds and listens on [address]:[port]; throws when the port cannot be opened. */
fun bind(address: String, port: Int): RemoteInputListener
}
interface RandomSource {
fun nextBytes(count: Int): ByteArray
}
/** One network address of a local interface, as enumerated by the platform. */
data class InterfaceAddress(
val interfaceName: String,
val address: String,
val up: Boolean,
val pointToPoint: Boolean,
val loopback: Boolean,
val linkLocal: Boolean,
val anyLocal: Boolean,
)
/**
* Explicit-address, bounded local input port shared by Android (java.net) and iOS (POSIX).
* Exactly one request is in flight: a client sends one newline-terminated UTF-8 frame of at most
* 64 KiB, the session publishes it as a pending JSON request, notifies the app through
* [dispatch] (which must run the callback on the app's UI thread, outside the lock), and blocks
* the serving thread until [complete] supplies the reply or the request deadline passes.
*/
class RemoteInputSession(
private val port: LocalServerPort,
private val random: RandomSource,
private val dispatch: (() -> Unit) -> Unit,
platform: ProtocolPlatform = protocolPlatform(),
private val wallClock: () -> Long = ::currentTimeMillis,
private val requestTimeoutMs: Long = REQUEST_TIMEOUT_MS,
private val readTimeoutMs: Long = READ_TIMEOUT_MS,
) {
private val condition = platform.createCondition()
private var server: RemoteInputListener? = null
private var client: RemoteInputConnection? = null
private var pending: String? = null
private var reply: String? = null
private var nextId = 0L
private var requestId = 0L
private var deadline = 0L
private var requestListener: (() -> Unit)? = null
fun setRequestListener(listener: (() -> Unit)?) {
condition.withLock { requestListener = listener }
}
/** Returns "" on success or a user-facing error. Never resolves hostnames or binds a wildcard. */
fun start(port: Int, address: String): String {
condition.withLock {
if (server != null) return ""
if (!isNumericLocalAddress(address)) return "Invalid local address."
if (!this.port.isLocalUnicastAddress(address)) return "Address is not assigned to a local interface."
val listener = try {
this.port.bind(address, port)
} catch (e: Exception) {
return "Could not open local input port $port."
}
server = listener
startThread("FaceclawInput", true) { serve(listener) }
return ""
}
}
fun stop() {
condition.withLock {
try { server?.close() } catch (ignored: Exception) {}
try { client?.close() } catch (ignored: Exception) {}
server = null
client = null
pending = null
requestId = 0
reply = null
condition.signalAll()
}
}
/** The pending request JSON (id, expiresAt, body), consumed once; null when none or expired. */
fun nextRequest(): String? {
condition.withLock {
if (wallClock() >= deadline) {
pending = null
return null
}
val result = pending
pending = null
return result
}
}
fun complete(id: Long, value: String?) {
condition.withLock {
if (id == requestId && wallClock() < deadline) {
reply = value
condition.signalAll()
}
}
}
fun randomSecret(): String = BinaryEncoding.bytesToHex(random.nextBytes(32))
private fun notifyRequestReady(id: Long) {
// Called with the condition held; dispatching keeps JS off the socket thread and outside the lock.
dispatch {
val callback = condition.withLock {
if (requestId != id || pending == null || wallClock() >= deadline) null else requestListener
}
callback?.invoke()
}
}
private fun serve(listener: RemoteInputListener) {
while (!listener.isClosed) {
val connection = listener.accept() ?: continue
try {
condition.withLock {
if (server !== listener) return
client = connection
}
val text = readFrame(connection) ?: continue
val response: String = condition.withLock {
if (server !== listener) return
requestId = ++nextId
deadline = wallClock() + requestTimeoutMs
reply = null
pending = Json.write(linkedMapOf("id" to requestId, "expiresAt" to deadline, "body" to text))
notifyRequestReady(requestId)
while (reply == null && server === listener && wallClock() < deadline) {
condition.awaitMs(maxOf(1L, deadline - wallClock()))
}
val result = reply ?: TIMEOUT_RESPONSE
if (server === listener) {
pending = null
reply = null
requestId = 0
}
result
}
connection.write((response + "\n").encodeToByteArray())
} catch (ignored: Exception) {
// Never log request bodies: they contain credentials and possibly private text.
} finally {
try { connection.close() } catch (ignored: Exception) {}
condition.withLock { if (server === listener) client = null }
}
}
}
/** One newline-terminated frame, or null when the client hung up, stalled or overflowed. */
private fun readFrame(connection: RemoteInputConnection): String? {
val readDeadline = wallClock() + readTimeoutMs
val body = ByteSink()
while (true) {
val remaining = readDeadline - wallClock()
if (remaining <= 0) return null
val b = connection.readByte(remaining)
if (b == -1) return null
if (b == '\n'.code) break
if (body.size() >= MAX_FRAME_BYTES) return null
body.write(b)
}
return try {
body.toByteArray().decodeToString(throwOnInvalidSequence = true)
} catch (e: Exception) {
null
}
}
companion object {
const val MAX_FRAME_BYTES = 65536
const val REQUEST_TIMEOUT_MS = 5000L
const val READ_TIMEOUT_MS = 5000L
@JvmField
val TIMEOUT_RESPONSE = "{\"ok\":false,\"error\":\"timeout\",\"message\":\"Faceclaw did not respond in time.\"}"
private val numericAddress = Regex("[0-9.]+|[0-9a-fA-F]*:[0-9a-fA-F:.]*(%[a-zA-Z0-9_.-]+)?")
/** Numeric IPv4/IPv6 literals only (optionally zone-scoped); hostnames are rejected. */
@JvmStatic fun isNumericLocalAddress(address: String): Boolean = numericAddress.matches(address)
/** Addresses a remote client could reach: up interfaces, minus loopback, link-local and wildcard. */
@JvmStatic
fun reachableAddresses(all: List<InterfaceAddress>): List<InterfaceAddress> =
all.filter { it.up && !it.loopback && !it.linkLocal && !it.anyLocal }
/** JSON array of {name, address, pointToPoint} consumed by app/remote/listeners.ts. */
@JvmStatic
fun interfacesJson(all: List<InterfaceAddress>): String =
Json.write(reachableAddresses(all).map {
linkedMapOf("name" to it.interfaceName, "address" to it.address, "pointToPoint" to it.pointToPoint)
})
/** Lowercase hex SHA-256 of the UTF-8 token; the stored form of remote-input tokens. */
@JvmStatic fun tokenHash(value: String): String = sha256Hex(value.encodeToByteArray())
}
}
@@ -0,0 +1,178 @@
package com.faceclaw.app
import kotlin.concurrent.Volatile
/** One open HTTP response body; [read] returns bytes read or -1 at end. */
interface DownloadResponse {
val code: Int
/** Body length if known, else -1. */
val contentLength: Long
fun read(buffer: ByteArray): Int
fun close()
}
/** Blocking GET; `rangeFrom > 0` asks for `Range: bytes=<rangeFrom>-`. */
interface DownloadTransport {
fun open(url: String, rangeFrom: Long): DownloadResponse
}
interface FileSink {
fun write(bytes: ByteArray, offset: Int, length: Int)
fun close()
}
/** Storage port; paths are platform file paths. Multi-GB files must stream, hence no whole-file reads. */
interface DownloadStorage {
/** Size in bytes, or -1 when missing. */
fun length(path: String): Long
fun prepareParent(path: String)
fun openWrite(path: String, append: Boolean): FileSink
/** Streams an existing file through [consumer] (bytes, count); stops early when it returns false. Returns bytes consumed. */
fun readAll(path: String, consumer: (ByteArray, Int) -> Boolean): Long
fun rename(from: String, to: String): Boolean
fun delete(path: String): Boolean
}
/**
* Large-file download to "<dest>.part" with HTTP Range resume across app restarts, a pinned
* sha256 hashed incrementally (including the resumed prefix), then a rename into place.
* [run] blocks on the calling thread; listener callbacks are invoked synchronously on it, so
* the platform adapter marshals them (Android posts to the constructing Looper).
*/
class ResumableDownload(
private val url: String,
private val destPath: String,
expectedSha256: String?,
private val expectedTotalBytes: Long,
private val transport: DownloadTransport,
private val storage: DownloadStorage,
private val listener: FaceclawModelDownloaderListener,
private val now: () -> Long = { currentTimeMillis() },
) {
private val partPath = "$destPath.part"
private val expectedSha256 = expectedSha256?.lowercase() ?: ""
@Volatile
private var cancelled = false
@Volatile
private var response: DownloadResponse? = null
/** Stops the download but keeps the .part file so a later run resumes. */
fun cancel() {
cancelled = true
try {
response?.close()
} catch (ignored: Exception) {
}
}
fun run() {
try {
if (storage.length(destPath) > 0) {
listener.onDone(destPath)
return
}
storage.prepareParent(destPath)
var digest = Sha256Digest()
var offset = 0L
if (storage.length(partPath) >= 0) {
offset = hashExistingPrefix(digest)
if (cancelled) return
}
val opened = transport.open(url, offset)
response = opened
var done: Long
try {
if (opened.code < 200 || opened.code >= 300) {
listener.onError("Model download failed: HTTP " + opened.code)
return
}
val resumed = opened.code == 206
if (offset > 0 && !resumed) {
// Server ignored the Range header; start over.
offset = 0L
digest = Sha256Digest()
}
val total =
if (expectedTotalBytes > 0) expectedTotalBytes
else if (opened.contentLength > 0) offset + opened.contentLength
else -1L
val out = storage.openWrite(partPath, resumed)
try {
val buffer = ByteArray(1 shl 16)
done = offset
var lastProgressAt = 0L
while (true) {
val read = opened.read(buffer)
if (read < 0) break
if (cancelled) return
out.write(buffer, 0, read)
digest.update(buffer, 0, read)
done += read
val time = now()
if (time - lastProgressAt >= PROGRESS_INTERVAL_MS) {
lastProgressAt = time
listener.onProgress(done, total)
}
}
} finally {
out.close()
}
} finally {
try {
opened.close()
} catch (ignored: Exception) {
}
}
val partLength = storage.length(partPath)
if (expectedTotalBytes > 0 && partLength != expectedTotalBytes) {
listener.onError("Model download ended early (" + partLength + " of " + expectedTotalBytes + " bytes); try again to resume")
return
}
val actualSha = BinaryEncoding.bytesToHex(digest.digest())
if (expectedSha256.isNotEmpty() && actualSha != expectedSha256) {
storage.delete(partPath)
listener.onError("Model download was corrupted (checksum mismatch); download it again")
return
}
if (!storage.rename(partPath, destPath)) {
listener.onError("Could not move the downloaded model into place")
return
}
listener.onDone(destPath)
} catch (e: Exception) {
if (cancelled) return
PlatformLog.w(TAG, "download failed: $e")
listener.onError("Model download failed: $e")
}
}
/** Hash the already-downloaded prefix so the final digest covers the whole file. */
private fun hashExistingPrefix(digest: Sha256Digest): Long =
storage.readAll(partPath) { bytes, count ->
if (cancelled) false
else {
digest.update(bytes, 0, count)
true
}
}
companion object {
private const val TAG = "FaceclawModelDl"
const val PROGRESS_INTERVAL_MS = 500L
}
}
@@ -0,0 +1,209 @@
package com.faceclaw.app
import kotlin.jvm.JvmStatic
/** Streaming POST transport; the platform (okhttp, NSURLSession) implements it. */
interface StreamingHttp {
fun post(url: String, body: String, headers: List<Pair<String, String>>, sink: ChunkSink): Cancellable
}
interface Cancellable {
fun cancel()
}
/** Raw response feed from a [StreamingHttp]; may be called from any thread, one call at a time. */
interface ChunkSink {
fun onStatus(code: Int)
fun onChunk(bytes: ByteArray, offset: Int, length: Int)
fun onComplete()
fun onFailure(message: String)
}
sealed class SseEvent {
data class Line(val text: String) : SseEvent()
data class HttpError(val code: Int, val body: String) : SseEvent()
object Complete : SseEvent()
data class Failure(val message: String) : SseEvent()
}
/**
* Server-sent-events response policy shared by both platforms. Feeds raw bytes in through
* [ChunkSink] and queues [SseEvent]s for [takeEvents]. Behavior (matching the stricter iOS
* implementation): a UTF-8 BOM is stripped from the first line; lines split on LF, CR or CRLF;
* non-2xx responses buffer at most [ERROR_BODY_LIMIT] bytes of body and end in [SseEvent.HttpError];
* a single line over [LINE_LIMIT] bytes, invalid UTF-8, or more than [QUEUE_BYTE_LIMIT] bytes /
* [QUEUE_EVENT_LIMIT] events waiting to be taken end the stream with a [SseEvent.Failure].
* After the terminal event nothing further is queued; [cancel] drops everything.
*/
class SseStream : ChunkSink {
private val lock = protocolPlatform().createLock()
private val events = ArrayList<SseEvent>()
private var queuedBytes = 0L
private var buffer = ByteArray(4096)
private var bufferLength = 0
private var status = 0
private var firstLine = true
private var finished = false
private var cancelled = false
val isFinished: Boolean
get() = lock.withLock { finished }
override fun onStatus(code: Int) {
lock.withLock { status = code }
}
override fun onChunk(bytes: ByteArray, offset: Int, length: Int) {
lock.withLock {
if (finished || cancelled || length <= 0) return
if (status < 200 || status >= 300) {
val remaining = ERROR_BODY_LIMIT - bufferLength
append(bytes, offset, minOf(remaining, length))
return
}
append(bytes, offset, length)
var start = 0
var i = 0
while (i < bufferLength) {
val c = buffer[i]
if (c != CR && c != LF) {
i++
continue
}
if (c == CR && i + 1 == bufferLength) break
line(start, i - start)
if (finished) return
if (c == CR && buffer[i + 1] == LF) i++
start = i + 1
i++
}
if (start > 0) {
buffer.copyInto(buffer, 0, start, bufferLength)
bufferLength -= start
}
if (bufferLength > LINE_LIMIT) finish(SseEvent.Failure("Streaming response line too large"))
}
}
override fun onComplete() {
lock.withLock {
if (finished || cancelled) return
if (status < 200 || status >= 300) {
finish(SseEvent.HttpError(status, decode(0, bufferLength) ?: ""))
return
}
if (bufferLength > 0) {
if (buffer[bufferLength - 1] == CR) bufferLength--
line(0, bufferLength)
if (finished) return
}
finish(SseEvent.Complete)
}
}
override fun onFailure(message: String) {
lock.withLock { finish(SseEvent.Failure(message)) }
}
/** Drains queued events in order. Empty once cancelled. */
fun takeEvents(): List<SseEvent> =
lock.withLock {
if (events.isEmpty()) return emptyList()
val taken = ArrayList(events)
events.clear()
queuedBytes = 0
taken
}
fun cancel() {
lock.withLock {
cancelled = true
events.clear()
queuedBytes = 0
bufferLength = 0
}
}
private fun line(start: Int, length: Int) {
var text = decode(start, length)
if (text == null) {
finish(SseEvent.Failure("Invalid UTF-8 in streaming response"))
return
}
if (firstLine && text.startsWith('')) text = text.substring(1)
firstLine = false
queuedBytes += length
if (queuedBytes > QUEUE_BYTE_LIMIT || events.size >= QUEUE_EVENT_LIMIT) {
events.clear()
finish(SseEvent.Failure("Streaming response queue overflow"))
return
}
events.add(SseEvent.Line(text))
}
private fun decode(start: Int, length: Int): String? =
try {
buffer.decodeToString(start, start + length, throwOnInvalidSequence = true)
} catch (e: CharacterCodingException) {
null
}
private fun finish(event: SseEvent) {
if (finished || cancelled) return
finished = true
events.add(event)
bufferLength = 0
}
private fun append(bytes: ByteArray, offset: Int, length: Int) {
if (length <= 0) return
if (bufferLength + length > buffer.size) buffer = buffer.copyOf(maxOf(bufferLength + length, buffer.size * 2))
bytes.copyInto(buffer, bufferLength, offset, offset + length)
bufferLength += length
}
companion object {
const val ERROR_BODY_LIMIT = 64 * 1024
const val LINE_LIMIT = 2 * 1024 * 1024
const val QUEUE_BYTE_LIMIT = 8L * 1024 * 1024
const val QUEUE_EVENT_LIMIT = 16384
private const val CR: Byte = '\r'.code.toByte()
private const val LF: Byte = '\n'.code.toByte()
/**
* Unpacks the flat alternating [name, value, name, value, ...] header array the
* TypeScript side builds (okhttp Headers cannot cross the JS bridge). Entries with a
* null/empty name or a null value are skipped, as before.
*/
@JvmStatic
fun unpackHeaders(flat: Array<String?>?): List<Pair<String, String>> {
if (flat == null) return emptyList()
val result = ArrayList<Pair<String, String>>()
var i = 0
while (i + 1 < flat.size) {
val name = flat[i]
val value = flat[i + 1]
if (!name.isNullOrEmpty() && value != null) result.add(name to value)
i += 2
}
return result
}
/** Delivers one event to a [FaceclawSseListener]. */
@JvmStatic
fun deliver(event: SseEvent, listener: FaceclawSseListener) {
when (event) {
is SseEvent.Line -> listener.onLine(event.text)
is SseEvent.HttpError -> listener.onHttpError(event.code, event.body)
SseEvent.Complete -> listener.onComplete()
is SseEvent.Failure -> listener.onFailure(event.message)
}
}
}
}
@@ -0,0 +1,71 @@
package com.faceclaw.app
/** Key/value backing store for app settings (SharedPreferences on Android, NSUserDefaults on iOS). */
interface SettingsStorage {
fun getString(key: String?, defaultValue: String?): String?
fun putString(key: String?, value: String?)
fun getBoolean(key: String?, defaultValue: Boolean): Boolean
fun putBoolean(key: String?, value: Boolean)
}
/** Runs an action on the thread that registered a listener (a Looper Handler, a dispatch queue). */
fun interface SettingsDispatcher {
fun post(action: () -> Unit)
}
/**
* Settings reads/writes plus change fan-out. Each JS isolate registers one listener together
* with a dispatcher for its own thread; every write notifies every listener through its own
* dispatcher, so callbacks never run on a foreign thread. A listener registered without a
* dispatcher is accepted but never notified (it can still read fresh values on demand).
*/
class SettingsChangeHub(
private val storage: SettingsStorage,
private val warn: (String) -> Unit = { PlatformLog.w("FaceclawSettings", it) },
platform: ProtocolPlatform = protocolPlatform(),
) {
private class Entry(val listener: FaceclawSettingsListener, val dispatcher: SettingsDispatcher?)
private val lock = platform.createLock()
private var listeners: List<Entry> = emptyList()
fun getString(key: String?, defaultValue: String?): String? = storage.getString(key, defaultValue)
fun setString(key: String?, value: String?) {
storage.putString(key, value)
notifyChanged(key)
}
fun getBoolean(key: String?, defaultValue: Boolean): Boolean = storage.getBoolean(key, defaultValue)
fun setBoolean(key: String?, value: Boolean) {
storage.putBoolean(key, value)
notifyChanged(key)
}
fun register(listener: FaceclawSettingsListener, dispatcher: SettingsDispatcher?) {
if (dispatcher == null) warn("settings listener registered from a thread without a dispatcher; it will never be notified")
lock.withLock { listeners = listeners + Entry(listener, dispatcher) }
}
fun unregister(listener: FaceclawSettingsListener?) {
lock.withLock { listeners = listeners.filter { it.listener !== listener } }
}
fun notifyChanged(key: String?) {
val current = lock.withLock { listeners }
for (entry in current) {
val dispatcher = entry.dispatcher ?: continue
dispatcher.post {
try {
entry.listener.onSettingChanged(key)
} catch (error: Exception) {
warn("settings listener failed for key $key: ${error.message}")
}
}
}
}
}
@@ -0,0 +1,105 @@
package com.faceclaw.app
/**
* Sleep that another thread can cut short. An interrupt delivered before the sleep begins is
* consumed by the next sleep (returns false immediately) rather than lost: interrupt() runs on
* other threads with no lock held by the sleeper between two work passes, so clearing the flag
* at entry would force a full sleep interval. Returns true when the full duration elapsed.
*/
class InterruptibleSleep(private val platform: ProtocolPlatform = protocolPlatform()) {
private val condition = platform.createCondition()
private var interrupted = false
fun sleep(ms: Long): Boolean {
val deadline = platform.elapsedRealtimeMs() + maxOf(1L, ms)
condition.lock()
try {
if (interrupted) {
interrupted = false
return false
}
while (true) {
val remaining = deadline - platform.elapsedRealtimeMs()
if (remaining <= 0) return true
condition.awaitMs(remaining)
if (interrupted) {
interrupted = false
return false
}
}
} finally {
condition.unlock()
}
}
fun interrupt() {
condition.withLock {
interrupted = true
condition.signalAll()
}
}
}
/** One-shot countdown; await returns true once the count reaches zero, false on timeout. */
class Latch(count: Int, private val platform: ProtocolPlatform = protocolPlatform()) {
private val condition = platform.createCondition()
private var remaining = count
fun countDown() {
condition.withLock {
if (remaining > 0) remaining--
if (remaining == 0) condition.signalAll()
}
}
fun await(timeoutMs: Long): Boolean {
val deadline = platform.elapsedRealtimeMs() + timeoutMs
condition.withLock {
while (remaining > 0) {
val left = deadline - platform.elapsedRealtimeMs()
if (left <= 0) return false
condition.awaitMs(left)
}
return true
}
}
}
/** Unbounded FIFO handoff between threads with a timed poll. */
class BlockingQueue<T : Any>(private val platform: ProtocolPlatform = protocolPlatform()) {
private val condition = platform.createCondition()
private val items = ArrayDeque<T>()
fun put(item: T) {
condition.withLock {
items.addLast(item)
condition.signalAll()
}
}
fun poll(timeoutMs: Long): T? {
val deadline = platform.elapsedRealtimeMs() + timeoutMs
condition.withLock {
while (items.isEmpty()) {
val left = deadline - platform.elapsedRealtimeMs()
if (left <= 0) return null
condition.awaitMs(left)
}
return items.removeFirst()
}
}
fun clear() {
condition.withLock { items.clear() }
}
val size: Int
get() = condition.withLock { items.size }
}
/** Starts a platform thread running [body]; daemon threads never block process exit on the JVM. */
expect fun startThread(name: String, daemon: Boolean, body: () -> Unit)
expect fun sleepMs(ms: Long)
fun currentThreadName(): String = com.faceclaw.shared.PlatformInfo.threadName()
@@ -0,0 +1,451 @@
package com.faceclaw.app
import kotlin.math.abs
import kotlin.math.ceil
import kotlin.math.max
import kotlin.math.min
/**
* Per-frame timing instrumentation, shared between the native BLE layer and the
* Typescript UI layer. A "frame" starts when we receive an input event (or a
* timer fires and we decide to redraw), and finishes when the resulting screen
* update has been fully transmitted to the glasses, is discarded unsent, or
* times out because nobody reported finishing it.
*
* Frames form a tree. One input event can fan out into several renders (the
* focused app's window plus the shell chrome, say), and each of those is its
* own frame linked back to the input frame that caused it via
* [startFrame]. The export nests descendants under their
* root and renders every line against the root's clock, so a single block
* shows the whole input-to-pixels story. Latency percentiles are measured over
* roots: root start to the first descendant that actually reached the glasses.
*
* All public methods are thread-safe and cheap enough to call from the BLE
* worker thread, the platform main thread, the JS thread, and app worker
* threads. Frame IDs are positive ints; 0 means "no frame" and is silently
* ignored everywhere, so callers do not need to null-check.
*
* This core owns the bookkeeping and the export text; the platform facade owns
* the export thread and file write (see the Android `FrameTimings`). The clock
* is [ProtocolPlatform.elapsedRealtimeMs] (monotonic, includes sleep); wall-clock,
* thread names and logging are injectable for tests.
*/
class FrameTimingsCore(
private val platform: ProtocolPlatform = protocolPlatform(),
private val wallClockMs: () -> Long = { currentTimeMillis() },
private val threadName: () -> String = { currentThreadName() },
private val formatWallClock: (Long) -> String = { formatLocalTime(it, "yyyy-MM-dd HH:mm:ss.SSS") },
private val logInfo: (String) -> Unit = { PlatformLog.i(TAG, it) },
private val logWarn: (String) -> Unit = { PlatformLog.w(TAG, it) },
) {
companion object {
const val TAG = "FrameTimings"
/** Frames still open after this long are finished as "timeout". */
const val FRAME_TIMEOUT_MS = 30_000L
const val EXPORT_INTERVAL_MS = 15_000L
const val SWEEP_INTERVAL_MS = 5_000L
private const val RECENT_ROOTS_KEPT = 40
private const val SLOWEST_ROOTS_KEPT = 20
private const val SENT_DURATIONS_WINDOW = 512
private const val MAX_LINES_PER_FRAME = 200
/**
* Frames retained for ID lookup. Well above the number any export can
* reference, so a late log/span/finish call always finds its frame; frames
* older than this are unreachable and get collected.
*/
private const val FRAMES_RETAINED = 1024
private fun percentileOfSorted(sorted: List<Long>, percentile: Int): Long {
val index = ceil(percentile / 100.0 * sorted.size).toInt() - 1
return sorted[max(0, min(sorted.size - 1, index))]
}
/** java.lang.String.format("%+7d"): explicit sign, right-aligned in 7 columns. */
private fun signedWidth7(value: Long): String {
val text = (if (value < 0) "-" else "+") + abs(value).toString()
return text.padStart(7)
}
}
private class Line(
val atMs: Long, // elapsedRealtimeMs
val thread: String,
val message: String?
)
private class Frame(
val id: Int,
var reason: String,
val startedAtMs: Long, // elapsedRealtimeMs
val startedWallClockMs: Long,
val parent: Frame?
) {
val children: MutableList<Frame> = ArrayList(0)
val lines: MutableList<Line> = ArrayList()
val openSpans: MutableMap<String, Long> = LinkedHashMap()
var finishedAtMs: Long = 0
var outcome: String? = null // null while open; "sent", "discarded: ...", "timeout: ..."
/** Set on the root once some frame in its subtree reached the glasses. */
var subtreeSentRecorded = false
fun root(): Frame {
var frame: Frame = this
while (frame.parent != null) {
frame = frame.parent!!
}
return frame
}
fun isOpen(): Boolean = outcome == null
fun durationMs(): Long = finishedAtMs - startedAtMs
fun wasSent(): Boolean {
val outcome = this.outcome
return outcome != null && outcome.startsWith("sent")
}
/** Last moment anything in this subtree happened, for whole-tree duration. */
fun subtreeEndAtMs(nowMs: Long): Long {
var end = if (isOpen()) nowMs else finishedAtMs
for (child in children) {
end = max(end, child.subtreeEndAtMs(nowMs))
}
return end
}
fun subtreeHasOpenFrame(): Boolean {
if (isOpen()) return true
for (child in children) {
if (child.subtreeHasOpenFrame()) return true
}
return false
}
}
private val lock = platform.createLock()
/**
* Every frame we still retain, keyed by ID, in insertion order: open frames
* plus enough history that late calls and the export can still resolve one.
*/
private val framesById: LinkedHashMap<Int, Frame> = LinkedHashMap()
private val recentRoots = ArrayDeque<Frame>()
private val slowestRoots: MutableList<Frame> = ArrayList()
private val inputLatencies = ArrayDeque<Long>()
private val renderLatencies = ArrayDeque<Long>()
private var nextFrameId = 1
private var framesStarted: Long = 0
private var framesSent: Long = 0
private var framesDiscarded: Long = 0
private var framesTimedOut: Long = 0
private var exportDirty = false
/** Begin a root frame; reason is a short label like "input:sys-event type=0". */
fun startFrame(reason: String?): Int = startFrame(reason, 0)
/**
* Begin a frame caused by an existing one (parentFrameId; 0 for a root).
* The child is nested under its root in the export and its latency counts
* against the root, so an input event that fans out into an app render and
* a shell-chrome render reads as one timeline instead of three.
*/
fun startFrame(reason: String?, parentFrameId: Int): Int {
val now = platform.elapsedRealtimeMs()
val frame = lock.withLock {
val parent = framesById[parentFrameId]
val frame = Frame(nextFrameId++, reason ?: "", now, wallClockMs(), parent)
framesById[frame.id] = frame
// Like LinkedHashMap.removeEldestEntry: drop at most the single eldest
// entry per insert, and only when it is already finished.
if (framesById.size > FRAMES_RETAINED) {
val eldest = framesById.entries.first()
if (!eldest.value.isOpen()) framesById.remove(eldest.key)
}
framesStarted++
if (parent != null) {
parent.children.add(frame)
addLineLocked(parent, now, "spawned frame#" + frame.id + " (" + frame.reason + ")")
}
frame
}
return frame.id
}
/**
* Append to a frame's label, for facts only known after it started (which
* app is in the foreground, which window a render is for). Shows up in the
* frame's header line, so the export is scannable without reading bodies.
*/
fun annotate(frameId: Int, text: String?) {
if (text == null || text.isEmpty()) return
lock.withLock {
val frame = framesById[frameId] ?: return
frame.reason = if (frame.reason.isEmpty()) text else frame.reason + " " + text
}
}
fun log(frameId: Int, message: String?) {
val now = platform.elapsedRealtimeMs()
lock.withLock {
val frame = openFrameLocked(frameId) ?: return
addLineLocked(frame, now, message)
}
}
fun spanStart(frameId: Int, name: String) {
val now = platform.elapsedRealtimeMs()
lock.withLock {
val frame = openFrameLocked(frameId) ?: return
frame.openSpans[name] = now
addLineLocked(frame, now, "span $name start")
}
}
fun spanEnd(frameId: Int, name: String) {
val now = platform.elapsedRealtimeMs()
lock.withLock {
val frame = openFrameLocked(frameId) ?: return
val startedAt = frame.openSpans.remove(name)
if (startedAt == null) {
addLineLocked(frame, now, "span $name end (start not recorded)")
} else {
addLineLocked(frame, now, "span " + name + " end (" + (now - startedAt) + "ms)")
}
}
}
/**
* Finish a frame. Outcomes: "sent" (counted in latency percentiles), anything
* starting with "discarded", or "timeout". First finish wins; later calls for
* the same frame are ignored, so racing completion paths are safe.
*/
fun finishFrame(frameId: Int, outcome: String?) {
val now = platform.elapsedRealtimeMs()
val finished = lock.withLock {
val frame = openFrameLocked(frameId) ?: return
finishFrameLocked(frame, now, outcome ?: "discarded: no outcome given")
frame
}
logInfo("frame#" + finished.id + " [" + finished.reason + "] -> " + finished.outcome
+ " in " + finished.durationMs() + "ms")
}
/** One-line stats summary, e.g. for showing in the phone UI. */
fun statsSummary(): String {
lock.withLock {
val input = percentilesLocked(inputLatencies)
return "frames started=" + framesStarted + " sent=" + framesSent +
" discarded=" + framesDiscarded + " timeout=" + framesTimedOut +
(if (input == null)
""
else " | input-to-display p50=" + input[0] + "ms p90=" + input[1] +
"ms p99=" + input[2] + "ms max=" + input[3] + "ms")
}
}
/** Finish every frame open longer than [FRAME_TIMEOUT_MS] as a timeout; returns how many. */
fun sweepTimedOut(): Int {
val now = platform.elapsedRealtimeMs()
val timedOut: MutableList<Frame> = ArrayList()
lock.withLock {
for (frame in ArrayList(framesById.values)) {
if (frame.isOpen() && now - frame.startedAtMs >= FRAME_TIMEOUT_MS) {
finishFrameLocked(frame, now, "timeout: never reported finished")
timedOut.add(frame)
}
}
}
for (frame in timedOut) {
logWarn("frame#" + frame.id + " [" + frame.reason + "] timed out after " +
frame.durationMs() + "ms without being finished")
}
return timedOut.size
}
/** True once a frame finished since the last [takeExport]/[buildExport] with clear. */
val isExportDirty: Boolean
get() = lock.withLock { exportDirty }
/** The full export text (does not clear the dirty flag). */
fun buildExport(): String = lock.withLock { buildExportLocked() }
/** The export text if anything changed since the last take, else null; clears the dirty flag. */
fun takeExport(): String? = lock.withLock {
if (!exportDirty) return null
exportDirty = false
buildExportLocked()
}
// ---------------------------------------------------------------------
/** The frame with this ID if it exists and is still open, else null. */
private fun openFrameLocked(frameId: Int): Frame? {
if (frameId <= 0) return null
val frame = framesById[frameId]
return if (frame != null && frame.isOpen()) frame else null
}
private fun addLineLocked(frame: Frame, now: Long, message: String?) {
if (frame.lines.size >= MAX_LINES_PER_FRAME) {
if (frame.lines.size == MAX_LINES_PER_FRAME) {
frame.lines.add(Line(now, threadName(), "... line cap reached"))
}
return
}
frame.lines.add(Line(now, threadName(), message))
}
private fun finishFrameLocked(frame: Frame, now: Long, outcome: String) {
frame.finishedAtMs = now
frame.outcome = outcome
for (open in frame.openSpans.entries) {
frame.lines.add(Line(now, threadName(),
"span " + open.key + " never ended (started at +" +
(open.value - frame.startedAtMs) + "ms)"))
}
frame.openSpans.clear()
addLineLocked(frame, now, "finished: $outcome")
val root = frame.root()
if (frame.wasSent()) {
framesSent++
// The user-visible latency is input (or timer) to the first pixels
// that actually reached the glasses, wherever in the tree that was.
if (!root.subtreeSentRecorded) {
root.subtreeSentRecorded = true
recordLatencyLocked(root, now - root.startedAtMs)
insertSlowestLocked(root)
}
} else if (outcome.startsWith("timeout")) {
framesTimedOut++
} else {
framesDiscarded++
}
if (root === frame) {
recentRoots.addLast(frame)
while (recentRoots.size > RECENT_ROOTS_KEPT) {
recentRoots.removeFirst()
}
}
exportDirty = true
}
private fun recordLatencyLocked(root: Frame, latencyMs: Long) {
val bucket = if (root.reason.startsWith("input:")) inputLatencies else renderLatencies
bucket.addLast(latencyMs)
while (bucket.size > SENT_DURATIONS_WINDOW) {
bucket.removeFirst()
}
}
private fun insertSlowestLocked(root: Frame) {
if (!slowestRoots.contains(root)) {
slowestRoots.add(root)
}
// Sorted and trimmed at export time, when every subtree duration is final.
}
/** {p50, p90, p99, max} over a rolling latency window, or null if empty. */
private fun percentilesLocked(window: ArrayDeque<Long>): LongArray? {
if (window.isEmpty()) return null
val sorted: MutableList<Long> = ArrayList(window)
sorted.sort()
return longArrayOf(
percentileOfSorted(sorted, 50),
percentileOfSorted(sorted, 90),
percentileOfSorted(sorted, 99),
sorted[sorted.size - 1],
)
}
private fun buildExportLocked(): String {
val now = platform.elapsedRealtimeMs()
val out = StringBuilder(64 * 1024)
out.append("FrameTimings export at ").append(formatWallClock(wallClockMs())).append('\n')
out.append(statsSummaryLocked()).append('\n')
out.append('\n')
out.append("Frames are trees: an input event's own frame is the root, and the renders it\n")
out.append("caused are indented under it with offsets measured from the root's start.\n")
out.append('\n')
// Stable sort, descending by whole-tree duration (matches Collections.sort).
slowestRoots.sortWith(compareByDescending { it.subtreeEndAtMs(now) - it.startedAtMs })
while (slowestRoots.size > SLOWEST_ROOTS_KEPT) {
slowestRoots.removeAt(slowestRoots.size - 1)
}
out.append("=== slowest frames that reached the glasses ===\n")
for (frame in slowestRoots) {
appendTreeLocked(out, frame, frame, now)
}
out.append("=== recent frames (oldest first) ===\n")
for (frame in recentRoots) {
appendTreeLocked(out, frame, frame, now)
}
return out.toString()
}
private fun statsSummaryLocked(): String {
val input = percentilesLocked(inputLatencies)
val render = percentilesLocked(renderLatencies)
val out = StringBuilder()
out.append("frames started=").append(framesStarted).append(" sent=").append(framesSent)
.append(" discarded=").append(framesDiscarded).append(" timeout=").append(framesTimedOut)
.append(" open=").append(openFrameCountLocked())
appendPercentilesLocked(out, "input-to-display latency", inputLatencies.size, input)
appendPercentilesLocked(out, "render-to-display latency", renderLatencies.size, render)
return out.toString()
}
private fun appendPercentilesLocked(out: StringBuilder, label: String, count: Int, percentiles: LongArray?) {
if (percentiles == null) return
out.append('\n').append(label).append(" (last ").append(count).append("): p50=")
.append(percentiles[0]).append("ms p90=").append(percentiles[1])
.append("ms p99=").append(percentiles[2]).append("ms max=").append(percentiles[3]).append("ms")
}
private fun openFrameCountLocked(): Int {
var open = 0
for (frame in framesById.values) {
if (frame.isOpen()) open++
}
return open
}
/** Print a frame and its descendants, all timed against root's start. */
private fun appendTreeLocked(out: StringBuilder, frame: Frame, root: Frame, now: Long) {
var depth = 0
var walk: Frame? = frame
while (walk !== root) {
depth++
walk = walk!!.parent
}
val indent = " ".repeat(depth)
val startOffsetMs = frame.startedAtMs - root.startedAtMs
out.append(indent).append("frame#").append(frame.id)
.append(" [").append(frame.reason).append(']')
if (frame === root) {
out.append(" started ").append(formatWallClock(frame.startedWallClockMs))
val totalMs = frame.subtreeEndAtMs(now) - frame.startedAtMs
out.append(" duration ").append(frame.durationMs()).append("ms")
if (frame.children.isNotEmpty()) {
out.append(" (tree ").append(totalMs).append("ms")
.append(if (frame.subtreeHasOpenFrame()) ", still open" else "").append(')')
}
} else {
out.append(" started +").append(startOffsetMs).append("ms")
.append(" duration ").append(if (frame.isOpen()) "open" else (frame.durationMs().toString() + "ms"))
}
out.append(" outcome ").append(frame.outcome ?: "(open)").append('\n')
for (line in frame.lines) {
out.append(indent).append(" ").append(signedWidth7(line.atMs - root.startedAtMs))
.append("ms [").append(line.thread).append("] ").append(line.message).append('\n')
}
for (child in frame.children) {
appendTreeLocked(out, child, root, now)
}
}
}
@@ -0,0 +1,161 @@
package com.faceclaw.app
import kotlin.jvm.JvmStatic
/** A JSON number kept as its source text so integers and decimals survive a round trip. */
data class JsonNumber(val text: String) {
fun toLong(): Long = text.toLongOrNull() ?: text.toDouble().toLong()
fun toInt(): Int = toLong().toInt()
fun toDouble(): Double = text.toDouble()
companion object {
@JvmStatic fun of(value: Long): JsonNumber = JsonNumber(value.toString())
@JvmStatic fun of(value: Int): JsonNumber = JsonNumber(value.toString())
@JvmStatic
fun of(value: Double): JsonNumber {
require(value.isFinite()) { "JSON numbers must be finite" }
val whole = value.toLong()
return JsonNumber(if (whole.toDouble() == value) whole.toString() else value.toString())
}
}
}
/**
* Minimal JSON codec shared by both platforms (org.json is JVM-only). Values are
* `Map<String, Any?>` (insertion ordered), `List<Any?>`, `String`, `Boolean`, `JsonNumber`
* and `null`. `parse` also accepts `//` and block comments plus trailing commas, which the
* settings documents rely on; `write` always emits strict JSON.
*/
object Json {
private val numberPattern = Regex("-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?(?:[eE][+-]?[0-9]+)?")
@JvmStatic fun parse(text: String): Any? = Parser(text).parse()
@JvmStatic fun parseObject(text: String): Map<String, Any?> = parse(text).asObject() ?: error("JSON object expected")
@JvmStatic fun parseArray(text: String): List<Any?> = parse(text).asArray() ?: error("JSON array expected")
@JvmStatic
fun write(value: Any?, pretty: Boolean = false): String = write(value, pretty, 0)
@JvmStatic
fun quote(text: String): String = buildString {
append('"')
for (c in text) when (c) {
'"' -> append("\\\"")
'\\' -> append("\\\\")
'\n' -> append("\\n")
'\r' -> append("\\r")
'\t' -> append("\\t")
else -> if (c < ' ') append("\\u" + c.code.toString(16).padStart(4, '0')) else append(c)
}
append('"')
}
private fun write(value: Any?, pretty: Boolean, depth: Int): String {
fun collection(open: String, close: String, entries: List<String>): String {
if (entries.isEmpty()) return open + close
return if (pretty) open + "\n" + entries.joinToString(",\n") { " ".repeat(depth + 1) + it } + "\n" + " ".repeat(depth) + close
else open + entries.joinToString(",") + close
}
return when (value) {
null -> "null"
is String -> quote(value)
is Boolean -> value.toString()
is JsonNumber -> value.text
is Int -> value.toString()
is Long -> value.toString()
is Float -> JsonNumber.of(value.toDouble()).text
is Double -> JsonNumber.of(value).text
is List<*> -> collection("[", "]", value.map { write(it, pretty, depth + 1) })
is Array<*> -> collection("[", "]", value.map { write(it, pretty, depth + 1) })
is Map<*, *> -> collection("{", "}", value.entries.map { quote(it.key as String) + (if (pretty) ": " else ":") + write(it.value, pretty, depth + 1) })
else -> error("Unsupported JSON value: ${value::class.simpleName}")
}
}
private class Parser(val text: String) {
var i = 0
fun parse(): Any? { val result = value(0); space(); require(i == text.length) { "Trailing characters in JSON" }; return result }
fun space() {
while (i < text.length) {
if (text[i] in " \r\n\t") { i++; continue }
if (text.startsWith("//", i)) { while (i < text.length && text[i] != '\n' && text[i] != '\r') i++; continue }
if (text.startsWith("/*", i)) { val end = text.indexOf("*/", i + 2); require(end >= 0); i = end + 2; continue }
break
}
}
fun take(c: Char): Boolean { space(); return if (i < text.length && text[i] == c) { i++; true } else false }
fun value(depth: Int): Any? {
require(depth < 64); space(); require(i < text.length) { "Unexpected end of JSON" }
return when (text[i]) {
'"' -> string()
'{' -> {
i++; val result = linkedMapOf<String, Any?>()
if (!take('}')) while (true) {
space(); val key = string(); require(!result.containsKey(key)) { "Duplicate key $key" }; require(take(':'))
result[key] = value(depth + 1)
if (take('}')) break
require(take(',')); if (take('}')) break
}
result
}
'[' -> {
i++; val result = mutableListOf<Any?>()
if (!take(']')) while (true) {
result.add(value(depth + 1)); if (take(']')) break
require(take(',')); if (take(']')) break
}
result
}
't' -> literal("true", true)
'f' -> literal("false", false)
'n' -> literal("null", null)
else -> {
val match = numberPattern.find(text, i)
require(match != null && match.range.first == i) { "Invalid JSON value at $i" }
require(match.value.toDouble().isFinite()); i += match.value.length; JsonNumber(match.value)
}
}
}
fun literal(word: String, result: Any?): Any? { require(text.startsWith(word, i)); i += word.length; return result }
fun string(): String {
require(i < text.length && text[i++] == '"')
return buildString {
while (true) {
require(i < text.length); val c = text[i++]
if (c == '"') break
require(c >= ' ')
if (c != '\\') { append(c); continue }
require(i < text.length)
append(when (val escaped = text[i++]) {
'"', '\\', '/' -> escaped
'b' -> '\b'; 'f' -> '\u000c'; 'n' -> '\n'; 'r' -> '\r'; 't' -> '\t'
'u' -> { require(i + 4 <= text.length); val hex = text.substring(i, i + 4); require(hex.all { it in "0123456789abcdefABCDEF" }); val code = hex.toInt(16); i += 4; code.toChar() }
else -> error("Invalid escape")
})
}
}
}
}
}
// Typed accessors for parsed values; each returns null when the value has another type.
@Suppress("UNCHECKED_CAST")
fun Any?.asObject(): Map<String, Any?>? = this as? Map<String, Any?>
fun Any?.asArray(): List<Any?>? = this as? List<Any?>
fun Any?.asString(): String? = this as? String
fun Any?.asBoolean(): Boolean? = this as? Boolean
fun Any?.asLong(): Long? = (this as? JsonNumber)?.toLong() ?: (this as? Long) ?: (this as? Int)?.toLong()
fun Any?.asInt(): Int? = asLong()?.toInt()
fun Any?.asDouble(): Double? = (this as? JsonNumber)?.toDouble() ?: (this as? Double) ?: (this as? Int)?.toDouble() ?: (this as? Long)?.toDouble()
@@ -0,0 +1,30 @@
package com.faceclaw.app
/** Incremental SHA-256; [digest] finishes the hash. */
expect class Sha256Digest() {
fun update(bytes: ByteArray, offset: Int, length: Int)
fun digest(): ByteArray
}
fun Sha256Digest.update(bytes: ByteArray) = update(bytes, 0, bytes.size)
fun sha256(bytes: ByteArray): ByteArray = Sha256Digest().also { it.update(bytes) }.digest()
fun sha256Hex(bytes: ByteArray): String = BinaryEncoding.bytesToHex(sha256(bytes))
/** Wall-clock milliseconds since the Unix epoch (may jump; use ProtocolPlatform for intervals). */
expect fun currentTimeMillis(): Long
/** Formats [epochMs] in local time with a Unicode/SimpleDateFormat-style [pattern] (e.g. "yyyyMMdd-HHmmss-SSS"). */
expect fun formatLocalTime(epochMs: Long, pattern: String): String
expect object PlatformLog {
fun i(tag: String, message: String)
fun w(tag: String, message: String)
fun e(tag: String, message: String, error: Throwable?)
}
fun PlatformLog.e(tag: String, message: String) = e(tag, message, null)
@@ -0,0 +1,105 @@
@file:OptIn(kotlinx.cinterop.ExperimentalForeignApi::class)
package com.faceclaw.app
import kotlinx.cinterop.addressOf
import kotlinx.cinterop.alloc
import kotlinx.cinterop.convert
import kotlinx.cinterop.free
import kotlinx.cinterop.memScoped
import kotlinx.cinterop.nativeHeap
import kotlinx.cinterop.ptr
import kotlinx.cinterop.reinterpret
import kotlinx.cinterop.usePinned
import platform.CoreCrypto.CC_SHA256_CTX
import platform.CoreCrypto.CC_SHA256_DIGEST_LENGTH
import platform.CoreCrypto.CC_SHA256_Final
import platform.CoreCrypto.CC_SHA256_Init
import platform.CoreCrypto.CC_SHA256_Update
import platform.Foundation.NSDate
import platform.Foundation.NSDateFormatter
import platform.Foundation.NSLocale
import platform.Foundation.NSLog
import platform.Foundation.NSThread
import platform.Foundation.dateWithTimeIntervalSince1970
import platform.Foundation.timeIntervalSince1970
import platform.posix.F_OK
import platform.posix.access
import platform.posix.fclose
import platform.posix.fopen
import platform.posix.fwrite
import platform.posix.rename
import platform.posix.stat
import platform.posix.unlink
import platform.posix.usleep
actual class Sha256Digest actual constructor() {
private var context = nativeHeap.alloc<CC_SHA256_CTX>().also { CC_SHA256_Init(it.ptr) }
private var finished = false
actual fun update(bytes: ByteArray, offset: Int, length: Int) {
check(!finished) { "digest already finished" }
if (length == 0) return
bytes.usePinned { CC_SHA256_Update(context.ptr, it.addressOf(offset), length.convert()) }
}
actual fun digest(): ByteArray {
check(!finished) { "digest already finished" }
val out = ByteArray(CC_SHA256_DIGEST_LENGTH)
out.usePinned { CC_SHA256_Final(it.addressOf(0).reinterpret(), context.ptr) }
nativeHeap.free(context.ptr)
finished = true
return out
}
}
actual fun currentTimeMillis(): Long = (NSDate().timeIntervalSince1970 * 1000.0).toLong()
actual fun formatLocalTime(epochMs: Long, pattern: String): String {
val formatter = NSDateFormatter()
formatter.locale = NSLocale("en_US_POSIX")
formatter.dateFormat = pattern
return formatter.stringFromDate(NSDate.dateWithTimeIntervalSince1970(epochMs / 1000.0))
}
actual object PlatformLog {
actual fun i(tag: String, message: String) = NSLog("%@", "$tag: $message")
actual fun w(tag: String, message: String) = NSLog("%@", "$tag: [warn] $message")
actual fun e(tag: String, message: String, error: Throwable?) =
NSLog("%@", "$tag: [error] $message" + (error?.let { " (${it.message})" } ?: ""))
}
actual fun startThread(name: String, daemon: Boolean, body: () -> Unit) {
val thread = NSThread(block = body)
thread.name = name
thread.start()
}
actual fun sleepMs(ms: Long) {
if (ms > 0) usleep((ms * 1000).convert())
}
actual fun writeFileData(path: String, bytes: ByteArray) {
val file = fopen(path, "wb") ?: error("Cannot write $path")
try {
if (bytes.isNotEmpty())
bytes.usePinned {
check(fwrite(it.addressOf(0), 1u, bytes.size.convert(), file) == bytes.size.convert<platform.posix.size_t>()) { "Short write to $path" }
}
} finally {
fclose(file)
}
}
actual fun fileExists(path: String): Boolean = access(path, F_OK) == 0
actual fun fileLength(path: String): Long = memScoped {
val info = alloc<stat>()
if (stat(path, info.ptr) != 0) -1L else info.st_size
}
actual fun deleteFile(path: String): Boolean = unlink(path) == 0
actual fun renameFile(from: String, to: String): Boolean = rename(from, to) == 0
@@ -10,7 +10,10 @@ import kotlinx.cinterop.*
import platform.CoreBluetooth.CBCharacteristicWriteType
import platform.CoreBluetooth.CBCharacteristicWriteWithResponse
import platform.CoreBluetooth.CBCharacteristicWriteWithoutResponse
import platform.Foundation.NSCondition
import platform.Foundation.NSDate
import platform.Foundation.NSRecursiveLock
import platform.Foundation.dateWithTimeIntervalSinceNow
import platform.posix.CLOCK_MONOTONIC_RAW
import platform.posix.clock_gettime_nsec_np
import platform.posix.memset
@@ -32,6 +35,21 @@ object IosProtocolPlatform : ProtocolPlatform {
override fun createDeflater(): ProtocolDeflater = IosDeflater()
override fun createCondition(): ProtocolCondition =
object : ProtocolCondition {
private val condition = NSCondition()
override fun lock() = condition.lock()
override fun unlock() = condition.unlock()
override fun awaitMs(timeoutMs: Long) {
if (timeoutMs > 0) condition.waitUntilDate(NSDate.dateWithTimeIntervalSinceNow(timeoutMs / 1000.0))
}
override fun signalAll() = condition.broadcast()
}
fun writeType(mode: GattWriteMode): CBCharacteristicWriteType =
when (mode) {
GattWriteMode.WITH_RESPONSE -> CBCharacteristicWriteWithResponse