@mentra/bluetooth-sdk 0.1.18 → 0.1.20

package/android/src/main/java/com/mentra/bluetoothsdk/sgcs/SGCManager.kt

@@ -6,6 +6,39 @@ import com.mentra.bluetoothsdk.DeviceStore
 import com.mentra.bluetoothsdk.PhotoRequest
 import com.mentra.bluetoothsdk.utils.ConnTypes
 
+/**
+ * One element of a scene frame (display.render()). Geometry is raw pixels on
+ * the device's drawable canvas; `change` is the host differ's annotation
+ * against the previous frame sent to this device.
+ */
+data class SceneElement(
+        val id: String,
+        val type: String, // "text" | "rect" | "image"
+        val x: Int,
+        val y: Int,
+        val w: Int,
+        val h: Int,
+        val text: String?,
+        val data: String?, // base64 image pixels (SGC decodes → re-encodes to wire format)
+        val border: Int,
+        val radius: Int,
+        val change: String, // "created" | "updated" | "moved" | "unchanged"
+        val contentHash: String
+)
+
+/**
+ * A whole scene from the host pipeline — the full frame plus per-element change
+ * annotations and host-computed removes. Full-frame consumers can serialize
+ * `elements` and ignore the annotations; per-element consumers walk them.
+ */
+data class SceneFrame(
+        val appId: String,
+        val epoch: Int,
+        val replay: Boolean,
+        val elements: List<SceneElement>,
+        val removed: List<String>
+)
+
 abstract class SGCManager {
     // Hard coded device properties:
     @JvmField var type: String = ""
@@ -91,6 +124,107 @@ abstract class SGCManager {
             borderWidth: Int = 0,
             borderRadius: Int = 0
     ) {}
+
+    /**
+     * Retained-mode layout element (bitmap). Like [displayBitmap] but tagged with a stable
+     * [elementId] within a [layoutId] scene, so an SGC that supports it (Nex) can diff:
+     * same id -> update in place, new id -> create, new layoutId -> clear the previous scene.
+     * Default: ignore the ids and behave exactly like [displayBitmap].
+     */
+    open fun drawLayoutBitmap(
+            base64ImageData: String,
+            x: Int,
+            y: Int,
+            width: Int,
+            height: Int,
+            elementId: String,
+            layoutId: String?
+    ): Boolean = displayBitmap(base64ImageData, x, y, width, height)
+
+    /** Retained-mode layout element (text). Default: behave like [sendPositionedText]. */
+    open fun drawLayoutText(
+            text: String,
+            x: Int,
+            y: Int,
+            width: Int,
+            height: Int,
+            borderWidth: Int,
+            borderRadius: Int,
+            elementId: String,
+            layoutId: String?
+    ) = sendPositionedText(text, x, y, width, height, borderWidth, borderRadius)
+
+    /** Remove a retained layout element by id. Default: no-op (SGC doesn't support layouts). */
+    open fun removeLayoutElement(elementId: String, layoutId: String?) {}
+
+    /**
+     * Apply a whole scene frame from the host pipeline (display.render()).
+     *
+     * The host has already diffed the scene against what it last sent, so each
+     * element arrives annotated (created/updated/moved/unchanged) and `removed`
+     * lists what disappeared. This default implementation is fully generic:
+     *
+     *  - PAINT-THEN-SWEEP: creates/updates/moves first (new content lands over
+     *    or beside old), removes LAST — so a scene transition never shows a
+     *    blank interval.
+     *  - "unchanged" elements are skipped entirely (the host diff is the truth;
+     *    this is also what prevents image re-uploads over BLE).
+     *  - `replay` frames arrive all-"created" after a reconnect/recovery —
+     *    [onSceneReplay] lets an SGC reset its component registry first so
+     *    creates take the create path (updates to dead firmware ids are dropped
+     *    silently by hardware).
+     *  - rects compile to empty bordered text boxes (no shape primitive on
+     *    current targets); a rect always gets a visible border.
+     *
+     * SGCs with per-element verbs (G2, Mentra Display) just implement
+     * [drawLayoutText]/[drawLayoutBitmap]/[removeLayoutElement]. A full-frame
+     * device (e.g. NIMO-style) overrides this whole method instead and
+     * serializes [SceneFrame.elements], ignoring the annotations.
+     */
+    open fun applySceneFrame(frame: SceneFrame) {
+        if (frame.replay) {
+            onSceneReplay(frame.appId)
+        }
+        // An id in `removed` that ALSO appears in `elements` is a type change
+        // (the differ keys matches by type:id). Its removal must run BEFORE the
+        // paint — registries key by id, so a post-paint sweep would delete the
+        // just-painted replacement.
+        val paintedIds = frame.elements.mapTo(HashSet()) { it.id }
+        for (id in frame.removed) {
+            if (id in paintedIds) removeLayoutElement(id, frame.appId)
+        }
+        for (el in frame.elements) {
+            if (!frame.replay && el.change == "unchanged") continue
+            when (el.type) {
+                "text" ->
+                    drawLayoutText(el.text ?: "", el.x, el.y, el.w, el.h, el.border, el.radius, el.id, frame.appId)
+                "rect" ->
+                    drawLayoutText("", el.x, el.y, el.w, el.h, maxOf(1, el.border), el.radius, el.id, frame.appId)
+                "image" ->
+                    el.data?.let { drawLayoutBitmap(it, el.x, el.y, el.w, el.h, el.id, frame.appId) }
+                else -> Bridge.log("SGC: applySceneFrame: unknown element type ${el.type}")
+            }
+        }
+        for (id in frame.removed) {
+            if (id !in paintedIds) removeLayoutElement(id, frame.appId)
+        }
+    }
+
+    /**
+     * A replay frame is about to repaint from scratch — forget any retained
+     * component bookkeeping for [appId] so "created" elements take the create
+     * path. Default: no-op.
+     */
+    open fun onSceneReplay(appId: String) {}
+
+    /**
+     * Remove a set of scene elements (scene→legacy handoff: a legacy layout is
+     * about to draw and the previous scene's elements must not linger under it).
+     */
+    open fun clearSceneElements(elementIds: List<String>) {
+        for (id in elementIds) removeLayoutElement(id, null)
+    }
+
     abstract fun showDashboard()
     abstract fun setDashboardPosition(height: Int, depth: Int)
 

package/android/src/main/java/com/mentra/bluetoothsdk/status/DeviceStatus.kt

@@ -255,7 +255,6 @@ internal data class BluetoothStatus(
     val shouldSendPcm: Boolean,
     val shouldSendLc3: Boolean,
     val shouldSendTranscript: Boolean,
-    val offlineCaptionsRunning: Boolean,
     val localSttFallbackActive: Boolean,
     val shouldSendBootingMessage: Boolean,
 ) {
@@ -307,7 +306,6 @@ internal data class BluetoothStatus(
             "should_send_pcm" to shouldSendPcm,
             "should_send_lc3" to shouldSendLc3,
             "should_send_transcript" to shouldSendTranscript,
-            "offline_captions_running" to offlineCaptionsRunning,
             "local_stt_fallback_active" to localSttFallbackActive,
             "shouldSendBootingMessage" to shouldSendBootingMessage,
         )
@@ -354,7 +352,6 @@ internal data class BluetoothStatus(
                 shouldSendPcm = boolValue(values, "should_send_pcm") ?: false,
                 shouldSendLc3 = boolValue(values, "should_send_lc3") ?: false,
                 shouldSendTranscript = boolValue(values, "should_send_transcript") ?: false,
-                offlineCaptionsRunning = boolValue(values, "offline_captions_running") ?: false,
                 localSttFallbackActive = boolValue(values, "local_stt_fallback_active") ?: false,
                 shouldSendBootingMessage = boolValue(values, "shouldSendBootingMessage") ?: true,
             )
@@ -558,7 +555,6 @@ internal data class BluetoothStatusUpdate(
     val shouldSendPcm: Boolean? = null,
     val shouldSendLc3: Boolean? = null,
     val shouldSendTranscript: Boolean? = null,
-    val offlineCaptionsRunning: Boolean? = null,
     val localSttFallbackActive: Boolean? = null,
     val shouldSendBootingMessage: Boolean? = null,
 ) {
@@ -600,7 +596,6 @@ internal data class BluetoothStatusUpdate(
             putIfNotNull("should_send_pcm", shouldSendPcm)
             putIfNotNull("should_send_lc3", shouldSendLc3)
             putIfNotNull("should_send_transcript", shouldSendTranscript)
-            putIfNotNull("offline_captions_running", offlineCaptionsRunning)
             putIfNotNull("local_stt_fallback_active", localSttFallbackActive)
             putIfNotNull("shouldSendBootingMessage", shouldSendBootingMessage)
         }
@@ -650,7 +645,6 @@ internal data class BluetoothStatusUpdate(
                 shouldSendPcm = optionalBoolValue(values, "should_send_pcm"),
                 shouldSendLc3 = optionalBoolValue(values, "should_send_lc3"),
                 shouldSendTranscript = optionalBoolValue(values, "should_send_transcript"),
-                offlineCaptionsRunning = optionalBoolValue(values, "offline_captions_running"),
                 localSttFallbackActive = optionalBoolValue(values, "local_stt_fallback_active"),
                 shouldSendBootingMessage = optionalBoolValue(values, "shouldSendBootingMessage"),
             )

package/android/src/main/java/com/mentra/bluetoothsdk/types/DeviceModels.kt

@@ -2,7 +2,6 @@ package com.mentra.bluetoothsdk
 
 import com.mentra.bluetoothsdk.utils.ControllerTypes
 import com.mentra.bluetoothsdk.utils.DeviceTypes
-import expo.modules.kotlin.exception.CodedException
 
 data class MentraBluetoothSdkConfig @JvmOverloads constructor(
     val deliverCallbacksOnMainThread: Boolean = true,
@@ -10,10 +9,10 @@ data class MentraBluetoothSdkConfig @JvmOverloads constructor(
 )
 
 class BluetoothSdkException(
-    code: String,
+    val code: String,
     message: String,
     cause: Throwable? = null,
-) : CodedException(code, message, cause)
+) : IllegalStateException(message, cause)
 
 enum class DeviceModel(val deviceType: String) {
     G1(DeviceTypes.G1),