@mentra/bluetooth-sdk 3.2.1-dev.314 → 3.2.1

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

@@ -0,0 +1,180 @@
+package com.mentra.bluetoothsdk.sgcs
+
+/** Serialized business-command state machine. An ACK means acceptance, never visible pixels. */
+internal class NimoCanvasSession {
+  sealed class Action {
+    data class Send(val key: Int, val frame: ByteArray, val ticket: Long) : Action()
+    data class Reconnect(val reason: String) : Action()
+    data class Rejected(val status: Int) : Action()
+  }
+  private data class Flight(val key: Int, val frame: ByteArray, val ticket: Long)
+  private var ready = false
+  private var transportReady = false
+  private var active = false
+  private var held = false
+  private var locked = false
+  private var launchBlocked = false
+  private var waitingReadiness = false
+  private var observedNotReady = false
+  private var readinessRetries = 0
+  private var probeRetries = 0
+  private var exitRequested = false
+  private var desired: ByteArray? = null
+  private var accepted: ByteArray? = null
+  private var rejected: ByteArray? = null
+  private var scope: String? = null
+  private var forceRevision = 0L
+  private var sentRevision = 0L
+  private var ticket = 0L
+  private var flight: Flight? = null
+
+  fun offer(frame: ByteArray, scope: String, force: Boolean = false): List<Action> {
+    require(frame.size in 3..(NimoCanvasCodec.MAX_STREAM - 8))
+    if (this.scope != scope || force) forceRevision++
+    this.scope = scope
+    desired = frame.copyOf()
+    exitRequested = false
+    return pump()
+  }
+
+  /** Enter a blank canvas on a fresh connection unless a newer host scene is retained. */
+  fun activate(): List<Action> {
+    if (desired == null) desired = byteArrayOf(0, 0, 1)
+    exitRequested = false
+    return pump()
+  }
+
+  /** Launch itself checks peer readiness in firmware. Retry only explicit NOT_READY,
+   * with a small budget; never retry an ambiguous/missing business ACK on this link. */
+  fun retryNotReady(): List<Action> {
+    if (!transportReady || !waitingReadiness || desired == null || probeRetries >= 3) return emptyList()
+    probeRetries++
+    waitingReadiness = false
+    ready = true
+    return pump()
+  }
+
+  /** Debug capture seam; production behavior is unchanged unless explicitly held. */
+  fun hold(value: Boolean, resume: Boolean = true): List<Action> {
+    held = value
+    return if (!value && resume) pump() else emptyList()
+  }
+
+  fun currentScope(): String? = scope
+
+  fun readiness(value: Boolean): List<Action> = updateReadiness(value, confirmed = false)
+
+  /** Newly received device predicates, not a replay of cached heartbeat state.
+   * The caller validates the report and discards traffic from older bearers. */
+  fun confirmedReadiness(value: Boolean): List<Action> = updateReadiness(value, confirmed = true)
+
+  private fun updateReadiness(value: Boolean, confirmed: Boolean): List<Action> {
+    transportReady = value
+    if (!value) { readinessRetries = 0; probeRetries = 0 }
+    if (!value && flight != null) return resetLink("Readiness lost during canvas command")
+    if (waitingReadiness) {
+      if (!value) observedNotReady = true
+      else if (!observedNotReady) {
+        if (!confirmed || readinessRetries >= 3) return emptyList()
+        readinessRetries++
+      }
+    }
+    ready = value
+    if (!value) { active = false; accepted = null }
+    if (value) waitingReadiness = false
+    return pump()
+  }
+
+  /** A new transport generation has no accepted frame. Retain only the latest desired scene. */
+  fun disconnected() {
+    ready = false; transportReady = false; active = false; held = false; locked = false; launchBlocked = false
+    waitingReadiness = false; observedNotReady = false
+    readinessRetries = 0; probeRetries = 0
+    accepted = null; rejected = null; flight = null; ticket++; forceRevision++
+  }
+
+  fun exit(): List<Action> {
+    desired = null; scope = null; accepted = null; rejected = null; exitRequested = true
+    return pump()
+  }
+
+  /** Firmware can restore its stock UI after reconnect. Keep host ownership and
+   * replay the newest scene, serializing behind any outstanding command ACK. */
+  fun nativeApp(appId: Int, entered: Boolean): List<Action> {
+    if ((appId == NimoCanvasCodec.APP_ID && !entered) || (appId != NimoCanvasCodec.APP_ID && entered)) {
+      active = false
+      accepted = null
+      return pump()
+    }
+    return emptyList()
+  }
+
+  fun acceptsResponse(key: Int, payload: ByteArray): Boolean {
+    val current = flight ?: return false
+    if (current.key != key || payload.isEmpty()) return false
+    val status = payload[0].toInt() and 255
+    val echo = if (key == 4) byteArrayOf(0, NimoCanvasCodec.APP_ID.toByte(), 0, 0, 0)
+      else byteArrayOf(0, NimoCanvasCodec.APP_ID.toByte())
+    if (status == 0 && !payload.contentEquals(echo)) return false
+    if (status != 0 && payload.size != 1 &&
+      !(payload.size == echo.size && payload.copyOfRange(1, payload.size).contentEquals(echo.copyOfRange(1, echo.size)))) return false
+    return true
+  }
+
+  fun response(key: Int, payload: ByteArray): List<Action> {
+    if (!acceptsResponse(key, payload)) return emptyList()
+    val current = flight ?: return emptyList()
+    val status = payload[0].toInt() and 255
+    flight = null
+    if (status != 0) {
+      when (status) {
+        7 -> { ready = false; waitingReadiness = true; observedNotReady = false; active = false; accepted = null }
+        8 -> { locked = true; active = false; accepted = null }
+        2 -> return listOf(Action.Rejected(status)) + resetLink("Canvas device timeout is ambiguous")
+        else -> {
+          if (key == 4) rejected = current.frame
+          else {
+            if (key == 1) launchBlocked = true else desired = null
+            active = false; exitRequested = false
+          }
+        }
+      }
+      return listOf(Action.Rejected(status)) + pump()
+    }
+    when (key) {
+      1 -> { active = true; accepted = null }
+      4 -> { accepted = current.frame; rejected = null; readinessRetries = 0; probeRetries = 0 }
+      3 -> { active = false; accepted = null; exitRequested = false }
+    }
+    return pump()
+  }
+
+  fun timeout(expectedTicket: Long): List<Action> {
+    if (flight?.ticket != expectedTicket) return emptyList()
+    return resetLink("Canvas ACK timeout; reconnect before reusing a command key")
+  }
+
+  private fun resetLink(reason: String): List<Action> {
+    ready = false; transportReady = false; active = false; accepted = null; flight = null; ticket++; forceRevision++
+    return listOf(Action.Reconnect(reason))
+  }
+
+  private fun pump(): List<Action> {
+    if (!ready || held || locked || launchBlocked || waitingReadiness || flight != null) return emptyList()
+    val next = desired
+    val key = when {
+      exitRequested && active -> 3
+      exitRequested -> { exitRequested = false; return emptyList() }
+      next == null -> return emptyList()
+      !active -> 1
+      next.contentEquals(rejected) -> return emptyList()
+      next.contentEquals(accepted) && sentRevision == forceRevision -> return emptyList()
+      else -> 4
+    }
+    val frame = if (key == 4) next!!.copyOf() else ByteArray(0)
+    if (key == 4) sentRevision = forceRevision
+    val sending = Flight(key, frame, ++ticket)
+    flight = sending
+    return listOf(Action.Send(key, frame.copyOf(), sending.ticket))
+  }
+}

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

@@ -105,6 +105,10 @@ abstract class SGCManager {
 
     // Display Control
     abstract fun setBrightness(level: Int, autoMode: Boolean)
+    /** Whether settings should briefly replace the display with a brightness confirmation. */
+    open val showBrightnessConfirmation: Boolean = true
+    /** Whether connection readiness should briefly replace the display with a welcome message. */
+    open val showConnectionConfirmation: Boolean = true
     abstract fun clearDisplay()
     abstract fun sendText(text: String)
     abstract fun sendTextWall(text: String)
@@ -191,6 +195,10 @@ abstract class SGCManager {
      * device (e.g. NIMO-style) overrides this whole method instead and
      * serializes [SceneFrame.elements], ignoring the annotations.
      */
+    // Full-frame adapters replace both scenes and legacy layouts atomically;
+    // a preparatory clear would introduce a blank frame (or race the new frame).
+    open val sceneHandoffRequiresClear: Boolean = true
+
     open fun applySceneFrame(frame: SceneFrame) {
         if (frame.replay) {
             onSceneReplay(frame.appId)
@@ -350,6 +358,9 @@ abstract class SGCManager {
     // Mentra Live center-mic loudness / Barrier gate
     open fun sendLoudnessGateSetting() {}
 
+    // Mentra Live power-off after a stretch of not being worn
+    open fun sendAutoPowerOffSetting() {}
+
     // Mentra Live mic tuning (super-mode only). No value authorized means the
     // implementation sends an explicit reset rather than skipping the send.
     open fun sendMicTuningSetting() {}

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

@@ -0,0 +1,17 @@
+package com.mentra.bluetoothsdk.sgcs
+
+/** An address is usable only when its accompanying name identifies the requested device. */
+internal object SelectedDeviceAddress {
+    fun resolve(
+        target: String,
+        pendingName: String?,
+        pendingAddress: String?,
+        savedName: String?,
+        savedAddress: String?,
+    ): String? {
+        if (target.isBlank()) return null
+        if (pendingName == target && !pendingAddress.isNullOrBlank()) return pendingAddress
+        if (savedName == target && !savedAddress.isNullOrBlank()) return savedAddress
+        return null
+    }
+}

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

@@ -4,6 +4,7 @@ import android.bluetooth.BluetoothGatt
 import android.bluetooth.BluetoothGattCallback
 import android.bluetooth.BluetoothGattCharacteristic
 import android.bluetooth.BluetoothGattDescriptor
+import android.os.Build
 
 /**
  * Binder callbacks only capture their arguments. Session validation and all callback effects run
@@ -45,6 +46,10 @@ internal abstract class SerializedGattCallback(
     final override fun onCharacteristicChanged(
         gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic,
     ) {
+        // Android 13 introduced the value callback; some framework versions also call
+        // this deprecated overload for the same notification. Decoding both replays
+        // each LC3 packet and doubles recorded audio. Older Android uses this path.
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) return
         val value = characteristic.value?.copyOf() ?: return
         dispatch(gatt) { handleCharacteristicChanged(gatt, characteristic, value) }
     }

package/android/src/main/java/com/mentra/bluetoothsdk/utils/G2Text.kt

@@ -0,0 +1,7 @@
+package com.mentra.bluetoothsdk.utils
+
+/** Encode blank rows without triggering the EvenHub empty-line parser bug. */
+internal object G2Text {
+  fun containerContent(text: String): String =
+    if (text.isEmpty()) " " else text.split("\n").joinToString("\n") { it.ifEmpty { "\u200B" } }
+}

package/android/src/release/java/com/mentra/bluetoothsdk/sgcs/NimoDiagnostics.kt

@@ -0,0 +1,20 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import android.content.Context
+import android.os.Handler
+
+/** No diagnostic receiver, commands, or screen capture in release builds. */
+@Suppress("UNUSED_PARAMETER")
+internal class NimoDiagnostics(
+  context: Context,
+  handler: Handler,
+  send: (ByteArray, () -> Unit) -> Boolean,
+  requestCanvasHold: ((() -> Unit) -> Unit) = { _ -> },
+  releaseCanvasHold: (resume: Boolean) -> Unit = { _ -> },
+) {
+  fun connected(maxWriteBytes: Int) {}
+  fun disconnected() {}
+  fun close() {}
+  fun onPacket(packet: ByteArray): Boolean = false
+  fun cancelHeldCapture(reason: String, resumeCanvas: Boolean = false) {}
+}

package/android/src/test/java/com/mentra/bluetoothsdk/DashboardContentFormatterTest.kt

@@ -7,7 +7,7 @@ class DashboardContentFormatterTest {
     @Test
     fun emptyContentReturnsStatusHeaderOnly() {
         assertEquals(
-            "\$TIME12$ \$DATE$ \$GBATT$ \$CONNECTION_STATUS$",
+            "\$TIME12$ \$DATE$ \$GBATT$",
             DashboardContentFormatter.template(""),
         )
     }
@@ -15,7 +15,7 @@ class DashboardContentFormatterTest {
     @Test
     fun nonEmptyContentIsAppendedExactlyAfterBlankLine() {
         assertEquals(
-            "\$TIME12$ \$DATE$ \$GBATT$ \$CONNECTION_STATUS$\n\n  Next meeting\nRoom 2  ",
+            "\$TIME12$ \$DATE$ \$GBATT$\n\n  Next meeting\nRoom 2  ",
             DashboardContentFormatter.template("  Next meeting\nRoom 2  "),
         )
     }

package/android/src/test/java/com/mentra/bluetoothsdk/DeviceIdentityPairingTest.kt

@@ -0,0 +1,59 @@
+package com.mentra.bluetoothsdk
+
+import androidx.test.core.app.ApplicationProvider
+import com.mentra.bluetoothsdk.sgcs.Simulated
+import org.junit.Assert.assertEquals
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+import org.robolectric.annotation.LooperMode
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [33])
+@LooperMode(LooperMode.Mode.PAUSED)
+class DeviceIdentityPairingTest {
+    @Test fun `readiness promotes a coherent name and address while preserving same-device reconnects`() {
+        Bridge.initialize(ApplicationProvider.getApplicationContext())
+        val saved = listOf("bluetooth", "glasses").associateWith { DeviceStore.store.getCategory(it) }
+        val singleton = DeviceManager::class.java.getDeclaredField("_instance").apply { isAccessible = true }
+        val previous = singleton.get(null)
+        val cases = listOf(
+            // pending name, pending address, saved model, expected address
+            listOf("new", "", "test", ""),
+            listOf("new", "new-address", "test", "new-address"),
+            listOf("old", "", "test", "old-address"),
+            listOf("", "", "test", "old-address"),
+            listOf("old", "", "other-model", ""),
+        )
+        try {
+            for ((pendingName, pendingAddress, savedModel, expectedAddress) in cases) {
+                val manager = DeviceManager(initializeHardware = false)
+                singleton.set(null, manager)
+                manager.sgc = Simulated().apply { type = "test" }
+                DeviceStore.set("bluetooth", "default_wearable", savedModel)
+                DeviceStore.set("bluetooth", "device_name", "old")
+                DeviceStore.set("bluetooth", "device_address", "old-address")
+                DeviceStore.set("bluetooth", "pending_device_name", pendingName)
+                DeviceStore.set("bluetooth", "pending_device_address", pendingAddress)
+                DeviceStore.set("bluetooth", "shouldSendBootingMessage", false)
+                try {
+                    manager.handleDeviceReady()
+                    assertEquals(pendingName.ifEmpty { "old" }, DeviceStore.get("bluetooth", "device_name"))
+                    assertEquals(expectedAddress, DeviceStore.get("bluetooth", "device_address"))
+                    assertEquals("", DeviceStore.get("bluetooth", "pending_device_name"))
+                    assertEquals("", DeviceStore.get("bluetooth", "pending_device_address"))
+                } finally {
+                    manager.disconnect()
+                    manager.cleanup()
+                }
+            }
+        } finally {
+            singleton.set(null, previous)
+            saved.forEach { (category, values) ->
+                (DeviceStore.store.getCategory(category).keys - values.keys).forEach { DeviceStore.store.remove(category, it) }
+                values.forEach { (key, value) -> DeviceStore.set(category, key, value) }
+            }
+        }
+    }
+}