@mentra/bluetooth-sdk 3.2.0-dev.195 → 3.2.0-dev.203

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

@@ -0,0 +1,64 @@
+package com.mentra.bluetoothsdk.sgcs
+
+/**
+ * Process-wide barrier between Mentra Live GATT teardown and the next connection attempt.
+ *
+ * Android can keep the physical link alive after a disconnect request until it delivers the
+ * disconnected callback. Starting another GATT session before that callback can reuse the old link,
+ * including its already-consumed MTU exchange. Callers queue connection work here and release it
+ * only after every outstanding teardown has completed or timed out. A newer deferred connection
+ * replaces the previous one so reconnect retries cannot start multiple GATT sessions together.
+ */
+internal class MentraLiveGattTeardownBarrier {
+    private val activeTeardowns = mutableSetOf<Long>()
+    private var waitingConnection: (() -> Unit)? = null
+    private var nextToken = 1L
+
+    @Synchronized
+    fun beginTeardown(): Long {
+        val token = nextToken++
+        activeTeardowns.add(token)
+        return token
+    }
+
+    /** Admission and execution are one operation; production callers all use the main looper. */
+    @Synchronized
+    fun runWhenIdle(work: () -> Unit) {
+        if (activeTeardowns.isEmpty()) work() else waitingConnection = work
+    }
+
+    @Synchronized
+    fun completeTeardown(token: Long) {
+        if (!activeTeardowns.remove(token) || activeTeardowns.isNotEmpty()) return
+        val ready = waitingConnection.also { waitingConnection = null }
+        ready?.invoke()
+    }
+}
+
+/** One-shot guard shared by the MTU callback and its watchdog fallback. */
+internal class MentraLiveMtuSetupGate {
+    private var nextToken = 1L
+    private var pendingToken: Long? = null
+
+    @Synchronized
+    fun begin(): Long {
+        val token = nextToken++
+        pendingToken = token
+        return token
+    }
+
+    /** Returns true exactly once for the current setup operation. */
+    @Synchronized
+    fun complete(token: Long): Boolean {
+        if (pendingToken != token) {
+            return false
+        }
+        pendingToken = null
+        return true
+    }
+
+    @Synchronized
+    fun cancel() {
+        pendingToken = null
+    }
+}

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

@@ -313,8 +313,10 @@ abstract class SGCManager {
 
     // Network Management
     abstract fun requestWifiScan(scanId: String?)
+    open fun requestSavedWifiNetworks(requestId: String, sid: String): Boolean = false
     abstract fun sendWifiCredentials(ssid: String, password: String)
     abstract fun forgetWifiNetwork(ssid: String)
+    open fun forgetWifiNetwork(ssid: String, requestId: String?, sid: String?): Boolean = false
     abstract fun sendHotspotState(enabled: Boolean)
 
     /** Set glasses system clock (Mentra Live and G2; no-op on other devices). */

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

@@ -0,0 +1,76 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import android.bluetooth.BluetoothGatt
+import android.bluetooth.BluetoothGattCallback
+import android.bluetooth.BluetoothGattCharacteristic
+import android.bluetooth.BluetoothGattDescriptor
+
+/**
+ * Binder callbacks only capture their arguments. Session validation and all callback effects run
+ * on the lifecycle owner, in the same queue as connect and teardown. Notification bytes must be
+ * copied before dispatch: Android reuses the mutable characteristic between notifications.
+ */
+internal abstract class SerializedGattCallback(
+    private val enqueue: (() -> Unit) -> Unit,
+    private val isCurrent: (BluetoothGatt) -> Boolean,
+) : BluetoothGattCallback() {
+    private fun dispatch(gatt: BluetoothGatt, work: () -> Unit) {
+        enqueue { if (isCurrent(gatt)) work() }
+    }
+
+    final override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) =
+        dispatch(gatt) { handleConnectionStateChange(gatt, status, newState) }
+
+    final override fun onServicesDiscovered(gatt: BluetoothGatt, status: Int) =
+        dispatch(gatt) { handleServicesDiscovered(gatt, status) }
+
+    final override fun onPhyUpdate(gatt: BluetoothGatt, txPhy: Int, rxPhy: Int, status: Int) =
+        dispatch(gatt) { handlePhyUpdate(gatt, txPhy, rxPhy, status) }
+
+    final override fun onPhyRead(gatt: BluetoothGatt, txPhy: Int, rxPhy: Int, status: Int) =
+        dispatch(gatt) { handlePhyRead(gatt, txPhy, rxPhy, status) }
+
+    final override fun onCharacteristicRead(
+        gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, status: Int,
+    ) = dispatch(gatt) { handleCharacteristicRead(gatt, characteristic, status) }
+
+    final override fun onReadRemoteRssi(gatt: BluetoothGatt, rssi: Int, status: Int) =
+        dispatch(gatt) { handleReadRemoteRssi(gatt, rssi, status) }
+
+    final override fun onCharacteristicWrite(
+        gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, status: Int,
+    ) = dispatch(gatt) { handleCharacteristicWrite(gatt, characteristic, status) }
+
+    @Suppress("DEPRECATION")
+    final override fun onCharacteristicChanged(
+        gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic,
+    ) {
+        val value = characteristic.value?.copyOf() ?: return
+        dispatch(gatt) { handleCharacteristicChanged(gatt, characteristic, value) }
+    }
+
+    final override fun onCharacteristicChanged(
+        gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, value: ByteArray,
+    ) {
+        val snapshot = value.copyOf()
+        dispatch(gatt) { handleCharacteristicChanged(gatt, characteristic, snapshot) }
+    }
+
+    final override fun onDescriptorWrite(
+        gatt: BluetoothGatt, descriptor: BluetoothGattDescriptor, status: Int,
+    ) = dispatch(gatt) { handleDescriptorWrite(gatt, descriptor, status) }
+
+    final override fun onMtuChanged(gatt: BluetoothGatt, mtu: Int, status: Int) =
+        dispatch(gatt) { handleMtuChanged(gatt, mtu, status) }
+
+    protected abstract fun handleConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int)
+    protected abstract fun handleServicesDiscovered(gatt: BluetoothGatt, status: Int)
+    protected abstract fun handlePhyUpdate(gatt: BluetoothGatt, txPhy: Int, rxPhy: Int, status: Int)
+    protected abstract fun handlePhyRead(gatt: BluetoothGatt, txPhy: Int, rxPhy: Int, status: Int)
+    protected abstract fun handleCharacteristicRead(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, status: Int)
+    protected abstract fun handleReadRemoteRssi(gatt: BluetoothGatt, rssi: Int, status: Int)
+    protected abstract fun handleCharacteristicWrite(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, status: Int)
+    protected abstract fun handleCharacteristicChanged(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, data: ByteArray)
+    protected abstract fun handleDescriptorWrite(gatt: BluetoothGatt, descriptor: BluetoothGattDescriptor, status: Int)
+    protected abstract fun handleMtuChanged(gatt: BluetoothGatt, mtu: Int, status: Int)
+}

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

@@ -189,6 +189,10 @@ data class VersionInfoResult(
     val appVersion: String,
     val packageName: String,
     val hotspotOtaVersion: Int,
+    val wifiForgetResultVersion: Int? = null,
+    val savedWifiNetworksVersion: Int? = null,
+    val versionInfoType: String? = null,
+    val sid: String? = null,
 ) {
     internal fun toMap(): Map<String, Any> =
         buildMap {
@@ -200,13 +204,16 @@ data class VersionInfoResult(
             systemTimeMs?.let { put("systemTimeMs", it) }
             put("otaVersionUrl", otaVersionUrl)
             put("appVersion", appVersion)
-            // Only when known. requestVersionInfo() resolves from ANY version_info chunk, and
-            // only chunk 1 carries package_name — emitting "" from a chunk-3 resolution would
-            // overwrite a known identity with "absent", which the OTA guard reads as stock.
+            // Only when known: per-chunk events may omit package identity. Emitting an empty
+            // value would overwrite a known identity, which the OTA guard uses to identify stock.
             if (packageName.isNotEmpty()) {
                 put("packageName", packageName)
             }
             put("hotspotOtaVersion", hotspotOtaVersion)
+            wifiForgetResultVersion?.let { put("wifiForgetResultVersion", it) }
+            savedWifiNetworksVersion?.let { put("savedWifiNetworksVersion", it) }
+            versionInfoType?.let { put("versionInfoType", it) }
+            sid?.let { put("sid", it) }
         }
 
     companion object {
@@ -237,6 +244,12 @@ data class VersionInfoResult(
                 packageName = stringValue(values, "packageName", "package_name") ?: "",
                 hotspotOtaVersion =
                     numberValue(values, "hotspotOtaVersion", "hotspot_ota_version") ?: 0,
+                wifiForgetResultVersion =
+                    numberValue(values, "wifiForgetResultVersion", "wifi_forget_result_version"),
+                savedWifiNetworksVersion =
+                    numberValue(values, "savedWifiNetworksVersion", "saved_wifi_networks_version"),
+                versionInfoType = stringValue(values, "versionInfoType", "version_info_type"),
+                sid = stringValue(values, "sid"),
             )
     }
 }

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

@@ -0,0 +1,14 @@
+package com.mentra.bluetoothsdk
+
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.Test
+
+class GlassesStatusClassicAudioTest {
+    @Test
+    fun `serializes connected Classic audio state for React Native`() {
+        val serialized =
+                GlassesStatus.fromMap(mapOf("bluetoothClassicConnected" to true)).toMap()
+
+        assertThat(serialized["bluetoothClassicConnected"]).isEqualTo(true)
+    }
+}

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

@@ -0,0 +1,16 @@
+package com.mentra.bluetoothsdk
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+class MessageAckPolicyTest {
+    @Test
+    fun `every non-ack message id is acknowledged regardless of type`() {
+        assertEquals(17L, incomingGlassesMessageAckId("wifi_forget_result", 17L))
+        assertEquals(18L, incomingGlassesMessageAckId("saved_wifi_networks", 18L))
+        assertEquals(19L, incomingGlassesMessageAckId("future_terminal_type", 19L))
+        assertNull(incomingGlassesMessageAckId("msg_ack", 20L))
+        assertNull(incomingGlassesMessageAckId("wifi_forget_result", null))
+    }
+}

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

@@ -0,0 +1,33 @@
+package com.mentra.bluetoothsdk
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [28])
+class VersionInfoBridgeTest {
+    @Test
+    fun wireMetadataSurvivesBridgeNormalizationAndCompletesOnlyAfterBothChunks() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+        val outcomes = mutableListOf<VersionInfoAccumulatorOutcome>()
+        val sink = Bridge.addEventSink { type, body ->
+            if (type == "version_info") outcomes.add(accumulator.accept(body))
+        }
+        val common = mapOf<String, Any>("request_id" to "request-1", "sid" to "asg-1", "chunkCount" to 2)
+        try {
+            Bridge.sendVersionInfo(common + mapOf("chunkIndex" to 1, "final" to false, "build_number" to "42"), "version_info_1")
+            Bridge.sendVersionInfo(common + mapOf("chunkIndex" to 2, "final" to true, "bes_fw_version" to "new"), "version_info_3")
+            assertEquals(VersionInfoAccumulatorOutcome.Waiting, outcomes[0])
+            val complete = outcomes[1] as VersionInfoAccumulatorOutcome.Complete
+            assertEquals("42", complete.result.buildNumber)
+            assertEquals("new", complete.result.besFirmwareVersion)
+            assertTrue(complete.result.toMap().keys.none { it.startsWith("_response") })
+        } finally {
+            Bridge.removeEventSink(sink)
+        }
+    }
+}

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

@@ -0,0 +1,169 @@
+package com.mentra.bluetoothsdk
+
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.Test
+
+class VersionInfoResponseAccumulatorTest {
+    @Test
+    fun mergesCurrentChunksAndCompletesOnFirmwareChunk() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+
+        assertThat(accumulator.accept(chunk("version_info_1", "request-1", "buildNumber" to "42")))
+            .isEqualTo(VersionInfoAccumulatorOutcome.Waiting)
+
+        val complete =
+            accumulator.accept(
+                chunk(
+                    "version_info_3",
+                    "request-1",
+                    "buildNumber" to "",
+                    "besFirmwareVersion" to "26.8.27.0",
+                    "mtkFirmwareVersion" to "MentraLive_20260709",
+                )
+            ) as VersionInfoAccumulatorOutcome.Complete
+
+        assertThat(complete.result.buildNumber).isEqualTo("42")
+        assertThat(complete.result.besFirmwareVersion).isEqualTo("26.8.27.0")
+        assertThat(complete.result.mtkFirmwareVersion).isEqualTo("MentraLive_20260709")
+    }
+
+    @Test
+    fun ignoresMismatchedAndTrailingStaleChunks() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+
+        assertThat(accumulator.accept(chunk("version_info_1", "other", "buildNumber" to "old")))
+            .isEqualTo(VersionInfoAccumulatorOutcome.Ignored)
+        assertThat(accumulator.accept(chunk("version_info_3", null, "besFirmwareVersion" to "stale")))
+            .isEqualTo(VersionInfoAccumulatorOutcome.Ignored)
+    }
+
+    @Test
+    fun doesNotMixCorrelatedAndUncorrelatedSequences() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+        accumulator.accept(chunk("version_info_1", "request-1", "buildNumber" to "42"))
+
+        assertThat(accumulator.accept(chunk("version_info_3", null, "besFirmwareVersion" to "stale")))
+            .isEqualTo(VersionInfoAccumulatorOutcome.Ignored)
+
+        val complete =
+            accumulator.accept(
+                chunk("version_info_3", "request-1", "besFirmwareVersion" to "current")
+            ) as VersionInfoAccumulatorOutcome.Complete
+        assertThat(complete.result.besFirmwareVersion).isEqualTo("current")
+    }
+
+    @Test
+    fun staleUncorrelatedResponsesCannotReplaceCorrelatedSequence() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+        accumulator.accept(chunk("version_info_1", "request-1", "buildNumber" to "42"))
+
+        assertThat(accumulator.accept(chunk("version_info_1", null, "buildNumber" to "stale")))
+            .isEqualTo(VersionInfoAccumulatorOutcome.Ignored)
+        assertThat(accumulator.accept(chunk("version_info", null, "buildNumber" to "legacy")))
+            .isEqualTo(VersionInfoAccumulatorOutcome.Ignored)
+
+        val complete =
+            accumulator.accept(
+                chunk("version_info_3", "request-1", "besFirmwareVersion" to "current")
+            ) as VersionInfoAccumulatorOutcome.Complete
+        assertThat(complete.result.buildNumber).isEqualTo("42")
+        assertThat(complete.result.besFirmwareVersion).isEqualTo("current")
+    }
+
+    @Test
+    fun repeatedFirstChunkResetsRatherThanMixingResponses() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+        accumulator.accept(chunk("version_info_1", null, "appVersion" to "old"))
+        accumulator.accept(chunk("version_info_1", null, "buildNumber" to "43"))
+
+        val complete = (accumulator.accept(chunk("version_info_3", null, "besFirmwareVersion" to "new"))
+            as VersionInfoAccumulatorOutcome.Complete).result
+
+        assertThat(complete.appVersion).isEmpty()
+        assertThat(complete.buildNumber).isEqualTo("43")
+        assertThat(complete.besFirmwareVersion).isEqualTo("new")
+    }
+
+    @Test
+    fun legacySingleMessageCompletesImmediately() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+
+        val complete =
+            accumulator.accept(chunk("version_info", null, "buildNumber" to "7"))
+                as VersionInfoAccumulatorOutcome.Complete
+
+        assertThat(complete.result.buildNumber).isEqualTo("7")
+    }
+
+    @Test
+    fun legacyFirstChunkDoesNotCompleteWithoutFinalChunk() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+        assertThat(accumulator.accept(chunk("version_info_1", null, "buildNumber" to "8")))
+            .isEqualTo(VersionInfoAccumulatorOutcome.Waiting)
+    }
+
+    @Test
+    fun modernFinalChunkWaitsForMissingFirstChunk() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+        assertThat(accumulator.accept(chunk("version_info_3", "request-1", "besFirmwareVersion" to "new")))
+            .isEqualTo(VersionInfoAccumulatorOutcome.Waiting)
+        val result = accumulator.accept(chunk("version_info_1", "request-1", "buildNumber" to "42"))
+            as VersionInfoAccumulatorOutcome.Complete
+        assertThat(result.result.buildNumber).isEqualTo("42")
+        assertThat(result.result.besFirmwareVersion).isEqualTo("new")
+    }
+
+    @Test
+    fun duplicateChunkDoesNotCountAsMissingChunk() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+        val first = chunk("version_info_1", "request-1", "buildNumber" to "42")
+        assertThat(accumulator.accept(first)).isEqualTo(VersionInfoAccumulatorOutcome.Waiting)
+        assertThat(accumulator.accept(first)).isEqualTo(VersionInfoAccumulatorOutcome.Waiting)
+    }
+
+    @Test
+    fun rejectsMalformedModernMetadataAndMixedProcess() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+        val first = chunk("version_info_1", "request-1", "buildNumber" to "42")
+        for ((key, value) in listOf(
+            VersionInfoResponseAccumulator.RESPONSE_COUNT_KEY to 2.5,
+            VersionInfoResponseAccumulator.RESPONSE_INDEX_KEY to true,
+            VersionInfoResponseAccumulator.RESPONSE_FINAL_KEY to true,
+            VersionInfoResponseAccumulator.RESPONSE_REQUEST_ID_KEY to "",
+        )) {
+            assertThat(accumulator.accept(first + (key to value))).isEqualTo(VersionInfoAccumulatorOutcome.Ignored)
+        }
+        accumulator.accept(first)
+        val last = chunk("version_info_3", "request-1", "besFirmwareVersion" to "new")
+        assertThat(accumulator.accept(last + (VersionInfoResponseAccumulator.RESPONSE_SID_KEY to "process-2")))
+            .isEqualTo(VersionInfoAccumulatorOutcome.Ignored)
+        assertThat(accumulator.accept(last)).isInstanceOf(VersionInfoAccumulatorOutcome.Complete::class.java)
+    }
+
+    @Test
+    fun correlatedResponseWithoutCompletenessMetadataCannotComplete() {
+        val accumulator = VersionInfoResponseAccumulator("request-1")
+        val event = mapOf<String, Any>(
+            VersionInfoResponseAccumulator.RESPONSE_CHUNK_KEY to "version_info_3",
+            VersionInfoResponseAccumulator.RESPONSE_REQUEST_ID_KEY to "request-1",
+        )
+        assertThat(accumulator.accept(event)).isEqualTo(VersionInfoAccumulatorOutcome.Ignored)
+    }
+
+    private fun chunk(
+        type: String,
+        requestId: String?,
+        vararg values: Pair<String, Any>,
+    ): Map<String, Any> =
+        buildMap {
+            put(VersionInfoResponseAccumulator.RESPONSE_CHUNK_KEY, type)
+            requestId?.let {
+                put(VersionInfoResponseAccumulator.RESPONSE_REQUEST_ID_KEY, it)
+                put(VersionInfoResponseAccumulator.RESPONSE_INDEX_KEY, if (type == "version_info_1") 1 else 2)
+                put(VersionInfoResponseAccumulator.RESPONSE_COUNT_KEY, 2)
+                put(VersionInfoResponseAccumulator.RESPONSE_FINAL_KEY, type == "version_info_3")
+                put(VersionInfoResponseAccumulator.RESPONSE_SID_KEY, "process-1")
+            }
+            putAll(values)
+        }
+}