@mentra/bluetooth-sdk 3.3.0-dev.822 → 3.3.0-dev.825

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 android.util.Log
 import com.mentra.bluetoothsdk.streaming.StreamSessionState
 import com.mentra.bluetoothsdk.utils.ControllerTypes
 import com.mentra.bluetoothsdk.utils.PhoneAudioMonitor
@@ -34,6 +35,21 @@ class MentraBluetoothSdk private constructor(
     private val listeners =
         Collections.synchronizedSet(mutableSetOf<MentraBluetoothSdkListener>())
     private val analytics = BluetoothSdkAnalytics(appContext, config.analytics)
+    private val updateCheck =
+        BluetoothSdkUpdateCheck(appContext, config.analytics.surface) { banner, result ->
+            Log.w(UPDATE_LOG_TAG, banner)
+            dispatchToListeners {
+                it.onRawEvent(
+                    "sdk_update_notice",
+                    buildMap {
+                        put("message", banner)
+                        put("status", result.status)
+                        put("installedVersion", BuildConfig.SDK_VERSION)
+                        result.latestVersion?.let { latest -> put("latestVersion", latest) }
+                    },
+                )
+            }
+        }
     private val discoveredDeviceNames = mutableSetOf<String>()
     private val bridgeEventSinkId: String
     private val storeListenerId: String
@@ -99,6 +115,7 @@ class MentraBluetoothSdk private constructor(
         analytics.initializeGlassesStatus(getRawGlassesStatus())
         storeListenerId = DeviceStore.store.addListener { category, changes -> dispatchStoreUpdate(category, changes) }
         analytics.captureStarted()
+        updateCheck.start()
     }
 
     companion object {
@@ -106,6 +123,8 @@ class MentraBluetoothSdk private constructor(
         private val SCAN_STATE_KEYS = setOf("searching", "searchingController", "searchResults")
         private const val DEFAULT_SCAN_TIMEOUT_MS = 15_000L
         private const val DEFAULT_REQUEST_TIMEOUT_MS = 15_000L
+        private const val UPDATE_LOG_TAG = "MentraBluetoothSDK"
+        private val MIC_STATE_KEYS = setOf("currentMic", "should_send_transcript", "local_stt_fallback_active")
         // Mirrors AsgConstants: one active + one coalesced pending FOV update, plus BLE margin.
         // Keep in sync with ios/Source/MentraBluetoothSDK.swift and the ASG readiness budget.
         private const val CAMERA_FOV_READY_TIMEOUT_MS = 20_000L
@@ -240,8 +259,10 @@ class MentraBluetoothSdk private constructor(
     // (expo.modules.AsyncFunctionQueue), so a blocked await here froze all
     // miniapp event delivery (Crust.mentraJsDispatchToJs) until the glasses
     // responded. resolve()/reject() stay callable from any thread.
-    private class PendingResponse<T>(
+    private inner class PendingResponse<T>(
         private val operation: String,
+        // The operation without per-request ids, so timeouts group in analytics.
+        private val telemetryOperation: String = operation,
     ) {
         private val deferred = CompletableDeferred<T>()
 
@@ -258,10 +279,13 @@ class MentraBluetoothSdk private constructor(
             // can only mean the deadline elapsed. A rejected deferred rethrows
             // its error from await() and propagates out unchanged.
             return withTimeoutOrNull(timeoutMs) { deferred.await() }
-                ?: throw BluetoothSdkException(
-                    "request_timeout",
-                    "$operation timed out waiting for glasses response.",
-                )
+                ?: run {
+                    analytics.recordUsage { requestTimedOut(telemetryOperation) }
+                    throw BluetoothSdkException(
+                        "request_timeout",
+                        "$operation timed out waiting for glasses response.",
+                    )
+                }
         }
 
     }
@@ -503,6 +527,7 @@ class MentraBluetoothSdk private constructor(
     }
 
     fun cancelConnectionAttempt() {
+        analytics.noteDisconnectRequested(BluetoothSdkAnalyticsTracker.DISCONNECT_CANCEL)
         DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_name", "")
         DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_address", "")
         DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_secure_pairing_capable", "")
@@ -514,6 +539,7 @@ class MentraBluetoothSdk private constructor(
     }
 
     fun disconnect() {
+        analytics.noteDisconnectRequested(BluetoothSdkAnalyticsTracker.DISCONNECT_USER)
         DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_name", "")
         DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_address", "")
         DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_secure_pairing_capable", "")
@@ -521,6 +547,7 @@ class MentraBluetoothSdk private constructor(
     }
 
     fun forget() {
+        analytics.noteDisconnectRequested(BluetoothSdkAnalyticsTracker.DISCONNECT_FORGET)
         deviceManager.forget()
     }
 
@@ -947,8 +974,12 @@ class MentraBluetoothSdk private constructor(
             pendingWifiStatus = PendingWifiStatusRequest(ssid, pending)
         }
         try {
-            deviceManager.sendWifiCredentials(ssid, password)
-            return pending.await()
+            return withUsageOutcome(
+                { latencyMs, errorCode, _ -> analytics.recordUsage { wifiSetupSettled(latencyMs, errorCode) } },
+            ) {
+                deviceManager.sendWifiCredentials(ssid, password)
+                pending.await()
+            }
         } finally {
             synchronized(oneShotLock) {
                 if (pendingWifiStatus?.pending === pending) {
@@ -1062,8 +1093,14 @@ class MentraBluetoothSdk private constructor(
                 pendingHotspotStatus = PendingHotspotStatusRequest(enabled, pending)
             }
             try {
-                deviceManager.setHotspotState(enabled)
-                pending.await()
+                withUsageOutcome(
+                    { latencyMs, errorCode, _ ->
+                        if (enabled) analytics.recordUsage { hotspotStartSettled(latencyMs, errorCode) }
+                    },
+                ) {
+                    deviceManager.setHotspotState(enabled)
+                    pending.await()
+                }
             } finally {
                 synchronized(oneShotLock) {
                     if (pendingHotspotStatus?.pending === pending) {
@@ -1090,13 +1127,31 @@ class MentraBluetoothSdk private constructor(
         Bridge.log(
             "NATIVE: PHOTO PIPELINE [3b/6] MentraBluetoothSdk.requestPhoto requestId=${routedRequest.requestId}"
         )
-        val pending = PendingResponse<PhotoResponseEvent>("photo request ${routedRequest.requestId}")
+        val pending = PendingResponse<PhotoResponseEvent>("photo request ${routedRequest.requestId}", "photo request")
         pendingPhotoRequests[routedRequest.requestId] = pending
         try {
-            deviceManager.requestPhoto(routedRequest)
-            return pending.await(
-                if (routedRequest.presendThumbnail) PHOTO_THUMBNAIL_REQUEST_TIMEOUT_MS else PHOTO_REQUEST_TIMEOUT_MS,
-            )
+            return withUsageOutcome(
+                { latencyMs, errorCode, event ->
+                    val fileSizeBytes = (event?.response as? PhotoResponse.Success)?.fileSizeBytes
+                    analytics.recordUsage {
+                        photoSettled(
+                            size = routedRequest.size.value,
+                            mode = routedRequest.mode.value,
+                            compress = routedRequest.compress.value,
+                            save = routedRequest.save,
+                            transferMethod = routedRequest.transferMethod,
+                            latencyMs = latencyMs,
+                            fileSizeBytes = fileSizeBytes,
+                            errorCode = errorCode,
+                        )
+                    }
+                },
+            ) {
+                deviceManager.requestPhoto(routedRequest)
+                pending.await(
+                    if (routedRequest.presendThumbnail) PHOTO_THUMBNAIL_REQUEST_TIMEOUT_MS else PHOTO_REQUEST_TIMEOUT_MS,
+                )
+            }
         } finally {
             pendingPhotoRequests.remove(routedRequest.requestId, pending)
         }
@@ -1112,7 +1167,7 @@ class MentraBluetoothSdk private constructor(
         mfnr: Boolean? = null,
     ): CameraStatusEvent {
         val effectiveRequestId = nonBlankRequestId(requestId) ?: generatedCameraRequestId("warm")
-        val pending = PendingResponse<CameraStatusEvent>("camera warm up $effectiveRequestId")
+        val pending = PendingResponse<CameraStatusEvent>("camera warm up $effectiveRequestId", "camera warm up")
         // Guard against a concurrent warm-up reusing the same requestId: a blind put would overwrite
         // (and strand) the first caller's continuation until it times out. Reject the duplicate.
         if (pendingCameraStatusRequests.putIfAbsent(effectiveRequestId, pending) != null) {
@@ -1159,35 +1214,55 @@ class MentraBluetoothSdk private constructor(
     }
 
     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()}"
         message["streamId"] = streamId
-        val pending = PendingResponse<StreamStatusEvent>("start stream $streamId")
-        var start: PendingStreamStart? = null
-        try {
-            // seq assignment and the BLE hand-off must be one critical section:
-            // rejectPreemptedStreamStarts only works if seq order equals the
-            // order the commands reach the glasses' FIFO.
-            synchronized(streamStartOrderLock) {
-                val registered = PendingStreamStart(streamStartSeq.incrementAndGet(), pending)
-                pendingStreamStarts[streamId] = registered
-                start = registered
-                deviceManager.startStream(message)
+        return withUsageOutcome(
+            { latencyMs, errorCode, _ ->
+                val glassesNetwork = glassesNetwork()
+                analytics.recordUsage {
+                    streamStartSettled(
+                        streamUrl = request.streamUrl,
+                        width = request.video?.width,
+                        height = request.video?.height,
+                        fps = request.video?.fps,
+                        bitrate = request.video?.bitrate,
+                        captureAudio = request.captureAudio,
+                        glassesNetwork = glassesNetwork,
+                        latencyMs = latencyMs,
+                        errorCode = errorCode,
+                    )
+                }
+            },
+        ) {
+            requireGlassesConnected("start stream")
+            if (!streamSession.supported) {
+                throw BluetoothSdkException("stream_control_unsupported", "Update the glasses software before starting a stream.")
+            }
+            val pending = PendingResponse<StreamStatusEvent>("start stream $streamId", "start stream")
+            val requestedAt = System.currentTimeMillis()
+            analytics.recordUsage { streamRequested(streamId, request.streamUrl, requestedAt) }
+            var start: PendingStreamStart? = null
+            try {
+                // seq assignment and the BLE hand-off must be one critical section:
+                // rejectPreemptedStreamStarts only works if seq order equals the
+                // order the commands reach the glasses' FIFO.
+                synchronized(streamStartOrderLock) {
+                    val registered = PendingStreamStart(streamStartSeq.incrementAndGet(), pending)
+                    pendingStreamStarts[streamId] = registered
+                    start = registered
+                    deviceManager.startStream(message)
+                }
+                pending.await(STREAM_START_TIMEOUT_MS)
+            } finally {
+                start?.let { pendingStreamStarts.remove(streamId, it) }
             }
-            val event = pending.await(STREAM_START_TIMEOUT_MS)
-            return event
-        } finally {
-            start?.let { pendingStreamStarts.remove(streamId, it) }
         }
     }
 
     suspend fun rgbLedControl(request: RgbLedRequest): RgbLedControlResponseEvent {
-        val pending = PendingResponse<RgbLedControlResponseEvent>("RGB LED command ${request.requestId}")
+        val pending = PendingResponse<RgbLedControlResponseEvent>("RGB LED command ${request.requestId}", "RGB LED command")
         pendingRgbLedRequests[request.requestId] = pending
         try {
             deviceManager.rgbLedControl(
@@ -1206,6 +1281,7 @@ class MentraBluetoothSdk private constructor(
     }
 
     suspend fun stopStream(): StreamStatusEvent {
+        analytics.updateUsage { streamStopRequested() }
         val pending = PendingResponse<StreamStatusEvent>("stop stream")
         val targetStreamId = streamSession.currentStreamId
         try {
@@ -1247,6 +1323,16 @@ class MentraBluetoothSdk private constructor(
                 "A video recording command is already waiting for requestId ${request.requestId}.",
             )
         }
+        analytics.updateUsage {
+            videoRequested(
+                request.requestId,
+                request.width,
+                request.height,
+                request.fps,
+                request.save,
+                request.maxRecordingTimeMinutes,
+            )
+        }
         try {
             deviceManager.startVideoRecording(
                     request.requestId,
@@ -1285,6 +1371,7 @@ class MentraBluetoothSdk private constructor(
                 "A video recording command is already waiting for requestId $requestId.",
             )
         }
+        analytics.updateUsage { videoStopRequested(requestId) }
         try {
             deviceManager.stopVideoRecording(requestId, webhookUrl, authToken)
             val timeoutMs =
@@ -1591,6 +1678,7 @@ class MentraBluetoothSdk private constructor(
         Bridge.removeEventSink(bridgeEventSinkId)
         DeviceStore.store.removeListener(storeListenerId)
         analytics.shutdown()
+        updateCheck.stop()
         listeners.clear()
     }
 
@@ -1600,7 +1688,7 @@ class MentraBluetoothSdk private constructor(
                 if (changes["connected"] == false) {
                     resetWifiProtocolSession("", "wifi_session_disconnected")
                 }
-                analytics.observeGlassesStatus(getRawGlassesStatus())
+                analytics.observeGlassesStatus(getRawGlassesStatus(), ::isPhoneBluetoothOff)
                 val state = getState()
                 dispatchToListeners {
                     it.onStateChanged(state)
@@ -1608,6 +1696,12 @@ class MentraBluetoothSdk private constructor(
                 }
             }
             ObservableStore.BLUETOOTH_CATEGORY -> {
+                if (analytics.isEnabled && changes.keys.any { it in MIC_STATE_KEYS }) {
+                    val bluetooth = getRawBluetoothStatus()
+                    val transcribing = bluetooth.shouldSendTranscript || bluetooth.localSttFallbackActive
+                    val now = System.currentTimeMillis()
+                    analytics.recordUsage { observeMic(bluetooth.currentMic, transcribing, now) }
+                }
                 val state = getState()
                 val scanChanged = changes.keys.any { it in SCAN_STATE_KEYS }
                 dispatchToListeners {
@@ -1874,6 +1968,10 @@ class MentraBluetoothSdk private constructor(
             "photo_response" -> {
                 val event = PhotoResponseEvent(data)
                 handlePhotoResponseForRequests(event)
+                val response = event.response
+                if (response is PhotoResponse.Error && event.requestId == BluetoothSdkUsageTracker.LOCAL_PHOTO_REQUEST_ID) {
+                    analytics.recordUsage { buttonPhotoFailed(response.errorCode) }
+                }
                 dispatchToListeners { it.onPhotoResponse(event) }
             }
             "photo_status" -> dispatchToListeners { it.onPhotoStatus(PhotoStatusEvent(data)) }
@@ -1885,6 +1983,8 @@ class MentraBluetoothSdk private constructor(
             "video_recording_status" -> {
                 val event = VideoRecordingStatusEvent(data)
                 handleVideoRecordingStatusForRequests(event)
+                val now = System.currentTimeMillis()
+                analytics.recordUsage { videoStatus(event.requestId, event.status, event.success, now) }
                 dispatchToListeners { it.onVideoRecordingStatus(event) }
             }
             "media_success", "media_error" -> {
@@ -1904,6 +2004,7 @@ class MentraBluetoothSdk private constructor(
                 if (data.containsKey("revision") && !streamSession.accept(data)) return
                 val event = StreamStatusEvent(data)
                 handleStreamStatusForRequests(event)
+                recordStreamStatus(event)
                 dispatchToListeners { it.onStreamStatus(event) }
             }
             "keep_alive_ack" -> {
@@ -1928,6 +2029,23 @@ class MentraBluetoothSdk private constructor(
                         )
                     }
                 }
+                if (analytics.isEnabled) {
+                    val glasses = getRawGlassesStatus()
+                    val now = System.currentTimeMillis()
+                    analytics.recordUsage {
+                        otaStatus(
+                            sessionId = event.sessionId,
+                            status = event.status,
+                            stepType = event.stepType,
+                            totalSteps = event.totalSteps,
+                            errorMessage = event.errorMessage,
+                            fromBuildNumber = glasses.buildNumber,
+                            fromBesFirmwareVersion = glasses.besFirmwareVersion,
+                            fromMtkFirmwareVersion = glasses.mtkFirmwareVersion,
+                            nowMs = now,
+                        )
+                    }
+                }
                 dispatchToListeners { it.onOtaStatus(event) }
             }
             "mic_health" -> {
@@ -1983,6 +2101,75 @@ class MentraBluetoothSdk private constructor(
         }
     }
 
+    private fun recordStreamStatus(event: StreamStatusEvent) {
+        if (!analytics.isEnabled) return
+        val status = event.status
+        val attempt =
+            when (status) {
+                is StreamStatus.Reconnecting -> status.attempt
+                is StreamStatus.Reconnected -> status.attempt
+                else -> null
+            }
+        val errorDetails = event.errorDetails ?: (status as? StreamStatus.Error)?.errorDetails
+        val now = System.currentTimeMillis()
+        analytics.recordUsage {
+            streamStatus(
+                streamId = event.streamId,
+                state = event.state.value,
+                terminal = event.terminal,
+                reconnectAttempt = attempt,
+                bitrate = event.stats?.bitrate,
+                fps = event.stats?.fps,
+                droppedFrames = event.stats?.droppedFrames,
+                temperatureC = event.stats?.temperatureC,
+                errorDetails = errorDetails,
+                nowMs = now,
+            )
+        }
+    }
+
+    private fun glassesNetwork(): String {
+        val glasses = getRawGlassesStatus()
+        return when {
+            glasses.hotspot is HotspotStatus.Enabled -> "hotspot"
+            glasses.wifi is WifiStatus.Connected -> "wifi"
+            else -> "none"
+        }
+    }
+
+    private fun isPhoneBluetoothOff(): Boolean =
+        try {
+            (appContext.getSystemService(Context.BLUETOOTH_SERVICE) as? BluetoothManager)?.adapter?.isEnabled == false
+        } catch (_: Exception) {
+            false
+        }
+
+    /**
+     * Runs a glasses command and reports its latency and outcome to usage
+     * analytics. Cancellation is the caller giving up, not a command outcome, so
+     * it is not reported.
+     */
+    private inline fun <T> withUsageOutcome(
+        record: (latencyMs: Long, errorCode: String?, result: T?) -> Unit,
+        block: () -> T,
+    ): T {
+        val startedAt = System.currentTimeMillis()
+        val result =
+            try {
+                block()
+            } catch (error: CancellationException) {
+                throw error
+            } catch (error: Exception) {
+                if (analytics.isEnabled) {
+                    val errorCode = (error as? BluetoothSdkException)?.code ?: error.javaClass.simpleName
+                    record(System.currentTimeMillis() - startedAt, errorCode, null)
+                }
+                throw error
+            }
+        if (analytics.isEnabled) record(System.currentTimeMillis() - startedAt, null, result)
+        return result
+    }
+
     private fun dispatchToListeners(callback: (MentraBluetoothSdkListener) -> Unit) {
         val snapshot = synchronized(listeners) { listeners.toList() }
         val deliver = {

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

@@ -12,7 +12,61 @@ class BluetoothSdkAnalyticsTrackerTest {
         model: String = "Mentra Live",
         serial: String = "",
         fullyBooted: Boolean = connected,
-    ) = AnalyticsGlassesSnapshot(connected = connected, fullyBooted = fullyBooted, model = model, serialNumber = serial)
+        battery: Int = -1,
+        charging: Boolean = false,
+    ) = AnalyticsGlassesSnapshot(
+        connected = connected,
+        fullyBooted = fullyBooted,
+        model = model,
+        serialNumber = serial,
+        batteryLevel = battery,
+        charging = charging,
+    )
+
+    @Test
+    fun `a counted connection reports its length, reason and battery when it ends`() {
+        tracker.initialize(snapshot(connected = false), reportingDay = 100)
+        tracker.observe(snapshot(connected = true), reportingDay = 100, nowMs = 1_000)
+        tracker.observe(snapshot(connected = true, battery = 80), reportingDay = 100, nowMs = 2_000)
+        tracker.observe(snapshot(connected = true, battery = 71, charging = true), reportingDay = 100, nowMs = 3_000)
+
+        val ended =
+            tracker.observe(snapshot(connected = false), reportingDay = 100, nowMs = 61_000) {
+                BluetoothSdkAnalyticsTracker.DISCONNECT_USER
+            }
+        val disconnected = ended.single()
+        assertThat(disconnected.name).isEqualTo("bluetooth_sdk_glasses_disconnected")
+        assertThat(disconnected.properties)
+            .containsEntry("session_duration_ms", 60_000L)
+            .containsEntry("disconnect_reason", "user_disconnect")
+            .containsEntry("battery_level_at_connect", 80)
+            .containsEntry("battery_level_at_disconnect", 71)
+            .containsEntry("charging", true)
+            .containsEntry("glasses_model", "Mentra Live")
+
+        // Further disconnected updates do not report the connection again.
+        assertThat(tracker.observe(snapshot(connected = false), reportingDay = 100, nowMs = 62_000)).isEmpty()
+    }
+
+    @Test
+    fun `a connection already up when the SDK started is not reported as ending`() {
+        tracker.initialize(snapshot(connected = true, serial = "MLAB0001"), reportingDay = 100)
+        assertThat(tracker.observe(snapshot(connected = false), reportingDay = 100, nowMs = 5_000)).isEmpty()
+    }
+
+    @Test
+    fun `battery from a previous connection does not leak into the next one`() {
+        tracker.initialize(snapshot(connected = false), reportingDay = 100)
+        tracker.observe(snapshot(connected = true, battery = 90), reportingDay = 100, nowMs = 0)
+        tracker.observe(snapshot(connected = false), reportingDay = 100, nowMs = 1_000)
+        tracker.observe(snapshot(connected = true), reportingDay = 100, nowMs = 2_000)
+        val second = tracker.observe(snapshot(connected = false), reportingDay = 100, nowMs = 3_000).single()
+        assertThat(second.properties)
+            .doesNotContainKey("battery_level_at_connect")
+            .doesNotContainKey("battery_level_at_disconnect")
+            .doesNotContainKey("charging")
+            .containsEntry("disconnect_reason", "unknown")
+    }
 
     @Test
     fun `connect then serial emits connected and identified once, reconnects do not repeat identification within a connection`() {
@@ -55,8 +109,9 @@ class BluetoothSdkAnalyticsTrackerTest {
         tracker.initialize(snapshot(connected = false), reportingDay = 100)
         tracker.observe(snapshot(connected = true, model = ""), reportingDay = 100)
         val ended = tracker.observe(snapshot(connected = false, model = ""), reportingDay = 100)
-        assertThat(ended.single().name).isEqualTo("bluetooth_sdk_glasses_connected")
-        assertThat(ended.single().properties).containsEntry("glasses_model_unresolved", true).doesNotContainKey("glasses_model")
+        assertThat(ended.map { it.name })
+            .containsExactly("bluetooth_sdk_glasses_connected", "bluetooth_sdk_glasses_disconnected")
+        assertThat(ended.first().properties).containsEntry("glasses_model_unresolved", true).doesNotContainKey("glasses_model")
     }
 
     @Test

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

@@ -0,0 +1,124 @@
+package com.mentra.bluetoothsdk
+
+import androidx.test.core.app.ApplicationProvider
+import android.content.Context
+import org.assertj.core.api.Assertions.assertThat
+import org.json.JSONObject
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [33])
+class BluetoothSdkUpdateCheckTest {
+    private val context: Context = ApplicationProvider.getApplicationContext()
+
+    private fun result(status: String, latest: String? = "3.2.1", minimum: String? = null) =
+        BluetoothSdkUpdateCheckResult(status, "latest", latest, minimum)
+
+    @Test
+    fun `parses the Core response, treating null and blank versions as unknown`() {
+        val parsed =
+            BluetoothSdkUpdateCheckResult.parse(
+                """{"status":"update_available","channel":"dev","latestVersion":"3.3.0-dev.821","minimumSupportedVersion":null}""",
+            )!!
+        assertThat(parsed).isEqualTo(BluetoothSdkUpdateCheckResult("update_available", "dev", "3.3.0-dev.821", null))
+        assertThat(BluetoothSdkUpdateCheckResult.parse("""{"status":"current","latestVersion":""}""")!!.latestVersion).isNull()
+        assertThat(BluetoothSdkUpdateCheckResult.parse("<html>502</html>")).isNull()
+    }
+
+    @Test
+    fun `the banner names the installed and latest versions and the surface's update command`() {
+        val reactNative = BluetoothSdkUpdateNotice.banner("3.1.0", result("update_available"), "react_native")!!
+        assertThat(reactNative)
+            .contains("MENTRA BLUETOOTH SDK UPDATE AVAILABLE")
+            .contains("Installed: 3.1.0")
+            .contains("Latest: 3.2.1")
+            .contains("bun add @mentra/bluetooth-sdk@3.2.1")
+            .doesNotContain("NO LONGER SUPPORTED")
+        assertThat(BluetoothSdkUpdateNotice.banner("3.1.0", result("update_available"), "android")!!)
+            .contains("com.mentraglass:bluetooth-sdk:3.2.1")
+        assertThat(BluetoothSdkUpdateNotice.banner("3.1.0", result("update_available"), "ios")!!)
+            .contains("MentraBluetoothSDK Swift package at 3.2.1")
+    }
+
+    @Test
+    fun `an unsupported version gets the stronger banner`() {
+        val banner = BluetoothSdkUpdateNotice.banner("3.0.5", result("unsupported", minimum = "3.1.0"), "android")!!
+        assertThat(banner)
+            .contains("MENTRA BLUETOOTH SDK 3.0.5 IS NO LONGER SUPPORTED")
+            .contains("known issues")
+    }
+
+    @Test
+    fun `no banner when current, unknown, or no latest version to point at`() {
+        assertThat(BluetoothSdkUpdateNotice.banner("3.2.1", result("current"), "android")).isNull()
+        assertThat(BluetoothSdkUpdateNotice.banner("3.2.1", result("unknown", latest = null), "android")).isNull()
+        assertThat(BluetoothSdkUpdateNotice.banner("3.2.1", result("update_available", latest = null), "android")).isNull()
+    }
+
+    @Test
+    fun `the request identifies the install, app and SDK`() {
+        val body = BluetoothSdkUpdateCheck(context, "react_native", sdkVersion = "3.1.0", transport = { null }) { _, _ -> }.requestBody()
+        assertThat(body.getString("install_id")).isEqualTo(BluetoothSdkInstallId.get(context)).startsWith("mentra-bt-sdk-")
+        assertThat(body.getString("app_identifier")).isEqualTo(context.packageName)
+        assertThat(body.getString("sdk_version")).isEqualTo("3.1.0")
+        assertThat(body.getString("sdk_platform")).isEqualTo("android")
+        assertThat(body.getString("sdk_surface")).isEqualTo("react_native")
+        assertThat(body.has("app_build_type")).isTrue()
+    }
+
+    @Test
+    fun `an out-of-date SDK prints the banner once at start and stops on close`() {
+        val notices = mutableListOf<String>()
+        var sentBody: String? = null
+        val check =
+            BluetoothSdkUpdateCheck(
+                context,
+                "android",
+                sdkVersion = "3.1.0",
+                transport = { body ->
+                    sentBody = body
+                    """{"status":"update_available","channel":"latest","latestVersion":"3.2.1","minimumSupportedVersion":null}"""
+                },
+            ) { banner, _ -> notices += banner }
+        check.start()
+        BluetoothSdkUpdateCheck.awaitIdle()
+        assertThat(notices).hasSize(1)
+        assertThat(notices.single()).contains("Latest: 3.2.1")
+        assertThat(JSONObject(sentBody!!).getString("sdk_version")).isEqualTo("3.1.0")
+        check.stop()
+    }
+
+    @Test
+    fun `failures and unknown versions are silent`() {
+        val notices = mutableListOf<String>()
+        BluetoothSdkUpdateCheck(context, "android", sdkVersion = "3.1.0", transport = { null }) { banner, _ -> notices += banner }.start()
+        BluetoothSdkUpdateCheck(context, "android", sdkVersion = "3.1.0", transport = { throw IllegalStateException("offline") }) { banner, _ -> notices += banner }.start()
+        var called = false
+        BluetoothSdkUpdateCheck(context, "android", sdkVersion = "unknown", transport = { called = true; null }) { banner, _ -> notices += banner }.start()
+        BluetoothSdkUpdateCheck.awaitIdle()
+        assertThat(notices).isEmpty()
+        assertThat(called).isFalse()
+    }
+
+    @Test
+    fun `a check stopped before the response arrives prints nothing`() {
+        val notices = mutableListOf<String>()
+        lateinit var check: BluetoothSdkUpdateCheck
+        check =
+            BluetoothSdkUpdateCheck(
+                context,
+                "android",
+                sdkVersion = "3.1.0",
+                transport = {
+                    check.stop()
+                    """{"status":"update_available","latestVersion":"3.2.1"}"""
+                },
+            ) { banner, _ -> notices += banner }
+        check.start()
+        BluetoothSdkUpdateCheck.awaitIdle()
+        assertThat(notices).isEmpty()
+    }
+}