@glassly/bluetooth-sdk 0.1.0-dev.99 → 0.2.8-dev.445

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

@@ -0,0 +1,119 @@
+package com.glassly.bluetoothsdk.sgcs
+
+/**
+ * Glassly CFW BLE link speed control (contract revision 26). The firmware
+ * boots on the stock connection profile; the phone can switch each lens to
+ * the 7.5 ms / latency-0 fast profile (slow mode suppressed) and back. The
+ * wire format is pinned by `patches/ble_link.c` in g2flash.
+ *
+ * Phone -> glasses, G2SettingPackage field 127: `['B','L',1,op]`.
+ * Glasses -> phone, field 128 on every settings read reply:
+ *   `['B','L',1, fast, side, wanted, applied, min16, max16, latency16,
+ *     liveInterval16, liveLatency16]`
+ * Intervals are little-endian in 1.25 ms units. Modes: 0xa3 fast, 0xa4 slow,
+ * 0 = update pending. min/max/latency are the profile the last request used;
+ * the live pair is the connection as the central granted it (absent from the
+ * first revision 26 builds, which sent 13 bytes).
+ */
+internal object G2BleLink {
+    const val PROTOCOL_VERSION = 1
+
+    enum class Op(
+        val value: Int,
+    ) {
+        STOCK(0),
+        FAST(1),
+        QUERY(2),
+    }
+
+    sealed class Mode {
+        object Fast : Mode()
+
+        object Slow : Mode()
+
+        object Pending : Mode()
+
+        data class Other(
+            val raw: Int,
+        ) : Mode()
+
+        val label: String
+            get() =
+                when (this) {
+                    Fast -> "fast"
+                    Slow -> "slow"
+                    Pending -> "pending"
+                    is Other -> "0x%02x".format(raw)
+                }
+
+        companion object {
+            fun of(raw: Int): Mode =
+                when (raw) {
+                    0xA3 -> Fast
+                    0xA4 -> Slow
+                    0 -> Pending
+                    else -> Other(raw)
+                }
+        }
+    }
+
+    data class Status(
+        val fast: Boolean,
+        val side: Int,
+        val wanted: Mode,
+        val applied: Mode,
+        /** The profile the last request asked for. */
+        val requestedMinMs: Double,
+        val requestedMaxMs: Double,
+        val requestedLatency: Int,
+        /** What the central granted; null on firmware that predates the field. */
+        val liveIntervalMs: Double?,
+        val liveLatency: Int?,
+    ) {
+        val summary: String
+            get() {
+                val text = StringBuilder()
+                text.append(if (fast) "FAST" else "stock")
+                text.append(" wanted=${wanted.label} applied=${applied.label}")
+                text.append(" requested %.2f-%.2f ms / latency %d".format(requestedMinMs, requestedMaxMs, requestedLatency))
+                if (liveIntervalMs != null && liveLatency != null) {
+                    text.append(" live %.2f ms / latency %d".format(liveIntervalMs, liveLatency))
+                }
+                return text.toString()
+            }
+    }
+
+    // ---------- Encoding (phone -> glasses) ----------
+
+    /**
+     * G2SettingPackage{commandId=1 (DEVICE_RECEIVE_INFO), magic=0, field 127}.
+     * Hand-framed like the firmware's replies: tag 127/wire 2 is 1018 = fa 07.
+     */
+    fun controlPacket(op: Op): ByteArray =
+        byteArrayOf(0x08, 0x01, 0x10, 0x00, 0xFA.toByte(), 0x07, 4, 0x42, 0x4C, PROTOCOL_VERSION.toByte(), op.value.toByte())
+
+    // ---------- Decoding (glasses -> phone) ----------
+
+    fun decodeStatus(data: ByteArray): Status? {
+        if (data.size < 13 || data[0] != 0x42.toByte() || data[1] != 0x4C.toByte() || data[2] != PROTOCOL_VERSION.toByte()) return null
+        val live = data.size >= 17
+        return Status(
+            fast = data[3].toInt() != 0,
+            side = data[4].toInt() and 0xFF,
+            wanted = Mode.of(data[5].toInt() and 0xFF),
+            applied = Mode.of(data[6].toInt() and 0xFF),
+            requestedMinMs = ms(u16(data, 7)),
+            requestedMaxMs = ms(u16(data, 9)),
+            requestedLatency = u16(data, 11),
+            liveIntervalMs = if (live) ms(u16(data, 13)) else null,
+            liveLatency = if (live) u16(data, 15) else null,
+        )
+    }
+
+    private fun ms(units: Int): Double = units * 1.25
+
+    private fun u16(
+        b: ByteArray,
+        i: Int,
+    ): Int = (b[i].toInt() and 0xFF) or ((b[i + 1].toInt() and 0xFF) shl 8)
+}

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

@@ -1,32 +1,35 @@
 package com.glassly.bluetoothsdk.sgcs
 
-/**
- * Stock-vs-Glassly-CFW classification of one G2 settings response's top-level
- * field 100 ("EVENCFW/NN feat feat …"; stock firmware never emits the field).
- *
- * Pure so the identity rules stay unit-testable — they gate the connect
- * banner: legacy text drawn before classification and cleared after it splits
- * draw/clear across render paths, and the stock text container then never
- * leaves the glass.
+/** Firmware identity advertised in settings field 100. Retain its revision for
+ * future protocol changes; current features depend only on the firmware family.
  */
-data class G2CfwClassification(
-    /** null = classified stock. */
-    val capabilityString: String?,
-    val features: List<String>,
-    val protocolVersion: Int,
-) {
-    val isCfw: Boolean get() = capabilityString != null
+data class G2CfwClassification(val family: Family, val capabilityString: String?) {
+    enum class Family { STOCK, UPSTREAM, GLASSLY }
+
+    /** Numeric contract revision, or null for stock/unknown revision text. */
+    val revision: Int?
+        get() = capabilityString?.substringBefore(' ')?.substringAfter('/')?.toIntOrNull()?.takeIf { it > 0 }
+
+    val isCfw: Boolean get() = family != Family.STOCK
+    val isGlassly: Boolean get() = family == Family.GLASSLY
+    val displayName: String? get() = when (family) {
+        Family.STOCK -> null
+        Family.UPSTREAM -> "g2flash CFW"
+        Family.GLASSLY -> revision?.let { "Glassly CFW v$it" } ?: "Glassly CFW"
+    }
 
     companion object {
-        val STOCK = G2CfwClassification(null, emptyList(), 0)
+        val STOCK = G2CfwClassification(Family.STOCK, null)
 
         /**
-         * Classify one settings response. Returns null when the packet proves
-         * nothing: a non-definitive response without the CFW banner (individual
-         * settings packets can legitimately omit the field or arrive truncated),
-         * or an absent banner on a connection already classified CFW — firmware
-         * identity is connection-sticky, and downgrading would reinterpret an
-         * installed mode-6 carrier as a stock BMP.
+         * The one revision gate: everything the app uses (SID-0xf0 transport,
+         * scenes, settle reports, fast BLE link) shipped together in this
+         * firmware line, so nothing older is special-cased; it is treated as stock.
+         */
+        const val MINIMUM_REVISION = 39
+
+        /** Partial settings notifications can omit field 100. Keep the connection's
+         * known identity so a missing field cannot switch the active render path.
          */
         fun classify(
             field100: ByteArray?,
@@ -34,13 +37,11 @@ data class G2CfwClassification(
             currentCapability: String?,
         ): G2CfwClassification? {
             val capability = field100?.toString(Charsets.UTF_8)?.trimEnd('\u0000')
+            if (capability?.startsWith("GLASSLYCFW/") == true) {
+                return G2CfwClassification(Family.GLASSLY, capability)
+            }
             if (capability?.startsWith("EVENCFW/") == true) {
-                val tokens = capability.split(' ').filter { it.isNotEmpty() }
-                return G2CfwClassification(
-                    capabilityString = capability,
-                    features = tokens.drop(1),
-                    protocolVersion = tokens.firstOrNull()?.removePrefix("EVENCFW/")?.toIntOrNull() ?: 0,
-                )
+                return G2CfwClassification(Family.UPSTREAM, capability)
             }
             if (definitive && currentCapability == null) return STOCK
             return null

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

@@ -13,7 +13,6 @@ import android.text.StaticLayout
 import android.text.TextPaint
 import android.util.Base64
 import java.io.ByteArrayOutputStream
-import java.util.zip.DeflaterOutputStream
 import kotlin.math.roundToInt
 
 /** Phone-side full-scene rasterizer for Glassly CFW's direct-framebuffer protocol. */
@@ -34,6 +33,9 @@ internal object G2CfwRenderer {
         val height: Int,
     )
 
+    /** The global setting is 1..3; the firmware placement tables are zero-based. */
+    fun depthLevelForSetting(depth: Int): Int = depth.coerceIn(1, 3) - 1
+
     fun lensBoxes(
         canvasWidth: Int,
         canvasHeight: Int,
@@ -74,6 +76,117 @@ internal object G2CfwRenderer {
      * glyph raster memo survives resets — rasters don't change.
      */
     private val textureCache = G2CfwTextureCache()
+    /**
+     * Retained object cache (modes 37-41); shares the texture cache with the
+     * raster path. Two lens mirrors: while every frame is flat only the left
+     * one is encoded and its SHOW goes to both lenses; the first frame with
+     * global or element depth copies it into the right mirror ([stereoSplit]) and from
+     * then on each lens gets its own SHOW whenever the two encodings differ.
+     */
+    private val scenes = listOf(G2CfwScene(), G2CfwScene())
+    private var stereoSplit = false
+
+    /** One frame of the object cache: the SHOWs to send, in order, each with its lens targets, after the asset [uploads]. */
+    class StereoEncoded(
+        val shows: List<Show>,
+        val uploads: List<ByteArray>,
+        /** False when the frame is the one already on screen (nothing new to send). */
+        val changed: Boolean,
+        val puts: Int,
+        val hits: Int,
+        val tweens: Int,
+    ) {
+        class Show(val payload: ByteArray, val lenses: Int)
+    }
+
+    /**
+     * Encode [frame] as SHOWs of the object cache (plus the asset PUT messages
+     * that must precede them): one SHOW for both lenses while the lens mirrors
+     * agree, else one per lens (element depth shifts the two encodings apart).
+     * [invalidate] means residency is unknown (a send failed): every object the
+     * frame shows is redefined, and the mirrors re-converge. Null when the frame
+     * does not fit the object table or the asset store.
+     */
+    fun encodeVector(
+        frame: SceneFrame,
+        boxes: LensBoxes,
+        cacheGeneration: Int,
+        invalidate: Boolean,
+        inlineText: Boolean,
+        tag: Int? = null,
+    ): StereoEncoded? = synchronized(this) {
+        if (textureCache.generation != cacheGeneration) textureCache.reset(cacheGeneration)
+        if (scenes[0].generation != textureCache.generation) {
+            scenes.forEach { it.reset(textureCache.generation) }
+            stereoSplit = false
+        } else if (invalidate) {
+            scenes.forEach { it.invalidate() }
+            stereoSplit = false
+        }
+        // Both mirrors rasterize the same element pixels: do it once per frame.
+        val rasters = HashMap<String, ByteArray?>()
+        val rasterizeOne: (SceneElement, Int, Int) -> ByteArray? = { element, w, h ->
+            rasters.getOrPut("${element.id}|${element.contentHash}|${w}x$h") {
+                rasterize(SceneFrame(frame.appId, frame.epoch, false, listOf(element.atOrigin()), emptyList(), w, h), w, h)
+            }
+        }
+        val mono = G2CfwScene.MonoFace({ monoCellMetrics(it) }) { cp, size, cw, lh -> monoGlyphRaster(cp, size, cw, lh) }
+        if (!stereoSplit && (boxes.leftX != boxes.rightX || boxes.leftY != boxes.rightY || frame.elements.any { it.depth != 0 })) {
+            scenes[1].adopt(scenes[0])
+            stereoSplit = true
+        }
+        val left = scenes[0].encode(
+            frame, boxes.leftX, boxes.leftY, textureCache, rasterizeOne, inlineText, mono, tag,
+            parallax = if (stereoSplit) 1 else 0,
+        ) ?: return null
+        if (!stereoSplit) {
+            return StereoEncoded(
+                listOf(StereoEncoded.Show(left.payload, G2CfwTransport.LENS_BOTH)), left.uploads, left.changed,
+                left.puts, left.hits, left.tweens,
+            )
+        }
+        val right = scenes[1].encode(frame, boxes.rightX, boxes.rightY, textureCache, rasterizeOne, inlineText, mono, tag, parallax = -1)
+            ?: return null
+        val shows = mutableListOf<StereoEncoded.Show>()
+        if (left.payload.contentEquals(right.payload)) {
+            shows.add(StereoEncoded.Show(left.payload, G2CfwTransport.LENS_BOTH))
+        } else {
+            // A lens whose frame did not change keeps quiet, unless neither changed (then both SHOWs go).
+            val both = left.changed == right.changed
+            if (both || left.changed) shows.add(StereoEncoded.Show(left.payload, G2CfwTransport.LENS_LEFT))
+            if (both || right.changed) shows.add(StereoEncoded.Show(right.payload, G2CfwTransport.LENS_RIGHT))
+        }
+        StereoEncoded(
+            shows, left.uploads + right.uploads, left.changed || right.changed,
+            left.puts + right.puts, left.hits + right.hits, left.tweens + right.tweens,
+        )
+    }
+
+    /** The panel went blank while the cache stayed: hidden objects mid-animation are re-snapped on their next show. */
+    fun sceneHidden() {
+        synchronized(this) { scenes.forEach { it.hidden() } }
+    }
+
+    /** The RESET reply named the store each lens could allocate; predict against the smaller one. */
+    fun setStoreCapacity(bytes: Int) {
+        synchronized(this) { textureCache.storeCapacity = bytes.coerceIn(G2CfwTextureCache.GRANULE, G2CfwTextureCache.STORE_SIZE) }
+    }
+
+    /** A lens answered MISSING: these ids (objects or assets) are redefined on the next frame. */
+    fun forget(ids: Collection<Int>) {
+        synchronized(this) {
+            scenes.forEach { it.forget(ids) }
+
+            textureCache.forget(ids)
+        }
+    }
+
+    /** Upload payloads that were dropped or failed: their assets may not be resident. */
+    fun forgetUploads(payloads: Collection<ByteArray>) {
+        synchronized(this) {
+            textureCache.forget(payloads.flatMap { G2CfwTextureCache.assetIdsInUploadPayload(it) })
+        }
+    }
     private val glyphRasterMemo = mutableMapOf<String, ByteArray>()
 
     private fun monoPaint(fontSize: Float): Paint =
@@ -261,10 +374,13 @@ internal object G2CfwRenderer {
         // A full cache resets between frames (never mid-frame: draws already
         // planned this frame reference the old offsets). Bumping past the
         // caller's generation keeps the caller's own bumps monotonic.
-        if ((useTexGlyphs || useTexImages) && (textureCache.generation != cacheGeneration || textureCache.exhausted)) {
+        if ((useTexGlyphs || useTexImages) && textureCache.generation != cacheGeneration) {
             textureCache.reset(cacheGeneration)
+            scenes.forEach { it.reset(cacheGeneration) }
+            stereoSplit = false
         }
 
+
         var grids: List<MonoGrid> = emptyList()
         val raster: ByteArray
         if (useTexGlyphs) {
@@ -509,7 +625,9 @@ internal object G2CfwRenderer {
             if (grid != null &&
                 elementBoxes.none { it.z > grid.z && it.intersects(rect) }
             ) {
-                val font = textureCache.font(grid.fontSize, grid.cellWidth, grid.lineHeight)
+                val font = textureCache.font(grid.fontSize, grid.cellWidth, grid.lineHeight) { code ->
+                    memoizedGlyphRaster(code, grid.fontSize, grid.cellWidth, grid.lineHeight)
+                }
                 if (font != null) {
                     val r0 = (rect.y - grid.originY) / grid.lineHeight
                     val r1 = (rect.y + rect.h - 1 - grid.originY) / grid.lineHeight
@@ -544,13 +662,7 @@ internal object G2CfwRenderer {
                         }
                         for (col in c0..c1) {
                             val scalar = grid.scalar(row, col)
-                            val resident =
-                                scalar in 32..126 &&
-                                    textureCache.ensureGlyph(font, scalar) {
-                                        memoizedGlyphRaster(
-                                            scalar, grid.fontSize, grid.cellWidth, grid.lineHeight
-                                        )
-                                    }
+                            val resident = scalar in 32..126 && scalar in font.glyphs
                             if (resident) {
                                 flushResidual(col)
                                 if (runChars.isEmpty()) runStartCol = col
@@ -578,7 +690,7 @@ internal object G2CfwRenderer {
                         for ((runX, runY, chars) in newRuns) {
                             val payload =
                                 G2CfwTextureCache.stringRunPayload(
-                                    fontTableOffset = font.tableOffset,
+                                    fontId = font.id,
                                     x = boxes.leftX + runX, y = boxes.leftY + runY,
                                     options = G2CfwTextureCache.OPAQUE_DRAW_OPTIONS, chars = chars,
                                 )
@@ -619,11 +731,11 @@ internal object G2CfwRenderer {
                             gray, (y - candidate.box.y0) * w, w,
                         )
                     }
-                    val offset = textureCache.ensureImage(candidate.key, gray, w, h)
+                    val asset = textureCache.ensureImage(candidate.key, gray, w, h)
                     val draw =
-                        offset?.let {
+                        asset?.let {
                             G2CfwTextureCache.imageDrawPayload(
-                                offset = it,
+                                assetId = it,
                                 x = boxes.leftX + candidate.box.x0,
                                 y = boxes.leftY + candidate.box.y0,
                                 options = G2CfwTextureCache.OPAQUE_DRAW_OPTIONS,
@@ -994,7 +1106,7 @@ internal object G2CfwRenderer {
                 canvas.clipRect(rect)
                 when (element.type) {
                     "text" -> if (!skipBuiltinInk) drawText(canvas, element, rect)
-                    "image" -> decodedImages[index]?.let { drawImage(canvas, it, rect) }
+                    "image" -> decodedImages[index]?.let { drawImage(canvas, it, rect, element.color) }
                 }
 
                 val border = maxOf(if (element.type == "rect") 1 else 0, element.border)
@@ -1064,7 +1176,8 @@ internal object G2CfwRenderer {
         canvas.restoreToCount(save)
     }
 
-    private fun drawImage(canvas: Canvas, bitmap: Bitmap, rect: RectF) {
+    /** [color] is the ink level 0..15 (-1 = as drawn): it scales the pixels, as the texture ramp does on vector firmware. */
+    private fun drawImage(canvas: Canvas, bitmap: Bitmap, rect: RectF, color: Int) {
         val scale = minOf(rect.width() / bitmap.width.coerceAtLeast(1), rect.height() / bitmap.height.coerceAtLeast(1))
         val targetWidth = bitmap.width * scale
         val targetHeight = bitmap.height * scale
@@ -1077,7 +1190,9 @@ internal object G2CfwRenderer {
                 rect.centerX() + targetWidth / 2f,
                 rect.centerY() + targetHeight / 2f,
             ),
-            Paint(Paint.ANTI_ALIAS_FLAG or Paint.FILTER_BITMAP_FLAG),
+            Paint(Paint.ANTI_ALIAS_FLAG or Paint.FILTER_BITMAP_FLAG).apply {
+                if (color >= 0) alpha = color.coerceIn(0, 15) * 255 / 15
+            },
         )
     }
 
@@ -1102,7 +1217,8 @@ internal object G2CfwRenderer {
         h: Int,
         frameId: Int,
     ): ByteArray? {
-        val compressed = zlib(rle) ?: return null
+        if (rle.isEmpty()) return null
+        // Plain RLE: the SID-0xf0 transport deflates the whole message.
         return byteArrayOf(
             0x83.toByte(),
             (lx / 4).toByte(),
@@ -1115,7 +1231,7 @@ internal object G2CfwRenderer {
             (h / 2).toByte(),
             (frameId and 0xFF).toByte(),
             ((frameId ushr 8) and 0xFF).toByte(),
-        ) + compressed
+        ) + rle
     }
 
     fun bundle(segments: List<ByteArray>): ByteArray? {
@@ -1158,15 +1274,12 @@ internal object G2CfwRenderer {
         return encodePixels(panel)
     }
 
-    fun blackPayload(): ByteArray? {
-        val compressed = zlib(rleEncodeSolid(0, FRAME_WIDTH * FRAME_HEIGHT)) ?: return null
-        return byteArrayOf(6) + compressed
-    }
+    fun blackPayload(): ByteArray? = byteArrayOf(6) + rleEncodeSolid(0, FRAME_WIDTH * FRAME_HEIGHT)
 
+    /** `[6][rle]`: plain RLE, the SID-0xf0 transport deflates the whole message. */
     fun encodePixels(grayscale: ByteArray): ByteArray? {
         if (grayscale.size != FRAME_WIDTH * FRAME_HEIGHT) return null
-        val compressed = zlib(rleEncode(pack4Bpp(grayscale))) ?: return null
-        return byteArrayOf(6) + compressed
+        return byteArrayOf(6) + rleEncode(pack4Bpp(grayscale))
     }
 
     /**
@@ -1242,12 +1355,4 @@ internal object G2CfwRenderer {
         }
     }
 
-    private fun zlib(data: ByteArray): ByteArray? =
-        try {
-            ByteArrayOutputStream().also { output ->
-                DeflaterOutputStream(output).use { it.write(data) }
-            }.toByteArray()
-        } catch (_: Exception) {
-            null
-        }
 }