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

package/android/src/main/java/com/mentra/bluetoothsdk/BluetoothSdkModule.kt

@@ -807,16 +807,8 @@ class BluetoothSdkModule : Module() {
             requireSdk().startStream(StreamRequest.fromMap(params)).values
         }
 
-        SdkCoroutineFunction("startExternallyManagedStream") { params: Map<String, Any> ->
-            requireSdk().startExternallyManagedStream(StreamRequest.fromMap(params)).values
-        }
-
         SdkCoroutineFunction("stopStream") { -> requireSdk().stopStream().values }
 
-        SdkAsyncFunction("sendExternallyManagedStreamKeepAlive") { params: Map<String, Any> ->
-            sdk?.sendExternallyManagedStreamKeepAlive(StreamKeepAliveRequest.fromMap(params))
-        }
-
         // MARK: - Microphone Commands
 
         SdkAsyncFunction("setMicState") {

package/android/src/main/java/com/mentra/bluetoothsdk/GeneratedReleaseMetadata.kt

@@ -3,9 +3,9 @@ package com.mentra.bluetoothsdk
 /** Generated by release CI. Do not edit in a release checkout. */
 internal object GeneratedReleaseMetadata {
     const val FAMILY_BASE_VERSION: String = "3.2.0"
-    const val RELEASE_IDENTITY: String = "3.2.0-dev.203"
-    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.203"
-    const val SOURCE_COMMIT: String = "7eb4deefff27d498c2b4562d628607f399aa1f40"
-    const val OTA_MANIFEST_URL: String = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.203.json"
-    const val OTA_MANIFEST_SHA256: String = "0ae026238c8e70970be4e181cc1ae73dd905418292edebddb610012f4f0a9b6f"
+    const val RELEASE_IDENTITY: String = "3.2.0-dev.208"
+    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.208"
+    const val SOURCE_COMMIT: String = "3c22b92a5a53ce608c087503417ca5b3d16cc926"
+    const val OTA_MANIFEST_URL: String = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.208.json"
+    const val OTA_MANIFEST_SHA256: String = "69ce2b786afea60faaa5a47aad1ff0c9e70933365658b6628e651fb0c6cfe7bd"
 }

package/android/src/main/java/com/mentra/bluetoothsdk/MentraBluetoothSdk.kt

@@ -8,6 +8,7 @@ import android.content.Context
 import android.os.Bundle
 import android.os.Handler
 import android.os.Looper
+import com.mentra.bluetoothsdk.streaming.StreamSessionState
 import com.mentra.bluetoothsdk.utils.ControllerTypes
 import com.mentra.bluetoothsdk.utils.PhoneAudioMonitor
 import java.util.Collections
@@ -52,8 +53,7 @@ class MentraBluetoothSdk private constructor(
         }
     private var activityLifecycleCallbacksRegistered = false
     private var suppressDefaultDeviceEvents = false
-    private val streamKeepAliveLock = Any()
-    private var activeStreamKeepAlive: ActiveStreamKeepAlive? = null
+    private val streamSession = StreamSessionState()
     private val pendingPhotoRequests = ConcurrentHashMap<String, PendingResponse<PhotoResponseEvent>>()
     private val pendingCameraStatusRequests = ConcurrentHashMap<String, PendingResponse<CameraStatusEvent>>()
     private val pendingVideoRecordingRequests =
@@ -110,7 +110,6 @@ class MentraBluetoothSdk private constructor(
         private const val OTA_BES_VERSION_WAIT_MS = 5_000L
         private const val OTA_MTK_VERSION_WAIT_MS = 2_000L
         private const val OTA_VERSION_POLL_MS = 100L
-        private const val DEFAULT_STREAM_KEEP_ALIVE_INTERVAL_SECONDS = 5
         private const val MAX_MISSED_STREAM_KEEP_ALIVE_ACKS = 3
 
         // Stream states the glasses only reach after start_stream has run past
@@ -139,18 +138,6 @@ class MentraBluetoothSdk private constructor(
         ): MentraBluetoothSdk = MentraBluetoothSdk(context, config, listener)
     }
 
-    private data class ActiveStreamKeepAlive(
-        val streamId: String,
-        val intervalMs: Long,
-        var pendingAckId: String? = null,
-        var missedAckCount: Int = 0,
-        var nextTick: Runnable? = null,
-        // Missed-ACK counting only begins once the stream is confirmed live/coming up, so a
-        // slow startup (glasses can't ACK until they reach starting/streaming) can't trip a
-        // false keep-alive timeout before the stream is ever up.
-        var armed: Boolean = false,
-    )
-
     // seq records send order (assigned and handed to the BLE queue under
     // streamStartOrderLock) so that an id-carrying status for a newer start can
     // identify which older in-flight starts it preempted.
@@ -1115,16 +1102,11 @@ class MentraBluetoothSdk private constructor(
         }
     }
 
-    suspend fun startStream(request: StreamRequest): StreamStatusEvent =
-        startStream(request, startSdkKeepAlive = true)
-
-    internal suspend fun startExternallyManagedStream(request: StreamRequest): StreamStatusEvent =
-        startStream(request, startSdkKeepAlive = false)
-
-    private suspend fun startStream(
-        request: StreamRequest,
-        startSdkKeepAlive: Boolean,
-    ): StreamStatusEvent {
+    suspend fun startStream(request: StreamRequest): StreamStatusEvent {
+        requireGlassesConnected("start stream")
+        if (!streamSession.supported) {
+            throw BluetoothSdkException("stream_control_unsupported", "Update the glasses software before starting a stream.")
+        }
         val message = request.toMap().toMutableMap()
         val streamId = (message["streamId"] as? String)?.takeIf { it.isNotBlank() }
                 ?: "sdk-${UUID.randomUUID()}"
@@ -1139,23 +1121,15 @@ class MentraBluetoothSdk private constructor(
                 val registered = PendingStreamStart(streamStartSeq.incrementAndGet(), pending)
                 pendingStreamStarts[streamId] = registered
                 start = registered
-                stopStreamKeepAliveMonitor()
                 deviceManager.startStream(message)
             }
             val event = pending.await(STREAM_START_TIMEOUT_MS)
-            if (startSdkKeepAlive) {
-                startStreamKeepAliveMonitor(streamId, DEFAULT_STREAM_KEEP_ALIVE_INTERVAL_SECONDS)
-            }
             return event
         } finally {
             start?.let { pendingStreamStarts.remove(streamId, it) }
         }
     }
 
-    internal fun sendExternallyManagedStreamKeepAlive(request: StreamKeepAliveRequest) {
-        deviceManager.keepStreamAlive(request.toMap().toMutableMap())
-    }
-
     suspend fun rgbLedControl(request: RgbLedRequest): RgbLedControlResponseEvent {
         val pending = PendingResponse<RgbLedControlResponseEvent>("RGB LED command ${request.requestId}")
         pendingRgbLedRequests[request.requestId] = pending
@@ -1177,9 +1151,7 @@ class MentraBluetoothSdk private constructor(
 
     suspend fun stopStream(): StreamStatusEvent {
         val pending = PendingResponse<StreamStatusEvent>("stop stream")
-        val targetStreamId = synchronized(streamKeepAliveLock) {
-            activeStreamKeepAlive?.streamId
-        }
+        val targetStreamId = streamSession.currentStreamId
         try {
             // The seq draw and the BLE hand-off share startStream's ordering
             // critical section: the stop takes its own slot in the send order,
@@ -1196,7 +1168,6 @@ class MentraBluetoothSdk private constructor(
                     pendingStreamStop =
                         PendingStreamStop(targetStreamId, streamStartSeq.incrementAndGet(), pending)
                 }
-                stopStreamKeepAliveMonitor()
                 deviceManager.stopStream()
             }
             return pending.await(STREAM_STOP_TIMEOUT_MS)
@@ -1554,7 +1525,6 @@ class MentraBluetoothSdk private constructor(
     }
 
     override fun close() {
-        stopStreamKeepAliveMonitor()
         resetWifiProtocolSession("", "sdk_closed")
         if (activityLifecycleCallbacksRegistered) {
             (appContext as? Application)?.unregisterActivityLifecycleCallbacks(
@@ -1871,17 +1841,18 @@ class MentraBluetoothSdk private constructor(
                 handleRgbLedResponseForRequests(event)
                 dispatchToListeners { it.onRgbLedControlResponse(event) }
             }
+            "stream_control_ready" -> {
+                streamSession.ready(data["sid"] as? String, (data["streamControlVersion"] as? Number)?.toInt())
+            }
             "stream_status" -> {
+                if (data.containsKey("revision") && !streamSession.accept(data)) return
                 val event = StreamStatusEvent(data)
                 handleStreamStatusForRequests(event)
-                handleStreamStatusForKeepAlive(event.status)
                 dispatchToListeners { it.onStreamStatus(event) }
             }
             "keep_alive_ack" -> {
                 val event = KeepAliveAckEvent(data)
-                if (!handleStreamKeepAliveAck(event)) {
-                    dispatchToListeners { it.onKeepAliveAck(event) }
-                }
+                dispatchToListeners { it.onKeepAliveAck(event) }
             }
             "ota_start_ack" -> {
                 val event = OtaStartAckEvent.fromMap(data + mapOf("type" to "ota_start_ack"))
@@ -1974,29 +1945,6 @@ class MentraBluetoothSdk private constructor(
         }
     }
 
-    private fun startStreamKeepAliveMonitor(streamId: String, requestedIntervalSeconds: Int) {
-        val intervalSeconds =
-                requestedIntervalSeconds.takeIf { it > 0 } ?: DEFAULT_STREAM_KEEP_ALIVE_INTERVAL_SECONDS
-        val tracker = ActiveStreamKeepAlive(
-                streamId = streamId,
-                intervalMs = intervalSeconds * 1_000L,
-        )
-        synchronized(streamKeepAliveLock) {
-            activeStreamKeepAlive = tracker
-        }
-        sendNextStreamKeepAlive(tracker)
-    }
-
-    private fun stopStreamKeepAliveMonitor() {
-        val tracker =
-                synchronized(streamKeepAliveLock) {
-                    val current = activeStreamKeepAlive
-                    activeStreamKeepAlive = null
-                    current
-                }
-        tracker?.nextTick?.let { mainHandler.removeCallbacks(it) }
-    }
-
     private fun handleStreamStatusForRequests(event: StreamStatusEvent) {
         val startMatch = matchingStreamStart(event)
         if (startMatch != null) {
@@ -2547,94 +2495,7 @@ class MentraBluetoothSdk private constructor(
         )
     }
 
-    private fun sendNextStreamKeepAlive(tracker: ActiveStreamKeepAlive) {
-        var timeoutEvent: StreamStatusEvent? = null
-        var request: StreamKeepAliveRequest? = null
 
-        synchronized(streamKeepAliveLock) {
-            if (activeStreamKeepAlive !== tracker) {
-                return
-            }
-
-            if (tracker.armed && tracker.pendingAckId != null) {
-                tracker.missedAckCount += 1
-                if (tracker.missedAckCount >= MAX_MISSED_STREAM_KEEP_ALIVE_ACKS) {
-                    activeStreamKeepAlive = null
-                    tracker.nextTick?.let { mainHandler.removeCallbacks(it) }
-                    timeoutEvent =
-                            StreamStatusEvent(
-                                    StreamStatus.Error(
-                                            streamId = tracker.streamId,
-                                            errorDetails =
-                                                    "Stream keep-alive timed out after ${tracker.missedAckCount} missed ACKs",
-                                            timestamp = System.currentTimeMillis(),
-                                            resolvedConfig = null,
-                                    )
-                            )
-                    return@synchronized
-                }
-            }
-
-            val ackId = "ack-${System.currentTimeMillis()}"
-            tracker.pendingAckId = ackId
-            request = StreamKeepAliveRequest(streamId = tracker.streamId, ackId = ackId)
-            val nextTick = Runnable { sendNextStreamKeepAlive(tracker) }
-            tracker.nextTick = nextTick
-            mainHandler.postDelayed(nextTick, tracker.intervalMs)
-        }
-
-        timeoutEvent?.let { event ->
-            dispatchToListeners { it.onStreamStatus(event) }
-            stopStreamKeepAliveMonitor()
-            deviceManager.stopStream()
-            return
-        }
-
-        request?.let { keepAlive ->
-            deviceManager.keepStreamAlive(keepAlive.toMap().toMutableMap())
-        }
-    }
-
-    private fun handleStreamKeepAliveAck(event: KeepAliveAckEvent): Boolean {
-        synchronized(streamKeepAliveLock) {
-            val tracker = activeStreamKeepAlive ?: return false
-            if (event.streamId != tracker.streamId || event.ackId != tracker.pendingAckId) {
-                return false
-            }
-            tracker.pendingAckId = null
-            tracker.missedAckCount = 0
-            return true
-        }
-    }
-
-    private fun handleStreamStatusForKeepAlive(status: StreamStatus) {
-        val streamId = status.streamId
-        val activeStreamId = synchronized(streamKeepAliveLock) { activeStreamKeepAlive?.streamId }
-        if (streamId == null || activeStreamId != streamId) {
-            return
-        }
-        when (status.state) {
-            StreamState.STOPPED,
-            StreamState.STOPPING,
-            StreamState.ERROR,
-            StreamState.RECONNECT_FAILED -> stopStreamKeepAliveMonitor()
-            // A non-terminal status means the stream is live or coming up and the glasses can
-            // now ACK; arm the missed-ACK detector from here so a slow startup before the first
-            // ACK can't trip a false keep-alive timeout. On the arming transition, drop any
-            // pre-arm bookkeeping so a stale unacked id (sent before the glasses could ACK)
-            // can't immediately count as a miss.
-            else ->
-                    synchronized(streamKeepAliveLock) {
-                        activeStreamKeepAlive?.let {
-                            if (it.streamId == streamId && !it.armed) {
-                                it.armed = true
-                                it.pendingAckId = null
-                                it.missedAckCount = 0
-                            }
-                        }
-                    }
-        }
-    }
 }
 
 /** OTA status messages are not request-correlated, so only known pre-ack failures settle a start. */

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

@@ -4086,6 +4086,14 @@ class MentraLive : SGCManager() {
                 val percent = json.optInt("percent", batteryLevel)
                 updateBatteryStatus(percent, isCharging)
             }
+            "stream_controller_probe" -> {
+                val values = mapOf("protocolVersion" to json.opt("protocolVersion"),
+                    "controllerId" to json.opt("controllerId"), "streamId" to json.opt("streamId"),
+                    "probeId" to json.opt("probeId"))
+                com.mentra.bluetoothsdk.streaming.StreamControllerProbe.response(values)?.let {
+                    sendJson(JSONObject(it))
+                }
+            }
             "pong" ->
                     // Process heartbeat pong response
                     Bridge.log("LIVE: Received pong response - connection healthy")
@@ -4565,6 +4573,10 @@ class MentraLive : SGCManager() {
                         mapOf("sid" to (glassesSessionId ?: "")),
                 )
                 readinessCompletedThisBleSession = true
+                Bridge.sendTypedMessage("stream_control_ready", mapOf(
+                    "sid" to json.optString("sid", ""),
+                    "streamControlVersion" to json.optInt("streamControlVersion", 0),
+                ))
 
                 // Set the ready flag to stop any future readiness checks
                 glassesReady = true
@@ -6802,6 +6814,8 @@ class MentraLive : SGCManager() {
             val json = JSONObject(message as Map<*, *>)
             // Remove timestamp as iOS does
             json.remove("timestamp")
+            json.put("controllerProbeVersion", 1)
+            json.put("controllerId", com.mentra.bluetoothsdk.streaming.StreamControllerProbe.controllerId)
             sendJson(json, true)
         } catch (e: Exception) {
             Log.e(TAG, "Error creating RTMP stream start JSON", e)

package/android/src/main/java/com/mentra/bluetoothsdk/streaming/StreamControllerProbe.kt

@@ -0,0 +1,14 @@
+package com.mentra.bluetoothsdk.streaming
+
+/** Process-scoped native ownership survives BLE reconnects, not app termination. */
+internal object StreamControllerProbe {
+    val controllerId: String = java.util.UUID.randomUUID().toString()
+
+    fun response(values: Map<String, Any?>): Map<String, Any>? {
+        if (values["protocolVersion"] != 1 || values["controllerId"] != controllerId) return null
+        val streamId = (values["streamId"] as? String)?.takeIf { it.isNotEmpty() } ?: return null
+        val probeId = (values["probeId"] as? String)?.takeIf { it.isNotEmpty() } ?: return null
+        return mapOf("type" to "stream_controller_response", "protocolVersion" to 1,
+            "controllerId" to controllerId, "streamId" to streamId, "probeId" to probeId)
+    }
+}

package/android/src/main/java/com/mentra/bluetoothsdk/streaming/StreamModels.kt

@@ -481,6 +481,14 @@ data class StreamStatusEvent(
     val status: StreamStatus,
     val stats: StreamLiveStats? = null,
 ) {
+    var processSessionId: String? = null
+        private set
+    var revision: Long? = null
+        private set
+    var terminal: Boolean? = null
+        private set
+    var errorDetails: String? = null
+        private set
     // True when the glasses will retry the failed publisher themselves
     // (emitting side lands in PR #3488); absent on older firmware and on
     // events not parsed from a glasses status map. Carried here instead of
@@ -493,6 +501,10 @@ data class StreamStatusEvent(
         stats = StreamLiveStats.fromMap(stringMapValue(values["stats"])),
     ) {
         willRetry = boolValue(values, "willRetry")
+        processSessionId = stringValue(values, "sid")
+        revision = longValue(values, "revision")
+        terminal = boolValue(values, "terminal")
+        errorDetails = stringValue(values, "errorDetails")
     }
 
     val state: StreamState get() = status.state
@@ -501,6 +513,10 @@ data class StreamStatusEvent(
     val values: Map<String, Any>
         get() = buildMap {
             putAll(status.toEventMap())
+            processSessionId?.let { put("sid", it) }
+            revision?.let { put("revision", it) }
+            terminal?.let { put("terminal", it) }
+            errorDetails?.let { put("errorDetails", it) }
             stats?.let { put("stats", it.toMap()) }
             willRetry?.let { put("willRetry", it) }
         }

package/android/src/main/java/com/mentra/bluetoothsdk/streaming/StreamSessionState.kt

@@ -0,0 +1,32 @@
+package com.mentra.bluetoothsdk.streaming
+
+/** Observes glasses-owned streaming; delivery gaps never imply publisher failure. */
+internal class StreamSessionState {
+    @Volatile var processSessionId: String? = null
+        private set
+    @Volatile var currentStreamId: String? = null
+        private set
+    @Volatile var supported = false
+        private set
+    private var revision = -1L
+
+    @Synchronized
+    fun ready(sessionId: String?, controlVersion: Int?) {
+        supported = controlVersion == 1 && !sessionId.isNullOrEmpty()
+        if (processSessionId != sessionId) {
+            currentStreamId = null
+            revision = -1
+        }
+        processSessionId = sessionId
+    }
+
+    @Synchronized
+    fun accept(values: Map<String, Any?>): Boolean {
+        if (!supported || values["sid"] != processSessionId) return false
+        val incomingRevision = (values["revision"] as? Number)?.toLong() ?: return false
+        if (incomingRevision < revision) return false
+        revision = incomingRevision
+        currentStreamId = if (values["terminal"] == true) null else values["streamId"] as? String
+        return true
+    }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/streaming/StreamControllerProbeTest.kt

@@ -0,0 +1,24 @@
+package com.mentra.bluetoothsdk.streaming
+
+import org.junit.Assert.*
+import org.junit.Test
+
+class StreamControllerProbeTest {
+    private fun probe() = mapOf<String, Any>("protocolVersion" to 1,
+        "controllerId" to StreamControllerProbe.controllerId, "streamId" to "stream", "probeId" to "nonce")
+
+    @Test fun answersCurrentProcessChallengeWithoutJsOrTimer() {
+        val response = StreamControllerProbe.response(probe())!!
+        assertEquals("stream_controller_response", response["type"])
+        assertEquals("nonce", response["probeId"])
+        assertEquals("stream", response["streamId"])
+    }
+
+    @Test fun rejectsPreviousProcessAndMalformedChallenges() {
+        assertNull(StreamControllerProbe.response(probe() + ("controllerId" to "previous-process")))
+        assertNull(StreamControllerProbe.response(probe() + ("protocolVersion" to 2)))
+        assertNull(StreamControllerProbe.response(probe() + ("protocolVersion" to true)))
+        assertNull(StreamControllerProbe.response(probe() + ("probeId" to "")))
+        assertNull(StreamControllerProbe.response(probe() - "streamId"))
+    }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/streaming/StreamSessionStateTest.kt

@@ -0,0 +1,43 @@
+package com.mentra.bluetoothsdk.streaming
+
+import org.junit.Assert.*
+import org.junit.Test
+
+class StreamSessionStateTest {
+    @Test fun readinessRequiresKnownProtocolAndProcessIdentity() {
+        val state = StreamSessionState()
+        state.ready("asg", null)
+        assertFalse(state.supported)
+        state.ready("asg", 2)
+        assertFalse(state.supported)
+        state.ready("", 1)
+        assertFalse(state.supported)
+        state.ready("asg", 1)
+        assertTrue(state.supported)
+    }
+
+    @Test fun reconnectReconcilesTerminalStateWithoutHeartbeatTimeouts() {
+        val state = StreamSessionState()
+        state.ready("asg", 1)
+        assertTrue(state.accept(event("asg", 1, false)))
+        state.ready("asg", 1)
+        assertEquals("stream", state.currentStreamId)
+        assertTrue(state.accept(event("asg", 3, true)))
+        assertNull(state.currentStreamId)
+        assertFalse(state.accept(event("asg", 2, false)))
+        assertNull(state.currentStreamId)
+    }
+
+    @Test fun restartRejectsOldStatusAndAcceptsNewStoppedSnapshot() {
+        val state = StreamSessionState()
+        state.ready("old", 1)
+        assertTrue(state.accept(event("old", 8, false)))
+        state.ready("new", 1)
+        assertFalse(state.accept(event("old", 9, false)))
+        assertTrue(state.accept(mapOf("sid" to "new", "revision" to 0, "terminal" to true)))
+        assertNull(state.currentStreamId)
+    }
+
+    private fun event(sid: String, revision: Int, terminal: Boolean) =
+        mapOf("sid" to sid, "revision" to revision, "streamId" to "stream", "terminal" to terminal)
+}

package/build/BluetoothSdk.types.d.ts

@@ -719,6 +719,11 @@ export type StreamLiveStats = {
 type StreamStatusCommon = {
     type: "stream_status";
     streamId?: string;
+    /** ASG process identity and monotonic revision for reconnect reconciliation. */
+    sid?: string;
+    revision?: number;
+    terminal?: boolean;
+    errorDetails?: string;
     timestamp?: number;
     resolvedConfig?: StreamResolvedConfig;
     stats?: StreamLiveStats;
@@ -746,7 +751,7 @@ export type StreamStatusEvent = (StreamStatusCommon & {
     errorDetails: string;
 }) | (StreamStatusCommon & {
     kind: "snapshot";
-    status: "streaming" | "reconnecting" | "stopped";
+    status: StreamStatusState;
     streaming: boolean;
     reconnecting: boolean;
     attempt?: number;