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

This commit is contained in:
James Babcock committed 2026-09-25 23:12:20 -07:00
commit a2166c6a6c
822 files changed
+79614 -30124

No files matched your search

@@ -0,0 +1,20 @@
package com.faceclaw.app
import java.nio.ByteBuffer
/** NativeScript's ArrayBuffer-backed ByteBuffer stays on the JVM side. */
class AndroidByteReader(buffer: ByteBuffer) : ByteReader() {
// NativeScript can reuse the same ByteBuffer for an ArrayBuffer. Reading one
// frame must not advance the cursor used by a later atlas/preview crossing.
private val buffer = buffer.duplicate()
override fun remaining(): Int = buffer.remaining()
override fun get(): Byte = buffer.get()
override fun get(index: Int): Byte = buffer.get(index)
override fun get(bytes: ByteArray, offset: Int, length: Int): ByteReader {
buffer.get(bytes, offset, length)
return this
}
}
@@ -0,0 +1,31 @@
package com.faceclaw.app
import java.io.FileOutputStream
import java.nio.ByteBuffer
import java.security.MessageDigest
/** Android's bulk ByteBuffer boundary avoids per-byte NativeScript crossings. */
object FaceclawFirmwareUtil {
@JvmStatic fun bytesToHex(bytes: ByteArray?): String = BinaryEncoding.bytesToHex(bytes)
@JvmStatic
fun sha256Hex(data: ByteBuffer): String {
val digest = MessageDigest.getInstance("SHA-256")
digest.update(data.duplicate())
return bytesToHex(digest.digest())
}
@JvmStatic
fun writeFile(path: String, data: ByteBuffer) {
try {
FileOutputStream(path).use { file ->
file.channel.use { channel ->
val view = data.duplicate()
while (view.hasRemaining()) channel.write(view)
}
}
} catch (e: java.io.IOException) {
throw RuntimeException("firmware write failed: ${e.message}", e)
}
}
}
@@ -0,0 +1,72 @@
package com.faceclaw.app
import android.util.Log
import java.io.File
import java.io.IOException
import java.io.RandomAccessFile
/** Android streaming file adapter; the PCM/WAV format is shared Kotlin. */
class FaceclawWavRecorder
@Throws(IOException::class)
constructor(
private val path: String,
private val sampleRate: Int,
private val channels: Int,
) {
private var file: RandomAccessFile?
private var dataBytes = 0L
init {
val parent = File(path).parentFile
if (parent != null && !parent.exists() && !parent.mkdirs())
throw IOException("could not create $parent")
file =
RandomAccessFile(path, "rw").also {
it.setLength(0)
it.write(BinaryEncoding.wavHeader(0, sampleRate, channels))
}
}
@Synchronized
fun append(pcm16le: ByteArray?) {
val current = file ?: return
if (pcm16le == null || pcm16le.isEmpty()) return
try {
current.write(pcm16le)
dataBytes += pcm16le.size
} catch (e: IOException) {
Log.w("FaceclawWavRecorder", "append failed", e)
}
}
@Synchronized fun getDurationMs(): Long = dataBytes * 1000L / (sampleRate * channels * 2L)
fun getPath(): String = path
@Synchronized
fun finish(): Long {
val current = file ?: return dataBytes
file = null
try {
current.use {
it.seek(0)
it.write(
BinaryEncoding.wavHeader(
minOf(dataBytes, Int.MAX_VALUE.toLong()).toInt(),
sampleRate,
channels,
)
)
}
} catch (e: IOException) {
Log.w("FaceclawWavRecorder", "finish failed", e)
}
return dataBytes
}
@Synchronized
fun discard() {
finish()
File(path).delete()
}
}
@@ -0,0 +1,41 @@
package com.faceclaw.app
internal actual fun protocolPlatform(): ProtocolPlatform = AndroidProtocolPlatform
internal actual fun readFileData(path: String): ByteArray {
val file = java.io.File(path)
require(file.isFile && file.canRead() && file.length() <= Int.MAX_VALUE)
return file.readBytes()
}
internal actual fun deflateData(bytes: ByteArray): ByteArray {
val encoder = java.util.zip.Deflater()
try {
encoder.setInput(bytes)
encoder.finish()
val out = ByteSink()
val buffer = ByteArray(8192)
while (!encoder.finished()) out.write(buffer, 0, encoder.deflate(buffer))
return out.toByteArray()
} finally {
encoder.end()
}
}
internal actual fun inflateData(bytes: ByteArray, size: Int): ByteArray {
val decoder = java.util.zip.Inflater()
try {
decoder.setInput(bytes)
val result = ByteArray(size)
var offset = 0
while (offset < size && !decoder.finished()) {
val count = decoder.inflate(result, offset, size - offset)
if (count == 0) break
offset += count
}
check(offset == size) { "recorded frame truncated: $offset of $size" }
return result
} finally {
decoder.end()
}
}
@@ -0,0 +1,61 @@
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 fun localUtcOffsetMs(epochMs: Long): Int = java.util.TimeZone.getDefault().getOffset(epochMs)
actual fun localTimeZoneId(): String = java.util.TimeZone.getDefault().id
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))
@@ -0,0 +1,64 @@
package com.faceclaw.app
import android.bluetooth.BluetoothGattCharacteristic
import android.os.SystemClock
import java.io.ByteArrayOutputStream
import java.util.concurrent.locks.ReentrantLock
import java.util.zip.Deflater
object AndroidProtocolPlatform : ProtocolPlatform {
override fun elapsedRealtimeMs(): Long = SystemClock.elapsedRealtime()
override fun createLock(): ProtocolLock =
object : ProtocolLock {
private val lock = ReentrantLock()
override fun lock() = lock.lock()
override fun unlock() = lock.unlock()
}
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) {
GattWriteMode.WITH_RESPONSE -> BluetoothGattCharacteristic.WRITE_TYPE_DEFAULT
GattWriteMode.WITHOUT_RESPONSE -> BluetoothGattCharacteristic.WRITE_TYPE_NO_RESPONSE
}
}
private class AndroidDeflater : ProtocolDeflater {
private val deflater = Deflater()
override fun reset() = deflater.reset()
override fun syncFlush(message: ByteArray): ByteArray {
deflater.setInput(message)
val out = ByteArrayOutputStream()
val chunk = ByteArray(4096)
do {
val count = deflater.deflate(chunk, 0, chunk.size, Deflater.SYNC_FLUSH)
out.write(chunk, 0, count)
} while (count == chunk.size)
return out.toByteArray()
}
override fun close() = deflater.end()
}
@@ -0,0 +1,15 @@
package com.faceclaw.app
import java.util.concurrent.ScheduledThreadPoolExecutor
import java.util.concurrent.TimeUnit
private object DrawRedrawScheduler {
val executor = ScheduledThreadPoolExecutor(1) { task ->
Thread(task, "Faceclaw draw animation").apply { isDaemon = true }
}.apply { removeOnCancelPolicy = true }
}
internal actual fun scheduleDrawRedraw(delayMs: Int, action: () -> Unit): () -> Unit {
val future = DrawRedrawScheduler.executor.schedule(action, delayMs.toLong(), TimeUnit.MILLISECONDS)
return { future.cancel(false); Unit }
}
@@ -0,0 +1,11 @@
package com.faceclaw.shared
import android.os.Looper
internal actual object PlatformInfo {
actual val name: String = "Android"
actual fun threadName(): String = Thread.currentThread().name
actual fun isMainThread(): Boolean = Looper.myLooper() == Looper.getMainLooper()
}
@@ -0,0 +1,22 @@
package com.faceclaw.app
/** Platform selection happens at compilation; protocol algorithms stay shared. */
internal expect fun protocolPlatform(): ProtocolPlatform
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
@@ -0,0 +1,70 @@
package com.faceclaw.app
/** Shared on-disk settings format. Native adapters own locking and atomic IO. */
class SettingsDocument private constructor(private val settings: Map<String, Any?>) {
fun containsString(key: String, value: String): Boolean = settings[key] == structuredValue(key, value)
fun getString(key: String, fallback: String): String = when (val value = settings[key]) {
is String -> value
is Map<*, *>, is List<*> -> Json.write(value)
else -> fallback
}
fun getBoolean(key: String, fallback: Boolean): Boolean = settings[key] as? Boolean ?: fallback
fun getNumber(key: String, fallback: Double): Double = (settings[key] as? JsonNumber)?.text?.toDoubleOrNull() ?: fallback
fun replacingNumber(key: String, value: Double): SettingsDocument =
SettingsDocument(settings + (key to JsonNumber(value.toString())))
fun removing(key: String): SettingsDocument = SettingsDocument(settings - key)
fun replacingString(key: String, value: String): SettingsDocument =
SettingsDocument(settings + (key to structuredValue(key, value)))
fun replacingBoolean(key: String, value: Boolean): SettingsDocument = SettingsDocument(settings + (key to value))
fun merged(other: SettingsDocument): SettingsDocument = SettingsDocument(settings + other.settings)
fun encode(): String = Json.write(mapOf("schema" to JsonNumber(CURRENT_SCHEMA.toString()), "settings" to settings), pretty = true) + "\n"
// A mutation/merge must never commit a document that the next launch rejects.
fun encodeForStorage(): String? {
val text = encode()
return if (runCatching { decode(text) }.isSuccess) text else null
}
companion object {
const val CURRENT_SCHEMA = 2
// Explicit keys avoid interpreting arbitrary text (prompts, passwords, drafts) as JSON.
private val structuredKeys = setOf(
"terminal.connections", "teleprompter.recents", "launcher.folders", "notifications.sources",
"files.bookmarks", "music.apps", "microphones.array-config", "display.uiFont2", "terminal.font",
"navigate.savedDestinations", "navigate.recentDestinations", "evenhub.installedApps.v1", "timers.state", "assistant.conversations"
)
private fun structuredValue(key: String, value: Any?): Any? {
if ((key !in structuredKeys && !key.startsWith("ios.ble.peripheral.")) || value !is String) return value
// Preserve empty/invalid old values: callers already provide their own fallback.
val parsed = runCatching { Json.parse(value) }.getOrNull()
return if (parsed is Map<*, *> || parsed is List<*>) parsed else value
}
// Each entry migrates version N to N+1. Never rewrite unknown future schemas.
private val migrations: Map<Int, (Map<String, Any?>) -> Map<String, Any?>> = mapOf(
1 to { old -> old.mapValues { (key, value) -> structuredValue(key, value) } }
)
internal fun decode(text: String): SettingsDocument {
require(text.encodeToByteArray().size <= 2 * 1024 * 1024) { "Config exceeds 2 MiB" }
val root = Json.parse(text) as? Map<*, *> ?: error("Expected config object")
var schema = (root["schema"] as? JsonNumber)?.text?.toIntOrNull() ?: error("Missing schema")
require(schema in 1..CURRENT_SCHEMA) { "Unsupported settings schema" }
val raw = root["settings"] as? Map<*, *> ?: error("Missing settings")
require(raw.size <= 4096)
var values: Map<String, Any?> = raw.entries.associate { (key, value) ->
require(key is String && key.isNotEmpty() && key.length <= 512)
require(value != null) { "Null setting" }
key to value
}
while (schema < CURRENT_SCHEMA) values = migrations.getValue(schema++)(values)
return SettingsDocument(values)
}
}
}
/** Nullable decode keeps invalid files recoverable across Objective-C/JVM bridges. */
class SettingsCodec {
fun needsMigration(text: String): Boolean = runCatching {
((Json.parse(text) as Map<*, *>)["schema"] as JsonNumber).text != SettingsDocument.CURRENT_SCHEMA.toString()
}.getOrDefault(false)
fun decode(text: String): SettingsDocument? = runCatching { SettingsDocument.decode(text) }.getOrNull()
}
@@ -0,0 +1,66 @@
package com.faceclaw.app
import kotlin.math.max
import kotlin.math.sqrt
/** Ends a hands-free utterance using the 16 kHz sample clock, not BLE arrival timing.
* Shared by Android's voice controller and iOS's native audio queue.
*/
class VoiceEndpointDetector {
private var totalSamples = 0L
private var noiseAccum = 0.0
private var noisePackets = 0
private var threshold = 0.0
private var speechStarted = false
private var silenceSamples = 0L
private var fired = false
fun reset() {
totalSamples = 0
noiseAccum = 0.0
noisePackets = 0
threshold = 0.0
speechStarted = false
silenceSamples = 0
fired = false
}
fun accept(pcm: ShortArray, count: Int): Boolean {
if (fired || count <= 0) return false
require(count <= pcm.size)
var squares = 0.0
for (i in 0 until count) {
val sample = pcm[i].toDouble()
squares += sample * sample
}
return acceptLevel(sqrt(squares / count), count)
}
/** RMS in PCM16 units. Allows native decoders to reuse their existing level calculation. */
fun acceptLevel(rms: Double, sampleCount: Int): Boolean {
if (fired || sampleCount <= 0) return false
totalSamples += sampleCount
val elapsedMs = totalSamples * 1000 / 16000
if (elapsedMs <= 300) {
noiseAccum += rms
noisePackets++
return false
}
if (threshold == 0.0) threshold = max(if (noisePackets > 0) noiseAccum / noisePackets else 0.0, 220.0)
if (!speechStarted) {
if (rms >= threshold * 3.0) {
speechStarted = true
silenceSamples = 0
} else if (elapsedMs >= 6000) {
fired = true
}
return fired
}
if (rms < threshold * 1.8) {
silenceSamples += sampleCount
if (silenceSamples * 1000 / 16000 >= 900) fired = true
} else silenceSamples = 0
if (elapsedMs >= 30000) fired = true
return fired
}
}
@@ -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,263 @@
package com.faceclaw.app
import kotlin.math.roundToInt
/**
* Spectral suppression for PCM from glasses microphones: 16 ms sqrt-Hann frames at 50% overlap,
* asymmetric noise-floor tracking and a smoothed Wiener gain. Android capture-session effects live
* in AndroidNoiseEffects. This processor has no platform dependencies and must be owned by a single
* audio worker.
*/
class FaceclawNoiseSuppressor {
companion object {
private const val FFT_SIZE: Int = 256
private val HOP: Int = (FFT_SIZE / 2)
private val OVERSUBTRACTION: Float = 1.6f
/** About -16 dB of residual: keeps the noise bed natural instead of gated. */
private val GAIN_FLOOR: Float = 0.15f
private val GAIN_SMOOTHING: Float = 0.6f
/** Frames of pure noise-floor learning after start/reset (~100 ms). */
private const val NOISE_WARMUP_FRAMES: Int = 12
/** In-place iterative radix-2 FFT (inverse includes the 1/N scale). */
private fun fft(re: FloatArray, im: FloatArray, inverse: Boolean): Unit {
var n: Int = re.size
run {
var i: Int = 1
var j: Int = 0
while ((i < n)) {
var bit: Int = (n shr 1)
run {
while (((j and bit) != 0)) {
j = (j xor bit)
bit = (bit shr 1)
}
}
j = (j xor bit)
if ((i < j)) {
var t: Float = re[i]
re[i] = re[j]
re[j] = t
t = im[i]
im[i] = im[j]
im[j] = t
}
i++
}
}
run {
var len: Int = 2
while ((len <= n)) {
var ang: Double = (((2 * kotlin.math.PI) / len) * (if (inverse) 1 else -1))
var wRe: Float = (kotlin.math.cos(ang)).toFloat()
var wIm: Float = (kotlin.math.sin(ang)).toFloat()
run {
var i: Int = 0
while ((i < n)) {
var curRe: Float = 1f
var curIm: Float = 0f
run {
var k: Int = 0
while ((k < (len / 2))) {
var a: Int = (i + k)
var b: Int = (a + (len / 2))
var xr: Float = ((re[b] * curRe) - (im[b] * curIm))
var xi: Float = ((re[b] * curIm) + (im[b] * curRe))
re[b] = (re[a] - xr)
im[b] = (im[a] - xi)
re[a] += xr
im[a] += xi
var nextRe: Float = ((curRe * wRe) - (curIm * wIm))
curIm = ((curRe * wIm) + (curIm * wRe))
curRe = nextRe
k++
}
}
i += len
}
}
len = (len shl 1)
}
}
if (inverse) {
run {
var i: Int = 0
while ((i < n)) {
re[i] /= n
im[i] /= n
i++
}
}
}
}
}
private val sampleRate: Int
private val window: FloatArray = FloatArray(FFT_SIZE)
private val history: FloatArray = FloatArray(FFT_SIZE)
private val overlap: FloatArray = FloatArray(HOP)
private val noise: FloatArray = FloatArray(((FFT_SIZE / 2) + 1))
private val gain: FloatArray = FloatArray(((FFT_SIZE / 2) + 1))
private val re: FloatArray = FloatArray(FFT_SIZE)
private val im: FloatArray = FloatArray(FFT_SIZE)
private val pending: ShortArray = ShortArray(HOP)
private var pendingCount: Int = 0
private var warmupFrames: Int = 0
constructor(sampleRate: Int) {
this.sampleRate = sampleRate
run {
var i: Int = 0
while ((i < FFT_SIZE)) {
window[i] = (kotlin.math.sin(((kotlin.math.PI * (i + 0.5)) / FFT_SIZE))).toFloat()
i++
}
}
reset()
}
fun getSampleRate(): Int {
return sampleRate
}
/** Forget the learned noise floor (e.g. after the suppressor was toggled off). */
fun reset(): Unit {
history.fill(0f)
overlap.fill(0f)
noise.fill(0f)
gain.fill(1f)
pendingCount = 0
warmupFrames = 0
}
/**
* Suppress noise in 16-bit little-endian mono PCM. Streaming: input not filling a whole 8 ms
* hop is carried into the next call, so the output may be up to one hop shorter than the input
* (and longer on a later call); total latency is one hop.
*/
fun process(pcm16le: ByteArray?): ByteArray? {
if (((pcm16le == null) || (pcm16le.size < 2))) {
return pcm16le
}
var sampleCount: Int = (pcm16le.size / 2)
var hops: Int = ((pendingCount + sampleCount) / HOP)
var out: ByteArray = ByteArray(((hops * HOP) * 2))
var outPos: Int = 0
var inPos: Int = 0
while ((inPos < sampleCount)) {
var take: Int = minOf((HOP - pendingCount), (sampleCount - inPos))
run {
var i: Int = 0
while ((i < take)) {
var lo: Int = (pcm16le[((inPos + i) * 2)] and 0xff)
var hi: Int = pcm16le[(((inPos + i) * 2) + 1)].toInt()
pending[(pendingCount + i)] = (((hi shl 8) or lo)).toShort()
i++
}
}
pendingCount += take
inPos += take
if ((pendingCount == HOP)) {
outPos = processHop(out, outPos)
pendingCount = 0
}
}
return out
}
private fun processHop(out: ByteArray, outPos: Int): Int {
var outPos = outPos
history.copyInto(history, 0, HOP, HOP + (FFT_SIZE - HOP))
run {
var i: Int = 0
while ((i < HOP)) {
history[((FFT_SIZE - HOP) + i)] = (pending[i] / 32768f)
i++
}
}
run {
var i: Int = 0
while ((i < FFT_SIZE)) {
re[i] = (history[i] * window[i])
im[i] = 0f
i++
}
}
fft(re, im, false)
var warming: Boolean = (warmupFrames < NOISE_WARMUP_FRAMES)
if (warming) {
warmupFrames++
}
run {
var b: Int = 0
while ((b <= (FFT_SIZE / 2))) {
var power: Float = ((re[b] * re[b]) + (im[b] * im[b]))
if (warming) {
noise[b] =
(if ((warmupFrames == 1)) power
else (noise[b] + ((power - noise[b]) / warmupFrames)))
} else {
if ((power < noise[b])) {
noise[b] += ((power - noise[b]) * 0.2f)
} else {
noise[b] = minOf(power, ((noise[b] * 1.006f) + 1e-10f))
}
}
var clean: Float = (power - (OVERSUBTRACTION * noise[b]))
var g: Float = (if ((clean > 0f)) (clean / power) else 0f)
if ((g < GAIN_FLOOR)) {
g = GAIN_FLOOR
}
g = ((GAIN_SMOOTHING * gain[b]) + ((1f - GAIN_SMOOTHING) * g))
gain[b] = g
re[b] *= g
im[b] *= g
if (((b > 0) && (b < (FFT_SIZE / 2)))) {
re[(FFT_SIZE - b)] *= g
im[(FFT_SIZE - b)] *= g
}
b++
}
}
fft(re, im, true)
run {
var i: Int = 0
while ((i < HOP)) {
var value: Float = ((overlap[i] + (re[i] * window[i])) * 32767f)
var sample: Int = value.roundToInt()
if ((sample > 32767)) {
sample = 32767
}
if ((sample < -32768)) {
sample = -32768
}
out[(outPos + (i * 2))] = ((sample and 0xff)).toByte()
out[((outPos + (i * 2)) + 1)] = (((sample shr 8) and 0xff)).toByte()
i++
}
}
run {
var i: Int = 0
while ((i < HOP)) {
overlap[i] = (re[(HOP + i)] * window[(HOP + i)])
i++
}
}
return (outPos + (HOP * 2))
}
}
@@ -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,6 @@
package com.faceclaw.app
/** Phone-side alarm actions (dismiss / snooze), delivered to the JS engine; implemented in JS. */
interface FaceclawAlarmListener {
fun onPhoneAction(id: Long, action: String?, minutes: Int): Unit
}
@@ -0,0 +1,10 @@
package com.faceclaw.app
interface FaceclawAmbientLightListener {
/**
* A CFW ambient-light report (settings-channel field 105) from the master temple. body is the
* raw 24-byte ['A','L',ver,reason,...] record; it is decoded on the TS side
* (app/native/ambient-light.ts).
*/
fun onAmbientLight(body: ByteArray?): Unit
}
@@ -0,0 +1,5 @@
package com.faceclaw.app
interface FaceclawAudioPacketListener {
fun onAudioPacket(data: ByteArray?, arm: String?, arrivalMs: Long): Unit
}
@@ -0,0 +1,39 @@
package com.faceclaw.app
interface FaceclawBleCommunicatorListener {
fun onStateChange(phase: String?, status: String?): Unit
fun onRingEvent(
kind: String?,
containerName: String?,
eventType: Int,
eventSource: Int,
systemExitReasonCode: Int,
frameId: Int,
ringTick: Long,
ringType: Int,
ringAux: Int,
ringSpeed: Int,
): Unit
fun onBatteryState(
headsetBattery: Int,
headsetCharging: Int,
ringBattery: Int,
ringCharging: Int,
): Unit
fun onSilentMode(silent: Boolean): Unit
fun onWearState(wearing: Boolean): Unit
fun onPhoneLockState(locked: Boolean): Unit
fun onEvenAppConflict(message: String?): Unit
fun onFrameMetrics(paintMs: Int, transmitMs: Int, tileCount: Int): Unit
fun onFrameFinished(frameId: Int, outcome: String?): Unit
fun onFirmwareInfo(leftVersion: String?, rightVersion: String?, extension: String?): Unit
}
@@ -0,0 +1,7 @@
package com.faceclaw.app
interface FaceclawBleListener {
fun onNotification(address: String?, characteristicUuid: String?, data: ByteArray?): Unit
fun onConnectionStateChange(address: String?, connected: Boolean): Unit
}
@@ -0,0 +1,22 @@
package com.faceclaw.app
interface FaceclawCaptionEngineListener {
/**
* One finished utterance. text may be empty when no ASR model is loaded or recognition produced
* nothing; embedding is the L2-normalized voice-print or null when the speaker model is
* unavailable or the utterance was too short. startMs/endMs are on the engine's sample clock
* (milliseconds of audio since start()).
*/
fun onUtterance(
text: String?,
embedding: FloatArray?,
startMs: Long,
endMs: Long,
peakRms: Double,
): Unit
/** A speech onset was detected; the utterance is now being collected. */
fun onSpeechStart(startMs: Long): Unit
fun onStatus(status: String?): Unit
}
@@ -0,0 +1,14 @@
package com.faceclaw.app
/** Receives stock compass heading and calibration notifications on the thread that subscribed. */
interface FaceclawCompassListener {
fun onCompassEvent(
command: Int,
headingDegrees: Int,
magneticAccuracy: Int,
magneticAnomalies: Int,
orientationSource: Int,
diagnosticFlags: Int,
sampleTimeMs: Long,
): Unit
}
@@ -0,0 +1,17 @@
package com.faceclaw.app
/** Callbacks from FaceclawDeviceDiscovery's live scan to the TypeScript layer. */
interface FaceclawDeviceDiscoveryListener {
/**
* One advertisement (or one bonded device) as a JSON object: {address, name, manufacturerData
* (hex, company id included), rssi|null, txPower|null, connectable|null, bonded, source,
* seenAtMs}. Protocol decoding happens in TypeScript (see app/g2/even-advertisement.ts).
*/
fun onAdvertisement(json: String?): Unit
/** The platform refused to start or continue the scan. */
fun onScanFailed(errorCode: Int, message: String?): Unit
/** Diagnostic line for the pairing log. */
fun onLog(line: String?): Unit
}
@@ -0,0 +1,15 @@
package com.faceclaw.app
/** Callbacks from FaceclawDeviceInfoProbe to the TypeScript layer. */
interface FaceclawDeviceInfoProbeListener {
fun onLog(line: String?): Unit
/** Lifecycle: connecting/authenticating for each arm, then querying. */
fun onState(state: String?, detail: String?): Unit
/** Terminal success: firmware versions and the firmware-extension string (empty on stock). */
fun onResult(leftVersion: String?, rightVersion: String?, extension: String?): Unit
/** Terminal failure (couldn't connect or read the version). */
fun onError(message: String?): Unit
}
@@ -0,0 +1,18 @@
package com.faceclaw.app
/**
* Callbacks from a hosted EvenHub app's WebView to the TypeScript host. All methods are delivered
* on the Android main thread (NativeScript's JS thread), regardless of which WebView-internal
* thread produced them.
*/
interface FaceclawEvenHubListener {
/**
* The app invoked window.flutter_inappwebview.callHandler(handlerName, ...args). argsJson is
* the JSON-encoded argument array; callId identifies the promise to resolve via
* window.__fcResolve(callId, ok, value).
*/
fun onEvenAppMessage(handlerName: String?, argsJson: String?, callId: Int): Unit
/** The WebView finished loading the app's page. */
fun onPageFinished(url: String?): Unit
}
@@ -0,0 +1,30 @@
package com.faceclaw.app
/** Callbacks from FaceclawFirmwareFlasher to the TypeScript layer. */
interface FaceclawFirmwareFlasherListener {
fun onLog(line: String?): Unit
/**
* Fine-grained progress for the UI bar. `lens` is "left"/"right"; component/block indices are
* 1-based against their counts. `bytesSent` / `bytesTotal` cover the whole lens image, so a bar
* driven by them moves evenly even though the components differ wildly in size.
*/
fun onProgress(
lens: String?,
componentIndex: Int,
componentCount: Int,
blockIndex: Int,
blockCount: Int,
bytesSent: Long,
bytesTotal: Long,
): Unit
/**
* Coarse lifecycle. `state` is one of: validating, connecting, flashing, rebooting, done,
* error. `detail` carries the lens name or a message.
*/
fun onState(state: String?, detail: String?): Unit
/** Terminal callback: success or failure, with an explanatory message. */
fun onComplete(success: Boolean, detail: String?): Unit
}
@@ -0,0 +1,25 @@
package com.faceclaw.app
/** Callbacks from FaceclawFlashPromptCommunicator to the TypeScript layer. */
interface FaceclawFlashPromptListener {
fun onLog(line: String?): Unit
/**
* Lifecycle updates. `state` is one of: connecting, connected, prompting, battery, result,
* cancelled, timeout, disconnected, error. `detail` carries the "approved"/"declined" text for
* result, or an error/explanation message.
*/
fun onState(state: String?, detail: String?): Unit
/**
* Battery percent of each arm, read after the user approved (or right after auth when the
* prompt is skipped); -1 when an arm didn't answer. Always fires before onResult(true).
*/
fun onBattery(rightPercent: Int, leftPercent: Int): Unit
/**
* Fires once the user picks a menu row (or, with skipPrompt, once the battery is read): true =
* flash, false = cancel.
*/
fun onResult(approved: Boolean): Unit
}
@@ -0,0 +1,9 @@
package com.faceclaw.app
/**
* Receives IMU (accelerometer) readings decoded from the glasses' sys-event stream. Registered on
* FaceclawBleCommunicator via addImuListener; callbacks are delivered on the Android main thread.
*/
interface FaceclawImuListener {
fun onImuData(x: Double, y: Double, z: Double, eventSource: Int): Unit
}
@@ -0,0 +1,16 @@
package com.faceclaw.app
/**
* Callbacks for one on-phone LLM generation. Like the other bridge listeners, implementations are
* typically created on the NativeScript JS thread and FaceclawLlamaRunner posts these callbacks
* back to that thread's Looper.
*/
interface FaceclawLlamaListener {
/** A piece of generated text (may be a partial word). */
fun onToken(piece: String?): Unit
/** Generation finished: "stop" (EOG), "length", or "cancelled". */
fun onDone(stopReason: String?): Unit
fun onError(message: String?): Unit
}
@@ -0,0 +1,13 @@
package com.faceclaw.app
/** One-shot Android location callbacks for the TypeScript Weather bridge. */
interface FaceclawLocationListener {
fun onLocation(
latitude: Double,
longitude: Double,
accuracyMeters: Float,
timestampMs: Long,
): Unit
fun onError(message: String?): Unit
}
@@ -0,0 +1,19 @@
package com.faceclaw.app
/** Continuous location callbacks for the TypeScript navigation bridge. */
interface FaceclawLocationTrackerListener {
/**
* A new fix. bearingDeg/speedMps are -1 when the fix doesn't carry them (common when
* stationary); accuracyMeters is -1 when unknown.
*/
fun onLocation(
latitude: Double,
longitude: Double,
accuracyMeters: Float,
bearingDeg: Float,
speedMps: Float,
timestampMs: Long,
): Unit
fun onError(message: String?): Unit
}
@@ -0,0 +1,10 @@
package com.faceclaw.app
interface FaceclawMediaBrowserListener {
fun onConnectResult(requestId: Int, connected: Boolean, rootId: String?, error: String?): Unit
fun onBrowseResult(requestId: Int, childrenJson: String?, error: String?): Unit
/** The service connection dropped after connecting (player crashed or was killed). */
fun onDisconnected(): Unit
}
@@ -0,0 +1,23 @@
package com.faceclaw.app
interface FaceclawMediaControllerListener {
/** All observed session owners, before filtering or choosing the active player. */
fun onSessionAppsChanged(appsJson: String?): Unit
fun onStateChange(
playbackState: String?,
packageName: String?,
appName: String?,
title: String?,
artist: String?,
album: String?,
positionMs: Long,
durationMs: Long,
playbackSpeed: Float,
canPlayPause: Boolean,
canSkipNext: Boolean,
canSkipPrevious: Boolean,
accessEnabled: Boolean,
status: String?,
): Unit
}
@@ -0,0 +1,10 @@
package com.faceclaw.app
interface FaceclawMicStatusListener {
/**
* A CFW mic_control field-104 status record from one temple. body is the raw 21-byte
* ['M','C',ver,...] record (decoded on the TS side); arm is "L" or "R" for the temple's own BLE
* link, "?" if unmatched.
*/
fun onMicStatus(body: ByteArray?, arm: String?): Unit
}
@@ -0,0 +1,11 @@
package com.faceclaw.app
/** Progress callbacks for FaceclawModelDownloader, posted to the creating thread's Looper. */
interface FaceclawModelDownloaderListener {
fun onProgress(bytesDownloaded: Long, totalBytes: Long): Unit
/** The file is fully downloaded, verified, and moved to its final path. */
fun onDone(path: String?): Unit
fun onError(message: String?): Unit
}
@@ -0,0 +1,5 @@
package com.faceclaw.app
interface FaceclawNotificationListener {
fun onNotificationPosted(key: String?): Unit
}
@@ -0,0 +1,10 @@
package com.faceclaw.app
/** Callbacks for one FaceclawQrScanner.scan; exactly one method fires. */
interface FaceclawQrScannerListener {
fun onResult(text: String?): Unit
fun onCancelled(): Unit
fun onError(message: String?): Unit
}
@@ -0,0 +1,6 @@
package com.faceclaw.app
/** Change-notification callback for FaceclawSettings; implemented in JS. */
interface FaceclawSettingsListener {
fun onSettingChanged(key: String?): Unit
}
@@ -0,0 +1,16 @@
package com.faceclaw.app
/** Callbacks for FaceclawSseRequest, delivered on the constructing thread's Looper. */
interface FaceclawSseListener {
/** One line of a successful (2xx) streaming response body, without the newline. */
fun onLine(line: String?): Unit
/** The server answered with a non-2xx status; body is the full error body. */
fun onHttpError(code: Int, body: String?): Unit
/** The 2xx response body ended normally. */
fun onComplete(): Unit
/** Network-level failure (connect, TLS, mid-stream drop). Not called after cancel(). */
fun onFailure(message: String?): Unit
}
@@ -0,0 +1,44 @@
package com.faceclaw.app
interface FaceclawVoiceControllerListener {
fun onStatus(status: String?): Unit
/**
* Best transcript of the current utterance so far. REPLACE semantics: text is the complete
* transcript, not a delta — display it verbatim, replacing any previous partial. isFinal marks
* the end of the utterance.
*/
fun onTranscript(text: String?, isFinal: Boolean): Unit
/** Capture has finished, after the final transcript or a startup/recognition error. */
fun onStopped(captureId: Int): Unit
/**
* Decoded microphone audio: 16 kHz mono signed 16-bit little-endian PCM. Emitted in every mode
* so raw-PCM consumers (levels, recording, captions) keep working while the onboard recognizer
* owns the transcript.
*/
fun onPcm(pcm16le: ByteArray?): Unit
/**
* Per-packet DSP metadata the glasses firmware appends to each 50 ms audio packet, computed on
* the raw stereo capture before its mono downmix: the direction-of-arrival in signed degrees (0
* = straight ahead, positive to the wearer's right) and a signal-strength ratio that serves as
* a confidence/energy proxy for the angle.
*/
fun onFrameMeta(angleDegrees: Int, ssr: Int): Unit
/**
* The speaker stopped, in a hands-free session that has no button release to end it. Only fires
* when endpointing was enabled for the session; see FaceclawVoiceController.setEndpointing.
*/
fun onSpeechEnd(): Unit
/**
* Result of speaker verification against the enrolled wearer voice-print, emitted once per
* capture session just before the final transcript. Only fires when verification was configured
* for the session; fails open (isWearer=true) when the utterance was too short to verify or the
* speaker model could not be loaded.
*/
fun onSpeakerVerified(isWearer: Boolean, similarity: Float): Unit
}
@@ -0,0 +1,17 @@
package com.faceclaw.app
/**
* Callbacks from the Android Wear (Wear OS) bridge; implemented in JS. Every call is delivered on
* the thread that registered the listener (see FaceclawWearBridge.setListener).
*/
interface FaceclawWearListener {
/**
* A message from the watch app. `path` is the Data Layer message path (e.g. "/faceclaw/input");
* `json` is the UTF-8 payload (always a JSON object, "{}" when the watch sent none); `nodeId`
* identifies the watch so a reply can be addressed to it.
*/
fun onMessage(path: String?, json: String?, nodeId: String?): Unit
/** The set of reachable watches running the Faceclaw watch app changed. */
fun onWatchConnection(reachable: Boolean, watchName: String?): Unit
}
@@ -0,0 +1,12 @@
package com.faceclaw.app
/** Callbacks for FaceclawWebSocket, delivered on the Android main thread. */
interface FaceclawWebSocketListener {
fun onOpen(): Unit
fun onTextMessage(message: String?): Unit
fun onClosed(code: Int, reason: String?): Unit
fun onFailure(message: String?): Unit
}
@@ -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,735 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
import kotlin.jvm.JvmStatic
class BleImageOptimizer {
companion object {
private const val TAG: String = "BleImageOptimizer"
/**
* Split an image into fragments (packets), taking advantage of the fact that each packet
* can declare a logical size longer than its byte payload to get free trailing
* zero-padding.
*
* Each fragment's logical size stays within maxFragmentSize, while trailing zeros inside
* that span can be omitted from the payload.
*/
@JvmStatic
fun planImageFragments(
bmp: ByteArray,
maxFragmentSize: Int,
): MutableList<BleProtocol.ImageFragment> {
return planImageFragments(bmp, maxFragmentSize, false)
}
@JvmStatic
fun planImageFragments(
bmp: ByteArray?,
maxFragmentSize: Int,
reserveFinalByte: Boolean,
): MutableList<BleProtocol.ImageFragment> {
if (((bmp == null) || (bmp.size == 0))) {
return mutableListOf(BleProtocol.ImageFragment(0, ByteArray(0), 0))
}
if ((maxFragmentSize <= 0)) {
throw IllegalArgumentException("maxFragmentSize must be positive")
}
val bulkLength: Int = (if (reserveFinalByte) (bmp.size - 1) else bmp.size)
val fragmentCount: Int =
((((bulkLength + maxFragmentSize) - 1) / maxFragmentSize) +
(if ((bulkLength < bmp.size)) 1 else 0))
val fragments: MutableList<BleProtocol.ImageFragment> = ArrayList(fragmentCount)
run {
var index: Int = 0
while (((index * maxFragmentSize) < bulkLength)) {
var start: Int = (index * maxFragmentSize)
var end: Int = minOf((start + maxFragmentSize), bulkLength)
fragments.add(buildFragment(index, bmp, start, end))
index++
}
}
if ((bulkLength < bmp.size)) {
fragments.add(
BleProtocol.ImageFragment(
fragments.size,
bmp.copyOfRange(bulkLength, bmp.size),
(bmp.size - bulkLength),
)
)
}
return fragments
}
private fun buildFragment(
index: Int,
bmp: ByteArray,
start: Int,
end: Int,
): BleProtocol.ImageFragment {
var dataEnd: Int = end
while (((dataEnd > start) && (bmp[(dataEnd - 1)].toInt() == 0))) {
dataEnd -= 1
}
if ((dataEnd == start)) {
return BleProtocol.ImageFragment(index, ByteArray(0), (end - start))
}
return BleProtocol.ImageFragment(index, bmp.copyOfRange(start, dataEnd), (end - start))
}
@JvmStatic
fun buildIncrementalImagePayload(
previous: ByteArray?,
next: ByteArray?,
width: Int,
height: Int,
frameId: Int,
): IncrementalPlan? {
var stride: Int = ((width + 1) shr 1)
if (
((((((width <= 0) || (height <= 0)) || (previous == null)) || (next == null)) ||
(previous.size != (stride * height))) || (next.size != (stride * height)))
) {
return null
}
var minByteX: Int = stride
var maxByteX: Int = -1
var minY: Int = height
var maxY: Int = -1
var changedBytes: Int = 0
var columnChanged: BooleanArray = BooleanArray(stride)
run {
var y: Int = 0
while ((y < height)) {
var rowOffset: Int = (y * stride)
run {
var x: Int = 0
while ((x < stride)) {
if ((previous[(rowOffset + x)] != next[(rowOffset + x)])) {
changedBytes++
columnChanged[x] = true
if ((x < minByteX)) {
minByteX = x
}
if ((x > maxByteX)) {
maxByteX = x
}
if ((y < minY)) {
minY = y
}
maxY = y
}
x++
}
}
y++
}
}
if ((maxY < 0)) {
return null
}
var clusterCount: Int = 0
var inCluster: Boolean = false
run {
var x: Int = minByteX
while ((x <= maxByteX)) {
if (columnChanged[x]) {
if (!inCluster) {
clusterCount++
}
inCluster = true
} else {
inCluster = false
}
x++
}
}
var left: Int = ((minByteX * 2) and 3.inv())
var rightExclusive: Int = minOf(width, ((((maxByteX + 1) * 2) + 3) and 3.inv()))
var top: Int = (minY and 1.inv())
var bottomExclusive: Int = minOf(height, ((maxY + 2) and 1.inv()))
var boxWidth: Int = (rightExclusive - left)
var boxHeight: Int = (bottomExclusive - top)
if (((boxWidth >= width) && (boxHeight >= height))) {
return null
}
var out: ByteArray =
encodeMode3Rect(next, stride, left, top, boxWidth, boxHeight, frameId)
return IncrementalPlan(out, changedBytes, ((boxWidth shr 1) * boxHeight), clusterCount)
}
/**
* The aligned changed bounding box between two same-size packed frames, or null when they
* are identical: pixel-space {left, top, width, height} with left/width multiples of 4 and
* top/height multiples of 2 (mode-3 header quantization). Exposed so the texture-cache
* planner can reuse the exact rect geometry the single-bbox path would send.
*/
@JvmStatic
fun computeChangedBox(
previous: ByteArray?,
next: ByteArray?,
width: Int,
height: Int,
): IntArray? {
var stride: Int = ((width + 1) shr 1)
if (
((((((width <= 0) || (height <= 0)) || (previous == null)) || (next == null)) ||
(previous.size != (stride * height))) || (next.size != (stride * height)))
) {
return null
}
var minByteX: Int = stride
var maxByteX: Int = -1
var minY: Int = height
var maxY: Int = -1
run {
var y: Int = 0
while ((y < height)) {
var rowOffset: Int = (y * stride)
run {
var x: Int = 0
while ((x < stride)) {
if ((previous[(rowOffset + x)] != next[(rowOffset + x)])) {
if ((x < minByteX)) {
minByteX = x
}
if ((x > maxByteX)) {
maxByteX = x
}
if ((y < minY)) {
minY = y
}
maxY = y
}
x++
}
}
y++
}
}
if ((maxY < 0)) {
return null
}
var left: Int = ((minByteX * 2) and 3.inv())
var rightExclusive: Int = minOf(width, ((((maxByteX + 1) * 2) + 3) and 3.inv()))
var top: Int = (minY and 1.inv())
var bottomExclusive: Int = minOf(height, ((maxY + 2) and 1.inv()))
return intArrayOf(left, top, (rightExclusive - left), (bottomExclusive - top))
}
/**
* The multi-rect split of the changed region (see computeSplitRects), or null when it is
* one region / too fragmented / the frames aren't comparable. Exposed for the texture-cache
* planner.
*/
@JvmStatic
fun computeChangedRects(
previous: ByteArray?,
next: ByteArray?,
width: Int,
height: Int,
maxRects: Int,
): MutableList<IntArray>? {
var stride: Int = ((width + 1) shr 1)
if (
((((((width <= 0) || (height <= 0)) || (previous == null)) || (next == null)) ||
(previous.size != (stride * height))) || (next.size != (stride * height)))
) {
return null
}
var rects: MutableList<IntArray>? =
computeSplitRects(previous, next, stride, width, height, maxRects)
return (if (((rects == null) || (rects.size < 2))) null else rects)
}
/**
* Encode one CFW mode-3 rectangle delta:
* [3][left/4][top/2][width/4][height/2][fid_lo][fid_hi][rle(box pixels)] left/width must be
* multiples of 4 (=> left>>1, width>>1 are whole bytes), top/ height multiples of 2. The
* box pixels are top-down rows of `next` (4bpp packed, width>>1 bytes/row), run-length
* encoded before deflate. Shared by the single-bbox path, each rect of a mode-8 multi-rect
* batch, and the resource-cache planner.
*/
@JvmStatic
fun encodeMode3Rect(
next: ByteArray,
stride: Int,
left: Int,
top: Int,
boxWidth: Int,
boxHeight: Int,
fid: Int,
): ByteArray {
var regionStride: Int = (boxWidth shr 1)
var region: ByteArray = ByteArray((regionStride * boxHeight))
run {
var y: Int = 0
while ((y < boxHeight)) {
next.copyInto(
region,
(y * regionStride),
(((top + y) * stride) + (left shr 1)),
(((top + y) * stride) + (left shr 1)) + regionStride,
)
y++
}
}
var compressed: ByteArray = rleEncode(region)
var out: ByteArray = ByteArray((7 + compressed.size))
out[0] = CFW_MSG_BOUNDING_BOX.toByte()
out[1] = ((left / 4)).toByte()
out[2] = ((top / 2)).toByte()
out[3] = ((boxWidth / 4)).toByte()
out[4] = ((boxHeight / 2)).toByte()
out[5] = ((fid and 0xff)).toByte()
out[6] = (((fid shr 8) and 0xff)).toByte()
compressed.copyInto(out, 7, 0, 0 + compressed.size)
return out
}
/** A full repaint in independently decodable commands below the uint16 record limit. */
@JvmStatic
fun encodeFullFrameBands(
packed: ByteArray,
width: Int,
height: Int,
firstFid: Int,
): MutableList<ByteArray> {
if (
(((((((width <= 0) || (width > 640)) || ((width and 3) != 0)) || (height <= 0)) ||
(height > 480)) || ((height and 1) != 0)) ||
(packed.size != ((width * height) / 2)))
) {
throw IllegalArgumentException("unsupported custom framebuffer dimensions")
}
var commands: MutableList<ByteArray> = ArrayList()
var fid: Int = firstFid
run {
var top: Int = 0
while ((top < height)) {
commands.add(
encodeMode3Rect(
packed,
(width / 2),
0,
top,
width,
minOf(64, (height - top)),
fid,
)
)
fid = (if ((fid >= 0xfffe)) 1 else (fid + 1))
top += 64
}
}
return commands
}
private const val MULTI_RECT_V_GAP_ROWS: Int = 4
private const val MULTI_RECT_H_GAP_BYTES: Int = 6
/**
* Build a mode-8 multi-rect payload for the change between two same-size 4bpp frames,
* assigning consecutive frame ids starting at fidStart (each rect needs a distinct fid —
* the CFW skips duplicate fids). Returns null when the change is a single region (use the
* single-rect path), when it fragments past maxRects, or when the frames aren't comparable.
*/
@JvmStatic
fun buildMultiRectImagePayload(
previous: ByteArray?,
next: ByteArray?,
width: Int,
height: Int,
fidStart: Int,
maxRects: Int,
): MultiRectPlan? {
var stride: Int = ((width + 1) shr 1)
if (
((((((width <= 0) || (height <= 0)) || (previous == null)) || (next == null)) ||
(previous.size != (stride * height))) || (next.size != (stride * height)))
) {
return null
}
var rects: MutableList<IntArray>? =
computeSplitRects(previous, next, stride, width, height, maxRects)
if (((rects == null) || (rects.size < 2))) {
return null
}
var subs: MutableList<ByteArray> = ArrayList(rects.size)
var coveredBytes: Int = 0
var fid: Int = fidStart
var total: Int = 2
for (r in rects) {
var sub: ByteArray = encodeMode3Rect(next, stride, r[0], r[1], r[2], r[3], fid)
subs.add(sub)
coveredBytes += ((r[2] shr 1) * r[3])
total += (2 + sub.size)
fid = (if ((fid >= 0xfffe)) 1 else (fid + 1))
}
var out: ByteArray = ByteArray(total)
out[0] = CFW_MSG_MULTI_SEGMENT.toByte()
out[1] = (rects.size).toByte()
var pos: Int = 2
for (sub in subs) {
out[pos] = ((sub.size and 0xff)).toByte()
out[(pos + 1)] = (((sub.size shr 8) and 0xff)).toByte()
pos += 2
sub.copyInto(out, pos, 0, 0 + sub.size)
pos += sub.size
}
return MultiRectPlan(out, rects.size, coveredBytes, fid)
}
/**
* Split the changed region between two packed 4bpp frames into a small set of aligned
* rectangles that together cover every changed pixel: maximal vertical bands of changed
* rows (merging gaps < V_GAP), each split into horizontal column clusters (merging gaps <
* H_GAP), with each cluster's rows tightened to where it actually changes. Rects are
* pixel-space {left,top,width,height}, left/width aligned to 4px and top/height to 2px.
* Returns null if there's no change or the split exceeds maxRects (caller falls back to a
* single bounding box).
*/
private fun computeSplitRects(
previous: ByteArray,
next: ByteArray,
stride: Int,
width: Int,
height: Int,
maxRects: Int,
): MutableList<IntArray>? {
var rowChanged: BooleanArray = BooleanArray(height)
var anyChange: Boolean = false
run {
var y: Int = 0
while ((y < height)) {
var off: Int = (y * stride)
run {
var x: Int = 0
while ((x < stride)) {
if ((previous[(off + x)] != next[(off + x)])) {
rowChanged[y] = true
anyChange = true
break
}
x++
}
}
y++
}
}
if (!anyChange) {
return null
}
var rects: MutableList<IntArray> = ArrayList()
var col: BooleanArray = BooleanArray(stride)
var y: Int = 0
while ((y < height)) {
if (!rowChanged[y]) {
y++
continue
}
var bandTop: Int = y
var bandBot: Int = y
var cur: Int = (y + 1)
while ((cur < height)) {
if (rowChanged[cur]) {
bandBot = cur
cur++
continue
}
var g: Int = cur
while (((g < height) && !rowChanged[g])) {
g++
}
if (((g < height) && ((g - cur) < MULTI_RECT_V_GAP_ROWS))) {
cur = g
} else {
break
}
}
col.fill(false)
run {
var yy: Int = bandTop
while ((yy <= bandBot)) {
if (!rowChanged[yy]) {
yy++
continue
}
var off: Int = (yy * stride)
run {
var x: Int = 0
while ((x < stride)) {
if ((previous[(off + x)] != next[(off + x)])) {
col[x] = true
}
x++
}
}
yy++
}
}
var x: Int = 0
while ((x < stride)) {
if (!col[x]) {
x++
continue
}
var cL: Int = x
var cR: Int = x
var cx: Int = (x + 1)
while ((cx < stride)) {
if (col[cx]) {
cR = cx
cx++
continue
}
var g: Int = cx
while (((g < stride) && !col[g])) {
g++
}
if (((g < stride) && ((g - cx) < MULTI_RECT_H_GAP_BYTES))) {
cx = g
} else {
break
}
}
var tTop: Int = height
var tBot: Int = -1
run {
var yy: Int = bandTop
while ((yy <= bandBot)) {
if (!rowChanged[yy]) {
yy++
continue
}
var off: Int = (yy * stride)
run {
var xx: Int = cL
while ((xx <= cR)) {
if ((previous[(off + xx)] != next[(off + xx)])) {
if ((yy < tTop)) {
tTop = yy
}
tBot = yy
break
}
xx++
}
}
yy++
}
}
if ((tBot >= 0)) {
var left: Int = ((cL * 2) and 3.inv())
var rightExclusive: Int = minOf(width, ((((cR + 1) * 2) + 3) and 3.inv()))
var top: Int = (tTop and 1.inv())
var bottomExclusive: Int = minOf(height, ((tBot + 2) and 1.inv()))
rects.add(
intArrayOf(left, top, (rightExclusive - left), (bottomExclusive - top))
)
if ((rects.size > maxRects)) {
return null
}
}
x = (cR + 1)
}
y = (bandBot + 1)
}
return rects
}
/**
* Run-length encode headerless 4bpp pixels for CFW load_image_z mode 6. Wire format:
* [6][rle(4bpp pixels)]. Always use mode 6: the logical image can be larger than its
* EvenHub carrier, so a raw BMP fallback would carry dimensions the legacy container loader
* cannot accept.
*/
@JvmStatic
fun maybeCompress(packed: ByteArray?, width: Int, height: Int): ByteArray {
if (((packed == null) || (packed.size == 0))) {
return packed ?: ByteArray(0)
}
var z: ByteArray = rleEncode(packed)
var out: ByteArray = ByteArray((z.size + 1))
out[0] = CFW_MSG_FULL_FRAME.toByte()
z.copyInto(out, 1, 0, 0 + z.size)
return out
}
/**
* Run-length encode packed 4bpp pixels for CFW modes 3 and 6, whose payload is RLE tokens;
* deflate belongs to the transport. Runs are over the pixel NIBBLES of {@code pix} in wire
* order (high nibble = left pixel), including the pad nibble that ends each row at odd
* widths — i.e. {@code pix} read as 2*length nibbles. One token is:
* <pre>
* [cnt4|color4] cnt 1..15
* [0|color4][cnt8] cnt 1..255
* [0|color4][0][cntLo][cntHi] cnt 1..65535, little-endian
* </pre>
* with the low nibble always the color; runs longer than 65535 split across tokens. Worst
* case (every nibble its own run) is exactly one byte per nibble, which is what the buffer
* is sized for.
*/
@JvmStatic
fun rleEncode(pix: ByteArray): ByteArray {
val n = pix.size * 2
val out = ByteArray(n)
var o: Int = 0
var i: Int = 0
while ((i < n)) {
val first = pix[i ushr 1].toInt() and 255
val v = if (i and 1 == 0) first ushr 4 else first and 15
// Start at a byte boundary, consuming the known low nibble
// first if the previous run ended halfway through a byte.
var j = i + (i and 1)
val pair = ((v shl 4) or v).toByte()
while (j < n && pix[j ushr 1] == pair) j += 2
// A final high nibble can match even when its low nibble doesn't.
if (j < n && (pix[j ushr 1].toInt() and 240) == v shl 4) j++
var run: Int = (j - i)
while ((run > 0)) {
var c: Int = minOf(run, 0xffff)
if ((c <= 15)) {
out[o++] = (((c shl 4) or v)).toByte()
} else {
if ((c <= 255)) {
out[o++] = (v).toByte()
out[o++] = (c).toByte()
} else {
out[o++] = (v).toByte()
out[o++] = 0
out[o++] = ((c and 0xff)).toByte()
out[o++] = ((c shr 8)).toByte()
}
}
run -= c
}
i = j
}
return out.copyOf(o)
}
}
constructor() {}
class TileImagePlan {
@JvmField val tileIndex: Int
@JvmField val tile: BleProtocol.ImageTileOptions
@JvmField val packed: ByteArray?
@JvmField val width: Int
@JvmField val height: Int
@JvmField val payload: ByteArray
@JvmField val sessionId: Int
@JvmField var fragments: MutableList<BleProtocol.ImageFragment> = mutableListOf()
constructor(
tileIndex: Int,
tile: BleProtocol.ImageTileOptions,
packed: ByteArray?,
width: Int,
height: Int,
sessionId: Int,
) {
this.tileIndex = tileIndex
this.tile = tile
this.packed = (if ((packed == null)) ByteArray(0) else packed)
this.width = width
this.height = height
this.payload = maybeCompress(this.packed, width, height)
this.sessionId = sessionId
}
constructor(
tileIndex: Int,
tile: BleProtocol.ImageTileOptions,
packed: ByteArray?,
width: Int,
height: Int,
sessionId: Int,
payloadOverride: ByteArray,
) {
this.tileIndex = tileIndex
this.tile = tile
this.packed = (if ((packed == null)) ByteArray(0) else packed)
this.width = width
this.height = height
this.payload = payloadOverride
this.sessionId = sessionId
}
}
/**
* A mode-3 incremental payload plus diagnostics about how tightly the bounding box fit the
* actual change. {@code changedBytes} is how many packed bytes actually differ; {@code
* boxBytes} is how many the box sends. A large box with few changed bytes / multiple clusters
* means distant small edits were merged into one oversized box (which can spill past the
* fragment size into an extra serialized BLE message).
*/
class IncrementalPlan {
@JvmField val payload: ByteArray
@JvmField val changedBytes: Int
@JvmField val boxBytes: Int
@JvmField val clusterCount: Int
constructor(payload: ByteArray, changedBytes: Int, boxBytes: Int, clusterCount: Int) {
this.payload = payload
this.changedBytes = changedBytes
this.boxBytes = boxBytes
this.clusterCount = clusterCount
}
}
/**
* A CFW mode-8 multi-segment payload (`[8][count]` then per-rect `[len16][mode-3 submsg]`)
* carrying several tight rectangle deltas instead of one bounding box, plus diagnostics. Each
* rect is applied to the firmware shadow with the panel push deferred, then presented once.
* Used when the change splits into regions whose bounding box wastes bytes (distant edits, or a
* sparse box); the caller falls back to the single-rect path when this returns null or isn't
* smaller.
*/
class MultiRectPlan {
@JvmField val payload: ByteArray
@JvmField val rectCount: Int
@JvmField val coveredBytes: Int
@JvmField val nextFid: Int
constructor(payload: ByteArray, rectCount: Int, coveredBytes: Int, nextFid: Int) {
this.payload = payload
this.rectCount = rectCount
this.coveredBytes = coveredBytes
this.nextFid = nextFid
}
}
class ImageUpdateStats {
@JvmField val paintMs: Int
@JvmField val tileCount: Int
@JvmField val frameId: Int
@JvmField var firstWriteStartedAtMs: Long = 0L
constructor(paintMs: Int, tileCount: Int, frameId: Int) {
this.paintMs = maxOf(0, paintMs)
this.tileCount = tileCount
this.frameId = frameId
}
}
}
@@ -0,0 +1,43 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
/**
* Allocates one-byte message identifiers in LRU order. Release records survive reuse so the
* communicator can diagnose late ACKs after a timeout.
*/
class BleMagicPool(private val platform: ProtocolPlatform) {
companion object {
const val MIN_MAGIC = 100
const val MAX_MAGIC = 255
}
private val lock = platform.createLock()
private val available = ArrayDeque((MIN_MAGIC..MAX_MAGIC).toList())
private val allocated = BooleanArray(256)
private val releaseRecords = mutableMapOf<String, ReleaseRecord>()
fun allocate(): Int = lock.withLock {
check(available.isNotEmpty()) { "no BLE magic values available" }
val magic = available.removeFirst()
allocated[magic] = true
magic
}
fun release(sid: Int, magic: Int, label: String?, reason: String?) = lock.withLock {
if (magic !in MIN_MAGIC..MAX_MAGIC) return@withLock
releaseRecords["$sid:$magic"] = ReleaseRecord(label, reason, platform.elapsedRealtimeMs())
if (!allocated[magic]) return@withLock
allocated[magic] = false
available.addLast(magic)
}
fun getReleaseRecord(sid: Int, magic: Int): ReleaseRecord? = lock.withLock {
releaseRecords["$sid:$magic"]
}
class ReleaseRecord(label: String?, reason: String?, @JvmField val releasedAtMs: Long) {
@JvmField val label: String = label ?: ""
@JvmField val reason: String = reason ?: ""
}
}
@@ -0,0 +1,102 @@
package com.faceclaw.app
import kotlin.math.abs
import kotlin.math.exp
import kotlin.math.ln
import kotlin.math.roundToInt
/** Phone-owned policy. Firmware receives only a transient target and fade time. */
class BrightnessPolicy {
var automatic = true
private set
var fadeMs = 280
private set
var target = 40
private set
private var manual = 50
private var minimum = 20
private var maximum = 100
private var curve = parseCurve(DEFAULT_CURVE)
private var filteredLux: Double? = null
private var sampleAt = 0L
fun setMode(auto: Boolean, level: Int) {
automatic = auto
manual = level.coerceIn(2, 100)
target = if (auto) filteredLux?.let { evaluate(it) } ?: target.coerceIn(minimum, maximum) else manual
}
fun configure(auto: Boolean, level: Int, min: Int, max: Int, points: String, fade: Int) {
val parsed = parseCurve(points) // Validate before mutating the live policy.
automatic = auto
manual = level.coerceIn(2, 100)
minimum = min.coerceIn(2, 100)
maximum = max.coerceIn(minimum, 100)
curve = parsed
fadeMs = fade.coerceIn(0, 1500)
target = if (auto) filteredLux?.let { evaluate(it) } ?: target.coerceIn(minimum, maximum) else manual
}
/** Only live successful passive POLL reports count, never cached query/start reports. */
fun sample(report: ByteArray, now: Long): Boolean {
if (report.size < 24 || report[0] != 65.toByte() || report[1] != 76.toByte() ||
report[2] != 1.toByte() || report[3] != 2.toByte() || (report[4].toInt() and 11) != 11) return false
var reading = 0L
for (i in 0..3) reading = reading or ((report[6+i].toLong() and 255) shl (8*i))
val lux = reading / 10.0
val old = filteredLux
val elapsed = (now - sampleAt).coerceAtLeast(0)
filteredLux = if (old == null || elapsed > 10_000) lux else {
val seconds = if (lux > old) 0.8 else 3.0
old + (lux-old) * (1-exp(-elapsed/1000.0/seconds))
}
sampleAt = now
if (!automatic) return false
val next = evaluate(filteredLux!!)
// Compare with the last accepted target, not the previous sample, so
// gradual drift accumulates. Bounds obey the same deadband to avoid
// extra panel writes when light hovers near the minimum or maximum.
if (abs(next-target) < AUTO_CHANGE_THRESHOLD) return false
val changed = target != next
target = next
return changed
}
fun resetSamples() { filteredLux = null; sampleAt = 0 }
private fun evaluate(lux: Double): Int {
val x = ln(1+lux.coerceAtLeast(0.0))
var fraction = curve.last().second / 100
if (x <= curve.first().first) fraction = curve.first().second / 100
else for (i in 1 until curve.size) {
val (right, high) = curve[i]
if (x <= right) {
val (left, low) = curve[i-1]
fraction = (low + (high-low)*(x-left)/(right-left))/100
break
}
}
return (minimum+(maximum-minimum)*fraction).roundToInt().coerceIn(minimum, maximum)
}
companion object {
private const val AUTO_CHANGE_THRESHOLD = 5
const val DEFAULT_CURVE = "0:0,0.2:7,1.5:33,5:100"
/** Lux:percent-of-configured-range knots; interpolate in log(1+lux). */
fun parseCurve(text: String): List<Pair<Double, Double>> {
val entries = text.split(',')
require(entries.size in 2..16) { "Use 2–16 lux:percent pairs" }
val points = entries.map {
val pair = it.trim().split(':')
require(pair.size == 2) { "Expected lux:percent" }
val lux = pair[0].trim().toDouble()
val percent = pair[1].trim().toDouble()
require(lux.isFinite() && lux in 0.0..1_000_000.0 && percent.isFinite() && percent in 0.0..100.0)
ln(1+lux) to percent
}
require(points.first() == (0.0 to 0.0) && points.last().second == 100.0) { "Start at 0:0 and end at 100%" }
require(points.zipWithNext().all { (a,b) -> b.first > a.first && b.second >= a.second }) { "Lux must increase and brightness must not decrease" }
return points
}
}
}
@@ -0,0 +1,39 @@
package com.faceclaw.app
/** Message IDs and header flags mirror g2flash/patches/zlib_glue.c. */
/** Retired wire ID; used internally by the phone optimizer. */
const val CFW_MSG_BOUNDING_BOX = 3
const val CFW_MSG_BUZZER = 5
/** Retired wire ID; used internally by the phone optimizer. */
const val CFW_MSG_FULL_FRAME = 6
const val CFW_MSG_DIAGNOSTICS = 7
/** Retired wire ID; used internally by the phone optimizer. */
const val CFW_MSG_MULTI_SEGMENT = 8
/** Retired wire ID; used internally by the phone optimizer. */
const val CFW_MSG_RECT_COPY = 9
const val CFW_MSG_COMPASS = 10
const val CFW_MSG_CLEANUP = 11
const val CFW_MSG_RETIRED_12 = 12
const val CFW_MSG_RETIRED_13 = 13
const val CFW_MSG_RETIRED_14 = 14
/** Retired wire ID; used internally by the phone optimizer. */
const val CFW_MSG_STOCK_FONT_STRING = 15
const val CFW_MSG_AMBIENT_LIGHT = 16
const val CFW_MSG_RING_BATTERY = 17
const val CFW_MSG_RETIRED_CACHE_WRITE = 18
/** Retired wire ID; used internally by the phone optimizer. */
const val CFW_MSG_CACHED_IMAGE = 19
/** Retired wire ID; used internally by the phone optimizer. */
const val CFW_MSG_CACHED_TEXT = 20
const val CFW_MSG_UPLOAD_RESOURCE = 21
const val CFW_MSG_EVICT_RESOURCE = 22
const val CFW_MSG_PANEL_READ = 23
const val CFW_MSG_PANEL_WRITE = 24
const val CFW_MSG_PANEL_PATTERN = 25
const val CFW_MSG_DRAW_CALLS = 26
const val CFW_MSG_SET_ROOT_DISPLAY_LIST = 27
const val CFW_MSG_PRESENT = 28
const val CFW_MSG_CREATE_SURFACE = 29
const val CFW_MSG_BRIGHTNESS = 30
const val CFW_MSG_TYPE_MASK = 127
const val CFW_MSG_FLAG_LENSES_DIFFER = 128
@@ -0,0 +1,51 @@
package com.faceclaw.app
import kotlin.jvm.JvmStatic
/** Ordered completion and go-back-N recovery for the custom-message window. */
class CfwMessageWindow private constructor() {
companion object {
// Flappy capture: p99 ACK 63ms, max 77ms. Allow full-frame processing
// while recovering a lost reply well before the stock timeout.
const val ACK_TIMEOUT_MS = 500
const val MAX_RETRIES = 3
/** ID reuse must not invalidate an earlier command still eligible for replay. */
@JvmStatic
fun canSend(messages: Iterable<OutboundMessage>, candidate: OutboundMessage): Boolean =
candidate.sid != CfwTransport.SID ||
candidate.message.firstOrNull()?.toInt() != ResourceCacheState.EVICT_MODE ||
messages.none { it.sid == CfwTransport.SID }
@JvmStatic
fun acknowledgedHead(messages: Iterable<OutboundMessage>): OutboundMessage? {
for (message in messages) {
if (message.sid != CfwTransport.SID) continue
return if (!message.cfwRetryPending && message.cfwAckLenses == CfwTransport.BOTH)
message
else null
}
return null
}
@JvmStatic
fun replayWindow(messages: Iterable<OutboundMessage>, nowMs: Long): List<OutboundMessage> {
val replay = mutableListOf<OutboundMessage>()
var failed = false
for (message in messages) {
if (message.sid != CfwTransport.SID) continue
failed =
failed ||
message.cfwRetryPending ||
(message.cfwAckLenses != CfwTransport.BOTH &&
message.ackDeadlineAtMs > 0 &&
message.ackDeadlineAtMs <= nowMs)
replay.add(message)
}
// Replaying only the named failure can strand an older unresolved
// attempt at the head. Rewind the entire unresolved custom window.
if (!failed) replay.clear()
return replay
}
}
}
@@ -0,0 +1,191 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
import kotlin.jvm.JvmStatic
/** Faceclaw/10 records: clear flags, wire length and decoded CRC; persistent zlib body. */
class CfwTransport(private val platform: ProtocolPlatform) {
private val lock = platform.createLock()
private var deflater: ProtocolDeflater? = null
private var resetPending = true
private var previousLenses = 0
fun reset() = lock.withLock {
deflater?.reset()
resetPending = true
previousLenses = 0
}
/** Release native compression resources. A later encode starts a fresh stream. */
fun close() = lock.withLock {
deflater?.close()
deflater = null
resetPending = true
previousLenses = 0
}
/** Compress only when writing, in exactly the order seen by the receiver. */
fun encode(message: ByteArray?, streamId: Int, lenses: Int, mtu: Int): List<ByteArray> =
lock.withLock {
validate(message, streamId, lenses, mtu)
val input = message!!
if (previousLenses != lenses) reset()
val reset = resetPending
val encoder = deflater ?: platform.createDeflater().also { deflater = it }
var body = encoder.syncFlush(input)
var flags = lenses or COMPRESSED or (if (reset) RESET_CONTEXT else 0)
if (body.isEmpty()) flags = flags and COMPRESSED.inv() // repeated empty sync flush
if (body.size > MAX_MESSAGE) {
// The attempted deflate advanced history: reset both ends before reuse.
reset()
body = input
flags = lenses or RESET_CONTEXT
} else {
resetPending = false
previousLenses = lenses
}
frameRecord(body, crc(input), streamId, flags, mtu)
}
companion object {
/** Mirrors g2flash/patches/message_transport.h. */
const val SID = 0xf0
const val BOTH = 3
const val MAX_MESSAGE = 65535
const val COMPRESSED = 4
const val RESET_CONTEXT = 8
private fun validate(message: ByteArray?, streamId: Int, lenses: Int, mtu: Int) {
require(
message != null &&
message.size <= MAX_MESSAGE &&
streamId in 0..255 &&
lenses in 1..BOTH &&
mtu in 23..517
) {
"invalid CFW stream parameters"
}
}
/** One logical command per stream. Packets are bounded by actual ATT MTU. */
@JvmStatic
fun frame(message: ByteArray?, streamId: Int, lenses: Int, mtu: Int): List<ByteArray> {
validate(message, streamId, lenses, mtu)
return frameRecord(message!!, crc(message), streamId, lenses or RESET_CONTEXT, mtu)
}
private fun frameRecord(
body: ByteArray,
checksum: Int,
streamId: Int,
flags: Int,
mtu: Int,
): List<ByteArray> {
val lenses = flags and BOTH
val capacity = minOf(252, mtu - 14)
val stream = ByteArray(body.size + 5)
stream[0] = flags.toByte()
stream[1] = body.size.toByte()
stream[2] = (body.size ushr 8).toByte()
stream[3] = checksum.toByte()
stream[4] = (checksum ushr 8).toByte()
body.copyInto(stream, 5)
val packets = mutableListOf<ByteArray>()
for (offset in stream.indices step capacity) {
val count = minOf(capacity, stream.size - offset)
val packet = ByteArray(count + 11)
packet[0] = 0xaa.toByte()
packet[1] = 0x21
packet[2] = (streamId + packets.size).toByte()
packet[3] = (count + 3).toByte()
packet[4] = 1
packet[5] = 1
packet[6] = SID.toByte()
packet[8] =
(lenses or
(if (offset == 0) 0x80 else 0) or
(if (offset + count == stream.size) 0x40 else 0))
.toByte()
stream.copyInto(packet, 9, offset, offset + count)
val crc = crc(packet, 8, count + 1)
packet[packet.size - 2] = crc.toByte()
packet[packet.size - 1] = (crc ushr 8).toByte()
packets.add(packet)
}
return packets
}
@JvmStatic fun crc(data: ByteArray): Int = crc(data, 0, data.size)
private fun crc(data: ByteArray, offset: Int, count: Int): Int {
var crc = 0xffff
for (i in offset until offset + count) {
crc = crc xor ((data[i].toInt() and 255) shl 8)
repeat(8) {
crc = ((crc shl 1) xor (if (crc and 0x8000 != 0) 0x1021 else 0)) and 65535
}
}
return crc
}
private fun u16(data: ByteArray, offset: Int): Int =
(data[offset].toInt() and 255) or ((data[offset + 1].toInt() and 255) shl 8)
@JvmStatic fun parseAck(packet: ByteArray?): Ack? = parseAcks(packet)?.first()
/**
* Validate the entire primary ACK and up to three preceding successes before applying any.
*/
@JvmStatic
fun parseAcks(packet: ByteArray?): Array<Ack>? {
if (
packet == null ||
packet.size !in 19..40 ||
(packet.size - 19) % 7 != 0 ||
packet[0].toInt() and 255 != 0xaa ||
packet[1].toInt() != 0x12 ||
packet[3].toInt() and 255 != packet.size - 8 ||
packet[4].toInt() != 1 ||
packet[5].toInt() != 1 ||
packet[6].toInt() and 255 != SID ||
packet[7].toInt() != 0 ||
(packet[8].toInt() != 1 && packet[8].toInt() != 3) ||
(packet[12].toInt() != 1 && packet[12].toInt() != 2) ||
(packet[8].toInt() == 3 && packet.size != 19) ||
crc(packet, 8, packet.size - 10) != u16(packet, packet.size - 2)
)
return null
return Array(1 + (packet.size - 19) / 7) { i ->
if (i == 0)
Ack(
packet[8].toInt() == 3,
packet[9].toInt() and 255,
u16(packet, 10),
packet[12].toInt(),
u16(packet, 13),
u16(packet, 15),
)
else {
val offset = 17 + (i - 1) * 7
Ack(
false,
packet[offset].toInt() and 255,
u16(packet, offset + 1),
packet[12].toInt(),
u16(packet, offset + 3),
u16(packet, offset + 5),
)
}
}
}
}
class Ack(
@JvmField val nack: Boolean,
@JvmField val streamId: Int,
@JvmField val messageId: Int,
@JvmField val lens: Int,
@JvmField val size: Int,
@JvmField val checksum: Int,
)
}
@@ -0,0 +1,83 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
class ConnectionOptions {
companion object {
@JvmField val WRITE_MODE = GattWriteMode.WITHOUT_RESPONSE
const val DESIRED_MTU = 512
const val CONNECT_TIMEOUT_MS = 5_000
const val SERVICES_TIMEOUT_MS = 5_000
const val DESCRIPTOR_TIMEOUT_MS = 5_000
const val RING_DESIRED_MTU = 247
const val RING_RECONNECT_DELAY_MS = 2_000
// The ring connects with autoConnect=true (see SessionLink.connect's
// 3-arg overload) - Android manages that as a background reconnect rather
// than an immediate attempt, so it needs far more room than the glasses'
// direct-connect CONNECT_TIMEOUT_MS. Untuned guess, not measured.
const val RING_CONNECT_TIMEOUT_MS = 20_000
const val WRITE_TIMEOUT_MS = 2_000
const val PRELUDE_TIMEOUT_MS = 2_000
// Application security-auth exchange (sid 0x80). The success notification
// only arrives once the BLE link is encrypted, which on a first-time
// connection means SMP pairing — possibly with an OS dialog the user has
// to accept — so the stock-firmware paths wait generously.
const val SECURITY_AUTH_TIMEOUT_MS = 30_000
// The main communicator's wait is soft (it proceeds on timeout so firmware
// that never answers can't stall every reconnect), so it is kept short.
const val SECURITY_AUTH_SOFT_TIMEOUT_MS = 6_000
const val ACK_TIMEOUT_MS = 3_500
const val HEARTBEAT_FAILURE_DEADLINE_MS = 10_000
const val HEARTBEAT_READY_MS = 4_000
const val HEARTBEAT_URGENT_MS = 6_000
const val BATTERY_REFRESH_INTERVAL_MS = 5 * 60_000
const val BATTERY_INPUT_QUIET_MS = 5_000
// Poll cadence while in charging mode; also bounds how quickly we notice
// the glasses coming back out of the case.
const val CHARGING_BATTERY_POLL_MS = 30_000
const val IMAGE_FRAGMENT_SIZE = 3800
const val IMAGE_RETRY_DELAY_MS = 2_000
const val MAX_CONSECUTIVE_ACK_TIMEOUTS = 8
const val EVEN_APP_WRITE_FAILURE_WINDOW_MS = 15_000
const val IDLE_SLEEP_MS = 100
const val RECONNECT_DELAY_MS = 2_000
// Cap on rects per batch. Each rect consumes a distinct CFW frame id, and the
// firmware's duplicate-fid ring holds 16, so keep several batches of history
// within it. Above this the split is abandoned for a single bounding box.
const val MULTI_RECT_MAX_RECTS = 6
// Don't bother splitting when the single bounding box already compresses this
// small (one tight rect); only attempt multi-rect above it or when the box
// spans multiple horizontal clusters.
const val MULTI_RECT_MIN_PAYLOAD = 900
}
@JvmField val sendImagesToLeft = true
@JvmField val skipSessionIds = true
// Max messages in flight (awaiting ack) at once — full pipelining. >1 lets a
// frame be sent before the previous frame's ack returns, hiding the BLE ack
// round-trip that otherwise serialized every update. Requires firmware that
// accepts pipelined image messages (the CFW snapshot/deferred FIFO). At 1 the
// communicator behaves exactly as before (serial sends + last-packet prewrite).
@JvmField val WINDOW_SIZE = 3
// Send changed-region (mode 3 bounding box) updates instead of full frames
// when the previous frame is known to be displayed. Requires firmware with
// the experimental bbox-incremental mode. Disabled: the firmware-side
// display buffer is not always the previous frame (occasionally two frames
// back, apparently display-driver buffer swapping), so partial updates
// composite onto stale content per-lens. Re-enable once the firmware
// guarantees the compositing base.
@JvmField val INCREMENTAL_FRAMES = true
// Send several tight rectangle deltas as one CFW mode-8 multi-segment message
// instead of a single bounding box, when the change splits into regions whose
// bounding box wastes bytes (distant edits, or a sparse box). Requires firmware
// with mode-8 multi-rect support; needs INCREMENTAL_FRAMES (same seeded shadow).
// Falls back to the single bounding box whenever multi-rect isn't smaller.
@JvmField val MULTI_RECT_FRAMES = true
// Ship text as on-glasses cached-glyph draws (CFW modes 19/20/21/22) instead of
// pixels, punching glyph ink out of the baked deltas (see TexturePlanner).
// Also gated at runtime on the firmware advertising Faceclaw/23 or later.
@JvmField val TEXTURE_CACHE_FRAMES = true
}
@@ -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,12 @@
package com.faceclaw.app
/** Draw-call wire IDs. Keep names and values in sync with cfw_draw_op in g2flash/patches/display_list.c. */
const val DRAW_OP_BOUNDING_BOX = 1
const val DRAW_OP_RECT_COPY = 2
const val DRAW_OP_STOCK_FONT_STRING = 3
const val DRAW_OP_IMAGE = 4
const val DRAW_OP_TEXT = 5
const val DRAW_OP_REMAP_COLORS = 6
const val DRAW_OP_DISPLAY_LIST = 7
const val DRAW_OP_ROUNDED_RECT = 8
const val DRAW_OP_CLEAR = 9
@@ -0,0 +1,260 @@
package com.faceclaw.app
/** Literal or branchless expression used by rounded-rectangle x/y in revision 27. */
sealed class DrawValue {
class Integer(val value: Int) : DrawValue()
class Expression(val program: ByteArray) : DrawValue()
companion object {
/** Smoothstep interpolation; time is measured from the next PRESENT. */
fun animate(from: Int, to: Int, durationMs: Int, elapsedMs: Int = 0): DrawValue {
require(durationMs > 0 && elapsedMs >= 0)
if (from == to || elapsedMs >= durationMs) return Integer(to)
val code = ByteSink()
fun integer(value: Int) {
code.write(DrawExpression.PUSH_I32)
code.write(ExtendedVarint.signed(value))
}
integer(from)
code.write(DrawExpression.I2F)
integer(to)
code.write(DrawExpression.I2F)
integer(durationMs - elapsedMs)
code.write(DrawExpression.TIME)
integer(elapsedMs)
code.write(DrawExpression.IADD)
code.write(DrawExpression.I2F)
integer(durationMs)
code.write(DrawExpression.I2F)
code.write(DrawExpression.FDIV)
code.write(DrawExpression.SMOOTHSTEP)
code.write(DrawExpression.LERP)
code.write(DrawExpression.F2I)
return Expression(code.toByteArray())
}
}
}
/** Prefix payload is most-significant first; continuation bytes use all eight bits. */
internal object ExtendedVarint {
private val widths = intArrayOf(7, 14, 21, 28, 32)
private val prefixes = intArrayOf(0, 0x80, 0xc0, 0xe0, 0xf0)
fun signed(value: Int): ByteArray {
val size = widths.indexOfFirst { bits ->
bits == 32 || value.toLong() in -(1L shl (bits - 1)) until (1L shl (bits - 1))
} + 1
return encode(value, size)
}
fun unsigned(value: UInt): ByteArray {
val size = widths.indexOfFirst { it == 32 || value.toLong() < (1L shl it) } + 1
return encode(value.toInt(), size)
}
private fun encode(value: Int, size: Int): ByteArray {
val bytes = ByteArray(size)
if (size == 5) {
bytes[0] = 0xf0.toByte()
} else {
val mask = (1 shl (8 - size)) - 1
bytes[0] = (prefixes[size - 1] or ((value ushr (8 * (size - 1))) and mask)).toByte()
}
for (i in 1 until size) bytes[i] = (value ushr (8 * (size - 1 - i))).toByte()
return bytes
}
fun read(reader: DrawReader, signed: Boolean, first: Int = reader.readU8()): Int {
val size = when {
first < 0x80 -> 1
first < 0xc0 -> 2
first < 0xe0 -> 3
first < 0xf0 -> 4
first == 0xf0 -> 5
else -> error("Reserved extended-varint prefix")
}
var value = if (size == 5) 0 else first and ((1 shl (8 - size)) - 1)
repeat(size - 1) { value = (value shl 8) or reader.readU8() }
val bits = widths[size - 1]
return if (signed && bits < 32) (value shl (32 - bits)) shr (32 - bits) else value
}
fun write(value: DrawValue): ByteArray = when (value) {
is DrawValue.Integer -> signed(value.value)
is DrawValue.Expression -> {
require(value.program.size <= DrawExpression.MAX_BYTES)
byteArrayOf(0xff.toByte()) + unsigned(value.program.size.toUInt()) + value.program
}
}
fun evaluate(reader: DrawReader, frame: DrawEvaluation): Int {
val first = reader.readU8()
if (first != 0xff) return read(reader, true, first)
val length = read(reader, false).toUInt()
// Outer framing errors reject the call; errors inside a framed program yield zero.
require(length <= reader.remaining.toUInt())
val program = reader.readSlice(length.toInt())
if (length > DrawExpression.MAX_BYTES.toUInt()) return 0
return DrawExpression.evaluate(program, frame)
}
}
internal class DrawEvaluation(val elapsedMs: Long) {
var animationPending = false
}
/** Typed i32/f32 stack machine. Keep opcode IDs and semantics in sync with draw_expression.c. */
internal object DrawExpression {
const val MAX_BYTES = 1024
const val MAX_STACK = 32
const val PUSH_I32 = 1
const val PUSH_F32 = 2
const val DUP = 3
const val DROP = 4
const val SWAP = 5
const val IADD = 16
const val ISUB = 17
const val IMUL = 18
const val IDIV = 19
const val IMOD = 20
const val INEG = 21
const val IMIN = 22
const val IMAX = 23
const val FADD = 32
const val FSUB = 33
const val FMUL = 34
const val FDIV = 35
const val FNEG = 36
const val FMIN = 37
const val FMAX = 38
const val I2F = 48
const val F2I = 49
const val TIME = 50
const val LERP = 64
const val SMOOTHSTEP = 65
const val EASE_IN_QUAD = 66
const val EASE_OUT_QUAD = 67
const val EASE_IN_OUT_QUAD = 68
const val EASE_IN_CUBIC = 69
const val EASE_OUT_CUBIC = 70
const val EASE_IN_OUT_CUBIC = 71
fun evaluate(reader: DrawReader, frame: DrawEvaluation): Int {
val bits = IntArray(MAX_STACK)
val floats = BooleanArray(MAX_STACK)
var size = 0
var pending = false
fun push(value: Int, float: Boolean = false) {
require(size < MAX_STACK)
bits[size] = value
floats[size++] = float
}
fun integer(): Int {
require(size > 0 && !floats[size - 1])
return bits[--size]
}
fun float(): Float {
require(size > 0 && floats[size - 1])
return Float.fromBits(bits[--size])
}
fun pushFloat(value: Float) {
require(value.isFinite())
push(value.toBits(), true)
}
fun toInteger(value: Float): Int {
require(value.isFinite() && value >= -2147483648f && value < 2147483648f)
return value.toInt()
}
try {
require(reader.remaining <= MAX_BYTES)
while (reader.remaining > 0) {
when (val op = reader.readU8()) {
PUSH_I32 -> push(ExtendedVarint.read(reader, true))
PUSH_F32 -> {
val value = reader.readU8() or (reader.readU8() shl 8) or
(reader.readU8() shl 16) or (reader.readU8() shl 24)
pushFloat(Float.fromBits(value))
}
DUP -> {
require(size > 0)
push(bits[size - 1], floats[size - 1])
}
DROP -> { require(size > 0); size-- }
SWAP -> {
require(size >= 2)
val value = bits[size - 1]
val type = floats[size - 1]
bits[size - 1] = bits[size - 2]
floats[size - 1] = floats[size - 2]
bits[size - 2] = value
floats[size - 2] = type
}
IADD, ISUB, IMUL, IDIV, IMOD, IMIN, IMAX -> {
val b = integer()
val a = integer()
push(when (op) {
IADD -> a + b
ISUB -> a - b
IMUL -> a * b
IDIV -> { require(b != 0); if (a == Int.MIN_VALUE && b == -1) a else a / b }
IMOD -> { require(b != 0); if (a == Int.MIN_VALUE && b == -1) 0 else a % b }
IMIN -> minOf(a, b)
else -> maxOf(a, b)
})
}
INEG -> push(-integer())
FADD, FSUB, FMUL, FDIV, FMIN, FMAX -> {
val b = float()
val a = float()
pushFloat(when (op) {
FADD -> a + b
FSUB -> a - b
FMUL -> a * b
FDIV -> { require(b != 0f); a / b }
FMIN -> minOf(a, b)
else -> maxOf(a, b)
})
}
FNEG -> pushFloat(-float())
I2F -> pushFloat(integer().toFloat())
F2I -> push(toInteger(float()))
TIME -> {
val maximum = integer()
require(maximum >= 0)
val time = frame.elapsedMs.coerceIn(0, maximum.toLong()).toInt()
if (time != maximum) pending = true
push(time)
}
LERP -> {
val t = float()
val b = float()
val a = float()
pushFloat(a + (b - a) * t)
}
in SMOOTHSTEP..EASE_IN_OUT_CUBIC -> {
val t = float().coerceIn(0f, 1f)
val u = 1f - t
pushFloat(when (op) {
SMOOTHSTEP -> t * t * (3f - 2f * t)
EASE_IN_QUAD -> t * t
EASE_OUT_QUAD -> 1f - u * u
EASE_IN_OUT_QUAD -> if (t < .5f) 2f * t * t else 1f - 2f * u * u
EASE_IN_CUBIC -> t * t * t
EASE_OUT_CUBIC -> 1f - u * u * u
else -> if (t < .5f) 4f * t * t * t else 1f - 4f * u * u * u
})
}
else -> error("Unknown expression opcode")
}
}
require(size > 0)
val result = if (floats[size - 1]) toInteger(float()) else integer()
frame.animationPending = frame.animationPending || pending
return result
} catch (_: IllegalArgumentException) {
return 0
} catch (_: IllegalStateException) {
return 0
}
}
}
@@ -0,0 +1,23 @@
package com.faceclaw.app
/**
* Draw-call flags, bounding-box flags, and the border sentinel mirror g2flash/patches/display_list.c.
* Image/text options mirror g2flash/patches/texture_draw.h.
*/
/** Common draw-call header bits. */
const val DRAW_FLAG_RESOURCE_TARGET = 1
const val DRAW_FLAG_DEPTH = 2
/** Revision 35: an x/y s16, w/h u16 clip rect follows the depth byte. */
const val DRAW_FLAG_CLIP = 4
const val DRAW_FLAGS_MASK = DRAW_FLAG_RESOURCE_TARGET or DRAW_FLAG_DEPTH or DRAW_FLAG_CLIP
/** Bounding-box payload flag: u16 coordinates/sizes instead of aligned compact units. */
const val DRAW_BBOX_FLAG_U16 = 1
/** Image/text options. */
const val CFW_TEXTURE_OPT_BRIGHTNESS_MASK = 15
const val CFW_TEXTURE_OPT_TRANSPARENT = 16
const val CFW_TEXTURE_OPT_INVERSE = 32
/** Rounded-rectangle border sentinel, not a color or flag bit. */
const val DRAW_ROUNDED_RECT_NO_BORDER = 16
@@ -0,0 +1,355 @@
package com.faceclaw.app
/**
* A draw call's clip rect (revision 35, DRAW_FLAG_CLIP), in the call's own
* coordinates: it moves with the call's depth, narrows any clip inherited
* from an enclosing play-list call, and is dropped by a target override.
*/
class DrawClip(val x: Int, val y: Int, val width: Int, val height: Int) {
init {
require(x in -32768..32767 && y in -32768..32767 && width in 0..65535 && height in 0..65535)
}
fun translated(dx: Int, dy: Int) = DrawClip(x + dx, y + dy, width, height)
}
/** Revision 35 wire grammar, shared by scene planning and the local renderer. */
object DrawProtocol {
/** Mirrors g2flash/patches/zlib_glue.c. */
const val DRAW = CFW_MSG_DRAW_CALLS
const val ROOT = CFW_MSG_SET_ROOT_DISPLAY_LIST
const val PRESENT = CFW_MSG_PRESENT
const val CREATE = CFW_MSG_CREATE_SURFACE
/** Mirrors g2flash/patches/resource_cache.h. */
const val IMAGE = CFW_RESOURCE_TYPE_IMAGE
const val FONT = CFW_RESOURCE_TYPE_FONT
const val LIST = CFW_RESOURCE_TYPE_DISPLAY_LIST
const val LARGE = CFW_RESOURCE_FLAG_LARGE
const val RLE = CFW_RESOURCE_FLAG_RLE
/** Mirrors g2flash/patches/display_list.c. */
const val SCREEN = 65535
const val CURRENT = 65534
/** Fixed-width resource/legacy fields, separate from the draw numeric codec. */
fun u16(b: ByteArray, p: Int): Int = (b[p].toInt() and 255) or ((b[p + 1].toInt() and 255) shl 8)
fun word(n: Int) = byteArrayOf(n.toByte(), (n ushr 8).toByte())
private fun encode(write: DrawWriter.() -> Unit): ByteArray = DrawWriter().apply(write).toByteArray()
fun call(op: Int, args: ByteArray, target: Int? = null, depth: Int? = null, clip: DrawClip? = null): ByteArray {
require(depth == null || depth in -128..127)
val flags = (if (target == null) 0 else DRAW_FLAG_RESOURCE_TARGET) or
(if (depth == null) 0 else DRAW_FLAG_DEPTH) or
(if (clip == null) 0 else DRAW_FLAG_CLIP)
return encode {
writeU8(op)
writeU8(flags)
if (target != null) writeU16(target)
if (depth != null) writeS8(depth)
if (clip != null) {
writeS16(clip.x)
writeS16(clip.y)
writeU16(clip.width)
writeU16(clip.height)
}
writeBytes(args)
}
}
private fun call(op: Int, target: Int? = null, depth: Int? = null, clip: DrawClip? = null,
write: DrawWriter.() -> Unit): ByteArray =
call(op, encode(write), target, depth, clip)
fun depthOffset(depth: Int, right: Boolean): Int =
if (right) -floorHalf(depth + 1) else floorHalf(depth)
private fun floorHalf(n: Int): Int = if (n < 0) (n - 1) / 2 else n / 2
fun roundedRect(
x: Int, y: Int, width: Int, height: Int, radius: Int, background: Int,
border: Int = DRAW_ROUNDED_RECT_NO_BORDER, depth: Int? = null,
): ByteArray = roundedRect(DrawValue.Integer(x), DrawValue.Integer(y), width, height, radius, background, border, depth)
fun roundedRect(
x: DrawValue, y: DrawValue, width: Int, height: Int, radius: Int, background: Int,
border: Int = DRAW_ROUNDED_RECT_NO_BORDER, depth: Int? = null, clip: DrawClip? = null,
): ByteArray {
require(width in 1..640 && height in 1..480 && radius in 0..65535)
require(background in 0..15 && border in 0..DRAW_ROUNDED_RECT_NO_BORDER)
return call(DRAW_OP_ROUNDED_RECT, depth = depth, clip = clip) {
writeExtended(x)
writeExtended(y)
writeU16(width)
writeU16(height)
writeU16(radius)
writeU8(background)
writeU8(border)
}
}
fun sequence(calls: List<ByteArray>): ByteArray {
require(calls.size <= 4096)
return encode {
writeU16(calls.size)
for (call in calls) {
require(call.size <= 65535)
writeU16(call.size)
writeBytes(call)
}
}
}
fun message(calls: List<ByteArray>) = byteArrayOf(DRAW.toByte()) + sequence(calls)
fun displayList(calls: List<ByteArray>) = byteArrayOf(LIST.toByte()) + sequence(calls)
fun root(id: Int) = byteArrayOf(ROOT.toByte()) + encode { writeU16(id) }
fun image(
id: Int, x: Int, y: Int, options: Int = CFW_TEXTURE_OPT_BRIGHTNESS_MASK,
target: Int? = null, depth: Int? = null, clip: DrawClip? = null,
): ByteArray = image(id, DrawValue.Integer(x), DrawValue.Integer(y), options, target, depth, clip)
/** Revision 35: x and y are extended values and may be expressions. */
fun image(
id: Int, x: DrawValue, y: DrawValue, options: Int = CFW_TEXTURE_OPT_BRIGHTNESS_MASK,
target: Int? = null, depth: Int? = null, clip: DrawClip? = null,
): ByteArray = call(DRAW_OP_IMAGE, target, depth, clip) {
writeU16(id)
writeExtended(x)
writeExtended(y)
writeU8(options)
}
fun rectCopy(
source: Int, x: Int, y: Int, width: Int, height: Int, dx: Int, dy: Int,
target: Int? = null, depth: Int? = null,
): ByteArray = rectCopy(source, DrawValue.Integer(x), DrawValue.Integer(y), width, height,
DrawValue.Integer(dx), DrawValue.Integer(dy), target, depth)
/** Revision 29: source and destination coordinates may be expressions; the source rect must stay in bounds. */
fun rectCopy(
source: Int, x: DrawValue, y: DrawValue, width: Int, height: Int, dx: DrawValue, dy: DrawValue,
target: Int? = null, depth: Int? = null, clip: DrawClip? = null,
): ByteArray = call(DRAW_OP_RECT_COPY, target, depth, clip) {
writeU16(source)
writeExtended(x)
writeExtended(y)
writeU16(width)
writeU16(height)
writeExtended(dx)
writeExtended(dy)
}
/**
* Fill the whole target, ignoring depth; under a clip (revision 35), just
* the clipped part. Depth still moves the clip rect, like any call's.
*/
fun clear(color: Int = 0, target: Int? = null, clip: DrawClip? = null, depth: Int? = null): ByteArray {
require(color in 0..15)
return call(DRAW_OP_CLEAR, target, depth, clip) { writeU8(color) }
}
/**
* The copy that starts every root list: firmware presents only what the root
* draws. A shifted copy clears first so its uncovered edge is not stale.
*/
fun screenCopy(width: Int, height: Int, depth: Int = 0): List<ByteArray> =
if (depth == 0) listOf(rectCopy(SCREEN, 0, 0, width, height, 0, 0))
else listOf(clear(), rectCopy(SCREEN, 0, 0, width, height, 0, 0, depth = depth))
fun stockText(x: Int, y: Int, options: Int, text: ByteArray): ByteArray {
require(text.size <= 255)
return call(DRAW_OP_STOCK_FONT_STRING) {
writeS16(x)
writeS16(y)
writeU8(options)
writeU8(text.size)
writeBytes(text)
}
}
fun text(id: Int, x: Int, y: Int, options: Int, text: ByteArray): ByteArray =
text(id, DrawValue.Integer(x), DrawValue.Integer(y), options, text)
/** Revision 35: x and y are extended values and may be expressions. */
fun text(id: Int, x: DrawValue, y: DrawValue, options: Int, text: ByteArray, depth: Int? = null,
clip: DrawClip? = null): ByteArray {
require(text.size <= 255)
return call(DRAW_OP_TEXT, depth = depth, clip = clip) {
writeU16(id)
writeExtended(x)
writeExtended(y)
writeU8(options)
writeU8(text.size)
writeBytes(text)
}
}
fun playList(id: Int, target: Int? = null, depth: Int? = null): ByteArray =
call(DRAW_OP_DISPLAY_LIST, target, depth) { writeU16(id) }
/** Revision 33: target pixels with even x+y map through [even], odd ones through [odd]. */
fun remapColors(x: Int, y: Int, width: Int, height: Int, even: IntArray, odd: IntArray): ByteArray {
require(even.size == 16 && odd.size == 16 && (even + odd).all { it in 0..15 })
fun packed(table: IntArray) = ByteArray(8) { i -> ((table[i * 2] shl 4) or table[i * 2 + 1]).toByte() }
return call(DRAW_OP_REMAP_COLORS) {
writeU16(x)
writeU16(y)
writeU16(width)
writeU16(height)
writeBytes(packed(even))
writeBytes(packed(odd))
}
}
/** Dim the whole target's light to factor/256 with DimDither's checkerboard. */
fun lut(width: Int, height: Int, factor: Int): ByteArray {
val (even, odd) = DimDither.tables(factor)
return remapColors(0, 0, width, height, even, odd)
}
fun rawImage(width: Int, height: Int, pixels: ByteArray = ByteArray(((width + 1) / 2) * height)): ByteArray {
require(width in 1..640 && height in 1..480 && pixels.size == ((width + 1) / 2) * height)
val result = byteArrayOf(LARGE.toByte()) + word(width) + word(height) + pixels
require(result.size <= ResourceCacheState.MAX_RESOURCE_SIZE)
return result
}
private fun boundingBox(
x: Int, y: Int, width: Int, height: Int, compact: Boolean, rle: ByteArray, target: Int? = null,
): ByteArray = call(DRAW_OP_BOUNDING_BOX, target) {
writeU8(if (compact) 0 else DRAW_BBOX_FLAG_U16)
if (compact) {
writeU8(x / 4)
writeU8(y / 2)
writeU8(width / 4)
writeU8(height / 2)
} else {
writeU16(x)
writeU16(y)
writeU16(width)
writeU16(height)
}
writeBytes(rle)
}
/** Packed rows -> RLE of exactly width*height pixels, omitting odd-row padding. */
fun bbox(packed: ByteArray, stride: Int, x: Int, y: Int, width: Int, height: Int, target: Int? = null): ByteArray {
val compact = x % 4 == 0 && y % 2 == 0 && width % 4 == 0 && height % 2 == 0 &&
x / 4 < 256 && y / 2 < 256 && width / 4 < 256 && height / 2 < 256
// Pixel RLE is an opaque byte block, with its own fixed-width run lengths.
val out = ByteSink()
var color = -1
var count = 0
fun flush() {
if (count == 0) return
if (count <= 15) {
out.write((count shl 4) or color)
} else {
out.write(color)
if (count <= 255) {
out.write(count)
} else {
out.write(0)
out.write(word(count))
}
}
}
for (yy in y until y + height) for (xx in x until x + width) {
val shift = if (xx % 2 == 0) 4 else 0
val value = (packed[yy * stride + xx / 2].toInt() ushr shift) and 15
if (value != color || count == 65535) {
flush()
color = value
count = 0
}
count++
}
flush()
return boundingBox(x, y, width, height, compact, out.toByteArray(), target)
}
/**
* Optimizer records retain their internal fixed-width format. Decode their
* numeric fields here so every outgoing draw field goes through DrawWriter.
*/
fun fromOptimized(payload: ByteArray, width: Int = 640, height: Int = 480): List<ByteArray> {
val reader = ArrayByteReader(payload)
fun u8() = reader.get().toInt() and 255
fun u16() = reader.getShort().toInt() and 65535
fun s16() = reader.getShort().toInt()
fun bytes(count: Int): ByteArray = ByteArray(count).also { reader.get(it) }
val result = when (val mode = u8() and CFW_MSG_TYPE_MASK) {
CFW_MSG_MULTI_SEGMENT -> {
val calls = ArrayList<ByteArray>()
repeat(u8()) {
calls.addAll(fromOptimized(bytes(u16()), width, height))
}
calls
}
CFW_MSG_BOUNDING_BOX -> {
val x = u8() * 4
val y = u8() * 2
val w = u8() * 4
val h = u8() * 2
u16() // Frame ID belongs only to the optimizer record.
listOf(boundingBox(x, y, w, h, true, bytes(reader.remaining())))
}
CFW_MSG_FULL_FRAME -> listOf(boundingBox(0, 0, width, height, false, bytes(reader.remaining())))
CFW_MSG_STOCK_FONT_STRING -> {
val x = s16()
val y = s16()
val options = u8()
listOf(stockText(x, y, options, bytes(u8())))
}
CFW_MSG_CACHED_IMAGE -> {
val id = u16()
val x = s16()
val y = s16()
val options = u8()
listOf(image(id, x, y, options))
}
CFW_MSG_CACHED_TEXT -> {
val id = u16()
val x = s16()
val y = s16()
val options = u8()
listOf(text(id, x, y, options, bytes(u8())))
}
CFW_MSG_RECT_COPY -> {
val x = u16()
val y = u16()
val w = u16()
val h = u16()
val dx = s16()
val dy = s16()
listOf(rectCopy(CURRENT, x, y, w, h, dx, dy))
}
else -> error("Unsupported internal draw format $mode")
}
require(reader.remaining() == 0)
return result
}
fun messages(calls: List<ByteArray>, maxBytes: Int = 65535): List<ByteArray> {
fun headerSize(count: Int) = 1 + encode { writeU16(count) }.size
val result = ArrayList<ByteArray>()
var batch = ArrayList<ByteArray>()
var bodySize = 0
for (call in calls) {
require(call.size <= 65535)
val framedSize = encode { writeU16(call.size) }.size + call.size
require(headerSize(1) + framedSize <= maxBytes)
if (headerSize(batch.size + 1) + bodySize + framedSize > maxBytes || batch.size == 4096) {
result.add(message(batch))
batch = ArrayList()
bodySize = 0
}
batch.add(call)
bodySize += framedSize
}
if (batch.isNotEmpty()) result.add(message(batch))
return result
}
}
@@ -0,0 +1,68 @@
package com.faceclaw.app
/**
* Numeric fields in the draw grammar go through this codec. Most fields still
* uses fixed-width little-endian values; rounded-rectangle x/y use extended varints and expressions. Byte blocks
* (RLE, text, LUTs and already-encoded calls) retain their own formats.
*/
internal class DrawReader(
private val bytes: ByteArray,
start: Int = 0,
private val end: Int = bytes.size,
) {
var position: Int = start
private set
val remaining: Int get() = end - position
init {
require(start >= 0 && start <= end && end <= bytes.size)
}
fun readU8(): Int {
require(remaining >= 1) { "Truncated draw field" }
return bytes[position++].toInt() and 255
}
fun readS8(): Int = readU8().toByte().toInt()
fun readU16(): Int {
val low = readU8()
return low or (readU8() shl 8)
}
fun readS16(): Int = readU16().toShort().toInt()
fun readBytes(count: Int): ByteArray {
require(count >= 0 && count <= remaining) { "Truncated draw data" }
val result = bytes.copyOfRange(position, position + count)
position += count
return result
}
/** A bounded view prevents a truncated call from consuming the next call. */
fun readSlice(count: Int): DrawReader {
require(count >= 0 && count <= remaining) { "Truncated draw call" }
val result = DrawReader(bytes, position, position + count)
position += count
return result
}
fun requireDone() {
require(remaining == 0) { "Trailing draw data" }
}
}
internal class DrawWriter {
private val out = ByteSink()
fun writeU8(value: Int) = out.write(value)
fun writeS8(value: Int) = out.write(value)
fun writeU16(value: Int) {
out.write(value)
out.write(value ushr 8)
}
fun writeS16(value: Int) = writeU16(value)
fun writeBytes(value: ByteArray) = out.write(value)
fun writeExtended(value: DrawValue) = out.write(ExtendedVarint.write(value))
fun toByteArray(): ByteArray = out.toByteArray()
}
@@ -0,0 +1,145 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
import kotlin.jvm.JvmStatic
class FaceclawRingEventDecoder {
companion object {
@JvmStatic
fun decode(raw: ByteArray?): DirectRingEvent? {
if (((raw == null) || (raw.size == 0))) {
return null
}
var chargerGesture: DirectRingEvent? = decodeChargerGesture(raw)
if ((chargerGesture != null)) {
return chargerGesture
}
return decodeDirectGesture(raw)
}
private fun decodeChargerGesture(raw: ByteArray): DirectRingEvent? {
if ((raw.size != 11)) {
return null
}
if (
((((u8(raw[0]) != 0x00) || (u8(raw[1]) != 0x09)) || (u8(raw[2]) != 0x61)) ||
(u8(raw[3]) != 0x00))
) {
return null
}
var code: Int = u8(raw[4])
var param: Int = (u8(raw[5]) or (u8(raw[6]) shl 8))
var tick: Long =
((((u8(raw[7]) or (u8(raw[8]) shl 8)) or (u8(raw[9]) shl 16)) or
(u8(raw[10]) shl 24))
.toLong() and 0xffffffffL)
var detail: String =
"code=0x${code.toString(16).padStart(2, '0')}(${chargerCodeName(code)}) param=0x${param.toString(16).padStart(4, '0')} tick=$tick"
when (code) {
0x00 -> {
return event(BleProtocol.EVENT_RING_LONG_PRESS, "LONG_PRESS", detail)
}
0x01 -> {
return event(BleProtocol.EVENT_CLICK, "TAP", detail)
}
0x02 -> {
return event(BleProtocol.EVENT_DOUBLE_CLICK, "DOUBLE_TAP", detail)
}
0x04 -> {
return event(BleProtocol.EVENT_SCROLL_TOP, "SWIPE_UP", detail)
}
0x05 -> {
return event(BleProtocol.EVENT_SCROLL_BOTTOM, "SWIPE_DOWN", detail)
}
0x08 -> {
return event(
BleProtocol.EVENT_RING_LONG_PRESS_RELEASE,
"LONG_PRESS_RELEASE",
detail,
)
}
else -> {
return null
}
}
}
private fun decodeDirectGesture(raw: ByteArray): DirectRingEvent? {
if (((raw.size != 3) || (u8(raw[0]) != 0xff))) {
return null
}
var type: Int = u8(raw[1])
var param: Int = u8(raw[2])
var detail: String =
"type=0x${type.toString(16).padStart(2, '0')} param=0x${param.toString(16).padStart(2, '0')}"
if (((type == 0x03) && (param == 0x20))) {
return event(BleProtocol.EVENT_RING_LONG_PRESS, "HOLD", detail)
}
if (((type == 0x04) && (param == 0x01))) {
return event(BleProtocol.EVENT_CLICK, "TAP_SINGLE", detail)
}
if (((type == 0x04) && (param == 0x02))) {
return event(BleProtocol.EVENT_DOUBLE_CLICK, "TAP_DOUBLE", detail)
}
if ((type == 0x05)) {
if ((param <= 0x01)) {
return event(BleProtocol.EVENT_SCROLL_BOTTOM, "SWIPE_FORWARD", detail)
}
return event(BleProtocol.EVENT_SCROLL_TOP, "SWIPE_BACKWARD", detail)
}
return null
}
private fun event(eventType: Int, label: String, detail: String): DirectRingEvent {
var event: G2Event =
G2Event("sys-event", "", eventType, BleProtocol.EVENT_SOURCE_RING, 0)
return DirectRingEvent(event, label, detail)
}
private fun chargerCodeName(code: Int): String {
when (code) {
0x00 -> {
return "LONG_PRESS"
}
0x01 -> {
return "TAP"
}
0x02 -> {
return "DOUBLE_TAP"
}
0x04 -> {
return "SWIPE_UP"
}
0x05 -> {
return "SWIPE_DOWN"
}
0x08 -> {
return "LONG_PRESS_RELEASE"
}
else -> {
return "unknown"
}
}
}
private fun u8(value: Byte): Int {
return (value and 0xff)
}
}
constructor() {}
class DirectRingEvent {
@JvmField val event: G2Event
@JvmField val label: String
@JvmField val detail: String
constructor(event: G2Event, label: String, detail: String) {
this.event = event
this.label = label
this.detail = detail
}
}
}
@@ -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_LENGTH = 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_LENGTH)
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,395 @@
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. Before the prompt is shown, the right arm's settings are read once more so a lens
* that reports silent mode (which blanks the display and ignores input) is refused with the
* way out instead of a prompt nobody can see.
*
* 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")
/**
* Shown instead of a bare "prompt page not acked" error. Silent mode is entered and left
* by the same gesture on the glasses and nothing here can clear it, so the instruction
* has to travel with the error.
*/
const val SILENT_MODE_MESSAGE =
"Your glasses are in silent mode, so they cannot show the confirmation prompt. " +
"Long-press both touchpads on the glasses to leave silent mode, then try again."
}
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) {
// Ask before writing a page that cannot be answered: silent mode blanks the
// display and stops the firmware dispatching input while BLE stays up, so the
// create-prompt write is still acked and the user is left waiting on a prompt
// that never appears.
requireNotSilent(rightAddress)
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 = readSettingsSnapshot(address, arm)?.battery ?: -1
/**
* The sid-0x09 settings read behind both the battery gate and the silent-mode check; one
* ack carries both fields. Two attempts, since on 2.2.9 a request sent right after the
* prelude can be dropped. Null when the arm does not answer or the ack has no battery field.
*/
private fun readSettingsSnapshot(address: String, arm: String): BleProtocol.BatterySnapshot? {
var attempt = 0
while (attempt < 2 && !cancelled) {
val ack = session.readSettings(address, timings.batteryAckTimeoutMs)
if (ack == null) {
emitLog("settings read attempt " + (attempt + 1) + " unacked: " + arm + " arm")
attempt++
continue
}
val snapshot = BleProtocol.parseSettingsBattery(ack)
if (snapshot != null) {
return snapshot
}
emitLog("settings read ack had no battery field: $arm arm")
attempt++
}
return null
}
/**
* Refuse the prompt only when the arm POSITIVELY reports silent mode. An arm that does not
* answer, and firmware whose ack omits the field, both fall through to the prompt exactly as
* before, so a missing answer can never block a flash.
*/
private fun requireNotSilent(address: String) {
val snapshot = readSettingsSnapshot(address, "right")
val state = when {
snapshot == null -> "unknown (arm did not answer)"
snapshot.silentMode < 0 -> "unknown (ack omits the field)"
snapshot.silentMode > 0 -> "on"
else -> "off"
}
emitLog("silent mode before prompt: $state")
if (snapshot != null && snapshot.silentMode > 0) {
throw IllegalStateException(SILENT_MODE_MESSAGE)
}
}
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,160 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
import kotlin.jvm.JvmStatic
class G2Event {
companion object {
@JvmStatic
fun decode(frame: BleProtocol.ParsedFrame): G2Event? {
return decodePayload(frame.sid, BleProtocol.stripTrailingCrc(frame.pb))
}
/** Decode an already validated payload, without the envelope's trailing CRC. */
@JvmStatic
fun decodePayload(sid: Int, pb: ByteArray): G2Event? {
if ((sid == BleProtocol.SID_EVEN_AI)) {
var commandId: Int = BleProtocol.readVarintFieldValue(pb, 1, -1)
if ((commandId != BleProtocol.EVEN_AI_CMD_CTRL)) {
return null
}
var ctrl: ByteArray? = BleProtocol.readFieldBytes(pb, 3)
if ((ctrl == null)) {
return null
}
var status: Int = BleProtocol.readVarintFieldValue(ctrl, 1, -1)
if ((status < 0)) {
return null
}
return G2Event("even-ai", "", status, 0, 0)
}
var deviceEvent: ByteArray? = BleProtocol.readFieldBytes(pb, 13)
if ((deviceEvent == null)) {
return null
}
var listEvent: ByteArray? = BleProtocol.readFieldBytes(deviceEvent, 1)
if ((listEvent != null)) {
return G2Event(
"list-click",
BleProtocol.readStringFieldValue(listEvent, 2),
BleProtocol.readVarintFieldValue(listEvent, 5, BleProtocol.EVENT_CLICK),
0,
0,
)
}
var textEvent: ByteArray? = BleProtocol.readFieldBytes(deviceEvent, 2)
if ((textEvent != null)) {
return G2Event(
"text-click",
BleProtocol.readStringFieldValue(textEvent, 2),
BleProtocol.readVarintFieldValue(textEvent, 3, BleProtocol.EVENT_CLICK),
0,
0,
)
}
var sysEvent: ByteArray? = BleProtocol.readFieldBytes(deviceEvent, 3)
if ((sysEvent != null)) {
var eventType: Int =
BleProtocol.readVarintFieldValue(sysEvent, 1, BleProtocol.EVENT_CLICK)
var eventSource: Int = BleProtocol.readVarintFieldValue(sysEvent, 2, 0)
var exitReason: Int = BleProtocol.readVarintFieldValue(sysEvent, 4, 0)
var imu: ByteArray? = BleProtocol.readFieldBytes(sysEvent, 3)
if ((imu != null)) {
var x: Double = BleProtocol.readFloatFieldValue(imu, 1, 0f).toDouble()
var y: Double = BleProtocol.readFloatFieldValue(imu, 2, 0f).toDouble()
var z: Double = BleProtocol.readFloatFieldValue(imu, 3, 0f).toDouble()
return G2Event(
"sys-event",
"",
eventType,
eventSource,
exitReason,
true,
x,
y,
z,
)
}
return G2Event("sys-event", "", eventType, eventSource, exitReason).apply {
// Faceclaw/19 SysEvent field 100: RI/v1 + raw R1 metadata.
val raw = BleProtocol.readFieldBytes(sysEvent, 100)
if (eventSource == 2 && raw != null && raw.size == 12 &&
raw[0] == 0x52.toByte() && raw[1] == 0x49.toByte() &&
raw[2] == 1.toByte() && raw[3] == 1.toByte() && raw[7] == 0.toByte()) {
ringTick = (0..3).fold(0L) { tick, i ->
tick or ((raw[8 + i].toLong() and 255L) shl (8 * i))
}
ringType = raw[4].toInt() and 255
ringAux = raw[5].toInt() and 255
ringSpeed = raw[6].toInt() and 255
}
}
}
return null
}
}
/** -1 means no original ring timestamp (stock/legacy/synthetic input). */
@JvmField var ringTick: Long = -1
@JvmField var ringType: Int = 0
@JvmField var ringAux: Int = 0
@JvmField var ringSpeed: Int = 0
@JvmField val kind: String
@JvmField val containerName: String
@JvmField val eventType: Int
@JvmField val eventSource: Int
@JvmField val systemExitReasonCode: Int
@JvmField val hasImu: Boolean
@JvmField val imuX: Double
@JvmField val imuY: Double
@JvmField val imuZ: Double
constructor(
kind: String,
containerName: String,
eventType: Int,
eventSource: Int,
systemExitReasonCode: Int,
) : this(
kind,
containerName,
eventType,
eventSource,
systemExitReasonCode,
false,
0.0,
0.0,
0.0,
) {}
constructor(
kind: String,
containerName: String,
eventType: Int,
eventSource: Int,
systemExitReasonCode: Int,
hasImu: Boolean,
imuX: Double,
imuY: Double,
imuZ: Double,
) {
this.kind = kind
this.containerName = containerName
this.eventType = eventType
this.eventSource = eventSource
this.systemExitReasonCode = systemExitReasonCode
this.hasImu = hasImu
this.imuX = imuX
this.imuY = imuY
this.imuZ = imuZ
}
}
@@ -0,0 +1,292 @@
package com.faceclaw.app
class MessageBuilder {
companion object {
private const val ACK_TIMEOUT_MS: Int = 3_500
private const val HEARTBEAT_TIMEOUT_MS: Int = 1_500
}
private var magicPool: BleMagicPool
constructor(magicPool: BleMagicPool) {
this.magicPool = magicPool
}
fun prelude(): OutboundMessage {
return OutboundMessage(
"prelude",
"prelude",
BleProtocol.PRELUDE_ACK_SID,
BleProtocol.FLAG_REQUEST,
BleProtocol.PRELUDE_ACK_MAGIC,
BleProtocol.PRELUDE_F5872_PAYLOAD,
ACK_TIMEOUT_MS,
-1,
false,
)
}
/** The per-connection sid-0x80 security-auth request (one per arm). */
fun securityAuth(leftArm: Boolean): OutboundMessage {
var magic: Int = magicPool.allocate()
return OutboundMessage(
"security-auth",
("security auth " + (if (leftArm) "L" else "R")),
BleProtocol.SID_SECURITY_AUTH,
BleProtocol.FLAG_SECURITY_AUTH,
magic,
BleProtocol.buildAuthenticationRequest(magic),
ConnectionOptions.SECURITY_AUTH_SOFT_TIMEOUT_MS,
-1,
leftArm,
)
}
fun shutdown(exitMode: Int): OutboundMessage {
var magic: Int = magicPool.allocate()
return OutboundMessage(
"shutdown",
("shutdown mode=" + exitMode),
BleProtocol.SID_EVENHUB,
BleProtocol.FLAG_REQUEST,
magic,
BleProtocol.buildShutdown(magic, exitMode),
ACK_TIMEOUT_MS,
-1,
false,
)
}
fun imagePayload(
tile: BleProtocol.ImageTileOptions,
sessionId: Int,
payload: ByteArray,
label: String,
leftArm: Boolean,
): OutboundMessage {
return imagePayload("sound", tile, sessionId, payload, label, leftArm)
}
fun imagePayload(
kind: String,
tile: BleProtocol.ImageTileOptions,
sessionId: Int,
payload: ByteArray,
label: String,
leftArm: Boolean,
): OutboundMessage {
return customMessage(kind, payload, label, -1, leftArm)
}
fun customMessage(
kind: String,
payload: ByteArray?,
label: String,
tileIndex: Int,
leftArm: Boolean,
): OutboundMessage {
if (((payload == null) || (payload.size > CfwTransport.MAX_MESSAGE))) {
throw IllegalArgumentException("CFW message exceeds uint16 length")
}
var streamId: Int = magicPool.allocate()
return OutboundMessage(
kind,
label,
CfwTransport.SID,
0,
streamId,
payload,
CfwMessageWindow.ACK_TIMEOUT_MS,
tileIndex,
leftArm,
)
}
fun cfwCleanup(
tile: BleProtocol.ImageTileOptions,
sessionId: Int,
leftArm: Boolean,
): OutboundMessage {
var payload: ByteArray = byteArrayOf((BleProtocol.CFW_IMAGE_MODE_CLEANUP).toByte())
return imagePayload("cfw-cleanup", tile, sessionId, payload, "CFW cleanup", leftArm)
}
fun enableOrDisableMic(enable: Boolean): OutboundMessage {
var magic: Int = magicPool.allocate()
return OutboundMessage(
"audio-control",
(if (enable) "G2 mic enable" else "G2 mic disable"),
BleProtocol.SID_EVENHUB,
BleProtocol.FLAG_REQUEST,
magic,
BleProtocol.buildAudioControl(magic, enable),
ACK_TIMEOUT_MS,
-1,
false,
)
}
fun enableOrDisableImu(enable: Boolean, reportFrq: Int): OutboundMessage {
var magic: Int = magicPool.allocate()
return OutboundMessage(
"imu-control",
(if (enable) "IMU enable" else "IMU disable"),
BleProtocol.SID_EVENHUB,
BleProtocol.FLAG_REQUEST,
magic,
BleProtocol.buildImuControl(magic, enable, reportFrq),
ACK_TIMEOUT_MS,
-1,
false,
)
}
fun setBrightness(autoAdjust: Boolean, brightnessLevel: Int): OutboundMessage {
var magic: Int = magicPool.allocate()
return OutboundMessage(
"brightness-control",
(if (autoAdjust) "brightness auto" else ("brightness level=" + brightnessLevel)),
BleProtocol.SID_UI_SETTING,
BleProtocol.FLAG_REQUEST,
magic,
BleProtocol.buildSetBrightness(magic, autoAdjust, brightnessLevel),
ACK_TIMEOUT_MS,
-1,
false,
)
}
fun setWearDetection(enabled: Boolean): OutboundMessage {
var magic: Int = magicPool.allocate()
return OutboundMessage(
"wear-detection-control",
("wear detection " + (if (enabled) "enable" else "disable")),
BleProtocol.SID_UI_SETTING,
BleProtocol.FLAG_REQUEST,
magic,
BleProtocol.buildSetWearDetection(magic, enabled),
ACK_TIMEOUT_MS,
-1,
false,
)
}
fun createLayout(): OutboundMessage {
var magic: Int = magicPool.allocate()
return OutboundMessage(
"create-layout",
"create-layout",
BleProtocol.SID_EVENHUB,
BleProtocol.FLAG_REQUEST,
magic,
BleProtocol.buildCreateInputPage(magic),
ACK_TIMEOUT_MS,
-1,
false,
)
}
fun startupTextProbe(): OutboundMessage {
var magic: Int = magicPool.allocate()
return OutboundMessage(
"startup-text-probe",
"startup text probe",
BleProtocol.SID_EVENHUB,
BleProtocol.FLAG_REQUEST,
magic,
BleProtocol.buildDashboardTextUpgrade(magic),
ACK_TIMEOUT_MS,
-1,
false,
)
}
fun heartbeat(): OutboundMessage {
var magic: Int = magicPool.allocate()
return OutboundMessage(
"heartbeat",
"heartbeat",
BleProtocol.SID_EVENHUB,
BleProtocol.FLAG_REQUEST,
magic,
BleProtocol.buildHeartbeat(magic),
HEARTBEAT_TIMEOUT_MS,
-1,
false,
)
}
fun batteryQuery(): OutboundMessage {
var magic: Int = magicPool.allocate()
return OutboundMessage(
"battery",
"battery",
BleProtocol.SID_UI_SETTING,
BleProtocol.FLAG_REQUEST,
magic,
BleProtocol.buildSettingsQuery(magic),
ACK_TIMEOUT_MS,
-1,
false,
)
}
fun faceclawWakeControl(operation: Int, nonce: Int, leftArm: Boolean): OutboundMessage {
return OutboundMessage(
"wake-lease-control",
(((("wake lease op=" + operation) + " nonce=") + nonce) +
(if (leftArm) " L" else " R")),
BleProtocol.SID_UI_SETTING,
BleProtocol.FLAG_REQUEST,
0,
BleProtocol.buildFaceclawWakeControl(operation, nonce),
ACK_TIMEOUT_MS,
-1,
leftArm,
)
}
fun faceclawFramebufferControl(operation: Int, leftArm: Boolean): OutboundMessage {
return OutboundMessage(
"framebuffer-lease-control",
(("framebuffer lease op=" + operation) + (if (leftArm) " L" else " R")),
BleProtocol.SID_UI_SETTING,
BleProtocol.FLAG_REQUEST,
0,
BleProtocol.buildFaceclawWakeControl(operation, 0),
ACK_TIMEOUT_MS,
-1,
leftArm,
)
}
/** CFW mic_control write (settings field 103) targeted at one temple. */
fun faceclawMicControl(record: ByteArray, label: String, leftArm: Boolean): OutboundMessage {
return OutboundMessage(
"mic-control",
(("mic control " + label) + (if (leftArm) " L" else " R")),
BleProtocol.SID_UI_SETTING,
BleProtocol.FLAG_REQUEST,
0,
BleProtocol.buildFaceclawMicControl(record),
ACK_TIMEOUT_MS,
-1,
leftArm,
)
}
fun faceclawWearQuery(leftArm: Boolean): OutboundMessage {
return OutboundMessage(
"wear-query-control",
("wear state query" + (if (leftArm) " L" else " R")),
BleProtocol.SID_UI_SETTING,
BleProtocol.FLAG_REQUEST,
0,
BleProtocol.buildFaceclawWakeControl(BleProtocol.FACECLAW_WEAR_OP_QUERY, 0),
ACK_TIMEOUT_MS,
-1,
leftArm,
)
}
}
@@ -0,0 +1,127 @@
package com.faceclaw.app
/** Split/coalesced notifications and protobuf fragments, isolated per BLE link and sequence. */
class MessageReceiver {
class Message(
val sid: Int,
val flag: Int,
val payload: ByteArray,
val command: Int,
val magic: Int,
val packet: ByteArray? = null,
)
private class Partial(val total: Int, var seen: Long) {
val chunks = mutableListOf<ByteArray>()
var size = 0
}
private val lock = protocolPlatform().createLock()
private val streams = mutableMapOf<String, ByteArray>()
private val messages = mutableMapOf<String, Partial>()
fun clear() = lock.withLock {
streams.clear()
messages.clear()
}
fun receive(link: String, data: ByteArray, now: Long): List<Message> = lock.withLock {
messages.entries.removeAll { now - it.value.seen > 5000 }
val stream = (streams[link] ?: ByteArray(0)) + data
val output = mutableListOf<Message>()
var offset = 0
while (stream.size - offset >= 8) {
fun u8(index: Int) = stream[offset + index].toInt() and 255
if (u8(0) != 0xaa || u8(1) !in intArrayOf(0x21, 0x12)) {
offset++
continue
}
val length = u8(3)
if (stream.size - offset < length + 8) break
val count = u8(4)
val index = u8(5)
val sid = u8(6)
val flag = u8(7)
val key = "$link:${u8(2)}:$sid:$flag"
val packet = stream.copyOfRange(offset, offset + length + 8)
val chunk = packet.copyOfRange(8, packet.size)
offset += length + 8
if (sid == CfwTransport.SID) {
output.add(Message(sid, flag, chunk, -1, -1, packet))
continue
}
if (count == 0 || index == 0 || index > count) {
messages.remove(key)
continue
}
if (index == 1) messages[key] = Partial(count, now)
val partial = messages[key]
if (partial == null || partial.total != count || partial.chunks.size + 1 != index) {
messages.remove(key)
continue
}
partial.chunks.add(chunk)
partial.size += chunk.size
partial.seen = now
if (partial.size > 65536) {
messages.remove(key)
continue
}
if (index != count) continue
messages.remove(key)
val bytes = ByteSink(partial.size)
partial.chunks.forEach { bytes.write(it) }
val complete = bytes.toByteArray()
if (complete.size < 2) continue
val payload = complete.copyOf(complete.size - 2)
val checksum =
(complete[complete.size - 2].toInt() and 255) or
((complete.last().toInt() and 255) shl 8)
if (CfwTransport.crc(payload) != checksum || !validProtobuf(payload)) continue
output.add(
Message(
sid,
flag,
payload,
BleProtocol.readVarintFieldValue(payload, 1, -1),
BleProtocol.readVarintFieldValue(payload, 2, -1),
)
)
}
streams[link] = stream.copyOfRange(offset, stream.size)
output
}
private fun validProtobuf(data: ByteArray): Boolean {
var offset = 0
fun varint(): Int? {
var value = 0
for (i in 0..4) {
if (offset == data.size) return null
val byte = data[offset++].toInt() and 255
if (i == 4 && byte > 15) return null
value = value or ((byte and 127) shl (i * 7))
if (byte and 128 == 0) return value
}
return null
}
while (offset < data.size) {
val key = varint() ?: return false
if (key ushr 3 == 0) return false
if (key and 7 == 0) {
varint() ?: return false
continue
}
val length =
when (key and 7) {
1 -> 8
5 -> 4
2 -> varint() ?: return false
else -> return false
}
if (length < 0 || length > data.size - offset) return false
offset += length
}
return true
}
}
@@ -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)
}
}
@@ -0,0 +1,68 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
/** Mutable attempt state, owned by the communicator and guarded by its lock. */
class OutboundMessage(
@JvmField val kind: String?,
@JvmField val label: String?,
@JvmField val sid: Int,
@JvmField val flag: Int,
@JvmField var magic: Int,
message: ByteArray?,
@JvmField val ackTimeoutMs: Int,
@JvmField val tileIndex: Int,
@JvmField val isLeftArmMessage: Boolean,
) {
@JvmField val message: ByteArray = message?.copyOf() ?: ByteArray(0)
@JvmField
val cfwChecksum: Int = if (sid == CfwTransport.SID) CfwTransport.crc(this.message) else 0
@JvmField var cfwAckLenses = 0
@JvmField var cfwRetries = 0
@JvmField var cfwRetryPending = false
@JvmField var imageUpdateId = 0
@JvmField var imageMessageNumber = 0
@JvmField var imageMessageCount = 0
@JvmField var sentAtMs = 0L
@JvmField var writeStartedAtMs = 0L
@JvmField var ackDeadlineAtMs = 0L
@JvmField var ackPayload = ByteArray(0)
@JvmField var onSent: MessageCallback? = null
@JvmField var onAck: MessageCallback? = null
@JvmField var onTimeout: MessageCallback? = null
/** NACK names this attempt's sequence, even without a decoded size. */
fun acceptCfwAck(ack: CfwTransport.Ack?): Boolean {
if (
ack == null ||
sid != CfwTransport.SID ||
magic != ack.streamId ||
ack.messageId != 0 ||
(ack.lens != 1 && ack.lens != 2)
)
return false
if (ack.nack) {
cfwRetryPending = true
return false
}
if (message.size != ack.size || cfwChecksum != ack.checksum) return false
cfwAckLenses = cfwAckLenses or ack.lens
return !cfwRetryPending && cfwAckLenses == CfwTransport.BOTH
}
/** Replace an attempt atomically under the communicator lock. */
fun prepareCfwReplay(streamId: Int) {
magic = streamId
cfwRetries++
cfwAckLenses = 0
cfwRetryPending = false
ackDeadlineAtMs = 0
ackPayload = ByteArray(0)
}
fun setImageUpdatePosition(updateId: Int, messageNumber: Int, messageCount: Int) {
imageUpdateId = updateId
imageMessageNumber = messageNumber
imageMessageCount = messageCount
}
}
@@ -0,0 +1,74 @@
package com.faceclaw.app
/** OS services used by the protocol state machines; supplied by their owner. */
interface ProtocolPlatform {
/** Monotonic milliseconds since boot, including time spent asleep. */
fun elapsedRealtimeMs(): Long
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. */
interface ProtocolLock {
fun lock()
fun unlock()
}
/** Persistent zlib stream. Each write completes a SYNC_FLUSH, not a new stream. */
interface ProtocolDeflater {
fun reset()
fun syncFlush(message: ByteArray): ByteArray
fun close()
}
internal inline fun <T> ProtocolLock.withLock(action: () -> T): T {
lock()
try {
return action()
} finally {
unlock()
}
}
enum class GattWriteMode {
WITH_RESPONSE,
WITHOUT_RESPONSE,
}
/** Keeps message callbacks independent of java.lang.Runnable. */
fun interface MessageCallback {
fun run()
}
@@ -0,0 +1,167 @@
package com.faceclaw.app
import kotlin.jvm.JvmOverloads
/** Immutable content-addressed bytes; equality verifies bytes when hashes collide. */
class CachedResource @JvmOverloads constructor(bytes: ByteArray, val owner: String? = null) {
val bytes: ByteArray = bytes.copyOf()
val hash: Long = this.bytes.fold(-3750763034362895579L) { hash, byte ->
(hash xor (byte.toLong() and 255)) * 1099511628211L
}
override fun hashCode(): Int = owner?.hashCode() ?: (hash xor (hash ushr 32)).toInt()
override fun equals(other: Any?): Boolean = this === other ||
other is CachedResource && owner == other.owner && hash == other.hash && bytes.contentEquals(other.bytes)
}
/**
* Phone-side residency for the firmware's compacting resource arena. The owner serializes calls.
* prepare() protects the current frame's hits before admitting misses, evicting only unprotected
* LRU entries. Commands must be sent in returned order, before any dependent draws.
*/
class ResourceCacheState {
companion object {
/** Mirrors g2flash/patches/resource_cache.h. */
const val CACHE_SIZE = 196608
const val RESOURCE_COUNT = 512
const val TABLE_BYTES = RESOURCE_COUNT * 4
const val ARENA_BYTES = CACHE_SIZE - TABLE_BYTES
const val MAX_RESOURCE_SIZE = 65536
const val BLOCK_HEADER_BYTES = 16
/** Mirrors g2flash/patches/zlib_glue.c. */
const val UPLOAD_MODE = CFW_MSG_UPLOAD_RESOURCE
const val EVICT_MODE = CFW_MSG_EVICT_RESOURCE
fun allocationBytes(size: Int): Int = BLOCK_HEADER_BYTES + ((size + 3) and -4)
}
private data class Resident(val id: Int, val resource: CachedResource, var lastUsed: Long)
private val residents = LinkedHashMap<CachedResource, Resident>()
private val occupied = BooleanArray(RESOURCE_COUNT)
var generation = 0
private set
private var pinned = emptySet<CachedResource>()
fun pin(resources: Collection<CachedResource>) { pinned = resources.toSet() }
private var allocated = 0
private var clock = 0L
private var resetRequired = true
private val evictions = linkedSetOf<Int>()
private val uploads = ArrayList<Resident>()
/** Forget uncertain device state. The next upload first evicts every ID on both lenses. */
fun reset() {
generation++
pinned = emptySet()
residents.clear(); occupied.fill(false); allocated = 0; clock = 0
evictions.clear(); uploads.clear(); resetRequired = true
}
fun usedBytes(): Int = TABLE_BYTES + allocated
fun residentCount(): Int = residents.size
fun resourceId(resource: CachedResource): Int = residents[resource]?.id ?: -1
/** Called once per frame after coalescing. -1 entries stay baked into the pixel fallback. */
fun prepare(resources: List<CachedResource>): IntArray {
check(uploads.isEmpty() && evictions.isEmpty()) { "Previous resource commands have not been drained" }
val protected = HashSet<Int>()
for (resource in pinned) residents[resource]?.let { protected.add(it.id) }
for (resource in resources) residents[resource]?.let { protected.add(it.id) }
return IntArray(resources.size) { index ->
val resource = resources[index]
val hit = residents[resource]
if (hit != null) {
hit.lastUsed = ++clock
hit.id
} else if (resource.bytes.isEmpty() || resource.bytes.size > MAX_RESOURCE_SIZE) {
-1
} else {
val needed = allocationBytes(resource.bytes.size)
// Check feasibility before evicting anything for a request that cannot fit.
val available = ARENA_BYTES - allocated + residents.values
.filter { it.id !in protected }.sumOf { allocationBytes(it.resource.bytes.size) }
val canGetId = residents.size < RESOURCE_COUNT || residents.values.any { it.id !in protected }
if (needed > available || !canGetId) -1
else {
while (allocated + needed > ARENA_BYTES || residents.size >= RESOURCE_COUNT) {
val victim = residents.values.filter { it.id !in protected }.minBy { it.lastUsed }
residents.remove(victim.resource); occupied[victim.id] = false
allocated -= allocationBytes(victim.resource.bytes.size)
evictions.add(victim.id)
}
val id = occupied.indexOfFirst { !it }
val entry = Resident(id, resource, ++clock)
occupied[id] = true; allocated += needed
residents[resource] = entry; uploads.add(entry); protected.add(id)
id
}
}
}
}
/** A rejected image plan must not commit unsent allocations or LRU changes. */
fun checkpoint(): () -> Unit {
val oldResidents = residents.mapValues { it.value.copy() }
val oldOccupied = occupied.copyOf()
val oldAllocated = allocated
val oldClock = clock
val oldReset = resetRequired
val oldEvictions = evictions.toList()
val oldUploads = uploads.toList()
return {
residents.clear(); residents.putAll(oldResidents); oldOccupied.copyInto(occupied)
allocated = oldAllocated; clock = oldClock; resetRequired = oldReset
evictions.clear(); evictions.addAll(oldEvictions)
uploads.clear(); uploads.addAll(oldUploads)
}
}
/** Batched evictions followed by bounded upload chunks, including exactly 64 KiB resources. */
fun drainCommands(maxPayloadBytes: Int): MutableList<ByteArray> {
require(maxPayloadBytes in 14..65535)
val result = ArrayList<ByteArray>()
val ids = if (resetRequired && uploads.isNotEmpty()) (0 until RESOURCE_COUNT).toList() else evictions.toList()
for (batch in ids.chunked((maxPayloadBytes - 3) / 2)) {
val out = ByteSink()
out.write(EVICT_MODE); write16(out, batch.size)
batch.forEach { write16(out, it) }
result.add(out.toByteArray())
}
var entries = ArrayList<ByteArray>()
var entryIds = HashSet<Int>()
var size = 3
fun flush() {
if (entries.isEmpty()) return
val out = ByteSink()
out.write(UPLOAD_MODE); write16(out, entries.size)
entries.forEach { out.write(it, 0, it.size) }
result.add(out.toByteArray())
entries = ArrayList(); entryIds = HashSet(); size = 3
}
for (entry in uploads) {
val data = entry.resource.bytes
if (entry.resource.owner != null) {
flush()
result.add(byteArrayOf(DrawProtocol.CREATE.toByte(), 1, 0) + DrawProtocol.word(entry.id) + data.copyOfRange(1, 5))
continue
}
var offset = 0
while (offset < data.size) {
val count = minOf(data.size - offset, maxPayloadBytes - 13)
val out = ByteSink()
write16(out, entry.id); write32(out, data.size)
write16(out, offset); write16(out, count)
out.write(data, offset, count)
val bytes = out.toByteArray()
if (size + bytes.size > maxPayloadBytes || entry.id in entryIds) flush()
entries.add(bytes); entryIds.add(entry.id); size += bytes.size
offset += count
}
}
flush()
if (uploads.isNotEmpty()) resetRequired = false
evictions.clear(); uploads.clear()
return result
}
private fun write16(out: ByteSink, value: Int) { out.write(value and 255); out.write((value ushr 8) and 255) }
private fun write32(out: ByteSink, value: Int) { write16(out, value); write16(out, value ushr 16) }
}
@@ -0,0 +1,10 @@
package com.faceclaw.app
/** Resource header types and flags; mirrored in g2flash/patches/resource_cache.h. */
const val CFW_RESOURCE_TYPE_IMAGE = 0
const val CFW_RESOURCE_TYPE_FONT = 1
const val CFW_RESOURCE_TYPE_DISPLAY_LIST = 2
const val CFW_RESOURCE_TYPE_MASK = 3
const val CFW_RESOURCE_FLAG_LARGE = 4
const val CFW_RESOURCE_FLAG_RLE = 8
const val CFW_RESOURCE_IMAGE_FLAGS_MASK = CFW_RESOURCE_FLAG_LARGE or CFW_RESOURCE_FLAG_RLE
@@ -0,0 +1,848 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
import kotlin.jvm.JvmStatic
/**
* RingProtocol: frame build/parse plus per-record decoding for the Even R1
* ring's health-data channel. Does _not_ include code for actually sending
* anything; for that, see GlassesSessionRing.kt (same split as BleProtocol).
*
* Platform-neutral and free of Android imports; the Java-facing surface
* (static members, public fields) is kept so the JVM self-test in
* tests/kotlin and the TypeScript health ingest read it unchanged.
*
* **This is a different protocol from BleProtocol's.** The glasses speak
* an `aa21` envelope with a CRC-16/CCITT; the ring speaks a 15-byte
* `64 .. 64` header with a CRC-32C. Nothing is shared between them, and
* in particular [crc32] must never be pointed at a glasses frame.
*
* Wire format (offsets from the start of the ATT value):
* ```
* off size field
* 0 1 FLAG 0x00 normally; 0x01 = fragmented, a continuation follows
* 1 4 CRC32 little-endian, over bytes [5:] of the *reassembled* frame
* 5 1 0x64 constant magic
* 6 1 CHAN 0x01 device/system, 0x02 health data
* 7 1 0x64 constant magic
* 8 1 SEQ phone-side: one counter shared by both channels
* 9 1 0x00 constant
* 10 1 KIND 0x00 REQ, 0x01 ACK, 0x02 DATA, 0x03 RSP
* 11 1 CMD_HI
* 12 1 CMD_LO
* 13 2 PLEN little-endian; equals (total frame length - 5)
* 15 .. PAYLOAD PLEN - 10 bytes; PAYLOAD[0:2] is a free per-message nonce
* ```
*
* Protocol spec and its evidence:
* knowledge/staging/faceclaw-ring-protocol-decode-return.md in the TLC
* knowledge base. Everything below is implemented from that document; the
* places where it is explicitly *not* solved are marked UNSOLVED and are
* surfaced raw rather than guessed at.
*/
class RingProtocol private constructor() {
companion object {
/** CRC-32C polynomial, MSB-first / non-reflected form. Not CRC-32 (0x04C11DB7). */
private const val CRC32C_POLY: Int = 0x1EDC6F41
const val MAGIC: Int = 0x64
const val HEADER_LEN: Int = 15
/** A continuation frame is FLAG(1) + CRC32(4) and then raw remainder bytes. */
const val CONTINUATION_PREFIX_LEN: Int = 5
const val FLAG_PLAIN: Int = 0x00
const val FLAG_FRAGMENTED: Int = 0x01
const val CHAN_DEVICE: Int = 0x01
const val CHAN_HEALTH: Int = 0x02
const val KIND_REQ: Int = 0x00
const val KIND_ACK: Int = 0x01
const val KIND_DATA: Int = 0x02
const val KIND_RSP: Int = 0x03
/** Every health record type uses CMD_LO = 0x01; the type lives in CMD_HI. */
const val CMD_LO_HEALTH: Int = 0x01
const val CMD_HI_HEART_RATE: Int = 0x01
const val CMD_HI_SPO2: Int = 0x02
const val CMD_HI_HRV: Int = 0x04
const val CMD_HI_STEPS: Int = 0x05
const val CMD_HI_SLEEP: Int = 0x06
/** Device/system channel commands all have CMD_HI = 0x00. */
const val CMD_HI_DEVICE: Int = 0x00
const val CMD_LO_PAGE_ACK: Int = 0x7E
/**
* The five health pulls, in the order Even's own app issues them:
* heart rate, HRV, SpO2, sleep, steps. That order is identical in all four
* sync bursts of the reference capture. (It is NOT the order the spec
* document happens to list them in — that is just its presentation order.)
* Whether the order matters to the ring is untested; matching the app is
* the cheapest way not to find out the hard way.
*/
@JvmField val HEALTH_COMMANDS: IntArray = intArrayOf(
CMD_HI_HEART_RATE,
CMD_HI_HRV,
CMD_HI_SPO2,
CMD_HI_SLEEP,
CMD_HI_STEPS,
)
/** Returned by anchor/timestamp accessors when the value is not known. */
const val UNKNOWN_TIME: Long = -1L
private val EMPTY = ByteArray(0)
// ------------------------------------------------------------------
// CRC
// ------------------------------------------------------------------
/**
* CRC-32C over `data[from, to)`: polynomial 0x1EDC6F41, MSB-first,
* init 0, no reflection, no final xor. Verified against 188/188 frames in
* the reference capture.
*/
@JvmStatic
fun crc32(data: ByteArray, from: Int, to: Int): Int {
var crc = 0
for (i in from until to) {
crc = crc xor ((data[i].toInt() and 0xff) shl 24)
for (bit in 0 until 8) {
crc = if ((crc and 0x80000000.toInt()) != 0) {
(crc shl 1) xor CRC32C_POLY
} else {
crc shl 1
}
}
}
return crc
}
@JvmStatic
fun crc32(data: ByteArray?): Int = if (data == null) 0 else crc32(data, 0, data.size)
// ------------------------------------------------------------------
// Frame building
// ------------------------------------------------------------------
/**
* Build one complete, CRC-correct frame. Fragmentation is a receive-side
* concern only: nothing we send approaches the 244-byte ATT ceiling.
*/
@JvmStatic
fun buildFrame(chan: Int, kind: Int, cmdHi: Int, cmdLo: Int, seq: Int, payload: ByteArray?): ByteArray {
val body = payload ?: EMPTY
val total = HEADER_LEN + body.size
val frame = ByteArray(total)
frame[0] = FLAG_PLAIN.toByte()
frame[5] = MAGIC.toByte()
frame[6] = (chan and 0xff).toByte()
frame[7] = MAGIC.toByte()
frame[8] = (seq and 0xff).toByte()
frame[9] = 0x00
frame[10] = (kind and 0xff).toByte()
frame[11] = (cmdHi and 0xff).toByte()
frame[12] = (cmdLo and 0xff).toByte()
val plen = total - 5
frame[13] = (plen and 0xff).toByte()
frame[14] = ((plen ushr 8) and 0xff).toByte()
body.copyInto(frame, HEADER_LEN)
writeIntLe(frame, 1, crc32(frame, 5, total))
return frame
}
/**
* A request frame. Health requests carry no arguments at all: the payload
* is the 2-byte nonce and nothing else.
*
* The nonce is a free per-message id — it is covered by the frame CRC but
* is not content-derived, so any value works. It is encoded little-endian.
*/
@JvmStatic
fun buildRequest(chan: Int, cmdHi: Int, cmdLo: Int, seq: Int, nonce: Int): ByteArray {
return buildFrame(chan, KIND_REQ, cmdHi, cmdLo, seq, nonceBytes(nonce))
}
/** One of the five health pulls; see [HEALTH_COMMANDS]. */
@JvmStatic
fun buildHealthRequest(cmdHi: Int, seq: Int, nonce: Int): ByteArray {
return buildRequest(CHAN_HEALTH, cmdHi, CMD_LO_HEALTH, seq, nonce)
}
/**
* The per-page acknowledgement: command 00:7E on the DEVICE channel,
* echoing the sequence number of the DATA page being acknowledged.
*
* Payload is 12 bytes: the usual 2-byte nonce, then
* `02 <cmd_hi> <cmd_lo> 00 <page_seq>`, then five zero bytes. (Note
* the echoed page seq is at payload offset 6, after the nonce — a spec doc
* that describes the payload as starting at `02` is off by the nonce.)
*
* The frame's own SEQ is the phone's shared counter, NOT the echoed page
* seq: across 20 ACKs in the reference capture the two are always different,
* and the header SEQ continues the same +1 sequence used by every other
* phone-to-ring write on both channels.
*
* Whether the ring actually *requires* this is untested — Even's app
* sends one for every page without exception (20/20), but no page has ever
* been deliberately left unacknowledged to see what happens.
*/
@JvmStatic
fun buildPageAck(seq: Int, nonce: Int, ackedCmdHi: Int, ackedCmdLo: Int, pageSeq: Int): ByteArray {
val payload = ByteArray(12)
payload[0] = (nonce and 0xff).toByte()
payload[1] = ((nonce ushr 8) and 0xff).toByte()
payload[2] = 0x02
payload[3] = (ackedCmdHi and 0xff).toByte()
payload[4] = (ackedCmdLo and 0xff).toByte()
payload[5] = 0x00
payload[6] = (pageSeq and 0xff).toByte()
// payload[7..11] stay zero.
return buildFrame(CHAN_DEVICE, KIND_ACK, CMD_HI_DEVICE, CMD_LO_PAGE_ACK, seq, payload)
}
private fun nonceBytes(nonce: Int): ByteArray {
return byteArrayOf((nonce and 0xff).toByte(), ((nonce ushr 8) and 0xff).toByte())
}
// ------------------------------------------------------------------
// Frame parsing
// ------------------------------------------------------------------
/** True when a value could be the start of a frame (magic bytes in place). */
@JvmStatic
fun looksLikeHeader(value: ByteArray?): Boolean {
return value != null
&& value.size >= HEADER_LEN
&& (value[5].toInt() and 0xff) == MAGIC
&& (value[7].toInt() and 0xff) == MAGIC
}
/** Total frame length declared by PLEN, or -1 when this is not a header. */
@JvmStatic
fun declaredLength(value: ByteArray?): Int {
if (value == null || !looksLikeHeader(value)) {
return -1
}
val plen = (value[13].toInt() and 0xff) or ((value[14].toInt() and 0xff) shl 8)
val total = plen + 5
return if (total < HEADER_LEN) -1 else total
}
/** Parse a complete (already reassembled) frame. Returns null if malformed. */
@JvmStatic
fun parse(frame: ByteArray?): Frame? {
if (frame == null || frame.size < HEADER_LEN) {
return null
}
if ((frame[5].toInt() and 0xff) != MAGIC || (frame[7].toInt() and 0xff) != MAGIC) {
return null
}
val plen = (frame[13].toInt() and 0xff) or ((frame[14].toInt() and 0xff) shl 8)
if (plen + 5 != frame.size) {
return null
}
val storedCrc = readIntLe(frame, 1)
val actualCrc = crc32(frame, 5, frame.size)
val payload = frame.copyOfRange(HEADER_LEN, frame.size)
return Frame(
frame[0].toInt() and 0xff,
frame[6].toInt() and 0xff,
frame[8].toInt() and 0xff,
frame[10].toInt() and 0xff,
frame[11].toInt() and 0xff,
frame[12].toInt() and 0xff,
payload,
frame,
storedCrc == actualCrc,
)
}
// ------------------------------------------------------------------
// Record decoding
// ------------------------------------------------------------------
/**
* Decode a health DATA page. Returns null when the frame is not a health
* DATA page or its body does not match the layout for its type.
*/
@JvmStatic
fun decode(frame: Frame?, receivedAtMs: Long): HealthRecord? {
if (frame == null || !frame.crcOk || !frame.isHealth() || frame.kind != KIND_DATA) {
return null
}
if (frame.cmdLo != CMD_LO_HEALTH) {
return null
}
return when (frame.cmdHi) {
CMD_HI_HEART_RATE, CMD_HI_SPO2, CMD_HI_HRV -> decodeHourly(frame, receivedAtMs)
CMD_HI_STEPS -> decodeSteps(frame, receivedAtMs)
CMD_HI_SLEEP -> decodeSleep(frame, receivedAtMs)
else -> null
}
}
/**
* Heart rate / SpO2 / HRV: an hourly `[index][avg][max][min]` series.
*
* Layout follows openR1 r1_health_encode_daily_u8/u16 in r1_health.c:
* count, signed timezone minutes, day start, optional latest timestamp/value,
* then count groups. There is no footer. HR/SpO2 values are one byte; HRV
* values are two. Subtracting a supposed four-byte footer misdecoded a
* one-group HRV page as one-byte values and rejected real HR/SpO2 pages.
*/
@JvmStatic
fun decodeHourly(frame: Frame, receivedAtMs: Long): HourlyRecord? {
val pay = frame.payload
if (pay.size < 9) {
return null
}
val count = pay[2].toInt() and 0xff
val anchor = anchorUnixSeconds(pay)
val width = if (frame.cmdHi == CMD_HI_HRV) 2 else 1
val groupBytes = count * (1 + 3 * width)
val prefixLength = pay.size - groupBytes
val hasLatest = prefixLength == 13 + width
if (count > 24 || (!hasLatest && prefixLength != 9)) return null
val tag = if (hasLatest) readUInt32Le(pay, 9) else UNKNOWN_TIME
val current = if (hasLatest) readUIntLe(pay, 13, width) else -1
var offset = prefixLength
val groups = arrayOfNulls<HourlyGroup>(count)
for (i in 0 until count) {
val hourIndex = pay[offset].toInt() and 0xff
if (hourIndex >= 24) return null
offset++
val avg = readUIntLe(pay, offset, width)
offset += width
val max = readUIntLe(pay, offset, width)
offset += width
val min = readUIntLe(pay, offset, width)
offset += width
val unix = if (anchor == UNKNOWN_TIME) UNKNOWN_TIME else anchor + hourIndex * 3600L
groups[i] = HourlyGroup(hourIndex, avg, max, min, unix)
}
@Suppress("UNCHECKED_CAST")
return HourlyRecord(frame.cmdHi, receivedAtMs, anchor, tag, current, width, groups as Array<HourlyGroup>)
}
/**
* Steps / activity buckets: `[index][v1][v2][v3]` after the record
* prefix. v1 (steps) is proven against a full-day total; v2 and v3 are
* calorie-shaped but unconfirmed, and the bucket index does NOT map to a
* known wall-clock time (see [StepsBucket]).
*/
@JvmStatic
fun decodeSteps(frame: Frame, receivedAtMs: Long): StepsRecord? {
val pay = frame.payload
if (pay.size < 9) {
return null
}
val count = pay[2].toInt() and 0xff
if (count > 144 || pay.size != 9 + count * 7) {
return null
}
val anchor = anchorUnixSeconds(pay)
var offset = 9
val buckets = arrayOfNulls<StepsBucket>(count)
for (i in 0 until count) {
val index = pay[offset].toInt() and 0xff
if (index >= 144) return null
val steps = readUInt16Le(pay, offset + 1)
val v2 = readUInt16Le(pay, offset + 3)
val v3 = readUInt16Le(pay, offset + 5)
offset += 7
buckets[i] = StepsBucket(index, steps, v2, v3)
}
@Suppress("UNCHECKED_CAST")
return StepsRecord(receivedAtMs, anchor, buckets as Array<StepsBucket>)
}
/**
* A sleep session. The ring transmits pre-classified stages, per-stage
* totals and the session boundaries; nothing is computed phone-side.
*
* `startTs`/`endTs` are ring-relative seconds, NOT Unix
* timestamps — see [SleepRecord].
*/
@JvmStatic
fun decodeSleep(frame: Frame, receivedAtMs: Long): SleepRecord? {
val pay = frame.payload
if (pay.size < 3) {
return null
}
val recordState = pay[2].toInt() and 0xff
val unknownA = safeRange(pay, 3, 9)
val unknownTag = if (pay.size >= 13) readUInt32Le(pay, 9) else UNKNOWN_TIME
if (recordState != 1) {
// RECSTATE 2 is the empty / end-of-list marker.
return SleepRecord(
receivedAtMs, recordState, unknownA, unknownTag,
0, 0, 0, 0, 0, 0, 0, arrayOf())
}
if (pay.size < 34) return null
val startTs = readUInt32Le(pay, 14)
val endTs = readUInt32Le(pay, 18)
val totalTime = readUInt16Le(pay, 22)
val wakeTime = readUInt16Le(pay, 24)
val remTime = readUInt16Le(pay, 26)
val lightTime = readUInt16Le(pay, 28)
val deepTime = readUInt16Le(pay, 30)
val segmentCount = readUInt16Le(pay, 32)
if (pay.size != 34 + segmentCount * 3) {
return null
}
var offset = 34
val segments = Array(segmentCount) {
val stage = pay[offset].toInt() and 0xff
val halfMinutes = readUInt16Le(pay, offset + 1)
offset += 3
SleepSegment(stage, halfMinutes)
}
return SleepRecord(
receivedAtMs, recordState, unknownA, unknownTag,
startTs, endTs, totalTime, wakeTime, remTime, lightTime, deepTime, segments)
}
/**
* The record's day anchor as Unix epoch seconds, or [UNKNOWN_TIME]
* when the day timestamp is zero or the timezone offset is invalid.
*
* **UNSOLVED:** a backlog page's true base is not understood as a
* general rule. One capture's backlog base landed at 2026-09-08 23:48:49
* local, which is the moment that sync ran plus a per-type offset — it is
* not a fixed offset from midnight and must not be hardcoded. Callers get
* [UNKNOWN_TIME] and the raw hour index instead of an invented
* absolute time.
*/
@JvmStatic
fun anchorUnixSeconds(payload: ByteArray?): Long {
if (payload == null || payload.size < 9) {
return UNKNOWN_TIME
}
// These two bytes are an int16 timezone offset, not magic. 10 ff is
// -240 minutes (EDT); Pacific time, UTC and eastern zones differ.
val timezoneMinutes = readUInt16Le(payload, 3).toShort().toInt()
val anchor = readUInt32Le(payload, 5)
return if (timezoneMinutes >= -840 && timezoneMinutes <= 840 && anchor != 0L) anchor else UNKNOWN_TIME
}
/** Device-channel 00:01 response, matching openR1 get_device_status(). */
@JvmStatic
fun decodeDeviceStatus(frame: Frame?): DeviceStatus? {
if (frame == null || !frame.crcOk || frame.chan != CHAN_DEVICE
|| frame.kind != KIND_RSP || frame.cmdHi != 0 || frame.cmdLo != 1
|| frame.payload.size != 9) return null
val battery = frame.payload[2].toInt() and 0xff
val charge = frame.payload[3].toInt() and 0xff
if (battery > 100 || charge > 3) return null
return DeviceStatus(battery, if (charge == 0) -1 else if (charge == 2) 0 else 1)
}
/** Hex, for logs. Mirrors GlassesSessionCore.hex(). */
@JvmStatic
fun hex(data: ByteArray?): String {
if (data == null || data.isEmpty()) {
return ""
}
val out = CharArray(data.size * 2)
for (i in data.indices) {
val value = data[i].toInt() and 0xff
out[i * 2] = HEX_DIGITS[value ushr 4]
out[i * 2 + 1] = HEX_DIGITS[value and 0x0f]
}
return out.concatToString()
}
/** The five health requests, ready to write, sharing one ascending seq run. */
@JvmStatic
fun buildHealthRequestBurst(firstSeq: Int, firstNonce: Int): List<ByteArray> {
val frames = ArrayList<ByteArray>(HEALTH_COMMANDS.size)
var seq = firstSeq
var nonce = firstNonce
for (cmdHi in HEALTH_COMMANDS) {
frames.add(buildHealthRequest(cmdHi, seq, nonce))
seq = (seq + 1) and 0xff
nonce = (nonce + 1) and 0xffff
}
return frames
}
// ------------------------------------------------------------------
// Little-endian and formatting helpers
// ------------------------------------------------------------------
private const val HEX_DIGITS = "0123456789abcdef"
/** Two lowercase hex digits, like `%02x` for a byte-sized value. */
internal fun hex2(value: Int): String {
val v = value and 0xff
return "" + HEX_DIGITS[v ushr 4] + HEX_DIGITS[v and 0x0f]
}
private fun writeIntLe(out: ByteArray, offset: Int, value: Int) {
out[offset] = (value and 0xff).toByte()
out[offset + 1] = ((value ushr 8) and 0xff).toByte()
out[offset + 2] = ((value ushr 16) and 0xff).toByte()
out[offset + 3] = ((value ushr 24) and 0xff).toByte()
}
private fun readIntLe(data: ByteArray, offset: Int): Int {
return (data[offset].toInt() and 0xff) or
((data[offset + 1].toInt() and 0xff) shl 8) or
((data[offset + 2].toInt() and 0xff) shl 16) or
((data[offset + 3].toInt() and 0xff) shl 24)
}
private fun readUInt32Le(data: ByteArray, offset: Int): Long {
return readIntLe(data, offset).toLong() and 0xffffffffL
}
private fun readUInt16Le(data: ByteArray, offset: Int): Int {
return (data[offset].toInt() and 0xff) or ((data[offset + 1].toInt() and 0xff) shl 8)
}
private fun readUIntLe(data: ByteArray, offset: Int, width: Int): Int {
var value = 0
for (i in 0 until width) {
value = value or ((data[offset + i].toInt() and 0xff) shl (8 * i))
}
return value
}
private fun safeRange(data: ByteArray?, from: Int, to: Int): ByteArray {
if (data == null || from >= data.size) {
return EMPTY
}
return data.copyOfRange(from, minOf(to, data.size))
}
}
// ------------------------------------------------------------------
// Fragment reassembly
// ------------------------------------------------------------------
/**
* Feeds raw ATT notification values in and produces complete frames,
* rejoining fragmented ones.
*
* Fragmentation (spec §2.3): when a frame exceeds the 244-byte ATT
* ceiling the ring sets FLAG=0x01, sends the first 244 bytes, and later
* sends a continuation frame in a different, headerless shape — FLAG(1),
* CRC32(4), then the remaining bytes verbatim.
*
* Two things the spec document does not say, both measured from the
* reference capture and both load-bearing here:
* - **The continuation is not adjacent.** In one of the six captured
* fragmentations three unrelated complete frames arrive between the
* first fragment and its continuation, so a "next value is the rest"
* rule mis-joins. Complete frames are therefore still parsed normally
* while a fragment is outstanding.
* - **The continuation's own CRC field is not reliably the reassembled
* CRC.** It matched in five of six cases and differed in the sixth
* (whose join is nonetheless byte-exact and CRC-valid), so the
* continuation must not be matched by comparing CRC fields.
*
* What is reliable, in all six cases, is length: a continuation carries
* exactly `CONTINUATION_PREFIX_LEN + bytesStillNeeded` bytes and does
* not itself look like a header. The reassembled frame's CRC is the real
* validator and is always checked.
*/
class Reassembler {
private companion object {
/**
* Give up on an outstanding fragment after this many intervening
* complete frames. The observed worst case is 3; this is slack, not a
* measured bound.
*/
const val MAX_INTERLEAVED_FRAMES = 16
}
private var pending: ByteArray? = null
private var pendingTotal = 0
private var interleaved = 0
fun hasPending(): Boolean = pending != null
fun reset() {
pending = null
pendingTotal = 0
interleaved = 0
}
/**
* Offer one ATT notification value. The result says whether the value
* belonged to this protocol at all (so the caller can fall through to
* the gesture decoder) and carries a frame once one is complete.
*/
fun accept(value: ByteArray?): Intake {
if (value == null || value.isEmpty()) {
return Intake.ignored()
}
val held = pending
if (held != null) {
val needed = pendingTotal - held.size
if (value.size == CONTINUATION_PREFIX_LEN + needed && !looksLikeHeader(value)) {
val joined = ByteArray(pendingTotal)
held.copyInto(joined, 0)
value.copyInto(joined, held.size, CONTINUATION_PREFIX_LEN, CONTINUATION_PREFIX_LEN + needed)
reset()
return complete(joined)
}
if (!looksLikeHeader(value)) {
val dropped = pendingTotal
reset()
return Intake.consumed(
"dropped $dropped-byte fragment: continuation was ${value.size} bytes, expected ${CONTINUATION_PREFIX_LEN + needed}")
}
if (++interleaved > MAX_INTERLEAVED_FRAMES) {
val dropped = pendingTotal
reset()
// Fall through and parse this value as a fresh frame.
val result = acceptFresh(value)
return result.withNote("dropped $dropped-byte fragment: continuation never arrived")
}
}
return acceptFresh(value)
}
private fun acceptFresh(value: ByteArray): Intake {
val total = declaredLength(value)
if (total < 0) {
return Intake.ignored()
}
if (value.size >= total) {
return complete(value.copyOf(total))
}
// Only one fragment is ever outstanding in the reference capture,
// but never silently clobber one if that assumption breaks.
val clobbered = if (pending == null) null else "dropped $pendingTotal-byte fragment: a new fragment started"
pending = value.copyOf()
pendingTotal = total
interleaved = 0
return Intake.consumed("fragment start, ${value.size} of $total bytes").withNote(clobbered)
}
private fun complete(raw: ByteArray): Intake {
val frame = parse(raw) ?: return Intake.consumed("malformed frame, " + raw.size + " bytes")
return Intake.frame(frame)
}
}
/** The outcome of offering one ATT value to a [Reassembler]. */
class Intake private constructor(
/** True when the value belonged to this protocol and must not be re-handled. */
@JvmField val consumed: Boolean,
/** Non-null once a complete frame is available. Check [Frame.crcOk]. */
@JvmField val frame: Frame?,
/** Human-readable detail for logging, or null. */
@JvmField val note: String?,
) {
internal companion object {
fun ignored(): Intake = Intake(false, null, null)
fun consumed(note: String?): Intake = Intake(true, null, note)
fun frame(frame: Frame): Intake = Intake(true, frame, null)
}
internal fun withNote(extra: String?): Intake {
if (extra == null) {
return this
}
return Intake(consumed, frame, if (note == null) extra else "$note; $extra")
}
}
/** One complete frame. */
class Frame internal constructor(
@JvmField val flag: Int,
@JvmField val chan: Int,
@JvmField val seq: Int,
@JvmField val kind: Int,
@JvmField val cmdHi: Int,
@JvmField val cmdLo: Int,
/** PLEN - 10 bytes. payload[0:2] is the sender's nonce. */
@JvmField val payload: ByteArray,
@JvmField val raw: ByteArray,
@JvmField val crcOk: Boolean,
) {
fun isHealth(): Boolean = chan == CHAN_HEALTH
fun commandLabel(): String = hex2(cmdHi) + ":" + hex2(cmdLo)
fun describe(): String =
"chan=" + hex2(chan) + " kind=" + hex2(kind) + " cmd=" + commandLabel() + " seq=" + hex2(seq) + " len=" + raw.size
}
class DeviceStatus internal constructor(
@JvmField val battery: Int,
@JvmField val charging: Int,
)
// ------------------------------------------------------------------
// Decoded record types
// ------------------------------------------------------------------
/** Common supertype so one store can hold every decoded page. */
abstract class HealthRecord internal constructor(
@JvmField val cmdHi: Int,
@JvmField val receivedAtMs: Long,
) {
/** The metric name, for logs. */
fun metric(): String = when (cmdHi) {
CMD_HI_HEART_RATE -> "heart_rate"
CMD_HI_SPO2 -> "spo2"
CMD_HI_HRV -> "hrv"
CMD_HI_STEPS -> "steps"
CMD_HI_SLEEP -> "sleep"
else -> "cmd" + hex2(cmdHi)
}
/** A one-line summary safe to put in a log. */
abstract fun summary(): String
}
/** Heart rate, SpO2 or HRV: one page of hourly buckets. */
class HourlyRecord internal constructor(
cmdHi: Int,
receivedAtMs: Long,
/** Day anchor in Unix seconds, or [UNKNOWN_TIME] on a backlog page. */
@JvmField val anchorUnixSeconds: Long,
/** Per-metric "last measured at". See the 4-hour skew note in the spec. */
@JvmField val tagRaw: Long,
/** The metric's latest value. */
@JvmField val current: Int,
/** 1 byte for HR/SpO2, 2 for HRV, as defined by the metric serializer. */
@JvmField val valueWidth: Int,
@JvmField val groups: Array<HourlyGroup>,
) : HealthRecord(cmdHi, receivedAtMs) {
/** True when this page has no anchor, i.e. it is a backlog page. */
fun isBacklog(): Boolean = anchorUnixSeconds == UNKNOWN_TIME
override fun summary(): String =
metric() + " groups=" + groups.size + " width=" + valueWidth + " current=" + current +
" anchor=" + (if (isBacklog()) "backlog(unanchored)" else anchorUnixSeconds.toString()) +
" tag=" + tagRaw
}
/** One hourly bucket. */
class HourlyGroup internal constructor(
/** Raw index as sent. On an anchored page this is hours since the anchor. */
@JvmField val hourIndex: Int,
@JvmField val avg: Int,
@JvmField val max: Int,
@JvmField val min: Int,
/**
* Absolute Unix seconds for this bucket, or [UNKNOWN_TIME] on a
* backlog page — where the base is UNSOLVED and deliberately not guessed.
*/
@JvmField val unixSeconds: Long,
)
/** One page of activity buckets. */
class StepsRecord internal constructor(
receivedAtMs: Long,
@JvmField val anchorUnixSeconds: Long,
@JvmField val buckets: Array<StepsBucket>,
) : HealthRecord(CMD_HI_STEPS, receivedAtMs) {
fun totalSteps(): Int = buckets.sumOf { it.steps }
override fun summary(): String =
"steps buckets=" + buckets.size + " total=" + totalSteps() +
" anchor=" + (if (anchorUnixSeconds == UNKNOWN_TIME) "none" else anchorUnixSeconds.toString())
}
/**
* One activity bucket.
*
* **UNSOLVED:** [index] does not map to a known wall-clock
* time. It runs 0-7, 10, 11, 13-34 and then jumps to 130+, and no bucket
* width at any base reproduces the app's own per-bucket distribution — even
* though the steps total across all buckets is exactly right. The raw index
* is stored as sent; no time-of-day mapping is invented.
*/
class StepsBucket internal constructor(
@JvmField val index: Int,
/** Confirmed: summed over a page this equals the app's daily step total. */
@JvmField val steps: Int,
/** UNCONFIRMED: calorie-shaped (v3 - v2 tracks per-bucket resting kcal). */
@JvmField val calorieLike2: Int,
/** UNCONFIRMED: calorie-shaped. */
@JvmField val calorieLike3: Int,
)
/**
* One sleep session.
*
* **[startTs] and [endTs] are ring-relative seconds, not Unix time.**
* Even's own app gets this wrong and stamps live-pushed sessions with
* timestamps in 1979. Do not feed them to a date formatter.
*
* **UNSOLVED:** [unknownPrefix] (6 bytes) and [unknownTag] (u32) are not
* decoded; one of them probably carries the session date, which would
* remove the anchoring problem. They are stored raw rather than interpreted.
*/
class SleepRecord internal constructor(
receivedAtMs: Long,
/** 1 = a real record, 2 = the empty / end-of-list marker. */
@JvmField val recordState: Int,
/** UNSOLVED per-record 6-byte field (payload[3:9]). Stored raw. */
@JvmField val unknownPrefix: ByteArray,
/** UNSOLVED u32 tag (payload[9:13]). Stored raw. */
@JvmField val unknownTag: Long,
/** Ring-relative seconds, NOT Unix. */
@JvmField val startTs: Long,
/** Ring-relative seconds, NOT Unix. */
@JvmField val endTs: Long,
@JvmField val totalTime: Int,
@JvmField val wakeTime: Int,
@JvmField val remTime: Int,
@JvmField val lightTime: Int,
@JvmField val deepTime: Int,
/**
* The stage series. Stage ids are the same 0-3 encoding the app's own
* export uses, but which id means wake/rem/light/deep is NOT stated by
* the spec and is deliberately not guessed here — see
* [halfMinutesForStage].
*/
@JvmField val segments: Array<SleepSegment>,
) : HealthRecord(CMD_HI_SLEEP, receivedAtMs) {
fun isRealRecord(): Boolean = recordState == 1
fun totalHalfMinutes(): Int = segments.sumOf { it.halfMinutes }
fun halfMinutesForStage(stage: Int): Int = segments.filter { it.stage == stage }.sumOf { it.halfMinutes }
/**
* The two whole-record arithmetic identities from the spec, which held
* exactly for all ten real records in the reference capture. A false
* result means the body was mis-parsed.
*/
fun identitiesHold(): Boolean {
if (!isRealRecord()) {
return true
}
val seconds = totalHalfMinutes() * 30
return seconds == totalTime + wakeTime && seconds == (endTs - startTs).toInt()
}
override fun summary(): String {
if (!isRealRecord()) {
return "sleep marker state=$recordState"
}
return "sleep segments=" + segments.size + " total=" + totalTime + "s wake=" + wakeTime +
" rem=" + remTime + " light=" + lightTime + " deep=" + deepTime +
" relStart=" + startTs + " relEnd=" + endTs + " identities=" + identitiesHold()
}
}
/** One stage run: a stage id and a duration in half-minutes (30 s units). */
class SleepSegment internal constructor(
@JvmField val stage: Int,
@JvmField val halfMinutes: Int,
)
}
@@ -0,0 +1,78 @@
package com.faceclaw.app
import kotlin.jvm.JvmOverloads
/** The delta base contains only app pixels. Shell resources are composed at presentation. */
class ScenePlanner(private val cache: ResourceCacheState) {
class Plan(val commands: List<ByteArray>, val nextFid: Int)
private val owned = HashMap<String, CachedResource>()
private val pixels = HashMap<String, ByteArray>()
private var previous: ByteArray? = null
private var screenWidth = 0
private var screenHeight = 0
private var epoch = -1
private var root = -1
@JvmOverloads
fun plan(screen: ByteArray, width: Int, height: Int, draws: Array<SurfaceCompositor.ScreenDraw>?, scene: ShellScene, firstId: Int, textures: Boolean = true, incremental: Boolean = true, multiRect: Boolean = true, maxRects: Int = 6): Plan {
require(width in 1..640 && height in 1..480)
if (epoch != cache.generation) { previous = null; pixels.clear(); root = -1; epoch = cache.generation }
require(screen.size == ((width + 1) / 2) * height)
if (width != screenWidth || height != screenHeight) previous = null
screenWidth = width; screenHeight = height
val commands = ArrayList<ByteArray>()
val keys = scene.layers.map { "shell:${it.key}:${it.width}x${it.height}" }
val surfaces = scene.layers.mapIndexed { i, layer -> owned.getOrPut(keys[i]) {
CachedResource(DrawProtocol.rawImage(layer.width, layer.height), keys[i])
} }
owned.keys.retainAll(keys.toSet()); pixels.keys.retainAll(keys.toSet())
val selectedResources = scene.retainedResources
cache.pin(surfaces + selectedResources)
val absent = surfaces.map { cache.resourceId(it) < 0 }
val prepared = cache.prepare(surfaces + selectedResources)
val ids = prepared.copyOfRange(0, surfaces.size)
val selectedIds = prepared.copyOfRange(surfaces.size, prepared.size)
check(prepared.all { it >= 0 }) { "Shell surfaces exceed the resource budget" }
commands.addAll(cache.drainCommands(3600))
val rootCalls = scene.calls(width, height, ids, selectedIds)
for ((i, layer) in scene.layers.withIndex()) {
val old = if (absent[i]) null else pixels[keys[i]]
commands.addAll(DrawProtocol.messages(pixelCalls(old, layer.packed, layer.width, layer.height, ids[i])))
pixels[keys[i]] = layer.packed
}
val base = if (incremental) previous else null
val texture = if (textures) TexturePlanner.plan(base, screen, width, height, draws, cache, firstId, multiRect, maxRects) else null
if (texture != null) {
commands.addAll(texture.resourceCommands)
commands.addAll(DrawProtocol.messages(DrawProtocol.fromOptimized(texture.payload, width, height)))
} else commands.addAll(DrawProtocol.messages(pixelCalls(base, screen, width, height, null)))
val list = CachedResource(DrawProtocol.displayList(rootCalls))
val rootId = cache.prepare(listOf(list))[0]
check(rootId >= 0) { "No space for root display list" }
commands.addAll(cache.drainCommands(3600))
cache.pin(surfaces + selectedResources + list)
val evicted = commands.any { it[0].toInt() == ResourceCacheState.EVICT_MODE }
if (evicted) commands.add(0, DrawProtocol.root(DrawProtocol.SCREEN))
if (root != rootId || evicted) commands.add(DrawProtocol.root(rootId))
commands.add(byteArrayOf(DrawProtocol.PRESENT.toByte()))
root = rootId; previous = screen.copyOf()
return Plan(commands, texture?.nextFid ?: firstId)
}
private fun pixelCalls(old: ByteArray?, next: ByteArray, width: Int, height: Int, target: Int?): List<ByteArray> {
val stride = (width + 1) / 2
if (old != null && old.contentEquals(next)) return emptyList()
val calls = ArrayList<ByteArray>()
for (top in 0 until height step 32) {
val rows = minOf(32, height - top)
if (old != null && (top * stride until (top + rows) * stride).all { old[it] == next[it] }) continue
var left = width; var right = -1
for (y in top until top + rows) for (x in 0 until width) {
val p = y * stride + x / 2; val shift = if (x % 2 == 0) 4 else 0
if (old == null || (((old[p].toInt() xor next[p].toInt()) ushr shift) and 15) != 0) { left = minOf(left, x); right = maxOf(right, x) }
}
if (right < left) continue
if (width % 4 == 0 && rows % 2 == 0) { left = left / 4 * 4; right = minOf(width, ((right + 4) / 4) * 4) - 1 }
calls.add(DrawProtocol.bbox(next, stride, left, top, right - left + 1, rows, target))
}
return calls
}
}
@@ -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,961 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
import kotlin.jvm.JvmOverloads
import kotlin.jvm.JvmStatic
/**
* Plans a screen update that ships text and icons as on-glasses cached draws instead of pixels (CFW
* modes 19/20/21/22; see g2flash/patches/zlib_glue.c and resource_cache.c).
*
* Approach: dirty rects come from comparing the fully composited old and new frames, exactly as the
* plain incremental path does. For each deferred draw (glyph or image) whose pixels intersect a
* sent rect, check that every pixel the on-glasses draw would write lands correct — i.e. the new
* composite's 4bpp value at each in-panel nonzero-source pixel equals what the draw produces (this
* one check subsumes plane occlusion, surface occlusion/clipping, and draw-on-draw overlap). A draw
* that passes and is (or can be made) resident in the resource cache is replayed on-glasses: its
* written pixels are punched to 0 in the delta rect content — which is what makes text and icons
* nearly free to compress — and re-emitted as a mode-20 string or mode-19 image sub-message in the
* same atomic mode-8 batch, so the shadow after apply equals the full composite exactly. Everything
* else stays baked.
*
* Fallback shape: when nothing qualifies, plan() returns null and the caller uses the plain
* single-bbox/multi-rect/full-frame paths unchanged.
*/
class TexturePlanner {
companion object {
/** Cap on mode-20 string sub-messages (mode-8 count is a u8). */
private const val MAX_GLYPH_RUNS: Int = 180
/**
* Soft cap on cached-glyph selection per update, before run grouping. Sized above a
* full-screen 6x12 terminal repaint (~4,240 cells) so dense screens draw everything; the
* run budget is the real bound.
*/
private const val MAX_SELECTED_GLYPHS: Int = 4600
/** Cap on mode-19 image sub-messages per update. */
private const val MAX_IMAGE_DRAWS: Int = 60
/** Cap on mode-15 builtin-font string sub-messages per update. */
private const val MAX_FWTEXT_RUNS: Int = 80
/** Resource command payload size that fits one BLE image message comfortably. */
private const val UPLOAD_PAYLOAD_MAX: Int = 3600
/** Max x-adjust control bytes between two glyphs before starting a new run. */
private const val MAX_ADJUST_BYTES: Int = 4
/** Options: identity LUT (top 15) + transparent, for mode-19 image draws. */
private const val IMAGE_DRAW_OPTIONS: Int = CFW_TEXTURE_OPT_BRIGHTNESS_MASK or CFW_TEXTURE_OPT_TRANSPARENT
/**
* Plan a cached-draw update. previous is the delta base (the frame the shadow currently
* holds), or null/mismatched for a full-frame keyframe. Returns null when the plain paths
* should run instead (no replayable draws, or identical frames).
*/
@JvmStatic
@JvmOverloads
fun plan(
previous: ByteArray?,
next: ByteArray?,
width: Int,
height: Int,
draws: Array<SurfaceCompositor.ScreenDraw>?,
cache: ResourceCacheState,
fidStart: Int,
allowMultiRect: Boolean,
maxRects: Int,
platform: ProtocolPlatform = protocolPlatform(),
): Result? {
if (
(((((next == null) || (draws == null)) || (draws.size == 0)) || (width <= 0)) ||
(height <= 0))
) {
return null
}
var stride: Int = ((width + 1) shr 1)
if ((next.size != (stride * height))) {
return null
}
var planStartedAtMs: Long = platform.elapsedRealtimeMs()
var fullFrame: Boolean = ((previous == null) || (previous.size != next.size))
var rects: MutableList<IntArray>
if (!fullFrame) {
var box: IntArray? =
BleImageOptimizer.computeChangedBox(previous, next, width, height)
if ((box == null)) {
return null
}
if (((box[2] >= width) && (box[3] >= height))) {
fullFrame = true
rects = mutableListOf(intArrayOf(0, 0, width, height))
} else {
var split: MutableList<IntArray>? =
(if (allowMultiRect)
BleImageOptimizer.computeChangedRects(
previous,
next,
width,
height,
maxRects,
)
else null)
rects = (if ((split != null)) split else mutableListOf(box))
}
} else {
rects = mutableListOf(intArrayOf(0, 0, width, height))
}
var matchStartedAtMs: Long = platform.elapsedRealtimeMs()
var selected: MutableList<Selected> = ArrayList()
var bakedCandidates: Int = 0
var selectedImages: Int = 0
var fwSubs: MutableList<ByteArray> = ArrayList()
var fwPunches: MutableList<FwPunch> = ArrayList()
var fwGlyphCount: Int = 0
var fwBaked: Int = 0
for (draw in draws) {
if ((draw.kind != SurfaceCompositor.ScreenDraw.KIND_FWTEXT)) {
continue
}
fwBaked += planFwRun(draw, rects, next, stride, width, height, fwSubs, fwPunches)
}
fwGlyphCount = fwPunches.size
bakedCandidates += fwBaked
for (draw in draws) {
if ((draw.kind == SurfaceCompositor.ScreenDraw.KIND_GLYPH)) {
var atlas: GlyphAtlas.Glyph? = GlyphAtlas.get(draw.fontId, draw.encoding)
if ((atlas == null)) {
continue
}
var gx: Int = (draw.x + atlas.bbxX)
var inkTop: Int = (draw.y + atlas.inkTop)
if (!intersectsAny(rects, gx, inkTop, atlas.width, atlas.inkHeight)) {
continue
}
if (
((((((draw.encoding < 32) || (draw.encoding > 127)) || (gx < 0)) ||
(draw.y < 0)) || (gx > 0xffff)) || (draw.y > 0xffff))
) {
bakedCandidates++
continue
}
var top: Int = BmpUtil.nibbleForGray(draw.value)
if (
!glyphMatchesComposite(next, stride, width, height, atlas, gx, draw.y, top)
) {
bakedCandidates++
continue
}
if ((selected.size >= MAX_SELECTED_GLYPHS)) {
bakedCandidates++
continue
}
selected.add(Selected(draw, atlas, null, gx, top))
} else {
var atlas: ImageAtlas.Entry? = ImageAtlas.get(draw.imageId)
if ((atlas == null)) {
continue
}
if (!intersectsAny(rects, draw.x, draw.y, atlas.width, atlas.height)) {
continue
}
if (
(((((draw.x < 0) || (draw.y < 0)) || (draw.x > 0xffff)) ||
(draw.y > 0xffff)) || (selectedImages >= MAX_IMAGE_DRAWS))
) {
bakedCandidates++
continue
}
if (
!imageMatchesComposite(next, stride, width, height, atlas, draw.x, draw.y)
) {
bakedCandidates++
continue
}
selected.add(Selected(draw, null, atlas, draw.x, 0))
selectedImages++
}
}
if ((selected.isEmpty() && fwSubs.isEmpty())) {
return null
}
val rollback = cache.checkpoint()
var cacheStartedAtMs: Long = platform.elapsedRealtimeMs()
var drawable: MutableList<Selected> =
(if (selected.isEmpty()) mutableListOf() else ensureResident(cache, selected))
bakedCandidates += (selected.size - drawable.size)
var glyphDrawable: MutableList<Selected> = ArrayList()
var imageDrawable: MutableList<Selected> = ArrayList()
for (sel in drawable) {
if ((sel.glyphAtlas != null)) {
glyphDrawable.add(sel)
} else {
imageDrawable.add(sel)
}
}
var runs: MutableList<ByteArray> = ArrayList()
var drawnGlyphs: MutableList<Selected> = buildRuns(glyphDrawable, runs)
bakedCandidates += (glyphDrawable.size - drawnGlyphs.size)
var drawn: MutableList<Selected> = ArrayList(drawnGlyphs)
drawn.addAll(imageDrawable)
if (
((drawn.isEmpty() && fwSubs.isEmpty()) ||
((((rects.size + runs.size) + imageDrawable.size) + fwSubs.size) > 255))
) {
if (!selected.isEmpty()) {
rollback()
}
return null
}
var punchStartedAtMs: Long = platform.elapsedRealtimeMs()
var punched: ByteArray = next.copyOf()
for (sel in drawn) {
punch(punched, stride, width, height, sel)
}
for (fw in fwPunches) {
punchFw(punched, stride, width, height, fw)
}
var encodeStartedAtMs: Long = platform.elapsedRealtimeMs()
var subs: MutableList<ByteArray> = ArrayList()
var fid: Int = fidStart
if (fullFrame) {
subs.add(BleImageOptimizer.maybeCompress(punched, width, height))
} else {
for (r in rects) {
subs.add(
BleImageOptimizer.encodeMode3Rect(
punched,
stride,
r[0],
r[1],
r[2],
r[3],
fid,
)
)
fid = (if ((fid >= 0xfffe)) 1 else (fid + 1))
}
}
for (sel in imageDrawable) {
subs.add(encodeImageDraw(sel))
}
subs.addAll(runs)
subs.addAll(fwSubs)
var payload: ByteArray = assembleMode8(subs)
if (payload.size > CfwTransport.MAX_MESSAGE - 16) {
rollback()
return null
}
val resourceCommands = cache.drainCommands(UPLOAD_PAYLOAD_MAX)
val uploadBytes = resourceCommands.sumOf { it.size }
var result: Result =
Result(
payload,
resourceCommands,
fid,
rects.size,
drawnGlyphs.size,
runs.size,
imageDrawable.size,
fwGlyphCount,
fwSubs.size,
bakedCandidates,
uploadBytes,
fullFrame,
)
var doneAtMs: Long = platform.elapsedRealtimeMs()
result.rectsMs = ((matchStartedAtMs - planStartedAtMs)).toInt()
result.matchMs = ((cacheStartedAtMs - matchStartedAtMs)).toInt()
result.cacheMs = ((punchStartedAtMs - cacheStartedAtMs)).toInt()
result.punchMs = ((encodeStartedAtMs - punchStartedAtMs)).toInt()
result.encodeMs = ((doneAtMs - encodeStartedAtMs)).toInt()
return result
}
/**
* Plan one firmware-font run (mode 15): classify every member, and when any correct ink
* member intersects a sent rect, emit sub-messages over the maximal correct stretches. A
* stretch never spans an incorrect member — the sub-message boundary restarts the
* firmware's advance walk at an explicit pen x, so occluded or unknown glyphs simply stay
* baked without disturbing their neighbors' positions. Emitted ink members are queued for
* punching. Returns how many ink members stay baked.
*/
private fun planFwRun(
draw: SurfaceCompositor.ScreenDraw,
rects: MutableList<IntArray>,
next: ByteArray,
stride: Int,
width: Int,
height: Int,
outSubs: MutableList<ByteArray>,
outPunches: MutableList<FwPunch>,
): Int {
var n: Int = draw.fwCps!!.size
if ((((n == 0) || (draw.y < 0)) || (draw.y > 0xffff))) {
return countInk(draw)
}
var top: Int = BmpUtil.nibbleForGray(draw.value)
var ok: BooleanArray = BooleanArray(n)
var entries: Array<FwGlyphAtlas.Entry?> = arrayOfNulls<FwGlyphAtlas.Entry>(n)
var relevant: Boolean = false
var baked: Int = 0
run {
var i: Int = 0
while ((i < n)) {
if (!draw.fwInk!![i]) {
ok[i] = true
i++
continue
}
var entry: FwGlyphAtlas.Entry? = FwGlyphAtlas.get(draw.fwCps!![i])
if ((entry == null)) {
baked++
i++
continue
}
var gx: Int = ((draw.x + draw.fwDx!![i]) + entry.ofsX)
var gy: Int = (draw.y + entry.inkTop)
if (!fwGlyphMatchesComposite(next, stride, width, height, entry, gx, gy, top)) {
baked++
i++
continue
}
ok[i] = true
entries[i] = entry
if (intersectsAny(rects, gx, gy, entry.boxW, entry.boxH)) {
relevant = true
}
i++
}
}
if (!relevant) {
return 0
}
var i: Int = 0
while (((i < n) && (outSubs.size < MAX_FWTEXT_RUNS))) {
while (((i < n) && !(ok[i] && draw.fwInk!![i]))) {
i++
}
if ((i >= n)) {
break
}
var startX: Int = (draw.x + draw.fwDx!![i])
if (((startX < 0) || (startX > 0xffff))) {
baked++
i++
continue
}
var j: Int = i
var lastInk: Int = -1
var bytesToLastInk: Int = 0
var bytesSoFar: Int = 0
while (((j < n) && ok[j])) {
var encodedLength: Int = utf8Length(draw.fwCps!![j])
if (((bytesSoFar + encodedLength) > 255)) {
break
}
bytesSoFar += encodedLength
if (draw.fwInk!![j]) {
lastInk = j
bytesToLastInk = bytesSoFar
}
j++
}
if ((lastInk < i)) {
baked++
i++
continue
}
var sub: ByteArray = ByteArray((7 + bytesToLastInk))
sub[0] = CFW_MSG_STOCK_FONT_STRING.toByte()
sub[1] = ((startX and 0xff)).toByte()
sub[2] = (((startX shr 8) and 0xff)).toByte()
sub[3] = ((draw.y and 0xff)).toByte()
sub[4] = (((draw.y shr 8) and 0xff)).toByte()
sub[5] = ((top or CFW_TEXTURE_OPT_TRANSPARENT)).toByte()
sub[6] = (bytesToLastInk).toByte()
var pos: Int = 7
run {
var k: Int = i
while ((k <= lastInk)) {
var encoded: ByteArray = codePointUtf8(draw.fwCps!![k])
encoded.copyInto(sub, pos, 0, 0 + encoded.size)
pos += encoded.size
k++
}
}
outSubs.add(sub)
run {
var k: Int = i
while ((k <= lastInk)) {
if (draw.fwInk!![k]) {
outPunches.add(
FwPunch(
entries[k]!!,
((draw.x + draw.fwDx!![k]) + entries[k]!!.ofsX),
(draw.y + entries[k]!!.inkTop),
)
)
}
k++
}
}
i = (lastInk + 1)
}
return baked
}
private fun utf8Length(cp: Int): Int {
if ((cp < 0x80)) {
return 1
}
if ((cp < 0x800)) {
return 2
}
if ((cp < 0x10000)) {
return 3
}
return 4
}
private fun countInk(draw: SurfaceCompositor.ScreenDraw): Int {
var count: Int = 0
for (ink in draw.fwInk!!) {
if (ink) {
count++
}
}
return count
}
/**
* Whether every in-panel nonzero pixel of the builtin-font glyph lands correct: the
* composite's 4bpp value must equal the firmware's LUT output src*top/15 (integer division
* — a general LUT check, since these glyphs are anti-aliased).
*/
private fun fwGlyphMatchesComposite(
packed: ByteArray,
stride: Int,
width: Int,
height: Int,
entry: FwGlyphAtlas.Entry,
gx: Int,
gy: Int,
top: Int,
): Boolean {
run {
var row: Int = 0
while ((row < entry.boxH)) {
var y: Int = (gy + row)
if (((y < 0) || (y >= height))) {
row++
continue
}
run {
var col: Int = 0
while ((col < entry.boxW)) {
var source: Int = entry.nibbleAt(col, row)
if ((source == 0)) {
col++
continue
}
var x: Int = (gx + col)
if (((x < 0) || (x >= width))) {
col++
continue
}
if ((nibbleAt(packed, stride, x, y) != ((source * top) / 15))) {
return false
}
col++
}
}
row++
}
}
return true
}
private fun punchFw(
packed: ByteArray,
stride: Int,
width: Int,
height: Int,
fw: FwPunch,
): Unit {
run {
var row: Int = 0
while ((row < fw.entry.boxH)) {
var y: Int = (fw.gy + row)
if (((y < 0) || (y >= height))) {
row++
continue
}
run {
var col: Int = 0
while ((col < fw.entry.boxW)) {
if ((fw.entry.nibbleAt(col, row) == 0)) {
col++
continue
}
punchPixel(packed, stride, width, (fw.gx + col), y)
col++
}
}
row++
}
}
}
private fun intersectsAny(
rects: MutableList<IntArray>,
x: Int,
y: Int,
w: Int,
h: Int,
): Boolean {
if (((w <= 0) || (h <= 0))) {
return false
}
for (r in rects) {
if (
((((x < (r[0] + r[2])) && ((x + w) > r[0])) && (y < (r[1] + r[3]))) &&
((y + h) > r[1]))
) {
return true
}
}
return false
}
/**
* Whether every in-panel ink pixel of the glyph lands correct in the packed new frame: the
* composite's 4bpp value must equal the firmware's LUT output source*top/15 (integer). For
* 1bpp glyphs (source 15) this is exactly `== top`; AA glyphs get the general check. Ink
* outside the panel is clipped by the firmware and irrelevant.
*/
private fun glyphMatchesComposite(
packed: ByteArray,
stride: Int,
width: Int,
height: Int,
atlas: GlyphAtlas.Glyph,
gx: Int,
lineY: Int,
top: Int,
): Boolean {
run {
var row: Int = atlas.inkTop
while ((row < (atlas.inkTop + atlas.inkHeight))) {
var y: Int = (lineY + row)
if (((y < 0) || (y >= height))) {
row++
continue
}
run {
var col: Int = 0
while ((col < atlas.width)) {
var source: Int = atlas.nibbleAt(col, row)
if ((source == 0)) {
col++
continue
}
var x: Int = (gx + col)
if (((x < 0) || (x >= width))) {
col++
continue
}
if ((nibbleAt(packed, stride, x, y) != ((source * top) / 15))) {
return false
}
col++
}
}
row++
}
}
return true
}
/**
* Whether every in-panel nonzero pixel of the cached image equals the packed new frame —
* the mode-19 transparent draw writes exactly those.
*/
private fun imageMatchesComposite(
packed: ByteArray,
stride: Int,
width: Int,
height: Int,
atlas: ImageAtlas.Entry,
left: Int,
top: Int,
): Boolean {
val pixels = atlas.nibbles
val imageWidth = atlas.width
val startX = maxOf(0, left)
val endX = minOf(width, left + imageWidth)
val endY = minOf(height, top + atlas.height)
var y = maxOf(0, top)
while (y < endY) {
var src = (y - top) * imageWidth + startX - left
val dstRow = y * stride
var x = startX
while (x < endX) {
val source = pixels[src++].toInt() and 255
if (source != 0) {
val byte = packed[dstRow + (x ushr 1)].toInt() and 255
val actual = if (x and 1 == 0) byte ushr 4 else byte and 15
if (actual != source) return false
}
x++
}
y++
}
return true
}
private fun nibbleAt(packed: ByteArray, stride: Int, x: Int, y: Int): Int {
var b: Int = (packed[((y * stride) + (x shr 1))] and 0xff)
return (if (((x and 1) != 0)) (b and 0x0f) else (b shr 4))
}
private fun punch(
packed: ByteArray,
stride: Int,
width: Int,
height: Int,
sel: Selected,
): Unit {
if ((sel.glyphAtlas != null)) {
var atlas: GlyphAtlas.Glyph = sel.glyphAtlas
run {
var row: Int = atlas.inkTop
while ((row < (atlas.inkTop + atlas.inkHeight))) {
var y: Int = (sel.draw.y + row)
if (((y < 0) || (y >= height))) {
row++
continue
}
run {
var col: Int = 0
while ((col < atlas.width)) {
if (!atlas.inkAt(col, row)) {
col++
continue
}
punchPixel(packed, stride, width, (sel.gx + col), y)
col++
}
}
row++
}
}
} else {
punchImage(packed, stride, width, height, sel.imageAtlas!!, sel.gx, sel.draw.y)
}
}
/** Clear only visible nonzero image pixels, preserving the neighboring nibble. */
private fun punchImage(
packed: ByteArray,
stride: Int,
width: Int,
height: Int,
atlas: ImageAtlas.Entry,
left: Int,
top: Int,
) {
val pixels = atlas.nibbles
val imageWidth = atlas.width
val startX = maxOf(0, left)
val endX = minOf(width, left + imageWidth)
val endY = minOf(height, top + atlas.height)
var y = maxOf(0, top)
while (y < endY) {
var src = (y - top) * imageWidth + startX - left
val dstRow = y * stride
var x = startX
while (x < endX) {
if (pixels[src++].toInt() != 0) {
val index = dstRow + (x ushr 1)
val mask = if (x and 1 == 0) 15 else 240
packed[index] = (packed[index].toInt() and mask).toByte()
}
x++
}
y++
}
}
private fun punchPixel(packed: ByteArray, stride: Int, width: Int, x: Int, y: Int): Unit {
if (((x < 0) || (x >= width))) {
return
}
var index: Int = ((y * stride) + (x shr 1))
if (((x and 1) != 0)) {
packed[index] = ((packed[index] and 0xf0)).toByte()
} else {
packed[index] = ((packed[index] and 0x0f)).toByte()
}
}
/** Protect every hit before LRU admission so a miss cannot evict this frame's later draws. */
private fun ensureResident(
cache: ResourceCacheState,
selected: MutableList<Selected>,
): MutableList<Selected> {
val fonts = selected.filter { it.glyphAtlas != null }.groupBy { it.draw.fontId }
.mapValues { (id, draws) -> FontResourceAtlas.get(id, draws.map { it.draw.encoding }.toSet()) }
val candidates = selected.filter { it.glyphAtlas == null || it.draw.encoding in fonts.getValue(it.draw.fontId).encodings }
val resources = candidates.map { sel ->
if (sel.glyphAtlas != null) fonts.getValue(sel.draw.fontId).resource else sel.imageAtlas!!.resource
}
val ids = cache.prepare(resources)
return candidates.filterIndexed { index, sel -> sel.resourceId = ids[index]; ids[index] >= 0 }.toMutableList()
}
/** Mode-19 cached-image draw: [19][resourceId u16][x u16][y u16][options u8]. */
@JvmStatic
private fun encodeImageDraw(sel: Selected): ByteArray = byteArrayOf(
CFW_MSG_CACHED_IMAGE.toByte(), sel.resourceId.toByte(), (sel.resourceId ushr 8).toByte(),
sel.draw.x.toByte(), (sel.draw.x ushr 8).toByte(),
sel.draw.y.toByte(), (sel.draw.y ushr 8).toByte(), IMAGE_DRAW_OPTIONS.toByte(),
)
/**
* Group selected glyphs into mode-20 string sub-messages: [20][fontResource u16][x u16][y
* u16][options u8][strlen u8][string] One run per (font, line y, top color) span; within a
* run, control bytes 1..31 adjust x by -10..+20 to hit each glyph's exact position, and
* each glyph advances x by its cached width. Order across runs is free: every drawn glyph's
* ink equals the composite, so overlaps write equal values. Returns the glyphs actually
* emitted (run budget can drop stragglers).
*/
@JvmStatic
private fun buildRuns(
drawable: MutableList<Selected>,
outRuns: MutableList<ByteArray>,
): MutableList<Selected> {
var sorted: MutableList<Selected> = ArrayList(drawable)
sorted.sortWith(
compareBy<Selected> { it.draw.fontId }
.thenBy { it.draw.y }
.thenBy { it.top }
.thenBy { it.gx }
)
var drawn: MutableList<Selected> = ArrayList(sorted.size)
var i: Int = 0
while (((i < sorted.size) && (outRuns.size < MAX_GLYPH_RUNS))) {
var first: Selected = sorted.get(i)
val fontResource = first.resourceId
if ((fontResource < 0)) {
i++
continue
}
var string: ByteSink = ByteSink()
var runGlyphs: MutableList<Selected> = ArrayList()
var cursor: Int = first.gx
var j: Int = i
while ((j < sorted.size)) {
var sel: Selected = sorted.get(j)
if (
(((sel.draw.fontId != first.draw.fontId) || (sel.draw.y != first.draw.y)) ||
(sel.top != first.top))
) {
break
}
var delta: Int = (sel.gx - cursor)
var adjustBytes: Int = adjustByteCount(delta)
if (((adjustBytes > MAX_ADJUST_BYTES) && (j > i))) {
break
}
if ((((string.size() + adjustBytes) + 1) > 255)) {
break
}
emitAdjust(string, delta)
string.write(sel.draw.encoding)
runGlyphs.add(sel)
cursor = (sel.gx + sel.glyphAtlas!!.width)
j++
}
if (!runGlyphs.isEmpty()) {
var stringBytes: ByteArray = string.toByteArray()
val run = ByteArray(9 + stringBytes.size)
run[0] = CFW_MSG_CACHED_TEXT.toByte()
run[1] = fontResource.toByte()
run[2] = (fontResource ushr 8).toByte()
run[3] = first.gx.toByte()
run[4] = (first.gx ushr 8).toByte()
run[5] = first.draw.y.toByte()
run[6] = (first.draw.y ushr 8).toByte()
run[7] = (first.top or CFW_TEXTURE_OPT_TRANSPARENT).toByte()
run[8] = stringBytes.size.toByte()
stringBytes.copyInto(run, 9)
outRuns.add(run)
drawn.addAll(runGlyphs)
i = j
} else {
i++
}
}
return drawn
}
/** How many 1..31 control bytes are needed to move the cursor by delta. */
internal fun adjustByteCount(delta: Int): Int {
if ((delta == 0)) {
return 0
}
return (if ((delta > 0)) ((delta + 19) / 20) else ((-delta + 9) / 10))
}
internal fun emitAdjust(out: ByteSink, delta: Int): Unit {
var delta = delta
while ((delta != 0)) {
var step: Int = (if ((delta > 0)) minOf(delta, 20) else maxOf(delta, -10))
out.write((step + 11))
delta -= step
}
}
/** [8][count]([len u16][sub])* — one atomic present for deltas + draws. */
private fun assembleMode8(subs: MutableList<ByteArray>): ByteArray {
var total: Int = 2
for (sub in subs) {
total += (2 + sub.size)
}
var out: ByteArray = ByteArray(total)
out[0] = CFW_MSG_MULTI_SEGMENT.toByte()
out[1] = (subs.size).toByte()
var pos: Int = 2
for (sub in subs) {
out[pos] = ((sub.size and 0xff)).toByte()
out[(pos + 1)] = (((sub.size shr 8) and 0xff)).toByte()
pos += 2
sub.copyInto(out, pos, 0, 0 + sub.size)
pos += sub.size
}
return out
}
}
constructor() {}
class Result {
/** Complete image payload: a mode-8 batch of rect deltas + cached draws. */
@JvmField val payload: ByteArray
/** Mode-22 evictions and mode-21 uploads to enqueue BEFORE the image message. */
@JvmField val resourceCommands: MutableList<ByteArray>
/** Next mode-3 frame id (deltas consumed some). */
@JvmField val nextFid: Int
@JvmField val rectCount: Int
@JvmField val drawnGlyphs: Int
@JvmField val runCount: Int
@JvmField val drawnImages: Int
@JvmField val fwGlyphs: Int
@JvmField val fwRuns: Int
@JvmField val bakedCandidates: Int
@JvmField val uploadBytes: Int
@JvmField val fullFrame: Boolean
/**
* Where the planning time went, in ms. This runs on the send thread, directly in the
* input-to-display path, so the split is reported in the frame log: rects = finding the
* changed region, match = checking each draw against the composite, cache =
* residency/uploads plus run building, punch = clearing replayed draws out of a copy of the
* frame, encode = compressing the leftover pixels.
*/
@JvmField var rectsMs: Int = 0
@JvmField var matchMs: Int = 0
@JvmField var cacheMs: Int = 0
@JvmField var punchMs: Int = 0
@JvmField var encodeMs: Int = 0
constructor(
payload: ByteArray,
resourceCommands: MutableList<ByteArray>,
nextFid: Int,
rectCount: Int,
drawnGlyphs: Int,
runCount: Int,
drawnImages: Int,
fwGlyphs: Int,
fwRuns: Int,
bakedCandidates: Int,
uploadBytes: Int,
fullFrame: Boolean,
) {
this.payload = payload
this.resourceCommands = resourceCommands
this.nextFid = nextFid
this.rectCount = rectCount
this.drawnGlyphs = drawnGlyphs
this.runCount = runCount
this.drawnImages = drawnImages
this.fwGlyphs = fwGlyphs
this.fwRuns = fwRuns
this.bakedCandidates = bakedCandidates
this.uploadBytes = uploadBytes
this.fullFrame = fullFrame
}
}
/** One draw selected for on-glasses replay. */
private class Selected {
var resourceId: Int = -1
@JvmField val draw: SurfaceCompositor.ScreenDraw
@JvmField val glyphAtlas: GlyphAtlas.Glyph?
@JvmField val imageAtlas: ImageAtlas.Entry?
@JvmField val gx: Int
@JvmField val top: Int
constructor(
draw: SurfaceCompositor.ScreenDraw,
glyphAtlas: GlyphAtlas.Glyph?,
imageAtlas: ImageAtlas.Entry?,
gx: Int,
top: Int,
) {
this.draw = draw
this.glyphAtlas = glyphAtlas
this.imageAtlas = imageAtlas
this.gx = gx
this.top = top
}
}
/** One punch task for an emitted firmware-font glyph. */
private class FwPunch {
@JvmField val entry: FwGlyphAtlas.Entry
@JvmField val gx: Int
@JvmField val gy: Int
constructor(entry: FwGlyphAtlas.Entry, gx: Int, gy: Int) {
this.entry = entry
this.gx = gx
this.gy = gy
}
}
}
@@ -0,0 +1,42 @@
package com.faceclaw.app
/** These functions run under the session monitor. Config survives reconnection;
* queued state and sensor freshness do not. Private commands are ordered with
* frames, so wake starts on the intended PRESENT, never on an older black frame. */
internal fun GlassesSessionCore.enqueueBrightnessLocked(frameVisible: Boolean? = null) {
if (!customFirmwareDetected || !sessionReady || !fixedLayoutCreated || shutdownRequested) return
val visible = frameVisible ?: brightnessSentVisible ?: return
val target = brightnessPolicy.target
if (brightnessSentLevel == target && brightnessSentVisible == visible) return
if (frameVisible == null && hasPendingImageLocked()) return
if (frameVisible == null && hasPendingOrInflightKindLocked("brightness-output")) return
val duration = if (brightnessSentVisible != visible) brightnessPolicy.fadeMs
else if (brightnessPolicy.automatic) 1200 else 120
val payload = byteArrayOf(CFW_MSG_BRIGHTNESS.toByte(), 1, target.toByte(),
(if (visible) 1 else 0).toByte(), duration.toByte(), (duration shr 8).toByte())
val message = messageBuilder.customMessage("brightness-output", payload,
"brightness target=$target visible=$visible fade=$duration", -1, connectionOptions.sendImagesToLeft)
message.onTimeout = MessageCallback {
brightnessSentLevel = -1
brightnessSentVisible = null
// Retry with a PRESENT even if the scene did not change during recovery.
lastEnqueuedFingerprint = ""
}
pendingMessages.addLast(message)
brightnessSentLevel = target
brightnessSentVisible = visible
}
internal fun GlassesSessionCore.maintainBrightnessLocked(now: Long) {
if (!customFirmwareDetected || !sessionReady || !fixedLayoutCreated || shutdownRequested) return
// Passive polling owns stock ALS even in manual mode. Slower manual polling
// keeps stock from writing the panel without needlessly streaming samples.
if (now - brightnessAlsStartedAt >= 2000 && !hasPendingOrInflightKindLocked("als-control")) {
val interval = if (brightnessDemoPolling) 250 else if (brightnessPolicy.automatic) 500 else 5000
val payload = byteArrayOf(CFW_MSG_AMBIENT_LIGHT.toByte(), 1, 1,
interval.toByte(), (interval shr 8).toByte(), 0, 0, 0xe8.toByte(), 3)
enqueueAmbientLightControlLocked(payload, "brightness passive ALS", false)
brightnessAlsStartedAt = now
}
enqueueBrightnessLocked()
}
@@ -0,0 +1,700 @@
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
directRingBattery = -1
directRingCharging = -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) {
// A missing glasses-side report must not erase a verified direct
// reading. Fall back to the glasses cache when the direct link drops.
val useDirect = ringConnected && directRingBattery >= 0
val reportedRingBattery = if (useDirect) directRingBattery else ringBattery
val reportedRingCharging = if (useDirect) directRingCharging else 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,746 @@
package com.faceclaw.app
/**
* The direct R1 ring link: its dedicated worker, the health-data protocol
* (RingProtocol) branch of the notification path, and the response-driven
* health pull. Extension functions on [GlassesSessionCore] like the sibling
* GlassesSessionSend.kt / GlassesSessionControls.kt; the state lives in the
* core's class body.
*/
/**
* Cap on decoded ring health pages held in memory. A full backlog sync is
* ~40 pages, so this holds several syncs; oldest is dropped first. This is a
* holding area until TypeScript ingests the records, not storage.
*/
private const val RING_HEALTH_MAX_RECORDS = 256
/**
* Floor between health pulls, independent of how often the ring
* reconnects. Heart rate/HRV/SpO2 update hourly at the source and steps
* every 10 minutes (confirmed from the real export,
* `knowledge/inbox/Even_health_data/`).
*
* **Reduced 30min -> 5min on 2026-09-12, and its JOB CHANGED.** The
* 30-minute figure was always meant as a CADENCE - how often to collect -
* but it was implemented here as a floor, which is a different thing. The
* result was that a connected, stable ring pulled *never*: nothing
* drives a pull on a timer, only `onRingReady()` on reconnect, so the
* floor was the only clock in the system and it gated a pull that had
* nothing to trigger it.
*
* The cadence now lives where it belongs, on a wall-clock-aligned tick
* (:01 and :31) in `health-live.ts`. What remains here is purely an
* ANTI-SPAM floor: stop a burst of reconnects turning into a burst of
* requests against the race documented on [requestRingHealth].
* That job needs 5 minutes, not 30.
*/
private const val RING_HEALTH_MIN_PULL_INTERVAL_MS = 5L * 60L * 1000L
/**
* Floor for a pull the user actually asked for by opening the health app,
* as opposed to the automatic one above.
*
* Deliberately much shorter than the automatic interval but **not
* zero**. An automatic pull is speculative — nobody is waiting for it, so
* there is no reason to spend a request. Opening the health app is the
* opposite: it is an explicit ask, and the response-driven
* [requestRingHealth] waits for each type's DATA and ACKs its pages before
* advancing, which is what made the backlog-discard race survivable in the
* first place. A floor still has to exist, because the discard risk
* documented on `requestRingHealth()` is real and open/close/open would
* otherwise hammer the ring.
*/
private const val RING_HEALTH_ON_DEMAND_MIN_INTERVAL_MS = 60L * 1000L
/**
* How many times a pull that ABORTED may be resumed inside the anti-spam
* floor before it goes back to waiting that floor out.
*
* The floor exists to stop SPECULATIVE repeat pulls, because a request
* that loses its race can permanently consume backlog - see
* [requestRingHealth]. Resuming a pull that never got a single answer is a
* different thing: nothing was ever in flight to be lost.
*
* Measured 2026-09-12: the 09:33 pull got `no RSP` for 0x1, 0x4
* and 0x2 and then died on `write error: IllegalStateException: Not
* connected`. Every attempt after it was refused by the 30-minute floor, so
* the rest of that night's data was simply never requested again - the
* night's second sleep block went with it. The floor was protecting against
* the wrong thing.
*
* Bounded and non-looping on purpose: the budget is spent whether or not
* the retries help, and a pull that completes resets it. Worst case is two
* extra attempts, then silence until the floor expires.
*
* ⚠ UNTESTED, and worth knowing before trusting this: whether an aborted
* pull's data is still on the ring at all, or was discarded when the ring
* RSP'd (it did not RSP here, which is the reason to think it survives).
* Nobody knows. The retry costs little if the data is gone.
*/
private const val RING_HEALTH_ABORTED_RETRY_LIMIT = 2
/**
* Gap before an aborted pull may be resumed. Short, but not zero - a link
* that just failed a write needs time to come back, and a tight loop
* against a dead connection helps nobody.
*/
private const val RING_HEALTH_ABORTED_RETRY_GAP_MS = 60L * 1000L
/**
* Device-channel commands Even's real app fires in the gaps between
* health requests - identity (0x0a), battery (0x01), firmware version
* (0x02), device id (0x0b) - found by extracting the literal wire order
* of a real successful sync (same capture as ringHealthRspTimeoutMs; two
* independent syncs in it agree). Rotated one-per-health-type here rather
* than replicated exactly (Even's real cadence isn't perfectly regular
* either - compare the two syncs in the capture), since which of these,
* if any, is actually load-bearing for the ring answering has never
* been isolated. This is matching cadence, not a confirmed protocol
* requirement.
*/
private val RING_DEVICE_PING_CMD_LO = intArrayOf(0x0a, 0x01, 0x02, 0x0b)
/** The opaque blob Even sends with every device-channel 0x0a request (f8f53d235ac4ceaa073885cc). */
private val RING_IDENTITY_BLOB: ByteArray = "f8f53d235ac4ceaa073885cc".chunked(2).map { it.toInt(16).toByte() }.toByteArray()
/**
* A snapshot of the health buffer together with the watermark identifying
* it.
*
* The two have to come out under ONE lock. Reading the list and the
* count separately would let a page land in between, and the consumer would
* then clear a record nothing had ingested - the exact failure the
* watermark exists to prevent.
*/
class RingHealthBatch internal constructor(
val records: List<RingProtocol.HealthRecord>,
/** Total-ever-added at the instant of the snapshot. */
val watermark: Long,
)
/** Sole owner of blocking ring operations; callbacks only enqueue ACKs. */
internal fun GlassesSessionCore.runRingWorker() {
while (running) {
try {
if (shouldAttemptRingConnect()) tryConnectRing("ring worker")
if (!running) break
flushRingOutbound()
runRequestedRingHealthPull()
resumeAbortedRingHealthPull()
monitor.withLock {
if (running) monitor.awaitMs(100)
}
} catch (t: Throwable) {
if (!running) {
// disconnect() interrupted a blocking wait; nothing to recover.
break
}
logLine("ring worker error: " + GlassesSessionCore.safeMessage(t))
// A ring failure must not tear down the glasses session.
monitor.withLock {
ringConnected = false
ringNotificationsReady = false
ringReconnectAfterMs = now() + ConnectionOptions.RING_RECONNECT_DELAY_MS
}
link.disconnect(ringAddress)
}
}
logLine("ring worker stop")
}
/**
* The R1 health-data protocol branch. Returns true when the value belonged
* to that protocol and must not fall through to the gesture decoder.
*
* Runs on the GATT callback thread, so it only ever queues writes.
*
* Restricted to R1_NOTIFY_CHAR_UUID because that is the notify
* characteristic (ATT handle 0x0017) the reference capture shows this
* protocol on; gesture traffic on the other notify characteristic is left
* strictly alone rather than being offered to the reassembler.
*/
internal fun GlassesSessionCore.handleRingHealthNotification(characteristicUuid: String, data: ByteArray): Boolean {
if (BleProtocol.R1_NOTIFY_CHAR_UUID != characteristicUuid || !host.supportsRingHealth()) {
return false
}
val intake = monitor.withLock { ringReassembler.accept(data) }
if (!intake.consumed) {
return false
}
val arrivalMs = now()
monitor.withLock {
lastIncomingAtMs = arrivalMs
}
if (intake.note != null) {
logLine("ring frame: " + intake.note)
}
val frame = intake.frame
if (frame == null) {
// Genuinely silent by default: the reassembler consumed these
// bytes (e.g. as a fragment awaiting its continuation) without
// yet producing a complete frame, and intake.note was null too.
// This exact blind spot cost real debugging time on 2026-09-10 -
// DATA appeared to simply never arrive, when the actual cause
// (once found, by temporarily logging every raw notification
// unconditionally) was a real handshake gap, not a dropped
// frame here. If DATA ever looks like it's going missing again
// with nothing logged at all, re-add that raw hex dump here
// rather than assuming nothing arrived on the wire.
logLine("ring frame: consumed, no complete frame yet, len=" + data.size)
return true
}
if (!frame.crcOk) {
// Never act on a frame whose CRC failed: the payload offsets below
// are only meaningful for an intact frame.
logLine("ring frame CRC mismatch " + frame.describe())
return true
}
// Keep the original bytes before acknowledging them. Ring firmware
// variants can have layouts we cannot decode yet, and the ring may
// never deliver an acknowledged page again. This private journal also
// lets us diagnose a new device without repeatedly draining its data.
if (!journalRingFrame(frame)) return true
// Route on the CHAN byte, not on the shape of the payload.
if (frame.chan != RingProtocol.CHAN_HEALTH) {
val status = RingProtocol.decodeDeviceStatus(frame)
if (status != null) {
monitor.withLock {
directRingBattery = status.battery
directRingCharging = status.charging
emitBatteryState(headsetBattery, headsetCharging)
}
logLine("direct ring battery " + status.battery + "% charging=" + status.charging)
}
logDebug("ring device frame " + frame.describe())
return true
}
if (frame.kind == RingProtocol.KIND_RSP) {
logDebug("ring health rsp " + frame.describe())
monitor.withLock {
ringHealthRspSeen = true
monitor.signalAll()
}
return true
}
if (frame.kind != RingProtocol.KIND_DATA) {
logDebug("ring health frame " + frame.describe())
return true
}
var record: RingProtocol.HealthRecord? = null
try {
record = RingProtocol.decode(frame, currentTimeMillis())
} catch (t: Throwable) {
logLine("ring health decode error " + frame.describe() + ": " + GlassesSessionCore.safeMessage(t))
}
if (record == null) {
logLine("ring health page undecoded " + frame.describe())
} else {
monitor.withLock {
if (ringHealthRecords.size >= RING_HEALTH_MAX_RECORDS) {
// This was silent. An eviction here drops a record that
// nothing has ingested yet - real data lost inside the
// phone, with no trace anywhere. Say so. With the consume
// path in place the buffer should never reach this size;
// if this line ever appears, the consumer has stopped.
logLine("ring health: buffer FULL at " + RING_HEALTH_MAX_RECORDS
+ " - dropping the oldest UNINGESTED record")
ringHealthRecords.removeAt(0)
}
ringHealthRecords.add(record)
ringHealthTotalAdded++
}
logLine("ring health " + record.summary())
}
// Acknowledge the page regardless of whether we could decode it: the
// ACK is what keeps the ring sending, and a decode gap must not stall
// the rest of the transfer.
queueRingPageAck(frame)
return true
}
internal fun GlassesSessionCore.queueRingPageAck(page: RingProtocol.Frame) {
monitor.withLock {
if (!ringNotificationsReady) {
return
}
val ack = RingProtocol.buildPageAck(
nextRingSeqLocked(),
nextRingNonceLocked(),
page.cmdHi,
page.cmdLo,
page.seq
)
ringOutbound.addLast(ack)
ringHealthPageCounter++
// Wakes the ring worker, independently of the glasses.
monitor.signalAll()
}
}
internal fun GlassesSessionCore.journalRingFrame(frame: RingProtocol.Frame): Boolean {
return try {
host.appendRingFrameJournal(
"\n{\"receivedAtMs\":" + currentTimeMillis() + ",\"raw\":\"" + GlassesSessionCore.hex(frame.raw) + "\"}\n")
true
} catch (error: Throwable) {
logLine("ring frame persistence failed; page not acknowledged: " + GlassesSessionCore.safeMessage(error))
false
}
}
/**
* The ring's data channel is subscribed: send the device-channel handshake,
* then run a health pull unless the anti-spam floor says one ran recently.
* Ring worker only (blocking).
*/
internal fun GlassesSessionCore.onRingDataChannelReady() {
// The handshake mirrors what Even's own app repeats on every one
// of its sync bursts (confirmed in the reference capture), so
// sending it on every reconnect matches known-working behavior.
// The actual health pull is throttled separately below - see
// ringHealthLastRequestedAtMs and requestRingHealth()'s own
// race-condition warning for why.
sendRingHandshake()
val now = now()
val dueForHealthPull: Boolean
val lastRequestedAtMs: Long
monitor.withLock {
lastRequestedAtMs = ringHealthLastRequestedAtMs
dueForHealthPull = ringHealthPullDueLocked(now)
if (dueForHealthPull) {
ringHealthLastRequestedAtMs = now
}
}
if (dueForHealthPull) {
runRingHealthPull()
} else {
logLine("ring health: pull skipped, last one was " + ((now - lastRequestedAtMs) / 1000) + "s ago")
}
}
/**
* Whether an automatic pull may run now. Caller must hold `monitor`.
*
* Two ways to be due: the ordinary anti-spam floor has expired, or the
* last pull ABORTED and still has retry budget. The second is not a
* speculative repeat - see RING_HEALTH_ABORTED_RETRY_LIMIT.
*/
internal fun GlassesSessionCore.ringHealthPullDueLocked(now: Long): Boolean {
if (ringHealthLastRequestedAtMs == 0L) {
return true
}
val since = now - ringHealthLastRequestedAtMs
if (since >= RING_HEALTH_MIN_PULL_INTERVAL_MS) {
return true
}
return ringHealthAbortedRetries > 0 && since >= RING_HEALTH_ABORTED_RETRY_GAP_MS
}
/**
* Run a pull and account for whether it finished. The ONLY place
* [requestRingHealth] may be called from, so that every path shares one
* definition of "aborted".
*/
internal fun GlassesSessionCore.runRingHealthPull() {
val completed = requestRingHealth()
monitor.withLock {
if (completed) {
ringHealthAbortedRetries = 0
} else if (ringHealthAbortedRetries < RING_HEALTH_ABORTED_RETRY_LIMIT) {
ringHealthAbortedRetries++
logLine("ring health: aborted pull may resume in "
+ (RING_HEALTH_ABORTED_RETRY_GAP_MS / 1000L) + "s (retry "
+ ringHealthAbortedRetries + "/" + RING_HEALTH_ABORTED_RETRY_LIMIT + ")")
} else {
ringHealthAbortedRetries = 0
logLine("ring health: aborted pull retry budget spent, back to the "
+ (RING_HEALTH_MIN_PULL_INTERVAL_MS / 60000L) + "-minute anti-spam floor")
}
}
}
/**
* Ring-worker tick that resumes a pull which ABORTED.
*
* Distinct from [runRequestedRingHealthPull]: nobody asked for this one. It
* exists because the automatic pull otherwise only fires from the ring-ready
* path, so an abort that is not followed by a reconnect would never be
* retried at all.
*/
internal fun GlassesSessionCore.resumeAbortedRingHealthPull() {
val now = now()
monitor.withLock {
if (ringHealthAbortedRetries == 0) {
return
}
if (!ringConnected || !ringNotificationsReady) {
return
}
if (now - ringHealthLastRequestedAtMs < RING_HEALTH_ABORTED_RETRY_GAP_MS) {
return
}
ringHealthLastRequestedAtMs = now
}
logLine("ring health: resuming an aborted pull")
runRingHealthPull()
}
/** Ring-worker side of [GlassesSessionCore.requestRingHealthNow]. */
internal fun GlassesSessionCore.runRequestedRingHealthPull() {
val now = now()
monitor.withLock {
if (!ringHealthPullRequested) {
return
}
ringHealthPullRequested = false
if (!ringConnected || !ringNotificationsReady) {
logLine("ring health: on-demand pull skipped, ring not ready")
return
}
if (ringHealthLastRequestedAtMs != 0L
&& now - ringHealthLastRequestedAtMs < RING_HEALTH_ON_DEMAND_MIN_INTERVAL_MS) {
logLine("ring health: on-demand pull skipped, last one was "
+ ((now - ringHealthLastRequestedAtMs) / 1000) + "s ago")
return
}
ringHealthLastRequestedAtMs = now
}
logLine("ring health: on-demand pull requested")
runRingHealthPull()
}
/**
* Device-channel initialization. 00:0e enables health recording; 00:05 sets
* the clock (signed timezone minutes plus Unix seconds).
*
* The inherited extra timezone shift is WRONG: on this PDT ring, fresh HR
* timestamps track receipt time + 7h. Firmware expects UTC seconds and
* applies the timezone separately. Do not simply deploy a seven-hour
* rewind: stock firmware can format its health database on a backward
* jump >= 1h. Existing pages also contain mixed clock domains and invalid
* daily anchors, so their dates cannot be repaired by one subtraction.
*
* TODO: controlled UTC migration after preserving ring history. Retain the
* existing wire behavior until that migration is authorized and validated.
* See notes/ring-health-live-validation.md for evidence and the next test.
*/
internal fun GlassesSessionCore.sendRingHandshake() {
val nowMs = currentTimeMillis()
val utcOffsetMs = localUtcOffsetMs(nowMs)
val clockOffsetSeconds = -utcOffsetMs / 1000L
val liveClockSeconds = (nowMs / 1000L) + clockOffsetSeconds
logLine("ring handshake legacy clock offset seconds = " + clockOffsetSeconds
+ " (tz " + localTimeZoneId() + ")")
val clock = le32(liveClockSeconds)
val seqs = IntArray(7)
val nonces = IntArray(7)
monitor.withLock {
for (i in 0 until 7) {
seqs[i] = nextRingSeqLocked()
nonces[i] = nextRingNonceLocked()
}
}
val frames = arrayOf(
RingProtocol.buildFrame(RingProtocol.CHAN_DEVICE, RingProtocol.KIND_REQ, 0x00, 0x08, seqs[0],
// NO nonce prefix on this one frame - payload is exactly the
// three bytes 3f 01 01. Every other request on both channels
// starts with the 2-byte nonce; 00:08 does not, and the ring
// silently drops the whole frame if you add one, then ignores
// everything that follows on the connection.
//
// Measured 2026-09-11 across all four btsnoop captures, 46
// real 00:08 writes, zero exceptions:
// payload 3f0101 (3 bytes) -> 3 writes, ALL answered (12-21 notifications each)
// payload 01003f0101 (5 bytes) -> 43 writes, ALL silent (zero notifications)
// The 5-byte form is the more common one in the captures only
// because it is ours, failing and retrying all night. Do not
// "fix" this back to the nonce form by pattern-matching the
// other frames or by counting which variant appears more.
//
// This also explains 2026-09-10: the handshake worked when it
// was raw bytes replayed from the capture, and stopped working
// the moment it was rebuilt "properly" through buildFrame(),
// which is what introduced the nonce prefix.
byteArrayOf(0x3f, 0x01, 0x01)),
RingProtocol.buildFrame(RingProtocol.CHAN_DEVICE, RingProtocol.KIND_DATA, 0x00, 0x0e, seqs[1],
le16(nonces[1]) + clock + byteArrayOf(0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00)),
RingProtocol.buildFrame(RingProtocol.CHAN_DEVICE, RingProtocol.KIND_DATA, 0x00, 0x05, seqs[2],
le16(nonces[2]) + le16(utcOffsetMs / 60000) + clock),
// Battery, firmware version, device id - all bare nonce-only REQs,
// same shape as the health requests.
RingProtocol.buildFrame(RingProtocol.CHAN_DEVICE, RingProtocol.KIND_REQ, 0x00, 0x01, seqs[3],
le16(nonces[3])),
RingProtocol.buildFrame(RingProtocol.CHAN_DEVICE, RingProtocol.KIND_REQ, 0x00, 0x02, seqs[4],
le16(nonces[4])),
RingProtocol.buildFrame(RingProtocol.CHAN_DEVICE, RingProtocol.KIND_REQ, 0x00, 0x0b, seqs[5],
le16(nonces[5])),
RingProtocol.buildFrame(RingProtocol.CHAN_DEVICE, RingProtocol.KIND_REQ, 0x00, 0x0a, seqs[6],
le16(nonces[6]) + RING_IDENTITY_BLOB),
)
for (frame in frames) {
if (!writeRingFrame(frame, "handshake")) {
return
}
}
logLine("ring health: sent device-channel handshake (" + frames.size + " frames)")
}
private fun le16(value: Int): ByteArray = byteArrayOf(value.toByte(), (value ushr 8).toByte())
private fun le32(value: Long): ByteArray =
byteArrayOf(value.toByte(), (value ushr 8).toByte(), (value ushr 16).toByte(), (value ushr 24).toByte())
/**
* Pull the five health record types. Each request is a bare 17-byte frame
* carrying only a nonce; the ring answers with an RSP on the same
* sequence number, then - sometimes - pushes one or more DATA pages,
* which arrive through [handleRingHealthNotification].
*
* **Response-driven, not sleep-driven (rewritten 2026-09-11).**
* The original version fired all five REQs on a blind fixed sleep and
* only flushed queued page ACKs after the whole loop finished - a real
* successful Even sync does the opposite: it waits for each REQ's own RSP,
* waits for DATA to go idle, ACKs immediately, then interleaves one
* device-channel command before the next health type. This version does
* the same, using the monitor's await/signalAll idiom already used
* elsewhere in the session.
*
* **Race condition, confirmed live 2026-09-10 - this is what the
* rewrite above addresses, not a reason to remove this warning.** The
* ring appears to hold only one health type's response in flight at a
* time. Sending the next health REQ before the previous type's DATA
* page(s) have actually arrived silently drops the earlier type's DATA:
* you still get its RSP, you never get its DATA, and nothing in the
* protocol signals an error. Evidence: five REQs fired back-to-back (the
* old blind-sleep version, badly timed) got five RSPs and zero DATA
* pages over more than a minute of waiting.
*
* **Worse: a lost race may PERMANENTLY discard that backlog, not
* just delay it.** On 2026-09-10, real HRV/SpO2/sleep backlog that
* should have existed (unreported since that morning, confirmed against
* the hourly export cadence in `knowledge/inbox/Even_health_data`)
* did not come back on a later, more carefully spaced retry. The working
* theory - not proven, but treat it as true until disproven, because the
* downside of being wrong is silent data loss with nothing to catch it
* - is that the ring advances its own "last delivered" watermark for a
* type as soon as it RSPs a REQ for it, whether or not the DATA page
* actually made it out. **Do not send a speculative or test health REQ
* for a type unless you intend to actually receive and persist its
* DATA** - re-requesting will not recover what an earlier, raced
* request already consumed. Waiting for DATA to go idle before advancing
* reduces how often this can happen but does not prove it can no longer
* happen (e.g. if the ring's real per-type timeout is shorter than
* ringHealthDataIdleMs for some type).
*
* A separate, completely ordinary case looks identical from the wire
* alone: an RSP with no DATA can also just mean the ring genuinely has
* nothing new for that metric since the last successful pull. There is
* currently no way to tell "raced and silently discarded" apart from
* "genuinely nothing new" other than knowing independently whether fresh
* data should exist (e.g. from the export's own sampling cadence).
*
* Runs on the ring worker, which is the only thread allowed to call the
* blocking write path - the wait loops below block that same thread, which
* is why [flushRingOutbound] is called inside the response and DATA waits
* rather than relying on the ring loop's own call to it.
*/
internal fun GlassesSessionCore.requestRingHealth(): Boolean {
// A previous attempt may have left an ACK queued after a failed write.
// Never start another type's request ahead of that acknowledgement.
if (flushRingOutbound() < 0) return false
val commands = RingProtocol.HEALTH_COMMANDS
var rspCount = 0
for (i in commands.indices) {
val command = commands[i]
val frame = monitor.withLock {
ringHealthRspSeen = false
RingProtocol.buildHealthRequest(command, nextRingSeqLocked(), nextRingNonceLocked())
}
if (!writeRingFrame(frame, "health request 0x" + command.toString(16))) {
// ABORTED: the sequence stopped partway. Distinct from "the
// ring had nothing for a type", which is an ordinary outcome
// and leaves the loop running - see the return below.
logLine("ring health: pull ABORTED on write at 0x" + command.toString(16)
+ " (" + i + " of " + commands.size + " types attempted, "
+ rspCount + " answered)")
return false
}
if (awaitRingHealthRsp(ringHealthRspTimeoutMs)) {
rspCount++
if (!awaitRingHealthDataIdle(ringHealthDataIdleMs)) {
logLine("ring health: pull ABORTED while acknowledging DATA")
return false
}
} else {
logLine("ring health: pull ABORTED waiting for RSP at 0x" + command.toString(16))
return false
}
if (i < commands.size - 1) {
sendRingDevicePing(RING_DEVICE_PING_CMD_LO[i % RING_DEVICE_PING_CMD_LO.size])
}
}
// Two more ways to have not really completed, both distinguishable from
// "completed but empty":
//
// - the link dropped while the loop was running, so the later types
// were written into nothing;
// - the ring answered NONE of the five. A type with no backlog still
// RSPs (measured: five REQs, five RSPs, zero DATA), so zero RSPs
// across the whole sequence means the ring was not answering at
// all, not that there was nothing to send.
//
// An RSP with no DATA remains ambiguous per type and is NOT treated as
// a failure here - that is the ordinary "nothing new" case.
val stillConnected = monitor.withLock { ringConnected }
if (!stillConnected || rspCount == 0) {
logLine("ring health: pull ABORTED - ran all " + commands.size + " types but "
+ (if (stillConnected) "the ring answered none of them" else "the link dropped"))
return false
}
logLine("ring health: requested " + commands.size + " record types, " + rspCount + " answered")
return true
}
/** Block (ring worker) until the health RSP flag is set or the timeout
* elapses. Not correlated to a specific command/seq - like the rest of
* this protocol's request path, it trusts the ring answers in order. */
internal fun GlassesSessionCore.awaitRingHealthRsp(timeoutMs: Long): Boolean {
val deadline = now() + timeoutMs
while (true) {
// A DATA notification may precede its RSP. Writes must happen
// outside the lock so GATT callbacks can continue delivering pages.
if (flushRingOutbound() < 0) return false
monitor.withLock {
if (!running || !ringConnected) return false
if (ringHealthRspSeen) return true
if (ringOutbound.isEmpty()) {
val remaining = deadline - now()
if (remaining <= 0) {
return false
}
monitor.awaitMs(minOf(remaining, 100L))
}
}
}
}
/** Block (ring worker) until DATA pages go idle for [idleMs], extending
* the window on every new page so a real multi-page backlog transfer isn't
* cut short. Not filtered by health type - correct given the ring only has
* one type in flight at a time (see [requestRingHealth]), so any page
* arriving here belongs to the type just requested. */
internal fun GlassesSessionCore.awaitRingHealthDataIdle(idleMs: Long): Boolean {
var idleDeadline = now() + idleMs
var lastSeenCounter = -1
while (true) {
// The next page can depend on this ACK. Waiting for idle first
// mistakes an ACK-paced transfer for a completed transfer.
val acknowledged = flushRingOutbound()
if (acknowledged < 0) return false
monitor.withLock {
if (!running || !ringConnected) return false
if (acknowledged > 0 || ringHealthPageCounter != lastSeenCounter) {
lastSeenCounter = ringHealthPageCounter
// Start the next-page window AFTER the blocking ACK write.
idleDeadline = now() + idleMs
}
// A callback may have queued a page between flush and lock.
if (ringOutbound.isEmpty()) {
val remaining = idleDeadline - now()
if (remaining <= 0) return true
monitor.awaitMs(minOf(remaining, 100L))
}
}
}
}
/**
* Fire one bare device-channel REQ in the gap between health types,
* matching (without waiting on a response) the cadence a real Even sync
* uses. See RING_DEVICE_PING_CMD_LO for provenance and caveats.
*/
internal fun GlassesSessionCore.sendRingDevicePing(cmdLo: Int) {
val frame = monitor.withLock {
val seq = nextRingSeqLocked()
val nonce = nextRingNonceLocked()
if (cmdLo == 0x0a) {
// The only one of these four that isn't a bare nonce - it
// carries the same opaque constant blob as the handshake's
// own 0x0a frame (confirmed byte-identical across two
// different nights, see sendRingHandshake()'s comments).
RingProtocol.buildFrame(RingProtocol.CHAN_DEVICE, RingProtocol.KIND_REQ, 0x00, 0x0a, seq,
le16(nonce) + RING_IDENTITY_BLOB)
} else {
RingProtocol.buildRequest(RingProtocol.CHAN_DEVICE, 0x00, cmdLo, seq, nonce)
}
}
writeRingFrame(frame, "device ping 0x" + cmdLo.toString(16))
}
/** Write one already-built ring frame. Ring worker only (blocking). */
internal fun GlassesSessionCore.writeRingFrame(frame: ByteArray, what: String): Boolean {
return try {
val ok = link.writeFrames(
ringAddress,
BleProtocol.R1_WRITE_CHAR_UUID,
listOf(frame),
ConnectionOptions.WRITE_MODE,
ConnectionOptions.WRITE_TIMEOUT_MS
)
if (!ok) {
logLine("ring $what write failed")
}
ok
} catch (t: Throwable) {
logLine("ring " + what + " write error: " + GlassesSessionCore.safeMessage(t))
false
}
}
/**
* Drain queued ring frames (page ACKs). Ring worker only. Returns the
* number written, or -1 if the link is unavailable or a write failed.
*/
internal fun GlassesSessionCore.flushRingOutbound(): Int {
var acknowledged = 0
while (true) {
val frame = monitor.withLock {
if (!ringNotificationsReady) return -1
ringOutbound.firstOrNull() ?: return acknowledged
}
if (!writeRingFrame(frame, "page ack")) return -1
monitor.withLock {
// Keep failed writes queued for retry. A disconnect can clear
// the queue during the write, so remove this exact frame only.
val index = ringOutbound.indexOfFirst { it === frame }
if (index >= 0) ringOutbound.removeAt(index)
acknowledged++
}
}
}
internal fun GlassesSessionCore.nextRingSeqLocked(): Int {
ringSeq = (ringSeq + 1) and 0xff
if (ringSeq == 0) {
ringSeq = 1
}
return ringSeq
}
internal fun GlassesSessionCore.nextRingNonceLocked(): Int {
ringNonce = (ringNonce + 1) and 0xffff
return ringNonce
}
@@ -0,0 +1,196 @@
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
/**
* [connect] with the platform's background-reconnect mode (Android's autoConnect) when
* [autoConnect] is set. The R1 ring needs it; platforms without the distinction ignore it.
*/
fun connect(address: String, timeoutMs: Int, autoConnect: Boolean): Boolean = connect(address, timeoutMs)
/** 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?)
/**
* Start the direct-ring worker thread running [body] once. Ring connect/write/health waits
* run there so they never park the glasses sender. The core joins it through its own latch.
*/
fun startRingWorker(body: () -> Unit) = startThread("FaceclawRing", false, body)
/** Interrupt the ring worker's blocking waits where the platform supports it. */
fun interruptRingWorker() {}
/**
* Whether this platform runs the R1 health-data protocol (handshake, pulls, page ACKs).
* Requires [appendRingFrameJournal] and a consumer for the decoded records; without
* one, ring notifications only feed the gesture decoder.
*/
fun supportsRingHealth(): Boolean = false
/**
* Durably append one line to the private ring-frame journal (health/ring-frames.jsonl in
* the app's files directory), syncing before returning. Throws when the line could not be
* stored; the caller then withholds the page ACK so the ring keeps the data.
*/
fun appendRingFrameJournal(line: String) {
throw UnsupportedOperationException("no ring frame journal on this platform")
}
}
/**
* 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,42 @@
package com.faceclaw.app
import kotlin.math.abs
import kotlin.math.pow
/**
* Color-remap tables that dim the display by a light factor using a checkerboard dither.
*
* The panel's response looks roughly linear in light, so level 1 already emits 1/15 of full
* brightness, and remapping each level to a single darker level has too little resolution
* near black. A dimmed level 1 is either unchanged or gone. Instead each level maps to a
* pair of adjacent levels, one for pixels with even x+y and one for odd x+y. That gives
* half-step averages, e.g. level 1 becomes a 1/0 halftone.
*/
object DimDither {
/** Relative light output of each level; replace with measurements if the panel isn't linear. */
private val levelLight = DoubleArray(16) { it.toDouble() }
/** Half-step k shows ceil(k/2) on even pixels and floor(k/2) on odd ones. */
private val halfStepLight = DoubleArray(31) { k -> (levelLight[(k + 1) / 2] + levelLight[k / 2]) / 2 }
/** Comparable perceived lightness (CIE L* is affine in the cube root at these levels). */
private fun lightness(light: Double) = light.pow(1.0 / 3)
/**
* Even- and odd-parity tables scaling light to factor256/256. Each level takes the half-step
* perceptually nearest its dimmed light, never brighter than the original, and a visible
* level keeps at least the 1/0 halftone.
*/
fun tables(factor256: Int): Pair<IntArray, IntArray> {
require(factor256 in 0..256)
val even = IntArray(16)
val odd = IntArray(16)
for (level in 1..15) {
val target = lightness(levelLight[level] * factor256 / 256)
val step = (1..2 * level).minBy { abs(lightness(halfStepLight[it]) - target) }
even[level] = (step + 1) / 2
odd[level] = step / 2
}
return even to odd
}
}
@@ -0,0 +1,42 @@
package com.faceclaw.app
/**
* PRESENT resets the clock; timer redraws preserve it. The owner serializes
* calls and supplies a cancellable 45 ms scheduler on its rendering thread.
*/
class DisplayListPlayer(
private val renderer: DisplayListRenderer,
private val screen: DisplayListRenderer.Target,
private val composition: DisplayListRenderer.Target,
private val clock: () -> Long,
private val schedule: (Int, () -> Unit) -> (() -> Unit),
private val displayed: () -> Unit,
) {
private var root = DrawProtocol.SCREEN
private var origin = 0L
private var generation = 0
private var cancel: (() -> Unit)? = null
fun present(root: Int) {
stop()
this.root = root
origin = clock()
draw(generation)
}
fun stop() {
generation++
cancel?.invoke()
cancel = null
}
private fun draw(token: Int) {
if (token != generation) return
cancel = null
renderer.render(root, screen, composition, (clock() - origin).coerceAtLeast(0))
displayed()
if (token == generation && renderer.animationPending) {
cancel = schedule(45) { draw(token) }
}
}
}
@@ -0,0 +1,438 @@
package com.faceclaw.app
/** Reference interpreter. It uses the firmware's packed rows, clipping, LUT and call grammar. */
class DisplayListRenderer(
private val resources: Map<Int, ByteArray>,
private val builtin: ((Int, Int) -> BuiltinGlyph)? = null,
private val rightLens: Boolean = false,
) {
class BuiltinGlyph(val image: ByteArray, val advance: Int, val x: Int = 0, val y: Int = 0)
/**
* [clip] (revision 35) is the writable [left, top, right, bottom) in
* shifted target pixels, or null for the whole target. Like the depth
* shift, it is inherited by nested lists and dropped by a target override.
*/
class Target(
val bytes: ByteArray,
val width: Int,
val height: Int,
val offset: Int = 0,
val shiftX: Int = 0,
val clip: IntArray? = null,
) {
val stride = (width + 1) / 2
init {
require(width > 0 && height > 0 && offset >= 0 && bytes.size - offset >= stride * height)
}
fun get(x: Int, y: Int): Int {
val shift = if (x % 2 == 0) 4 else 0
return (bytes[offset + y * stride + x / 2].toInt() ushr shift) and 15
}
fun shifted(dx: Int) = Target(bytes, width, height, offset, shiftX + dx, clip)
/** Narrow the clip to a rect in (unshifted) call coordinates. */
fun clipped(x: Int, y: Int, w: Int, h: Int): Target {
val left = x + shiftX
val rect = intArrayOf(left, y, left + w, y + h)
if (clip != null) {
rect[0] = maxOf(rect[0], clip[0]); rect[1] = maxOf(rect[1], clip[1])
rect[2] = minOf(rect[2], clip[2]); rect[3] = minOf(rect[3], clip[3])
}
return Target(bytes, width, height, offset, shiftX, rect)
}
fun writable(x: Int, y: Int): Boolean =
x in 0 until width && y in 0 until height &&
(clip == null || (x >= clip[0] && y >= clip[1] && x < clip[2] && y < clip[3]))
fun put(localX: Int, y: Int, value: Int) {
val x = localX + shiftX
if (!writable(x, y)) return
val index = offset + y * stride + x / 2
val old = bytes[index].toInt()
bytes[index] = if (x % 2 == 0) {
((old and 15) or (value shl 4)).toByte()
} else {
((old and 240) or value).toByte()
}
}
}
/** Shared by nested calls, and reset between validation and drawing. */
var animationPending: Boolean = false
private set
private class Walk(val screen: Target, val apply: Boolean, val references: MutableSet<Int>, val frame: DrawEvaluation) {
val ancestors = mutableListOf<Int>()
var remainingCalls = 4096
}
private class Image(val width: Int, val height: Int, val pixels: IntArray)
private fun resource(id: Int) = requireNotNull(resources[id]) { "Missing resource $id" }
// Resource headers, font offsets and RLE have their own fixed-width grammar;
// they do not use the draw-call numeric codec.
private fun readU8(reader: ByteReader): Int = reader.get().toInt() and 255
private fun readU16(reader: ByteReader): Int = reader.getShort().toInt() and 65535
private fun decodeRle(reader: ByteReader, count: Int, exact: Boolean): IntArray {
val pixels = IntArray(count)
var index = 0
while (index < count) {
val token = readU8(reader)
var run = token ushr 4
if (run == 0) {
run = readU8(reader)
if (run == 0) run = readU16(reader)
}
require(run > 0 && run <= count - index)
pixels.fill(token and 15, index, index + run)
index += run
}
require(!exact || reader.remaining() == 0)
return pixels
}
private fun image(bytes: ByteArray, start: Int = 0): Image {
require(start in bytes.indices)
val reader = ArrayByteReader(bytes, start)
val flags = readU8(reader)
require(flags and CFW_RESOURCE_IMAGE_FLAGS_MASK == flags)
val large = flags and CFW_RESOURCE_FLAG_LARGE != 0
val width = if (large) readU16(reader) else readU8(reader)
val height = if (large) readU16(reader) else readU8(reader)
require(width in 1..640 && height in 1..480)
val pixels = if (flags and CFW_RESOURCE_FLAG_RLE != 0) {
decodeRle(reader, width * height, false)
} else {
val offset = bytes.size - reader.remaining()
val target = Target(bytes, width, height, offset)
IntArray(width * height) { target.get(it % width, it / width) }
}
return Image(width, height, pixels)
}
private fun target(id: Int): Target {
val bytes = resource(id)
val reader = ArrayByteReader(bytes)
val flags = readU8(reader)
require(flags and (CFW_RESOURCE_TYPE_MASK or CFW_RESOURCE_FLAG_RLE) == 0)
image(bytes) // Validate the complete raw image before exposing a write target.
val large = flags and CFW_RESOURCE_FLAG_LARGE != 0
val width = if (large) readU16(reader) else readU8(reader)
val height = if (large) readU16(reader) else readU8(reader)
return Target(bytes, width, height, bytes.size - reader.remaining())
}
private fun draw(image: Image, target: Target, x: Int, y: Int, options: Int, apply: Boolean) {
if (!apply) return
for (i in image.pixels.indices) {
val value = image.pixels[i]
if (value == 0 && options and CFW_TEXTURE_OPT_TRANSPARENT != 0) continue
val source = if (options and CFW_TEXTURE_OPT_INVERSE != 0) 15 - value else value
val brightness = source * (options and CFW_TEXTURE_OPT_BRIGHTNESS_MASK) / 15
target.put(x + i % image.width, y + i / image.width, brightness)
}
}
private fun roundedContains(x: Int, y: Int, width: Int, height: Int, radius: Int): Boolean {
if (x !in 0 until width || y !in 0 until height) return false
val r = minOf(radius, width / 2, height / 2)
val dx = maxOf(0, 2 * r - (2 * minOf(x, width - 1 - x) + 1))
val dy = maxOf(0, 2 * r - (2 * minOf(y, height - 1 - y) + 1))
return dx * dx + dy * dy <= 4 * r * r
}
private fun copyScreen(screen: Target, composition: Target) {
val source = screen.bytes
val destination = composition.bytes
// Shared backing arrays can overlap and the pixel loop intentionally reads
// earlier writes. Keep that behavior, as well as shifted target clipping.
if (source === destination || composition.shiftX != 0) {
for (y in 0 until screen.height) for (x in 0 until screen.width) composition.put(x, y, screen.get(x, y))
return
}
val width = minOf(screen.width, composition.width)
val height = minOf(screen.height, composition.height)
val sourceStride = screen.stride
val destinationStride = composition.stride
var src = screen.offset
var dst = composition.offset
if (screen.width == composition.width && width and 1 == 0) {
source.copyInto(destination, dst, src, src + sourceStride * height)
return
}
val pairs = width / 2
for (y in 0 until height) {
source.copyInto(destination, dst, src, src + pairs)
// The last pixel of an odd-width row shares a byte with padding or
// an untouched destination pixel; preserve that low nibble.
if (width and 1 != 0) destination[dst + pairs] =
((source[src + pairs].toInt() and 240) or (destination[dst + pairs].toInt() and 15)).toByte()
src += sourceStride
dst += destinationStride
}
}
/** Validate the whole graph before changing any pixels. Resource writes remain call-scoped. */
fun render(root: Int, screen: Target, composition: Target, elapsedMs: Long = 0): Set<Int> {
animationPending = false
val frame = DrawEvaluation(elapsedMs)
val references = mutableSetOf<Int>()
for (apply in listOf(false, true)) {
// A root list composes the whole frame, including its screen copy.
if (root != DrawProtocol.SCREEN) {
executeList(root, composition, Walk(screen, apply, references, frame))
} else if (apply) {
copyScreen(screen, composition)
}
}
animationPending = frame.animationPending
return references
}
fun execute(sequence: ByteArray, target: Target, screen: Target = target, elapsedMs: Long = 0): Set<Int> {
animationPending = false
val frame = DrawEvaluation(elapsedMs)
val references = mutableSetOf<Int>()
for (apply in listOf(false, true)) {
executeSequence(DrawReader(sequence), target, Walk(screen, apply, references, frame))
}
animationPending = frame.animationPending
return references
}
private fun executeList(id: Int, target: Target, walk: Walk) {
require(walk.ancestors.size < 8 && id !in walk.ancestors)
val bytes = resource(id)
require(bytes.size >= 3 && bytes[0].toInt() == CFW_RESOURCE_TYPE_DISPLAY_LIST)
walk.references.add(id)
walk.ancestors.add(id)
executeSequence(DrawReader(bytes, start = 1), target, walk)
walk.ancestors.removeAt(walk.ancestors.lastIndex)
}
private fun executeSequence(reader: DrawReader, inherited: Target, walk: Walk) {
val count = reader.readU16()
repeat(count) {
val length = reader.readU16()
require(walk.remainingCalls > 0)
walk.remainingCalls--
executeCall(reader.readSlice(length), inherited, walk)
}
reader.requireDone()
}
private fun executeCall(reader: DrawReader, inherited: Target, walk: Walk) {
val opcode = reader.readU8()
val flags = reader.readU8()
require(flags and DRAW_FLAGS_MASK.inv() == 0)
var target = inherited
if (flags and DRAW_FLAG_RESOURCE_TARGET != 0) {
val id = reader.readU16()
walk.references.add(id)
target = target(id).shifted(inherited.shiftX)
}
if (flags and DRAW_FLAG_DEPTH != 0) {
target = target.shifted(DrawProtocol.depthOffset(reader.readS8(), rightLens))
}
if (flags and DRAW_FLAG_CLIP != 0) {
target = target.clipped(reader.readS16(), reader.readS16(), reader.readU16(), reader.readU16())
}
when (opcode) {
DRAW_OP_BOUNDING_BOX -> drawBoundingBox(reader, target, walk)
DRAW_OP_RECT_COPY -> drawRectCopy(reader, target, walk)
DRAW_OP_STOCK_FONT_STRING -> drawStockText(reader, target, walk)
DRAW_OP_IMAGE -> drawImage(reader, target, walk)
DRAW_OP_TEXT -> drawText(reader, target, walk)
DRAW_OP_REMAP_COLORS -> remapColors(reader, target, walk)
DRAW_OP_ROUNDED_RECT -> drawRoundedRect(reader, target, walk)
DRAW_OP_CLEAR -> clear(reader, target, walk)
DRAW_OP_DISPLAY_LIST -> {
val id = reader.readU16()
reader.requireDone()
executeList(id, target, walk)
}
else -> error("Unknown draw opcode $opcode")
}
}
private fun drawBoundingBox(reader: DrawReader, target: Target, walk: Walk) {
val flags = reader.readU8()
require(flags and DRAW_BBOX_FLAG_U16.inv() == 0)
val wide = flags and DRAW_BBOX_FLAG_U16 != 0
val x = if (wide) reader.readU16() else reader.readU8() * 4
val y = if (wide) reader.readU16() else reader.readU8() * 2
val width = if (wide) reader.readU16() else reader.readU8() * 4
val height = if (wide) reader.readU16() else reader.readU8() * 2
require(width > 0 && height > 0 && x + width <= target.width && y + height <= target.height)
val rle = ArrayByteReader(reader.readBytes(reader.remaining))
val pixels = decodeRle(rle, width * height, true)
if (walk.apply) {
for (i in pixels.indices) target.put(x + i % width, y + i / width, pixels[i])
}
}
private fun drawRectCopy(reader: DrawReader, target: Target, walk: Walk) {
val id = reader.readU16()
val x = ExtendedVarint.evaluate(reader, walk.frame)
val y = ExtendedVarint.evaluate(reader, walk.frame)
val width = reader.readU16()
val height = reader.readU16()
val dx = ExtendedVarint.evaluate(reader, walk.frame)
val dy = ExtendedVarint.evaluate(reader, walk.frame)
reader.requireDone()
require(x >= 0 && y >= 0)
val source = when (id) {
DrawProtocol.SCREEN -> walk.screen
DrawProtocol.CURRENT -> target
else -> {
walk.references.add(id)
target(id)
}
}
require(width > 0 && height > 0 && x + width <= source.width && y + height <= source.height)
// Mirrors the firmware's overflow guard before the depth shift.
if (walk.apply && dx in -65536..65536) {
// Snapshot the rectangle so overlapping copies have memmove semantics.
val copy = IntArray(width * height) { source.get(x + it % width, y + it / width) }
for (i in copy.indices) target.put(dx + i % width, dy + i / width, copy[i])
}
}
private fun drawStockText(reader: DrawReader, target: Target, walk: Walk) {
var x = reader.readS16()
val y = reader.readS16()
val options = reader.readU8()
val bytes = reader.readBytes(reader.readU8())
reader.requireDone()
val text = bytes.decodeToString(throwOnInvalidSequence = true)
val codePoints = ArrayList<Int>()
var index = 0
while (index < text.length) {
val char = text[index++].code
val codePoint = if (char in 0xd800..0xdbff) {
require(index < text.length)
0x10000 + ((char - 0xd800) shl 10) + text[index++].code - 0xdc00
} else {
char
}
codePoints.add(codePoint)
}
for (i in codePoints.indices) {
val codePoint = codePoints[i]
if (codePoint in 1..31) {
x += codePoint - 11
continue
}
val next = codePoints.drop(i + 1).firstOrNull { it !in 1..31 } ?: 0
val glyph = requireNotNull(builtin) { "Builtin font provider required" }(codePoint, next)
draw(image(glyph.image), target, x + glyph.x, y + glyph.y, options, walk.apply)
x += glyph.advance
}
}
/** Mirrors the firmware: far-off image/text coordinates draw nothing (before the depth shift can overflow). */
private fun offTarget(x: Int, y: Int) = x !in -65536..65536 || y !in -65536..65536
private fun drawImage(reader: DrawReader, target: Target, walk: Walk) {
val id = reader.readU16()
val x = ExtendedVarint.evaluate(reader, walk.frame)
val y = ExtendedVarint.evaluate(reader, walk.frame)
val options = reader.readU8()
reader.requireDone()
walk.references.add(id)
val image = image(resource(id))
if (!offTarget(x, y)) draw(image, target, x, y, options, walk.apply)
}
private fun drawText(reader: DrawReader, target: Target, walk: Walk) {
val id = reader.readU16()
var x = ExtendedVarint.evaluate(reader, walk.frame)
val y = ExtendedVarint.evaluate(reader, walk.frame)
val options = reader.readU8()
val text = reader.readBytes(reader.readU8())
reader.requireDone()
walk.references.add(id)
val data = resource(id)
require(data.size >= 193 && data[0].toInt() == CFW_RESOURCE_TYPE_FONT)
val apply = walk.apply && !offTarget(x, y)
for (byte in text) {
val char = byte.toInt() and 255
if (char in 1..31) {
x += char - 11
continue
}
require(char in 32..127)
val offset = DrawProtocol.u16(data, 1 + (char - 32) * 2)
require(offset >= 193)
val glyph = image(data, offset)
draw(glyph, target, x, y, options, apply)
x += glyph.width
}
}
private fun remapColors(reader: DrawReader, target: Target, walk: Walk) {
val x = reader.readU16()
val y = reader.readU16()
val width = reader.readU16()
val height = reader.readU16()
val tables = reader.readBytes(16)
reader.requireDone()
require(width > 0 && height > 0 && x + width <= target.width && y + height <= target.height)
if (!walk.apply) return
for (yy in y until y + height) for (xx in x until x + width) {
val tx = xx + target.shiftX
if (!target.writable(tx, yy)) continue
val value = target.get(tx, yy)
val shift = if (value % 2 == 0) 4 else 0
// The even-parity table comes first; parity is of the shifted target pixel.
target.put(xx, yy, (tables[((tx + yy) and 1) * 8 + value / 2].toInt() ushr shift) and 15)
}
}
private fun clear(reader: DrawReader, target: Target, walk: Walk) {
val color = reader.readU8()
reader.requireDone()
require(color <= 15)
if (!walk.apply) return
val clip = target.clip
if (clip == null) {
target.bytes.fill((color * 17).toByte(), target.offset, target.offset + target.stride * target.height)
} else {
// Revision 35: a clipped clear fills just the clip, which is in shifted pixels already.
for (y in maxOf(0, clip[1]) until minOf(target.height, clip[3])) {
for (x in maxOf(0, clip[0]) until minOf(target.width, clip[2])) target.put(x - target.shiftX, y, color)
}
}
}
private fun drawRoundedRect(reader: DrawReader, target: Target, walk: Walk) {
val x = ExtendedVarint.evaluate(reader, walk.frame)
val y = ExtendedVarint.evaluate(reader, walk.frame)
val width = reader.readU16()
val height = reader.readU16()
val radius = reader.readU16()
val fill = reader.readU8()
val border = reader.readU8()
reader.requireDone()
require(width in 1..640 && height in 1..480 && fill <= 15 && border <= DRAW_ROUNDED_RECT_NO_BORDER)
if (!walk.apply) return
if (x < -width - target.shiftX || x >= target.width - target.shiftX ||
y < -height || y >= target.height) return
for (yy in 0 until height) for (xx in 0 until width) {
if (!roundedContains(xx, yy, width, height, radius)) continue
val tx = x + xx + target.shiftX
val ty = y + yy
if (tx !in 0 until target.width || ty !in 0 until target.height) continue
val edge = !roundedContains(xx - 1, yy - 1, width - 2, height - 2, maxOf(0, radius - 1))
val value = if (edge && border < DRAW_ROUNDED_RECT_NO_BORDER) border else maxOf(fill, target.get(tx, ty))
target.put(x + xx, ty, value)
}
}
}
@@ -0,0 +1,17 @@
package com.faceclaw.app
/** TS/native bridge tags, not firmware draw opcodes. Keep in sync with presentation-wire.ts. */
object DrawRecordKind {
const val GLYPH = 0
const val TEXTURE_IMAGE = 1
const val FIRMWARE_TEXT = 2
const val MENU_SELECTION = 3
const val TRANSPARENT_IMAGE = 4
const val MASKED_IMAGE = 5
const val DISPLAY_LIST = 7
fun isPresentation(kind: Int): Boolean = when (kind) {
MENU_SELECTION, TRANSPARENT_IMAGE, MASKED_IMAGE, DISPLAY_LIST -> true
else -> false
}
}
@@ -0,0 +1,7 @@
package com.faceclaw.app
/** One-shot scheduler; the owner acquires its rendering lock in [action]. */
internal expect fun scheduleDrawRedraw(delayMs: Int, action: () -> Unit): () -> Unit
private val drawTimeOrigin = kotlin.time.TimeSource.Monotonic.markNow()
internal fun drawAnimationTimeMs(): Long = drawTimeOrigin.elapsedNow().inWholeMilliseconds
@@ -0,0 +1,40 @@
package com.faceclaw.app
/** Self-contained font snapshots; their 96 u16 glyph offsets survive firmware compaction. */
class FontResourceAtlas {
class Font(val resource: CachedResource, val encodings: Set<Int>)
companion object {
private val lock = protocolPlatform().createLock()
private val fonts = HashMap<Int, Font>()
fun get(fontId: Int, requested: Set<Int>): Font {
lock.withLock {
val old = fonts[fontId]
if (old != null && old.encodings.containsAll(requested)) return old
val glyphs = HashMap<Int, GlyphAtlas.Glyph>()
var size = 193
// Current-frame glyphs take precedence if the entire font cannot fit.
for (encoding in requested.sorted() + (old?.encodings ?: emptySet()).sorted()) {
if (encoding !in 32..127 || glyphs.containsKey(encoding)) continue
val glyph = GlyphAtlas.get(fontId, encoding) ?: continue
if (size + glyph.cachedBytes.size > ResourceCacheState.MAX_RESOURCE_SIZE) continue
glyphs[encoding] = glyph; size += glyph.cachedBytes.size
}
val bytes = ByteArray(size)
bytes[0] = DrawProtocol.FONT.toByte()
var offset = 193
for (encoding in glyphs.keys.sorted()) {
val glyph = glyphs.getValue(encoding)
val slot = 1 + (encoding - 32) * 2
bytes[slot] = offset.toByte(); bytes[slot + 1] = (offset ushr 8).toByte()
glyph.cachedBytes.copyInto(bytes, offset)
offset += glyph.cachedBytes.size
}
val font = Font(CachedResource(bytes), glyphs.keys.toSet())
fonts[fontId] = font
return font
}
}
}
}
@@ -0,0 +1,241 @@
package com.faceclaw.app
/** A retained draw submitted with frame pixels, before cache IDs have been assigned. */
interface RetainedDrawing {
val resources: List<CachedResource>
val fingerprint: String
fun translated(dx: Int, dy: Int): RetainedDrawing
fun calls(ids: IntArray, nowMs: Long): List<ByteArray>
}
internal fun readRetainedDrawing(reader: ByteReader, kind: Int): RetainedDrawing =
if (kind == DrawRecordKind.DISPLAY_LIST) FrameDisplayList.read(reader) else MenuSelection.read(reader, kind)
/**
* Generic TS-authored calls. No menu or easing policy lives in this bridge.
*
* Besides literal firmware calls, a record may carry a DRAWS call (bridge
* only): glyph and icon records in the frame draw-record format, whose atlas
* identities TS registered while painting. They compile to IMAGE calls on
* ImageAtlas resources, then TEXT runs on FontResourceAtlas fonts, all offset
* by the call's (possibly animated) x/y. When any record cannot be resolved,
* the whole list draws nothing: the frame's own pixels show instead, rather
* than content with a glyph missing.
*/
class FrameDisplayList private constructor(
private val x: Int, private val y: Int, private val depth: Int,
override val resources: List<CachedResource>, private val commands: List<Command>,
internal val startedAt: Long, private val identity: String,
) : RetainedDrawing {
override val fingerprint: String get() = "$x,$y,$depth,$identity"
override fun translated(dx: Int, dy: Int) = FrameDisplayList(x + dx, y + dy, depth, resources, commands, startedAt, identity)
/** Image/text [values] are resource, x offset, y offset, options; the offsets add to [x]/[y]. */
private class Command(val op: Int, val depth: Int, val values: IntArray,
val x: DrawValue = DrawValue.Integer(0), val y: DrawValue = DrawValue.Integer(0),
val dx: DrawValue = DrawValue.Integer(0), val dy: DrawValue = DrawValue.Integer(0),
val clip: DrawClip? = null, val text: ByteArray? = null)
override fun calls(ids: IntArray, nowMs: Long): List<ByteArray> {
require(ids.size == resources.size)
val elapsed = (nowMs - startedAt).coerceIn(0, Int.MAX_VALUE.toLong()).toInt()
fun resource(index: Int) = if (index == DrawProtocol.SCREEN) index else ids[index]
return commands.map { c ->
val v = c.values
val clip = c.clip?.translated(x, y)
when (c.op) {
DRAW_OP_ROUNDED_RECT -> DrawProtocol.roundedRect(bind(c.x, elapsed, x), bind(c.y, elapsed, y),
v[0], v[1], v[2], v[3], v[4], depth + c.depth, clip)
DRAW_OP_IMAGE -> DrawProtocol.image(resource(v[0]), bind(c.x, elapsed, x + v[1]), bind(c.y, elapsed, y + v[2]),
v[3], depth = depth + c.depth, clip = clip)
DRAW_OP_TEXT -> DrawProtocol.text(resource(v[0]), bind(c.x, elapsed, x + v[1]), bind(c.y, elapsed, y + v[2]),
v[3], c.text!!, depth + c.depth, clip)
DRAW_OP_RECT_COPY -> DrawProtocol.rectCopy(resource(v[0]),
bind(c.x, elapsed, if (v[0] == DrawProtocol.SCREEN) x else 0),
bind(c.y, elapsed, if (v[0] == DrawProtocol.SCREEN) y else 0),
v[1], v[2], bind(c.dx, elapsed, x), bind(c.dy, elapsed, y), depth = depth + c.depth, clip = clip)
DRAW_OP_CLEAR -> DrawProtocol.clear(v[0], clip = clip, depth = if (clip == null) null else depth + c.depth)
else -> error("Unsupported frame display-list opcode")
}
}
}
companion object {
// Bridge-only constant binding, removed before a program reaches either renderer.
private const val ELAPSED = 128
private const val MAX_RECORD_BYTES = 4 * 1024 * 1024
/** Bridge-only: replay glyph/icon draw records (see the class comment). */
private const val DRAWS = 32
/** Bridge opcode bit: an x/y s16, w/h u16 clip rect follows the call's depth. */
private const val CLIPPED = 128
private const val IMAGE_OPTIONS = CFW_TEXTURE_OPT_BRIGHTNESS_MASK or CFW_TEXTURE_OPT_TRANSPARENT
private fun bind(value: DrawValue, elapsed: Int, offset: Int): DrawValue {
if (value is DrawValue.Integer) return DrawValue.Integer(value.value + offset)
val reader = DrawReader((value as DrawValue.Expression).program)
val out = ByteSink()
while (reader.remaining > 0) {
when (val op = reader.readU8()) {
ELAPSED -> { out.write(DrawExpression.PUSH_I32); out.write(ExtendedVarint.signed(elapsed)) }
DrawExpression.PUSH_I32 -> { out.write(op); out.write(ExtendedVarint.signed(ExtendedVarint.read(reader, true))) }
DrawExpression.PUSH_F32 -> { out.write(op); out.write(reader.readBytes(4)) }
else -> out.write(op)
}
}
if (offset != 0) {
out.write(DrawExpression.PUSH_I32); out.write(ExtendedVarint.signed(offset)); out.write(DrawExpression.IADD)
}
val program = out.toByteArray()
require(program.size <= DrawExpression.MAX_BYTES)
return DrawValue.Expression(program)
}
private class GlyphRecord(val fontId: Int, val encoding: Int, val penX: Int, val lineY: Int, val value: Int)
private class ImageRecord(val imageId: Int, val x: Int, val y: Int)
/**
* Compile one DRAWS call into [out], adding atlas resources through
* [resource]. False when a record has no atlas entry, or its font
* snapshot cannot hold every glyph this call needs.
*/
private fun compileDraws(glyphs: List<GlyphRecord>, images: List<ImageRecord>, x: DrawValue, y: DrawValue,
depth: Int, clip: DrawClip?, resource: (CachedResource) -> Int, out: MutableList<Command>): Boolean {
for (image in images) {
val entry = ImageAtlas.get(image.imageId) ?: return false
out.add(Command(DRAW_OP_IMAGE, depth, intArrayOf(resource(entry.resource), image.x, image.y, IMAGE_OPTIONS),
x, y, clip = clip))
}
for ((fontId, fontGlyphs) in glyphs.groupBy { it.fontId }) {
val encodings = fontGlyphs.map { it.encoding }.toSet()
val font = FontResourceAtlas.get(fontId, encodings)
if (!font.encodings.containsAll(encodings)) return false
val fontIndex = resource(font.resource)
// One run per line and color, like TexturePlanner's: control
// bytes move the pen to each glyph's exact left edge.
val lines = fontGlyphs.groupBy { it.lineY to BmpUtil.nibbleForGray(it.value) }
for ((line, members) in lines) {
val placed = members.map { glyph ->
val atlas = GlyphAtlas.get(fontId, glyph.encoding) ?: return false
Triple(glyph.penX + atlas.bbxX, atlas.width, glyph.encoding)
}.sortedBy { it.first }
var start = 0
while (start < placed.size) {
val text = ByteSink()
var cursor = placed[start].first
var end = start
while (end < placed.size) {
val (left, width, encoding) = placed[end]
if (text.size() + TexturePlanner.adjustByteCount(left - cursor) + 1 > 255) break
TexturePlanner.emitAdjust(text, left - cursor)
text.write(encoding)
cursor = left + width
end++
}
out.add(Command(DRAW_OP_TEXT, depth,
intArrayOf(fontIndex, placed[start].first, line.first, line.second or CFW_TEXTURE_OPT_TRANSPARENT),
x, y, clip = clip, text = text.toByteArray()))
start = end
}
}
}
return true
}
fun read(input: ByteReader, nowMs: Long = drawAnimationTimeMs()): FrameDisplayList {
val length = input.getInt()
require(length in 21..MAX_RECORD_BYTES && length <= input.remaining())
val bytes = ByteArray(length).also { input.get(it) }
val r = DrawReader(bytes)
val x = r.readS16(); val y = r.readS16()
val width = r.readU16(); val height = r.readU16()
require(width in 1..640 && height in 1..480)
val depth = r.readS8()
r.readBytes(4) // Stable timeline token is included in the identity below.
val elapsed = r.readU16() or (r.readU16() shl 16)
require(elapsed >= 0)
val resourceCount = r.readU16(); require(resourceCount <= 256)
val local = List(resourceCount) {
val w = r.readU16(); val h = r.readU16()
require(w in 1..640 && h in 1..480 && 5 + (w + 1) / 2 * h <= 65536)
val gray = r.readBytes(w * h)
CachedResource(DrawProtocol.rawImage(w, h, BmpUtil.pack4bppFromGray8(gray, w, h)))
}
val resources = ArrayList(local)
val atlasIndices = HashMap<CachedResource, Int>()
fun atlasResource(cached: CachedResource): Int = atlasIndices.getOrPut(cached) { resources.add(cached); resources.size - 1 }
fun value(): DrawValue {
val first = r.readU8()
if (first != 255) return DrawValue.Integer(ExtendedVarint.read(r, true, first))
val size = ExtendedVarint.read(r, false).toUInt()
require(size <= 900u)
return DrawValue.Expression(r.readBytes(size.toInt())).also {
// Validate framing and worst-case binding growth before retaining the frame.
bind(it, Int.MAX_VALUE, Int.MAX_VALUE)
}
}
fun resource(): Int = r.readU16().also { require(it == DrawProtocol.SCREEN || it in local.indices) }
val count = r.readU16(); require(count <= 4096)
val commands = ArrayList<Command>()
var replayable = true
repeat(count) {
val header = r.readU8(); val op = header and CLIPPED.inv()
val d = r.readS16(); require(depth + d in -128..127)
val clip = if (header and CLIPPED != 0) DrawClip(r.readS16(), r.readS16(), r.readU16(), r.readU16()) else null
when (op) {
DRAW_OP_ROUNDED_RECT -> {
val xx = value(); val yy = value()
val w = r.readU16(); val h = r.readU16(); val radius = r.readU16()
val background = r.readU8(); val border = r.readU8()
require(w in 1..640 && h in 1..480 && background in 0..15 && border in 0..16)
commands.add(Command(op, d, intArrayOf(w, h, radius, background, border), xx, yy, clip = clip))
}
DRAW_OP_IMAGE -> {
val id = resource(); require(id != DrawProtocol.SCREEN)
val xx = r.readS16(); val yy = r.readS16(); val options = r.readU8()
require(options == 15 || options == 31)
commands.add(Command(op, d, intArrayOf(id, xx, yy, options), clip = clip))
}
DRAW_OP_RECT_COPY -> {
val id = resource(); val sx = value(); val sy = value()
val w = r.readU16(); val h = r.readU16(); val dx = value(); val dy = value()
require(w in 1..640 && h in 1..480)
// Relative SCREEN sources may be negative until placement is added.
require(id == DrawProtocol.SCREEN || listOf(sx, sy).all { it !is DrawValue.Integer || it.value >= 0 })
commands.add(Command(op, d, intArrayOf(id, w, h), sx, sy, dx, dy, clip = clip))
}
DRAW_OP_CLEAR -> {
val color = r.readU8(); require(color in 0..15)
commands.add(Command(op, d, intArrayOf(color), clip = clip))
}
DRAWS -> {
val xx = value(); val yy = value()
val glyphs = ArrayList<GlyphRecord>(); val images = ArrayList<ImageRecord>()
repeat(r.readU16()) {
when (r.readU8()) {
DrawRecordKind.GLYPH -> {
val fontId = r.readU16(); val encoding = r.readU16() or (r.readU16() shl 16)
glyphs.add(GlyphRecord(fontId, encoding, r.readS16(), r.readS16(), r.readU8()))
}
DrawRecordKind.TEXTURE_IMAGE -> {
val imageId = r.readU16() or (r.readU16() shl 16)
images.add(ImageRecord(imageId, r.readS16(), r.readS16()))
}
else -> error("Unsupported display-list draw record")
}
}
if (replayable) replayable = compileDraws(glyphs, images, xx, yy, d, clip, ::atlasResource, commands)
}
else -> error("Unsupported frame display-list opcode")
}
}
r.requireDone()
// Elapsed changes while the same timeline is resubmitted; it is not content identity.
bytes.fill(0, 13, 17)
val identity = CachedResource(bytes).hash.toString()
if (!replayable || commands.size > 4096 || resources.size > 511) {
return FrameDisplayList(x, y, depth, emptyList(), emptyList(), nowMs - elapsed, identity)
}
return FrameDisplayList(x, y, depth, resources, commands, nowMs - elapsed, identity)
}
}
}
@@ -0,0 +1,89 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
import kotlin.jvm.JvmStatic
/**
* Process-wide registry of the glasses' builtin 20 px font's glyph rasters, fed from the TS side
* (EvenHubFont's extracted firmware font data). Unlike GlyphAtlas/ImageAtlas entries, these are
* never uploaded: the firmware already owns the font, and mode 15 draws it directly. The planner
* needs the rasters purely phone-side — for the "would this draw land correctly" check against the
* composite and for punching drawn ink out of delta rects.
*
* Placement model matches the firmware's mode-15 math: a glyph draws at (penX + ofsX, lineY +
* inkTop) where inkTop already folds in the root font's line height and baseline. The TS side only
* registers glyphs whose on-glasses rendering it predicts exactly (native-table glyphs; baseline-
* shifted fallback symbols stay baked).
*/
class FwGlyphAtlas {
companion object {
private val lock = protocolPlatform().createLock()
private val entries: MutableMap<Int, Entry> = HashMap()
/**
* Register glyph rasters. Little-endian buffer of records: [cp u32][ofsX s16][inkTop
* s16][boxW u8][boxH u8] [boxH x ceil(boxW/2) nibble bytes] Re-registration of a codepoint
* is ignored (the builtin font is fixed).
*/
@JvmStatic
fun register(buffer: ByteReader?): Unit {
if ((buffer == null)) {
return
}
val cursor: ByteReader = buffer
lock.withLock {
while ((cursor.remaining() >= 10)) {
var cp: Int = cursor.getInt()
var ofsX: Int = cursor.getShort().toInt()
var inkTop: Int = cursor.getShort().toInt()
var boxW: Int = (cursor.get() and 0xff)
var boxH: Int = (cursor.get() and 0xff)
var nibbles: ByteArray = ByteArray((((boxW + 1) shr 1) * boxH))
cursor.get(nibbles)
if ((((boxW > 0) && (boxH > 0)) && !entries.containsKey(cp))) {
entries.put(cp, Entry(ofsX, inkTop, boxW, boxH, nibbles))
}
}
}
}
@JvmStatic
fun get(cp: Int): Entry? {
lock.withLock {
return entries.get(cp)
}
}
}
constructor() {}
class Entry {
/** Draw x = pen x + ofsX. */
@JvmField val ofsX: Int
/** First raster row relative to the run's line-top y. */
@JvmField val inkTop: Int
@JvmField val boxW: Int
@JvmField val boxH: Int
/** 4bpp rows, stride ceil(boxW/2), high nibble = left pixel. */
@JvmField val nibbles: ByteArray
constructor(ofsX: Int, inkTop: Int, boxW: Int, boxH: Int, nibbles: ByteArray) {
this.ofsX = ofsX
this.inkTop = inkTop
this.boxW = boxW
this.boxH = boxH
this.nibbles = nibbles
}
/** The 4bpp source value at (col, row); the draw skips 0 (transparent). */
fun nibbleAt(col: Int, row: Int): Int {
var b: Int = (nibbles[((row * ((boxW + 1) shr 1)) + (col shr 1))] and 0xff)
return (if (((col and 1) != 0)) (b and 0x0f) else (b shr 4))
}
}
}
@@ -0,0 +1,326 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
import kotlin.jvm.JvmStatic
/**
* Process-wide registry of glyph rasters, fed from the TS side so glyph identity survives to the
* BLE encoder (see notes/texture-cache-display-list- design.md). A frame's glyph list references
* entries here by (fontId, encoding); the resource-cache planner uses the raster three ways:
*
* - as the ink mask for the "would this draw land correctly" check against the composited frame,
* - to punch the ink pixels out of the baked delta rect it replaces,
* - pre-encoded as the CFW cached-image bytes ([flags=RLE][w][h][4bpp RLE]) uploaded as resources and drawn via
* the resource-text draw call with a top-color LUT. 1bpp (BDF) glyphs store ink at 15 so the LUT maps them to exactly
* the requested level; AA (TTF) glyphs store true coverage nibbles the LUT scales.
*
* Fonts are identified by a stable string key (the embedded font name), NOT a per-JS-context
* counter: worker threads register independently and must agree on ids. Glyph rasters are immutable
* once registered; re-registration of the same (fontId, encoding) is ignored.
*
* Cell model: a cached glyph image is bbxWidth x cellHeight (the font's line height), with the ink
* rows at inkTop — so every glyph of a line is drawn at the same y (the line top), which is what
* lets one mode-14 string carry a whole run. The horizontal bearing (bbxX) is applied phone-side
* when computing the draw x. Vertical padding is nearly free: it RLE-encodes to a couple of tokens.
*/
class GlyphAtlas {
companion object {
private val lock = protocolPlatform().createLock()
private val fontIds: MutableMap<String, Int> = HashMap()
private val glyphs: MutableMap<Long, Glyph> = HashMap()
private var nextFontId: Int = 1
/** Stable id for a font key; assigns one on first use. */
@JvmStatic
fun fontId(key: String): Int {
lock.withLock {
var id: Int? = fontIds.get(key)
if ((id == null)) {
id = nextFontId++
fontIds.put(key, id)
}
return id
}
}
@JvmStatic
fun get(fontId: Int, encoding: Int): Glyph? {
lock.withLock {
return glyphs.get(key(fontId, encoding))
}
}
private fun key(fontId: Int, encoding: Int): Long {
return (((fontId).toLong() shl 32) or (encoding.toLong() and 0xffffffffL))
}
/**
* Register a batch of glyph rasters. Little-endian buffer, a sequence of font groups:
* [keyLen u8][key utf8][cellHeight u8][count u16] each followed by count glyph records:
* [encoding u32][bbxX s8][inkTop u8][width u8][inkHeight u8] [inkHeight x rows u32] (bit
* (ceil(width/8)*8 - 1 - col) = ink) Records for an already-registered (font, encoding) are
* skipped (glyph rasters are immutable for a given font key). Malformed buffers throw: they
* indicate a phone-side marshalling bug, never device state.
*/
@JvmStatic
fun register(buffer: ByteReader?): Unit {
if ((buffer == null)) {
return
}
val cursor: ByteReader = buffer
lock.withLock {
while ((cursor.remaining() > 0)) {
var keyLen: Int = (cursor.get() and 0xff)
var keyBytes: ByteArray = ByteArray(keyLen)
cursor.get(keyBytes)
var fontKey: String = keyBytes.decodeToString()
var cellHeight: Int = (cursor.get() and 0xff)
var count: Int = (cursor.getShort().toInt() and 0xffff)
var idBoxed: Int? = fontIds.get(fontKey)
var id: Int = 0
if ((idBoxed == null)) {
id = nextFontId++
fontIds.put(fontKey, id)
} else {
id = idBoxed
}
run {
var g: Int = 0
while ((g < count)) {
var encoding: Int = cursor.getInt()
val bbxX: Int = cursor.get().toInt()
var inkTop: Int = (cursor.get() and 0xff)
var width: Int = (cursor.get() and 0xff)
var inkHeight: Int = (cursor.get() and 0xff)
val rows: IntArray = IntArray(inkHeight)
run {
var r: Int = 0
while ((r < inkHeight)) {
rows[r] = cursor.getInt()
r++
}
}
var k: Long = key(id, encoding)
if (
(((!glyphs.containsKey(k) && (width > 0)) && (cellHeight > 0)) &&
((inkTop + inkHeight) <= cellHeight))
) {
glyphs.put(
k,
Glyph(width, cellHeight, inkTop, inkHeight, bbxX, rows, null),
)
}
g++
}
}
}
}
}
/**
* Register a batch of antialiased (4bpp) glyph rasters, e.g. TTF renders. Same font-group
* framing as register(), but each glyph record carries packed coverage instead of 1bpp
* rows: [encoding u32][bbxX s8][inkTop u8][width u8][inkHeight u8]
* [inkHeight x ceil(width/2) packed bytes, high nibble = left pixel] Nibble values are the
* final 4bpp source levels (the draw-time LUT scales them by the top color).
* Already-registered (font, encoding) records are skipped, as in register().
*/
@JvmStatic
fun registerAa(buffer: ByteReader?): Unit {
if ((buffer == null)) {
return
}
val cursor: ByteReader = buffer
lock.withLock {
while ((cursor.remaining() > 0)) {
var keyLen: Int = (cursor.get() and 0xff)
var keyBytes: ByteArray = ByteArray(keyLen)
cursor.get(keyBytes)
var fontKey: String = keyBytes.decodeToString()
var cellHeight: Int = (cursor.get() and 0xff)
var count: Int = (cursor.getShort().toInt() and 0xffff)
var idBoxed: Int? = fontIds.get(fontKey)
var id: Int = 0
if ((idBoxed == null)) {
id = nextFontId++
fontIds.put(fontKey, id)
} else {
id = idBoxed
}
run {
var g: Int = 0
while ((g < count)) {
var encoding: Int = cursor.getInt()
val bbxX: Int = cursor.get().toInt()
var inkTop: Int = (cursor.get() and 0xff)
var width: Int = (cursor.get() and 0xff)
var inkHeight: Int = (cursor.get() and 0xff)
var stride: Int = ((width + 1) shr 1)
var coverage: ByteArray = ByteArray((width * inkHeight))
run {
var r: Int = 0
while ((r < inkHeight)) {
run {
var b: Int = 0
while ((b < stride)) {
var packed: Int = (cursor.get() and 0xff)
var col: Int = (b * 2)
coverage[((r * width) + col)] =
((packed shr 4)).toByte()
if (((col + 1) < width)) {
coverage[(((r * width) + col) + 1)] =
((packed and 0x0f)).toByte()
}
b++
}
}
r++
}
}
var k: Long = key(id, encoding)
if (
(((!glyphs.containsKey(k) && (width > 0)) && (cellHeight > 0)) &&
((inkTop + inkHeight) <= cellHeight))
) {
glyphs.put(
k,
Glyph(
width,
cellHeight,
inkTop,
inkHeight,
bbxX,
null,
coverage,
),
)
}
g++
}
}
}
}
}
}
constructor() {}
class Glyph {
/** Cached image width in pixels (the glyph's tight bbox width). */
@JvmField val width: Int
/** Cached image height in pixels (the font's line height). */
@JvmField val cellHeight: Int
/** First row of ink within the cell. */
@JvmField val inkTop: Int
/** Number of ink rows. */
@JvmField val inkHeight: Int
/** Horizontal bearing: draw x = pen x + bbxX. */
@JvmField val bbxX: Int
/** 1bpp ink rows (inkHeight entries), bit (rowBitWidth-1-col) = ink; null for AA glyphs. */
@JvmField val rows: IntArray?
@JvmField val rowBitWidth: Int
/** AA coverage, width*inkHeight nibble values 0..15; null for 1bpp glyphs. */
@JvmField val coverage: ByteArray?
/** CFW cached-image bytes: [flags=RLE][w][cellHeight][RLE(w*cellHeight px)]. */
@JvmField val cachedBytes: ByteArray
constructor(
width: Int,
cellHeight: Int,
inkTop: Int,
inkHeight: Int,
bbxX: Int,
rows: IntArray?,
coverage: ByteArray?,
) {
this.width = width
this.cellHeight = cellHeight
this.inkTop = inkTop
this.inkHeight = inkHeight
this.bbxX = bbxX
this.rows = rows
this.coverage = coverage
this.rowBitWidth = (((width + 7) shr 3) shl 3)
this.cachedBytes = encodeCachedImage()
}
/**
* The cell pixel's 4bpp source value at (col, row), row cell-relative. 1bpp glyphs are
* stored at 15 so the draw-time LUT (source*top/15) maps them to exactly the requested top
* color; AA glyphs carry their true coverage level.
*/
fun nibbleAt(col: Int, row: Int): Int {
if (((col < 0) || (col >= width))) {
return 0
}
var inkRow: Int = (row - inkTop)
if (((inkRow < 0) || (inkRow >= inkHeight))) {
return 0
}
if ((coverage != null)) {
return coverage[((inkRow * width) + col)].toInt()
}
return (if ((((rows!![inkRow] ushr ((rowBitWidth - 1) - col)) and 1) != 0)) 15 else 0)
}
/** Whether the cell pixel at (col, row) has any ink (row is cell-relative). */
fun inkAt(col: Int, row: Int): Boolean {
return (nibbleAt(col, row) != 0)
}
/**
* The firmware cached-image encoding: [flags=RLE][width][height][RLE tokens] covering exactly
* width*cellHeight pixels (no row padding), each pixel's stored color being its nibbleAt
* value.
*/
private fun encodeCachedImage(): ByteArray {
var total: Int = (width * cellHeight)
var out: ByteArray = ByteArray((3 + total))
out[0] = DrawProtocol.RLE.toByte()
out[1] = (width).toByte()
out[2] = (cellHeight).toByte()
var o: Int = 3
var i: Int = 0
while ((i < total)) {
var color: Int = nibbleAt((i % width), (i / width))
var j: Int = (i + 1)
while (((j < total) && (nibbleAt((j % width), (j / width)) == color))) {
j++
}
var run: Int = (j - i)
while ((run > 0)) {
var c: Int = minOf(run, 0xffff)
if ((c <= 15)) {
out[o++] = (((c shl 4) or color)).toByte()
} else {
if ((c <= 255)) {
out[o++] = (color).toByte()
out[o++] = (c).toByte()
} else {
out[o++] = (color).toByte()
out[o++] = 0
out[o++] = ((c and 0xff)).toByte()
out[o++] = ((c shr 8)).toByte()
}
}
run -= c
}
i = j
}
var trimmed: ByteArray = ByteArray(o)
out.copyInto(trimmed, 0, 0, 0 + o)
return trimmed
}
}
}
@@ -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,138 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
import kotlin.jvm.JvmStatic
/**
* Process-wide registry of icon/image rasters for the resource-cache pipeline, the image counterpart
* of GlyphAtlas. Entries are content-addressed: the TS side keys each image by a hash of its
* dimensions and pixels, so the same icon registered from any thread or rendered at any time
* dedupes to one entry, and an icon whose content changes is simply a new entry.
*
* Unlike glyphs (1-bit ink recolored at draw time), images keep their exact 4bpp values: the cached
* bytes quantize the registered 8bpp pixels with the same GRAY_TO_NIBBLE table the composite is
* packed with, and the planner draws them via the image draw call with an identity LUT (top color 15) and the
* transparent bit — the draw writes exactly the nonzero-nibble pixels, which is what the
* eligibility check and hole punching are defined over.
*/
class ImageAtlas {
companion object {
private val lock = protocolPlatform().createLock()
private val ids: MutableMap<String, Int> = HashMap()
private val entries: MutableList<Entry> = ArrayList()
/**
* Register an image (8bpp grayscale pixels, width*height bytes, row-major) under a content
* key, returning its id — or the existing id when the key is already registered (the pixels
* are then ignored: same key means same content). Ids are positive and stable for the
* process lifetime.
*/
@JvmStatic
fun ensure(key: String?, width: Int, height: Int, pixels8bpp: ByteReader?): Int {
if (
(((((((key == null) || (width <= 0)) || (width > 255)) || (height <= 0)) ||
(height > 255)) || (pixels8bpp == null)) ||
(pixels8bpp.remaining() < (width * height)))
) {
throw IllegalArgumentException(
((("bad image registration " + width) + "x") + height)
)
}
lock.withLock {
var existing: Int? = ids.get(key)
if ((existing != null)) {
return existing
}
var nibbles: ByteArray = ByteArray((width * height))
run {
var i: Int = 0
while ((i < nibbles.size)) {
nibbles[i] = (BmpUtil.nibbleForGray((pixels8bpp.get(i) and 0xff))).toByte()
i++
}
}
entries.add(Entry(width, height, nibbles))
var id: Int = entries.size
ids.put(key, id)
return id
}
}
@JvmStatic
fun get(id: Int): Entry? {
lock.withLock {
return (if (((id >= 1) && (id <= entries.size))) entries.get((id - 1)) else null)
}
}
}
constructor() {}
class Entry {
@JvmField val width: Int
@JvmField val height: Int
/** One 4bpp value per pixel, row-major. */
@JvmField val nibbles: ByteArray
/** CFW cached-image bytes: [flags=RLE][w][h][RLE(w*h pixels)]. */
@JvmField val cachedBytes: ByteArray
val resource: CachedResource
constructor(width: Int, height: Int, nibbles: ByteArray) {
this.width = width
this.height = height
this.nibbles = nibbles
this.cachedBytes = encodeCachedImage()
this.resource = CachedResource(cachedBytes)
}
/** The 4bpp value the mode-13 draw would write at (col, row); 0 = skipped. */
fun nibbleAt(col: Int, row: Int): Int {
return nibbles[row * width + col].toInt() and 255
}
private fun encodeCachedImage(): ByteArray {
var total: Int = (width * height)
var out: ByteArray = ByteArray((3 + total))
out[0] = DrawProtocol.RLE.toByte()
out[1] = (width).toByte()
out[2] = (height).toByte()
var o: Int = 3
var i: Int = 0
while ((i < total)) {
var color: Int = (nibbles[i] and 0xff)
var j: Int = (i + 1)
while (((j < total) && ((nibbles[j] and 0xff) == color))) {
j++
}
var run: Int = (j - i)
while ((run > 0)) {
var c: Int = minOf(run, 0xffff)
if ((c <= 15)) {
out[o++] = (((c shl 4) or color)).toByte()
} else {
if ((c <= 255)) {
out[o++] = (color).toByte()
out[o++] = (c).toByte()
} else {
out[o++] = (color).toByte()
out[o++] = 0
out[o++] = ((c and 0xff)).toByte()
out[o++] = ((c shr 8)).toByte()
}
}
run -= c
}
i = j
}
var trimmed: ByteArray = ByteArray(o)
out.copyInto(trimmed, 0, 0, 0 + o)
return trimmed
}
}
}
@@ -0,0 +1,250 @@
package com.faceclaw.app
import kotlin.jvm.JvmField
import kotlin.jvm.JvmStatic
/**
* Reader for the serialized LVGL font image in the G2's CJK flash partition. Faceclaw bundles that
* font because it is Source Han Sans SC Light under the SIL OFL. Proprietary fonts embedded in the
* main firmware never pass through this class and are instead extracted on the user's phone during
* CFW install.
*/
class LvglFontFile {
companion object {
private val lock = protocolPlatform().createLock()
private fun load(path: String?): FontData? = lock.withLock {
if (path.isNullOrEmpty()) return null
val cached = fontCache.remove(path)
if (cached != null) {
fontCache[path] = cached
return cached
}
try {
val font = FontData(readFileData(path))
fontCache[path] = font
while (fontCache.size > FONT_CACHE_SIZE) fontCache.remove(fontCache.keys.first())
font
} catch (_: Exception) {
null
}
}
private const val TAG: String = "LvglFontFile"
private const val MAPPED_BASE: Int = -2146435072
private const val FONT_CACHE_SIZE: Int = 2
private val fontCache: MutableMap<String, FontData> = LinkedHashMap<String, FontData>()
/**
* Returns [lineHeight, baseline] or an empty array when the font is invalid. The baseline
* is measured down from the top of the line.
*/
@JvmStatic
fun getMetrics(path: String): ByteArray {
var font: FontData? = load(path)
if ((font == null)) {
return ByteArray(0)
}
return byteArrayOf((font.lineHeight).toByte(), (font.baseline).toByte())
}
/**
* Returns one packed glyph: u16 boxW, u16 boxH, i16 ofsX, i16 ofsY, then aligned 4bpp
* bitmap bytes. Returns an empty array when the code point is not mapped.
*/
@JvmStatic
fun getGlyph(path: String, codePoint: Int): ByteArray {
var font: FontData? = load(path)
if ((font == null)) {
return ByteArray(0)
}
var glyphId: Int? = font.codePointToGlyph.get(codePoint)
if (((glyphId == null) || (glyphId <= 0))) {
return ByteArray(0)
}
try {
var descriptor: Int = (font.glyphDescriptors + (glyphId * 16))
var bitmapIndex: Int = font.u32(descriptor)
var boxWidth: Int = font.u16((descriptor + 8))
var boxHeight: Int = font.u16((descriptor + 10))
var offsetX: Int = font.i16((descriptor + 12))
var offsetY: Int = font.i16((descriptor + 14))
var stride: Int = ((boxWidth / 2) + 1)
var bitmapLength: Int =
(if (((boxWidth > 0) && (boxHeight > 0))) (stride * boxHeight) else 0)
font.check((font.glyphBitmaps + bitmapIndex), bitmapLength)
var result: ByteArray = ByteArray((8 + bitmapLength))
putU16(result, 0, boxWidth)
putU16(result, 2, boxHeight)
putU16(result, 4, offsetX)
putU16(result, 6, offsetY)
font.bytes.copyInto(
result,
8,
(font.glyphBitmaps + bitmapIndex),
(font.glyphBitmaps + bitmapIndex) + bitmapLength,
)
return result
} catch (e: RuntimeException) {
return ByteArray(0)
}
}
private fun putU16(destination: ByteArray, offset: Int, value: Int): Unit {
destination[offset] = ((value and 0xff)).toByte()
destination[(offset + 1)] = (((value ushr 8) and 0xff)).toByte()
}
}
constructor() {}
private class FontData {
@JvmField val bytes: ByteArray
@JvmField val lineHeight: Int
@JvmField val baseline: Int
@JvmField val glyphBitmaps: Int
@JvmField val glyphDescriptors: Int
@JvmField val codePointToGlyph: MutableMap<Int, Int>
constructor(bytes: ByteArray) {
this.bytes = bytes
if (
(((((bytes.size < 0x40) || (bytes[0].toInt() != 90)) || (bytes[1].toInt() != 90)) ||
(bytes[2].toInt() != 90)) || (bytes[3].toInt() != 90))
) {
throw IllegalArgumentException("missing ZZZZ font header")
}
lineHeight = u16(0x38)
var baseLine: Int = u16(0x3a)
baseline = (lineHeight - baseLine)
var descriptor: Int = pointerOffset(u32(0x34))
glyphBitmaps = pointerOffset(u32(descriptor))
glyphDescriptors = pointerOffset(u32((descriptor + 4)))
var cmaps: Int = pointerOffset(u32((descriptor + 8)))
var packed: Int = u16((descriptor + 18))
var cmapCount: Int = (packed and 0x1ff)
var bitsPerPixel: Int = ((packed ushr 9) and 0xf)
var bitmapFormat: Int = ((packed ushr 14) and 0x3)
if (
(((((lineHeight <= 0) || (baseline < 0)) || (cmapCount <= 0)) ||
(bitsPerPixel != 4)) || (bitmapFormat != 3))
) {
throw IllegalArgumentException("unsupported LVGL font metadata")
}
codePointToGlyph = HashMap()
run {
var index: Int = 0
while ((index < cmapCount)) {
readCmap((cmaps + (index * 20)))
index++
}
}
}
fun readCmap(address: Int): Unit {
var rangeStart: Int = u32(address)
var rangeLength: Int = u16((address + 4))
var glyphIdStart: Int = u16((address + 6))
var unicodeListPointer: Int = u32((address + 8))
var glyphIdOffsetsPointer: Int = u32((address + 12))
var listLength: Int = u16((address + 16))
var type: Int = u8((address + 18))
if ((type == 2)) {
run {
var relative: Int = 0
while ((relative < rangeLength)) {
codePointToGlyph.put((rangeStart + relative), (glyphIdStart + relative))
relative++
}
}
return
}
if ((type == 0)) {
var offsets: Int = pointerOffset(glyphIdOffsetsPointer)
run {
var relative: Int = 0
while ((relative < rangeLength)) {
var offset: Int = u8((offsets + relative))
if (((relative != 0) && (offset == 0))) {
relative++
continue
}
codePointToGlyph.put((rangeStart + relative), (glyphIdStart + offset))
relative++
}
}
return
}
if (((type == 3) || (type == 1))) {
var unicodeList: Int = pointerOffset(unicodeListPointer)
var offsets: Int =
(if ((glyphIdOffsetsPointer == 0)) -1 else pointerOffset(glyphIdOffsetsPointer))
run {
var index: Int = 0
while ((index < listLength)) {
var relative: Int = u16((unicodeList + (index * 2)))
var offset: Int = index
if ((offsets >= 0)) {
offset =
(if ((type == 1)) u16((offsets + (index * 2)))
else u8((offsets + index)))
if (((index != 0) && (offset == 0))) {
index++
continue
}
}
codePointToGlyph.put((rangeStart + relative), (glyphIdStart + offset))
index++
}
}
return
}
throw IllegalArgumentException(("unknown cmap type " + type))
}
fun u8(offset: Int): Int {
check(offset, 1)
return (bytes[offset] and 0xff)
}
fun u16(offset: Int): Int {
check(offset, 2)
return ((bytes[offset].toInt() and 255) or ((bytes[offset + 1].toInt() and 255) shl 8))
}
fun i16(offset: Int): Int {
check(offset, 2)
return u16(offset).toShort().toInt()
}
fun u32(offset: Int): Int {
check(offset, 4)
return u16(offset) or (u16(offset + 2) shl 16)
}
fun pointerOffset(pointer: Int): Int {
var unsignedPointer: Long = (pointer.toLong() and 0xffffffffL)
var offset: Long = (unsignedPointer - (MAPPED_BASE.toLong() and 0xffffffffL))
if (((offset < 0) || (offset > Int.MAX_VALUE))) {
throw IllegalArgumentException("font pointer is outside the mapped partition")
}
check((offset).toInt(), 1)
return (offset).toInt()
}
fun check(offset: Int, length: Int): Unit {
if ((((offset < 0) || (length < 0)) || (((offset).toLong() + length) > bytes.size))) {
throw IllegalArgumentException("font range is out of bounds")
}
}
}
}
@@ -0,0 +1,62 @@
package com.faceclaw.app
/** A retained selection or image, replayed at stereo depth over the screen and shell surfaces. */
class MenuSelection(val x: Int, val y: Int, val width: Int, val height: Int, val radius: Int,
val background: Int, val border: Int, val depth: Int, val packed: ByteArray, val occlusions: List<IntArray> = emptyList(), val kind: Int = DrawRecordKind.MENU_SELECTION, val mask: List<IntArray> = emptyList()) : RetainedDrawing {
val resource = CachedResource(DrawProtocol.rawImage(width, height, packed))
override val resources = listOf(resource)
override val fingerprint = "$kind,${mask.joinToString { it.joinToString() }},$x,$y,$width,$height,$radius,$background,$border,$depth,${resource.hash},${occlusions.joinToString { it.joinToString() }}"
override fun translated(dx: Int, dy: Int) = MenuSelection(x + dx, y + dy, width, height, radius, background, border, depth, packed, occlusions.map { intArrayOf(it[0] + dx, it[1] + dy, it[2], it[3]) }, kind, mask)
override fun calls(ids: IntArray, nowMs: Long) = calls(ids.single())
fun calls(id: Int): List<ByteArray> {
val image = when (kind) {
DrawRecordKind.MENU_SELECTION -> listOf(DrawProtocol.roundedRect(x, y, width, height, radius, background, border, depth),
DrawProtocol.image(id, x, y, CFW_TEXTURE_OPT_BRIGHTNESS_MASK or CFW_TEXTURE_OPT_TRANSPARENT, depth = depth))
DrawRecordKind.TRANSPARENT_IMAGE -> listOf(DrawProtocol.image(id, x, y, CFW_TEXTURE_OPT_BRIGHTNESS_MASK or CFW_TEXTURE_OPT_TRANSPARENT, depth = depth))
// Gray8 zero is transparent but gray8 one is opaque black. Rect copies preserve
// that distinction after packing, including the transparent corners of app menus.
DrawRecordKind.MASKED_IMAGE -> mask.map { rect ->
DrawProtocol.rectCopy(id, rect[0], rect[1], rect[2], rect[3],
x + rect[0], y + rect[1], depth = depth)
}
else -> error("Invalid presentation kind")
}
return image + occlusions.map { rect ->
DrawProtocol.rectCopy(DrawProtocol.SCREEN, rect[0], rect[1], rect[2], rect[3], rect[0], rect[1])
}
}
companion object {
/** The caller has consumed a presentation tag from [DrawRecordKind]. Colors and pixels cross in gray8. */
fun read(reader: ByteReader, kind: Int = DrawRecordKind.MENU_SELECTION): MenuSelection {
require(kind in listOf(DrawRecordKind.MENU_SELECTION, DrawRecordKind.TRANSPARENT_IMAGE, DrawRecordKind.MASKED_IMAGE))
require(reader.remaining() >= 15)
val x = reader.getShort().toInt(); val y = reader.getShort().toInt()
val w = reader.getShort().toInt() and 65535; val h = reader.getShort().toInt() and 65535
val radius = reader.getShort().toInt() and 65535
val background = BmpUtil.nibbleForGray(reader.get() and 255)
val border = BmpUtil.nibbleForGray(reader.get() and 255)
val depth = reader.get().toByte().toInt()
val count = reader.getShort().toInt() and 65535
require(count <= 2048)
require(w in 1..640 && h in 1..480 && 5 + (w + 1) / 2 * h <= 65536 && reader.remaining() >= w * h)
val gray = ByteArray(w * h); reader.get(gray)
require(reader.remaining() >= count * 8)
val occlusions = List(count) { IntArray(4) { reader.getShort().toInt() and 65535 } }
val mask = ArrayList<IntArray>()
if (kind == DrawRecordKind.MASKED_IMAGE) for (yy in 0 until h) {
var start = -1
for (xx in 0..w) {
val covered = xx < w && gray[yy * w + xx].toInt() != 0
if (covered && start < 0) start = xx
if (!covered && start >= 0) {
val previous = mask.lastOrNull { it[0] == start && it[2] == xx - start && it[1] + it[3] == yy }
if (previous != null) previous[3]++ else mask.add(intArrayOf(start, yy, xx - start, 1))
start = -1
}
}
}
return MenuSelection(x, y, w, h, radius, background, border, depth, BmpUtil.pack4bppFromGray8(gray, w, h), occlusions, kind, mask)
}
}
}
@@ -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)
}
}
Loaded 100 of 822 files, more files were not shown because too many files have changed in this diff. Show more