@glassly/bluetooth-sdk 0.1.0-dev.98 → 0.2.8-dev.444

package/android/src/main/java/com/glassly/bluetoothsdk/sgcs/G2CfwTransport.kt

@@ -0,0 +1,402 @@
+package com.glassly.bluetoothsdk.sgcs
+
+import java.io.ByteArrayOutputStream
+import java.util.zip.Deflater
+import kotlinx.coroutines.CompletableDeferred
+
+/**
+ * Private SID-0xf0 message-stream transport of the Glassly CFW (GLASSLYCFW/31,
+ * upstream Faceclaw/10+). Custom commands no longer ride an EvenHub image
+ * container: they are records in a byte stream that the firmware reconstructs
+ * before any TPL reassembly, on whichever lenses the options byte selects (the
+ * other lens receives them over the frame bridge, in arrival order), and each
+ * record is answered with an ACK or NACK notification through the BLE ingress
+ * lens.
+ *
+ * Wire format (see g2flash `patches/message_transport.c`):
+ *
+ * - packet: `[0xAA][0x21][seq][len+2][1][1][0xF0][0][options][stream bytes][crc16 LE]`
+ *   where `options` = lens bits (1 left, 2 right) | 0x80 RESET on the first
+ *   packet of a stream | 0x40 END on its last, `seq` increments per packet
+ *   (uint8 wrap) and the CRC (CCITT-FALSE) covers `options` + stream bytes.
+ *   The stream id is the RESET packet's `seq`.
+ * - record: `[flags][len:u16][crc16 of the plain message:u16][body]` where
+ *   flags = lens bits | 4 COMPRESSED | 8 RESET_CONTEXT. A compressed body is
+ *   the output of one persistent deflate context ending in a SYNC_FLUSH (never
+ *   finished); RESET_CONTEXT tells the glasses to start a fresh inflater, which
+ *   the phone must set whenever its own deflater is new.
+ * - ACK: `[1][stream][ordinal:u16][lens][size:u16][crc:u16]` + up to three
+ *   7-byte history entries of preceding successes; NACK is `[3]...` alone.
+ *
+ * This client sends one record per stream (RESET..END), so every ordinal is 0
+ * and a stream id identifies the message. After a NACK or a timeout the
+ * glasses have dropped their inflater, so the encoder starts a new context and
+ * the next record carries RESET_CONTEXT.
+ */
+internal object G2CfwTransport {
+    const val SERVICE_ID: Byte = 0xF0.toByte()
+    const val LENS_LEFT = 1
+    const val LENS_RIGHT = 2
+    const val LENS_BOTH = 3
+    const val FLAG_COMPRESSED = 4
+    const val FLAG_RESET_CONTEXT = 8
+    const val PACKET_RESET = 0x80
+    const val PACKET_END = 0x40
+    const val ACK_KIND = 1
+    const val NACK_KIND = 3
+    /** GLASSLYCFW/38: an object-cache reply, sent by each lens before its ACK. */
+    const val REPLY_KIND = 5
+    const val MAX_MESSAGE_BYTES = 0xFFFF
+
+    /**
+     * The firmware caps a packet at 252 stream bytes; our writes stay within the
+     * driver's packet payload (`G2BLE.MAX_PACKET_PAYLOAD` = 236: options byte +
+     * chunk + CRC).
+     */
+    const val MAX_CHUNK_BYTES = 233
+
+    fun crc16(bytes: ByteArray, from: Int = 0, to: Int = bytes.size): Int {
+        var crc = 0xFFFF
+        for (i in from until to) {
+            crc = crc xor ((bytes[i].toInt() and 0xFF) shl 8)
+            repeat(8) {
+                crc = if (crc and 0x8000 != 0) ((crc shl 1) xor 0x1021) and 0xFFFF else (crc shl 1) and 0xFFFF
+            }
+        }
+        return crc
+    }
+
+    /**
+     * ACK deadline for a stream: a both-lens stream acks at ~1.1 KB/s once the
+     * right lens has it over the frame bridge (GLASSLYCFW/39), so allow 1 ms per
+     * byte on top of 3.5 s. A tighter deadline times out uploads that are still
+     * landing, and each timeout re-uploads more.
+     */
+    fun ackTimeoutMs(streamBytes: Int): Long = 3500L + streamBytes
+
+    /**
+     * Persistent deflate context: records share dictionary state across
+     * messages, so a keyframe after a delta compresses against it.
+     */
+    class Encoder {
+        private var deflater: Deflater? = null
+        var needsContextReset = true
+            private set
+
+        /** Drop the context: the next record carries RESET_CONTEXT. */
+        fun resetContext() {
+            deflater?.end()
+            deflater = null
+            needsContextReset = true
+        }
+
+        /**
+         * One stream record for `message`, or null when it cannot be framed.
+         * Falls back to an uncompressed record (still resetting the context)
+         * when deflate would not fit the two-byte length.
+         */
+        fun record(message: ByteArray, targets: Int): ByteArray? {
+            if (message.size > MAX_MESSAGE_BYTES || targets and LENS_BOTH.inv() != 0) return null
+            // Each lens inflates only the records addressed to it, so a record for one
+            // lens can neither continue the shared context (the other lens would fall
+            // out of sync) nor be continued from: deflate it from a fresh context and
+            // start fresh again afterwards.
+            val exclusive = targets != LENS_BOTH
+            if (exclusive) resetContext()
+            try {
+                return frame(message, targets, crc16(message))
+            } finally {
+                if (exclusive) resetContext()
+            }
+        }
+
+        private fun frame(message: ByteArray, targets: Int, crc: Int): ByteArray {
+            var flags = targets
+            val compressed = deflateSyncFlush(message)
+            val body: ByteArray
+            if (compressed != null && compressed.size <= MAX_MESSAGE_BYTES) {
+                body = compressed
+                flags = flags or FLAG_COMPRESSED
+                if (needsContextReset) {
+                    flags = flags or FLAG_RESET_CONTEXT
+                    needsContextReset = false
+                }
+            } else {
+                // The glasses cannot resume a context this record skipped.
+                resetContext()
+                body = message
+                flags = flags or FLAG_RESET_CONTEXT
+            }
+            val out = ByteArrayOutputStream(5 + body.size)
+            out.write(flags)
+            out.write(body.size and 0xFF)
+            out.write((body.size ushr 8) and 0xFF)
+            out.write(crc and 0xFF)
+            out.write((crc ushr 8) and 0xFF)
+            out.write(body)
+            return out.toByteArray()
+        }
+
+        private fun deflateSyncFlush(message: ByteArray): ByteArray? {
+            val z = deflater ?: Deflater(Deflater.DEFAULT_COMPRESSION).also {
+                deflater = it
+                needsContextReset = true
+            }
+            return try {
+                z.setInput(message)
+                val out = ByteArrayOutputStream(message.size / 2 + 64)
+                val buffer = ByteArray(8192)
+                do {
+                    val n = z.deflate(buffer, 0, buffer.size, Deflater.SYNC_FLUSH)
+                    out.write(buffer, 0, n)
+                } while (n == buffer.size || !z.needsInput())
+                val bytes = out.toByteArray()
+                if (bytes.size < 4) {
+                    resetContext()
+                    null
+                } else {
+                    bytes
+                }
+            } catch (_: Exception) {
+                resetContext()
+                null
+            }
+        }
+    }
+
+    /**
+     * Split `stream` (one or more records) into SID-0xf0 packets. `sequence` is
+     * the first packet's `seq` and the stream id; packets count up from it.
+     */
+    fun packets(stream: ByteArray, sequence: Int, targets: Int, chunkBytes: Int = MAX_CHUNK_BYTES): List<ByteArray> {
+        val chunk = chunkBytes.coerceIn(1, 252)
+        val packets = mutableListOf<ByteArray>()
+        var offset = 0
+        var index = 0
+        do {
+            val end = minOf(offset + chunk, stream.size)
+            var options = targets and LENS_BOTH
+            if (offset == 0) options = options or PACKET_RESET
+            if (end >= stream.size) options = options or PACKET_END
+            val body = ByteArray(1 + end - offset)
+            body[0] = options.toByte()
+            System.arraycopy(stream, offset, body, 1, end - offset)
+            val crc = crc16(body)
+            val packet = ByteArray(10 + body.size)
+            packet[0] = 0xAA.toByte()
+            packet[1] = 0x21
+            packet[2] = ((sequence + index) and 0xFF).toByte()
+            packet[3] = (body.size + 2).toByte()
+            packet[4] = 1
+            packet[5] = 1
+            packet[6] = SERVICE_ID
+            packet[7] = 0
+            System.arraycopy(body, 0, packet, 8, body.size)
+            packet[8 + body.size] = (crc and 0xFF).toByte()
+            packet[9 + body.size] = ((crc ushr 8) and 0xFF).toByte()
+            packets.add(packet)
+            index += 1
+            offset = end
+        } while (offset < stream.size)
+        return packets
+    }
+
+    data class AckEntry(val streamId: Int, val ordinal: Int, val size: Int, val crc: Int)
+
+    /** The message this reply is about ([entries] first), then preceding successes. */
+    data class Ack(val success: Boolean, val lens: Int, val entries: List<AckEntry>) {
+        val current: AckEntry get() = entries[0]
+    }
+
+    private fun u16(b: ByteArray, i: Int): Int = (b[i].toInt() and 0xFF) or ((b[i + 1].toInt() and 0xFF) shl 8)
+
+    /** Parse a reply body (the packet payload with header and CRC stripped). */
+    fun parseAck(b: ByteArray): Ack? {
+        if (b.size < 9 || (b.size - 9) % 7 != 0 || b.size > 9 + 3 * 7) return null
+        val kind = b[0].toInt() and 0xFF
+        val lens = b[4].toInt() and 0xFF
+        if (kind != ACK_KIND && kind != NACK_KIND) return null
+        if (lens != LENS_LEFT && lens != LENS_RIGHT) return null
+        if (kind == NACK_KIND && b.size != 9) return null
+        val entries = mutableListOf(AckEntry(b[1].toInt() and 0xFF, u16(b, 2), u16(b, 5), u16(b, 7)))
+        var i = 9
+        while (i < b.size) {
+            entries.add(AckEntry(b[i].toInt() and 0xFF, u16(b, i + 1), u16(b, i + 3), u16(b, i + 5)))
+            i += 7
+        }
+        return Ack(kind == ACK_KIND, lens, entries)
+    }
+
+    /**
+     * Object-cache reply (GLASSLYCFW/38): `[5][stream][ordinal:u16][lens]` then
+     * `[mode][request:u16][status][epoch:u16][revision:u32][extra]`.
+     */
+    data class CacheReply(
+        val streamId: Int, val ordinal: Int, val lens: Int, val mode: Int, val request: Int,
+        val status: Int, val epoch: Int, val revision: Long, val extra: ByteArray,
+    ) {
+        companion object {
+            const val APPLIED = 0
+            const val STALE = 1
+            const val MISSING = 2
+            const val CAPACITY = 3
+            const val REFUSED = 4
+            const val UNCHANGED = 5
+            const val DELTA = 6
+            const val SNAPSHOT = 7
+            const val RESET = 8
+            private val NAMES = listOf("applied", "stale", "missing", "capacity", "refused", "unchanged", "delta", "snapshot", "reset")
+        }
+
+        /** A RESET reply's store size in bytes (0 when the reply did not carry it). */
+        val storeBytes: Int
+            get() = if (mode == 41 && status == APPLIED && extra.size >= 3) ((extra[1].toInt() and 0xFF) or ((extra[2].toInt() and 0xFF) shl 8)) * 1024 else 0
+
+        /** Ids a MISSING reply names (objects and assets share the field). */
+        val missingIds: List<Int>
+            get() {
+                if (status != MISSING || extra.size < 2) return emptyList()
+                val out = mutableListOf<Int>()
+                var i = 2
+                while (i + 4 <= extra.size) {
+                    out.add((extra[i].toInt() and 0xFF) or ((extra[i + 1].toInt() and 0xFF) shl 8) or ((extra[i + 2].toInt() and 0xFF) shl 16) or ((extra[i + 3].toInt() and 0xFF) shl 24))
+                    i += 4
+                }
+                return out
+            }
+
+        val summary: String
+            get() {
+                val name = NAMES.getOrNull(status) ?: "status $status"
+                return when (status) {
+                    MISSING -> "$name $missingIds"
+                    REFUSED -> "$name reason ${extra.firstOrNull()?.toInt() ?: 0}"
+                    APPLIED, CAPACITY -> if ((extra.firstOrNull()?.toInt() ?: 0) > 0) "$name, evicted ${extra[0].toInt()}" else name
+                    else -> name
+                }
+            }
+    }
+
+    fun parseCacheReply(b: ByteArray): CacheReply? {
+        if (b.size < 15 || (b[0].toInt() and 0xFF) != REPLY_KIND) return null
+        val lens = b[4].toInt() and 0xFF
+        if (lens != LENS_LEFT && lens != LENS_RIGHT) return null
+        val revision = (u16(b, 11).toLong() or (u16(b, 13).toLong() shl 16))
+        return CacheReply(b[1].toInt() and 0xFF, u16(b, 2), lens, b[5].toInt() and 0xFF, u16(b, 6), b[8].toInt() and 0xFF, u16(b, 9), revision, b.copyOfRange(15, b.size))
+    }
+
+    /** True for messages of the object cache (modes 37-41), which carry an epoch and a request id. */
+    fun isCacheMessage(message: ByteArray): Boolean = message.size >= 5 && (message[0].toInt() and 0xFF) in 37..41
+
+    /**
+     * Copy of a cache message with the session epoch filled in and, when the encoder left
+     * the request id 0 (never for STATE, whose bytes are the revision), `request` stamped:
+     * the firmware acknowledges a SHOW or HIDE repeating the last applied request id
+     * without applying it again, so every distinct message needs its own.
+     */
+    fun stamp(message: ByteArray, epoch: Int, request: Int): ByteArray {
+        if (!isCacheMessage(message)) return message
+        val out = message.copyOf()
+        out[1] = (epoch and 0xFF).toByte()
+        out[2] = ((epoch ushr 8) and 0xFF).toByte()
+        if ((out[0].toInt() and 0xFF) != 40 && out[3].toInt() == 0 && out[4].toInt() == 0 && request != 0) {
+            out[3] = (request and 0xFF).toByte()
+            out[4] = ((request ushr 8) and 0xFF).toByte()
+        }
+        return out
+    }
+
+    /**
+     * Read-only, single-packet parse of a raw notify frame: the reply body if
+     * this is a complete SID-0xf0 frame with a valid CRC.
+     */
+    fun replyBody(raw: ByteArray): ByteArray? {
+        if (raw.size < 10) return null
+        if (raw[0] != 0xAA.toByte() || (raw[3].toInt() and 0xFF) + 8 != raw.size) return null
+        if (raw[4].toInt() != 1 || raw[5].toInt() != 1 || raw[6] != SERVICE_ID) return null
+        if (((raw[7].toInt() and 0xFF) shr 1) and 0x0F != 0) return null
+        val body = raw.copyOfRange(8, raw.size - 2)
+        val crc = crc16(body)
+        if (raw[raw.size - 2] != (crc and 0xFF).toByte() || raw[raw.size - 1] != ((crc ushr 8) and 0xFF).toByte()) return null
+        return body
+    }
+}
+
+/**
+ * The single in-flight stream ACK, completed on the BLE callback thread. A
+ * message sent to both lenses completes when each lens has acked it; any
+ * NACK fails it. Completing a finished deferred is a no-op, so duplicate and
+ * stale replies are harmless.
+ */
+internal class G2CfwAckBox {
+    @Volatile private var streamId: Int? = null
+    @Volatile private var expectedLenses = 0
+    @Volatile private var ackedLenses = 0
+    @Volatile private var pending: CompletableDeferred<Boolean>? = null
+    @Volatile var lastSuccessMs: Long = 0
+        private set
+    @Volatile var lastOutcome: String = ""
+        private set
+    private val replies = mutableMapOf<Int, G2CfwTransport.CacheReply>()
+
+    /** The cache replies the last message drew, by lens (1 left, 2 right). */
+    @Synchronized
+    fun cacheReplies(): Map<Int, G2CfwTransport.CacheReply> = replies.toMap()
+
+    /** Feed one cache reply; it is kept when it belongs to the armed stream. */
+    @Synchronized
+    fun record(reply: G2CfwTransport.CacheReply) {
+        val armed = streamId ?: return
+        if (armed == reply.streamId && reply.ordinal == 0) replies[reply.lens] = reply
+    }
+
+    /** Arm for `streamId`; returns the deferred to await after sending. */
+    @Synchronized
+    fun arm(streamId: Int, lenses: Int): CompletableDeferred<Boolean> {
+        val deferred = CompletableDeferred<Boolean>()
+        this.streamId = streamId
+        expectedLenses = lenses and G2CfwTransport.LENS_BOTH
+        ackedLenses = 0
+        pending = deferred
+        lastOutcome = ""
+        replies.clear()
+        return deferred
+    }
+
+    /** Queue guard scoped to this arm, even when an 8-bit stream ID is reused. */
+    @Synchronized
+    fun isPending(deferred: CompletableDeferred<Boolean>): Boolean = pending === deferred && deferred.isActive
+
+    /** Forget `deferred` if it is still the armed one (after its await ended). */
+    @Synchronized
+    fun disarm(deferred: CompletableDeferred<Boolean>, outcome: String) {
+        if (pending === deferred) {
+            pending = null
+            streamId = null
+            if (lastOutcome.isEmpty()) lastOutcome = outcome
+        }
+    }
+
+    /** Feed one reply. Returns true when it resolved the in-flight message. */
+    @Synchronized
+    fun resolve(ack: G2CfwTransport.Ack): Boolean {
+        val deferred = pending ?: return false
+        val armed = streamId ?: return false
+        if (armed != ack.current.streamId || ack.current.ordinal != 0) return false
+        if (!ack.success) {
+            lastOutcome = "nack"
+            pending = null
+            streamId = null
+            deferred.complete(false)
+            return true
+        }
+        ackedLenses = ackedLenses or (ack.lens and expectedLenses)
+        if (ackedLenses != expectedLenses) return false
+        lastOutcome = "ack"
+        lastSuccessMs = System.currentTimeMillis()
+        pending = null
+        streamId = null
+        deferred.complete(true)
+        return true
+    }
+}

package/android/src/main/java/com/glassly/bluetoothsdk/sgcs/G2DisplayDiagnostics.kt

@@ -0,0 +1,84 @@
+package com.glassly.bluetoothsdk.sgcs
+
+import java.util.UUID
+
+/**
+ * Bounded aggregates shared by the BLE writer and main thread; never retain payloads.
+ * Lines stay small: a sample is logged only for a window with display work, a
+ * backlog or a late tick; zero, false and empty values and sub-millisecond
+ * timings are left out; the link's fixed facts go in a separate session line.
+ */
+internal class G2DisplayDiagnostics(private var startedAt: Long) {
+    companion object {
+        /** Link upkeep that runs whether or not anything is drawn: IMU reports, touch debouncing and heartbeat writes alone leave a window idle. */
+        private val AMBIENT_COUNTERS = setOf("imuReceived", "touchDebounced", "txBytes", "txPackets")
+        private val AMBIENT_TIMINGS = setOf("notifyDispatchMs", "writeQueueMs")
+        /** A tick this late means the main thread or the process was held up: logged even when idle. */
+        const val STRETCHED_WINDOW_MS = 2000L
+        /** The session line is repeated this often so a trimmed log excerpt still has it. */
+        const val SESSION_REPEAT_MS = 60_000L
+    }
+
+    private data class Timing(var count: Int = 0, var total: Long = 0, var maximum: Long = 0)
+    private val counters = mutableMapOf<String, Int>()
+    private val timings = mutableMapOf<String, Timing>()
+    /** Short: it is on every line, and only has to tell apart the runs in one log. */
+    private val run = UUID.randomUUID().toString().take(8)
+    private var sequence = 0
+    private var sessionKey: Map<String, Any>? = null
+    private var lastSession = 0L
+
+    @Synchronized fun count(name: String, amount: Int = 1) {
+        counters[name] = (counters[name] ?: 0) + amount
+    }
+
+    @Synchronized fun timing(name: String, milliseconds: Long) {
+        val value = milliseconds.coerceAtLeast(0)
+        val timing = timings.getOrPut(name) { Timing() }
+        timing.count++
+        timing.total += value
+        timing.maximum = maxOf(timing.maximum, value)
+    }
+
+    /** The link's fixed facts: logged when they change and once a minute, instead of on every sample. */
+    @Synchronized fun session(now: Long, timestamp: Long, facts: Map<String, Any>): Map<String, Any>? {
+        if (facts == sessionKey && now - lastSession < SESSION_REPEAT_MS) return null
+        sessionKey = facts
+        lastSession = now
+        return facts + record("session", timestamp)
+    }
+
+    /** The window's summary, or null when it is not due or was idle. `busy` means something is queued for the glasses. */
+    @Synchronized fun sample(now: Long, timestamp: Long, context: Map<String, Any>, busy: Boolean = false): Map<String, Any>? {
+        val elapsed = now - startedAt
+        if (elapsed < 1000) return null
+        startedAt = now
+        val counters = counters.toMap()
+        val timings = timings.toMap()
+        this.counters.clear()
+        this.timings.clear()
+        val active = busy || elapsed >= STRETCHED_WINDOW_MS ||
+            counters.keys.any { it !in AMBIENT_COUNTERS } || timings.keys.any { it !in AMBIENT_TIMINGS }
+        if (!active) return null
+        val fields = context.toMutableMap()
+        fields["windowMs"] = elapsed
+        fields.putAll(counters)
+        // A timing that never reached a millisecond shows no delay: left out.
+        for ((key, value) in timings) {
+            if (value.maximum < 1) continue
+            fields[key + "Avg"] = Math.round(value.total * 10.0 / value.count) / 10.0
+            fields[key + "Max"] = value.maximum
+        }
+        return fields.filterValues { !isEmpty(it) } + record("sample", timestamp)
+    }
+
+    private fun record(type: String, timestamp: Long): Map<String, Any> =
+        mapOf("v" to 1, "run" to run, "id" to ++sequence, "t" to timestamp, "type" to type)
+
+    private fun isEmpty(value: Any): Boolean = when (value) {
+        is Boolean -> !value
+        is Number -> value.toDouble() == 0.0
+        is String -> value.isEmpty()
+        else -> false
+    }
+}

package/android/src/main/java/com/glassly/bluetoothsdk/sgcs/G2FlashProtocol.kt

@@ -43,9 +43,9 @@ internal object G2FlashProtocol {
 
     val goldenStock =
         GoldenVector(
-            sha256 = "a03fbea9f68a9de6bc271daabb9f3a41c59053d1086622c76a4e990f829cc561",
-            ps = 3_697_284,
-            progEnd = 0x007B_EA64,
+            sha256 = "187ccf2bcc5c17a212106e8a376745511e8289c4232b634a7ea94b9bf25a0979",
+            ps = 3_758_720,
+            progEnd = 0x007C_DA60,
             pass = true,
         )
 

package/android/src/main/java/com/glassly/bluetoothsdk/sgcs/G2Flasher.kt

@@ -40,18 +40,18 @@ internal object G2FirmwareCatalog {
             G2FirmwareArtifact(
                 id = "stock",
                 displayName = "Stock firmware",
-                version = "2.2.9.22",
-                fileName = "g2-stock-2.2.9.22.evenota.bin",
-                sha256 = "a03fbea9f68a9de6bc271daabb9f3a41c59053d1086622c76a4e990f829cc561",
-                size = 4_476_518,
+                version = "2.3.0.24",
+                fileName = "g2-stock-2.3.0.24.evenota.bin",
+                sha256 = "187ccf2bcc5c17a212106e8a376745511e8289c4232b634a7ea94b9bf25a0979",
+                size = 4_537_963,
             ),
             G2FirmwareArtifact(
                 id = "glassly-cfw",
-                displayName = "Glassly CFW",
-                version = "2.2.9.22 CFW",
-                fileName = "g2-glassly-cfw-2.2.9.22.evenota.bin",
-                sha256 = "ceeede999529505ebc0a1369f57ab3c941273379a90b16669ccd39cc6bd99135",
-                size = 4_515_846,
+                displayName = "Glassly CFW v39",
+                version = "2.3.0.24",
+                fileName = "g2-glassly-cfw-2.3.0.24.evenota.bin",
+                sha256 = "4c7bf9a552df1a42f26b3378425c7c2121ca4058fed7283ec863c3f8d2cd13fe",
+                size = 4_661_963,
             ),
         )