@mentra/bluetooth-sdk 0.1.12 → 0.1.13

package/README.md

@@ -325,7 +325,7 @@ React Native narrows returned values to success shapes where the raw listener ev
 | `startVideoRecording(...)` | `VideoRecordingStartedStatusEvent` with `success: true` and `status: "recording_started"`. | Rejects on `success: false` statuses such as `already_recording`, send failure, or timeout. |
 | `stopVideoRecording(...)` | `VideoRecordingStoppedStatusEvent` with `success: true` and `status: "recording_stopped"`. When a webhook URL is supplied, resolves after the video upload succeeds. | Rejects on `success: false` statuses such as `not_recording`, webhook upload failure, send failure, or timeout. |
 | `rgbLedControl(...)` | `RgbLedControlSuccessResponseEvent` with `state: "success"`. | Rejects when raw `rgb_led_control_response.state === "error"` or the response times out. |
-| `checkForOtaUpdate()` / `retryOtaVersionCheck()` | `OtaQueryResult`, either `ota_update_available` or current `ota_status`. | Rejects on command transport timeout/failure. A returned `ota_status.status === "failed"` is glasses OTA state, not a command rejection. |
+| `checkForOtaUpdate()` | `boolean`, true when the configured OTA manifest has an ASG APK, MTK, or BES update for the connected glasses; false only when the manifest was checked successfully and no update is available. | Rejects when the glasses are disconnected, version info is unavailable, the manifest cannot be fetched, or the manifest response is invalid/missing required ASG app version fields. |
 
 Android and iOS async APIs use `BluetoothException` / `BluetoothError` for the same error paths. Their returned event structs are the successful response in normal `try`/`await` code, while raw listener/delegate events still include both success and error payloads.
 
@@ -335,9 +335,16 @@ Android and iOS async APIs use `BluetoothException` / `BluetoothError` for the s
 
 Mentra Live firmware owns the OTA flow. The SDK mirrors the MentraOS app commands and events:
 
-- `checkForOtaUpdate()` sends `ota_query_status` and resolves with the ASG response (`ota_update_available` or the current `ota_status`).
-- `startOtaUpdate()` sends `ota_start` and resolves with the ASG start ack after your app presents the update and the user accepts it.
-- `retryOtaVersionCheck()` sends `ota_retry_version_check` and resolves with the same ASG response shape as `checkForOtaUpdate()`; use it only after fixing a known clock-skew/TLS failure.
+- `checkForOtaUpdate()` fetches the configured manifest and resolves with `true` when an ASG APK, MTK, or BES update is available.
+- `startOtaUpdate()` sends `ota_start` with the same configured manifest URL and resolves with the ASG start ack after your app presents the update and the user accepts it.
+
+The default manifest is derived from the SDK version:
+`https://github.com/Mentra-Community/MentraOS/releases/download/bluetooth-sdk-ota/bluetooth-sdk-<sdkVersion>-version.json`.
+Each published SDK version points at a durable ASG client APK and firmware
+manifest that were built for that SDK release. Pre-wall-clock ASG builds that
+ignore `ota_start.ota_version_url` are checked against the URL they advertise,
+or the production default if they do not advertise one, so the app does not
+prompt for an update the glasses cannot install.
 
 ```ts
 import BluetoothSdk from '@mentra/bluetooth-sdk'
@@ -346,9 +353,9 @@ BluetoothSdk.addListener('ota_status', (event) => {
   console.log(`OTA ${event.status}: ${event.overall_percent}%`)
 })
 
-const ota = await BluetoothSdk.checkForOtaUpdate()
-if (ota.type === 'ota_update_available') {
-  const userAccepted = await promptUserToInstallUpdate(ota) // your app's UI
+const hasUpdate = await BluetoothSdk.checkForOtaUpdate()
+if (hasUpdate) {
+  const userAccepted = await promptUserToInstallUpdate() // your app's UI
   if (userAccepted) {
     const startAck = await BluetoothSdk.startOtaUpdate()
     console.log('OTA start acknowledged', startAck.timestamp)
@@ -425,7 +432,7 @@ export function HardwareEventLogger() {
 
 For non-React modules, `BluetoothSdk.addListener(...)` is the low-level subscription API. Keep the returned subscription and call `remove()` when the listener is no longer needed.
 
-Common event names include `button_press`, `touch_event`, `head_up`, `battery_status`, `wifi_status_change`, `wifi_scan_result`, `hotspot_status_change`, `photo_status`, `photo_response`, `gallery_status`, `settings_ack`, `version_info`, `stream_status`, `ota_update_available`, `ota_start_ack`, `ota_status`, `mic_pcm`, `mic_lc3`, `local_transcription`, `rgb_led_control_response`, `audio_connected`, `audio_disconnected`, and `log`.
+Common event names include `button_press`, `touch_event`, `head_up`, `battery_status`, `wifi_status_change`, `wifi_scan_result`, `hotspot_status_change`, `photo_status`, `photo_response`, `gallery_status`, `settings_ack`, `version_info`, `stream_status`, `ota_start_ack`, `ota_status`, `mic_pcm`, `mic_lc3`, `local_transcription`, `rgb_led_control_response`, `audio_connected`, `audio_disconnected`, and `log`.
 
 React Native event payload fields usually use camelCase. OTA events intentionally mirror the glasses firmware field names, such as `overall_percent` and `version_name`. For example, `touch_event` includes `gestureName`, `wifi_scan_result` includes `networks` and `scanComplete`, `version_info` matches the `requestVersionInfo()` result shape, `photo_response` success includes `uploadUrl` and may include webhook-returned `photoUrl`, `statusUrl`, `contentType`, and `fileSizeBytes`, and `gallery_status` includes `hasContent`, `cameraBusy`, and optional `cameraBusyReason`. `photo_status` reports intermediate photo states such as `accepted`, `queued`, `configuring`, `capturing`, `captured`, `compressing`, `ble_fallback_compression`, `uploading`, `ready_for_transfer`, `transferring`, and `failed`; the `configuring` event includes `resolvedConfig` with the effective JPEG dimensions, quality, requested size, transfer method, compression, and manual exposure fields when present. The `capturing` event may include `requestedCaptureConfig` and `meteredPreview`; the `captured` event may include `captureMetadata` with the HAL-applied exposure, ISO, frame duration, and AE state. `mic_pcm` includes `sampleRate`, `bitsPerSample`, `channels`, and `encoding`; `mic_lc3` includes `sampleRate`, `channels`, `encoding`, `frameDurationMs`, `frameSizeBytes`, `bitrate`, and `packetizedFromGlasses`.
 
@@ -458,7 +465,7 @@ For bare native iOS apps, use the public SwiftPM repository:
 https://github.com/Mentra-Community/mentra-bluetooth-sdk-ios.git
 ```
 
-Add the `MentraBluetoothSDK` product to your app target at version `0.1.12` or newer.
+Select version `0.1.13`, then add the `MentraBluetoothSDK` product to your app target.
 
 For local SDK development, add this package folder directly in Xcode:
 

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

@@ -441,8 +441,37 @@ class BluetoothSdkModule : Module() {
             sdk?.setVoiceActivityDetectionEnabled(enabled)
         }
 
-        AsyncFunction("setButtonPhotoSettings") { size: String ->
-            requireSdk().setButtonPhotoSettings(ButtonPhotoSize.fromValue(size)).values
+        AsyncFunction("setButtonPhotoCaptureSettings") { params: Map<String, Any?> ->
+            val size = (params["size"] as? String)?.let { ButtonPhotoSize.fromValue(it) }
+            val mfnr = params["mfnr"] as? Boolean
+            val zsl = params["zsl"] as? Boolean
+            val noiseReduction = params["noiseReduction"] as? Boolean
+            val edgeEnhancement = params["edgeEnhancement"] as? Boolean
+            val ispDigitalGain = (params["ispDigitalGain"] as? Number)?.toInt()
+            val ispAnalogGain = params["ispAnalogGain"] as? String
+            val aeExposureDivisor = (params["aeExposureDivisor"] as? Number)?.toInt()
+            val isoCap = (params["isoCap"] as? Number)?.toInt()
+            val compress = params["compress"] as? String
+            val sound = params["sound"] as? Boolean
+            val resetCaptureTuning = params["resetCaptureTuning"] as? Boolean == true
+            requireSdk()
+                .setButtonPhotoSettings(
+                    ButtonPhotoSettings(
+                        size = size,
+                        mfnr = mfnr,
+                        zsl = zsl,
+                        noiseReduction = noiseReduction,
+                        edgeEnhancement = edgeEnhancement,
+                        ispDigitalGain = ispDigitalGain,
+                        ispAnalogGain = ispAnalogGain,
+                        aeExposureDivisor = aeExposureDivisor,
+                        isoCap = isoCap,
+                        compress = compress,
+                        sound = sound,
+                        resetCaptureTuning = resetCaptureTuning,
+                    ),
+                )
+                .values
         }
 
         AsyncFunction("setButtonVideoRecordingSettings") { width: Int, height: Int, fps: Int ->
@@ -483,7 +512,26 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - OTA Commands
 
-        AsyncFunction("sendOtaStart") { requireSdk().sendOtaStart().values }
+        Function("setOtaVersionUrl") { otaVersionUrl: String ->
+            requireSdk().setOtaVersionUrl(otaVersionUrl)
+        }
+
+        Function("getOtaVersionUrl") { requireSdk().getOtaVersionUrl() }
+
+        // Runs on Dispatchers.IO, not the shared Expo AsyncFunctionQueue:
+        // manifest fetches and version waits can block for several seconds.
+        AsyncFunction("checkForOtaUpdate") Coroutine { ->
+            withContext(Dispatchers.IO) { requireSdk().checkForOtaUpdate() }
+        }
+
+        AsyncFunction("startOtaUpdate") { otaVersionUrl: String? ->
+            val sdk = requireSdk()
+            if (otaVersionUrl.isNullOrBlank()) {
+                sdk.startOtaUpdate().values
+            } else {
+                sdk.startOtaUpdate(otaVersionUrl).values
+            }
+        }
 
         AsyncFunction("sendOtaQueryStatus") { requireSdk().sendOtaQueryStatus().values }
 

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

@@ -247,6 +247,7 @@ class DeviceManager {
     private var audioOutputFormat: AudioOutputFormat = AudioOutputFormat.LC3
     private var lastLc3Event: Long? = null
     private var micReinitRunnable: Runnable? = null
+    private var systemMicAvailabilityRecheckRunnable: Runnable? = null
 
     // VAD
     private val vadBuffer = mutableListOf<ByteArray>()
@@ -358,6 +359,37 @@ class DeviceManager {
         }
     }
 
+    private fun scheduleSystemMicAvailabilityRecheck(reason: String) {
+        if (systemMicAvailabilityRecheckRunnable != null) {
+            return
+        }
+
+        val recheck =
+                object : Runnable {
+                    override fun run() {
+                        systemMicAvailabilityRecheckRunnable = null
+
+                        if (!micEnabled || !systemMicUnavailable) {
+                            return
+                        }
+
+                        val stillBlocked = phoneMic?.hasBlockingMicInterruption() ?: true
+                        if (stillBlocked) {
+                            scheduleSystemMicAvailabilityRecheck(reason)
+                            return
+                        }
+
+                        systemMicUnavailable = false
+                        Bridge.log("MAN: MIC_UNAVAILABLE: FALSE recheck_after_$reason")
+                        appendLog("MAN: MIC_UNAVAILABLE: FALSE recheck_after_$reason")
+                        updateMicState()
+                    }
+                }
+
+        systemMicAvailabilityRecheckRunnable = recheck
+        mainHandler.postDelayed(recheck, 2_000)
+    }
+
     // MARK: - Unique (Android)
     private fun setupPermissionMonitoring() {
         val context = Bridge.getContext()
@@ -947,6 +979,7 @@ class DeviceManager {
                 systemMicUnavailable = true
                 Bridge.log("MAN: MIC_UNAVAILABLE: TRUE external_app_recording")
                 appendLog("MAN: MIC_UNAVAILABLE: TRUE external_app_recording")
+                scheduleSystemMicAvailabilityRecheck("external_app_recording")
             }
             "audio_focus_available" -> {
                 // Audio focus is available again
@@ -965,6 +998,7 @@ class DeviceManager {
                 systemMicUnavailable = true
                 Bridge.log("MAN: MIC_UNAVAILABLE: TRUE phone_call_interruption")
                 appendLog("MAN: MIC_UNAVAILABLE: TRUE phone_call_interruption")
+                scheduleSystemMicAvailabilityRecheck("phone_call_interruption")
             }
             "phone_call_ended" -> {
                 // Phone call ended - mark mic as available again
@@ -977,12 +1011,14 @@ class DeviceManager {
                 systemMicUnavailable = true
                 Bridge.log("MAN: MIC_UNAVAILABLE: TRUE phone_call_active")
                 appendLog("MAN: MIC_UNAVAILABLE: TRUE phone_call_active")
+                scheduleSystemMicAvailabilityRecheck("phone_call_active")
             }
             "audio_focus_denied" -> {
                 // Another app has audio focus
                 systemMicUnavailable = true
                 Bridge.log("MAN: MIC_UNAVAILABLE: TRUE audio_focus_denied")
                 appendLog("MAN: MIC_UNAVAILABLE: TRUE audio_focus_denied")
+                scheduleSystemMicAvailabilityRecheck("audio_focus_denied")
             }
             "permission_denied" -> {
                 // Microphone permission not granted
@@ -1010,6 +1046,9 @@ class DeviceManager {
                 // systemMicUnavailable = false
                 Bridge.log("MAN: MIC_UNAVAILABLE: UNKNOWN recording_stopped")
                 appendLog("MAN: MIC_UNAVAILABLE: UNKNOWN recording_stopped")
+                if (systemMicUnavailable) {
+                    scheduleSystemMicAvailabilityRecheck("recording_stopped")
+                }
             }
             else -> {
                 // Other route changes (headset plug/unplug, BT connect/disconnect, etc.)
@@ -1380,9 +1419,9 @@ class DeviceManager {
      * Send OTA start command to glasses. Called when user approves an update (onboarding or
      * background mode). Triggers glasses to begin download and installation.
      */
-    fun sendOtaStart() {
+    fun sendOtaStart(otaVersionUrl: String? = null) {
         Bridge.log("MAN: 📱 Sending OTA start command to glasses")
-        (sgc as? MentraLive)?.sendOtaStart()
+        (sgc as? MentraLive)?.sendOtaStart(otaVersionUrl)
     }
 
     fun sendOtaQueryStatus() {
@@ -1396,8 +1435,26 @@ class DeviceManager {
     }
 
     fun sendButtonPhotoSettings(requestId: String, size: String) {
+        sendButtonPhotoSettings(requestId, ButtonPhotoSettings(ButtonPhotoSize.fromValue(size)))
+    }
+
+    fun sendButtonPhotoSettings(requestId: String, settings: ButtonPhotoSettings) {
         val live = sgc as? MentraLive ?: throw IllegalStateException("unsupported_device")
-        live.sendButtonPhotoSettings(requestId, size)
+        live.sendButtonPhotoSettings(
+            requestId,
+            settings.size?.value,
+            settings.mfnr,
+            settings.zsl,
+            settings.noiseReduction,
+            settings.edgeEnhancement,
+            settings.ispDigitalGain,
+            settings.ispAnalogGain,
+            settings.aeExposureDivisor,
+            settings.isoCap,
+            settings.compress,
+            settings.sound,
+            settings.resetCaptureTuning == true,
+        )
     }
 
     fun sendButtonVideoRecordingSettings(requestId: String, width: Int, height: Int, fps: Int) {
@@ -1538,38 +1595,31 @@ class DeviceManager {
         updateMicState()
     }
 
-    fun requestPhoto(
-            requestId: String,
-            appId: String,
-            size: String,
-            webhookUrl: String,
-            authToken: String?,
-            compress: String,
-            flash: Boolean,
-            save: Boolean,
-            sound: Boolean,
-            exposureTimeNs: Double? = null,
-            iso: Int? = null,
-    ) {
+    fun requestPhoto(request: PhotoRequest) {
         val exposureNs: Long? =
-                exposureTimeNs?.takeIf { it.isFinite() && it > 0 }?.let { v ->
+                request.exposureTimeNs?.takeIf { it.isFinite() && it > 0 }?.let { v ->
                     when {
                         v > Long.MAX_VALUE.toDouble() -> Long.MAX_VALUE
                         else -> v.toLong()
                     }
                 }
-        val manualIso = if (exposureNs != null) iso?.takeIf { it > 0 } else null
+        val manualIso = if (exposureNs != null) request.iso?.takeIf { it > 0 } else null
+        val routed =
+                request.copy(
+                    exposureTimeNs = exposureNs?.toDouble(),
+                    iso = manualIso,
+                )
         Bridge.log(
-                "MAN: PHOTO PIPELINE [4/6] DeviceManager.requestPhoto requestId=$requestId appId=$appId size=$size compress=$compress flash=$flash save=$save sound=$sound exposureTimeNs=$exposureNs iso=${manualIso ?: "auto"} sgc=${sgc?.javaClass?.simpleName ?: "null"}"
+                "MAN: PHOTO PIPELINE [4/6] DeviceManager.requestPhoto requestId=${routed.requestId} appId=${routed.appId} size=${routed.size.value} compress=${routed.compress.value} flash=${routed.flash} save=${routed.save} sound=${routed.sound} exposureTimeNs=$exposureNs iso=${manualIso ?: "auto"} aeDivisor=${routed.aeExposureDivisor} isoCap=${routed.isoCap} sgc=${sgc?.javaClass?.simpleName ?: "null"}"
         )
         val activeSgc = sgc
         if (activeSgc == null) {
             Bridge.log(
-                    "MAN: PHOTO PIPELINE — sgc is null (glasses not connected); dropping requestId=$requestId"
+                    "MAN: PHOTO PIPELINE — sgc is null (glasses not connected); dropping requestId=${routed.requestId}"
             )
             return
         }
-        activeSgc.requestPhoto(requestId, appId, size, webhookUrl, authToken, compress, flash, save, sound, exposureNs, manualIso)
+        activeSgc.requestPhoto(routed)
     }
 
     fun rgbLedControl(
@@ -1781,6 +1831,8 @@ class DeviceManager {
 
         micReinitRunnable?.let { mainHandler.removeCallbacks(it) }
         micReinitRunnable = null
+        systemMicAvailabilityRecheckRunnable?.let { mainHandler.removeCallbacks(it) }
+        systemMicAvailabilityRecheckRunnable = null
 
         // Clean up transcriber resources
         transcriber?.shutdown()

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

@@ -126,7 +126,7 @@ object DeviceStore {
         store.set("bluetooth", "gallery_mode", true)
         store.set("bluetooth", "voice_activity_detection_enabled", BluetoothSdkDefaults.VOICE_ACTIVITY_DETECTION_ENABLED)
         store.set("bluetooth", "screen_disabled", false)
-        store.set("bluetooth", "button_photo_size", "medium")
+        store.set("bluetooth", "button_photo_size", "max")
         store.set("bluetooth", "button_camera_led", true)
         store.set("bluetooth", "button_max_recording_time", 10)
         store.set("bluetooth", "camera_fov", mapOf("fov" to 118, "roi_position" to 0))

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

@@ -45,6 +45,7 @@ class MentraBluetoothSdk private constructor(
     private var pendingWifiStatus: PendingWifiStatusRequest? = null
     private var pendingHotspotStatus: PendingHotspotStatusRequest? = null
     private var pendingVersionInfo: PendingResponse<VersionInfoResult>? = null
+    @Volatile private var configuredOtaVersionUrl: String? = null
 
     init {
         listeners.add(listener)
@@ -68,6 +69,9 @@ class MentraBluetoothSdk private constructor(
         private const val VIDEO_UPLOAD_STOP_TIMEOUT_MS = 10 * 60 * 1000L
         private const val STREAM_START_TIMEOUT_MS = 30_000L
         private const val STREAM_STOP_TIMEOUT_MS = 15_000L
+        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
 
@@ -470,16 +474,59 @@ class MentraBluetoothSdk private constructor(
         DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "voice_activity_detection_enabled", enabled)
     }
 
-    fun setButtonPhotoSettings(size: ButtonPhotoSize): SettingsAckEvent =
+    fun setButtonPhotoSettings(settings: ButtonPhotoSettings): SettingsAckEvent =
         performSettingsCommand(
             setting = "button_photo",
-            updateStore = { _ -> DeviceStore.set(ObservableStore.BLUETOOTH_CATEGORY, "button_photo_size", size.value) },
-            send = { requestId -> deviceManager.sendButtonPhotoSettings(requestId, size.value) },
+            updateStore = { _ ->
+                if (settings.resetCaptureTuning) {
+                    // Clear all stored scan-tuning keys from phone cache
+                    listOf(
+                        "button_photo_mfnr",
+                        "button_photo_zsl",
+                        "button_photo_noise_reduction",
+                        "button_photo_edge_enhancement",
+                        "button_photo_isp_digital_gain",
+                        "button_photo_isp_analog_gain",
+                        "button_photo_ae_exposure_divisor",
+                        "button_photo_iso_cap",
+                        "button_photo_compress",
+                        "button_photo_sound",
+                    ).forEach { key ->
+                        DeviceStore.store.remove(ObservableStore.BLUETOOTH_CATEGORY, key)
+                    }
+                }
+                // Only update size if explicitly provided; omitted size = leave stored value unchanged
+                settings.size?.let { DeviceStore.set(ObservableStore.BLUETOOTH_CATEGORY, "button_photo_size", it.value) }
+                settings.mfnr?.let { DeviceStore.set(ObservableStore.BLUETOOTH_CATEGORY, "button_photo_mfnr", it) }
+                settings.zsl?.let { DeviceStore.set(ObservableStore.BLUETOOTH_CATEGORY, "button_photo_zsl", it) }
+                settings.noiseReduction?.let {
+                    DeviceStore.set(ObservableStore.BLUETOOTH_CATEGORY, "button_photo_noise_reduction", it)
+                }
+                settings.edgeEnhancement?.let {
+                    DeviceStore.set(ObservableStore.BLUETOOTH_CATEGORY, "button_photo_edge_enhancement", it)
+                }
+                settings.ispDigitalGain?.let {
+                    DeviceStore.set(ObservableStore.BLUETOOTH_CATEGORY, "button_photo_isp_digital_gain", it)
+                }
+                settings.ispAnalogGain?.let {
+                    DeviceStore.set(ObservableStore.BLUETOOTH_CATEGORY, "button_photo_isp_analog_gain", it)
+                }
+                settings.aeExposureDivisor?.let {
+                    DeviceStore.set(ObservableStore.BLUETOOTH_CATEGORY, "button_photo_ae_exposure_divisor", it)
+                }
+                settings.isoCap?.let {
+                    DeviceStore.set(ObservableStore.BLUETOOTH_CATEGORY, "button_photo_iso_cap", it)
+                }
+                settings.compress?.let {
+                    DeviceStore.set(ObservableStore.BLUETOOTH_CATEGORY, "button_photo_compress", it)
+                }
+                settings.sound?.let {
+                    DeviceStore.set(ObservableStore.BLUETOOTH_CATEGORY, "button_photo_sound", it)
+                }
+            },
+            send = { requestId -> deviceManager.sendButtonPhotoSettings(requestId, settings) },
         )
 
-    fun setButtonPhotoSettings(settings: ButtonPhotoSettings): SettingsAckEvent =
-        setButtonPhotoSettings(size = settings.size)
-
     fun setButtonVideoRecordingSettings(width: Int, height: Int, fps: Int): SettingsAckEvent =
         performSettingsCommand(
             setting = "button_video_recording",
@@ -677,19 +724,7 @@ class MentraBluetoothSdk private constructor(
         val pending = PendingResponse<PhotoResponseEvent>("photo request ${request.requestId}")
         pendingPhotoRequests[request.requestId] = pending
         try {
-            deviceManager.requestPhoto(
-                request.requestId,
-                request.appId,
-                request.size.value,
-                request.webhookUrl,
-                request.authToken,
-                request.compress.value,
-                request.flash,
-                request.save,
-                request.sound,
-                request.exposureTimeNs,
-                request.iso,
-            )
+            deviceManager.requestPhoto(request)
             return pending.await()
         } finally {
             pendingPhotoRequests.remove(request.requestId, pending)
@@ -871,8 +906,41 @@ class MentraBluetoothSdk private constructor(
         }
     }
 
-    /** Ask connected Mentra Live glasses to check/report OTA availability and status. */
-    fun checkForOtaUpdate(): OtaQueryResult =
+    internal fun setOtaVersionUrl(otaVersionUrl: String) {
+        configuredOtaVersionUrl = OtaManifestChecker.normalizeHttpUrl(otaVersionUrl)
+    }
+
+    internal fun getOtaVersionUrl(): String = configuredOtaVersionUrl ?: OtaManifestDefaults.defaultOtaVersionUrl()
+
+    /** Fetch the configured OTA manifest and return whether any ASG/BES/MTK update is available. */
+    fun checkForOtaUpdate(): Boolean {
+        val status = getFreshGlassesStatus()
+        if (!status.connected) {
+            throw BluetoothException(
+                "glasses_not_connected",
+                "Cannot check OTA update because glasses are not connected.",
+            )
+        }
+        if (status.buildNumber.isBlank()) {
+            throw BluetoothException(
+                "missing_glasses_version",
+                "Cannot check OTA update because glasses build number is unavailable.",
+            )
+        }
+
+        val manifestUrl = resolveOtaVersionUrl(status)
+        val manifest = OtaManifestChecker.fetch(manifestUrl)
+        val otaStatus = waitForOtaManifestStatus(status, manifest)
+        return OtaManifestChecker.hasUpdate(
+            otaStatus.buildNumber,
+            otaStatus.mtkFirmwareVersion,
+            otaStatus.besFirmwareVersion,
+            manifest,
+        )
+    }
+
+    /** Ask connected Mentra Live glasses to report the current OTA install/session status. */
+    private fun queryOtaStatus(): OtaQueryResult =
         performOtaQuery("OTA status query") {
             deviceManager.sendOtaQueryStatus()
         }
@@ -905,6 +973,11 @@ class MentraBluetoothSdk private constructor(
 
     /** Start the OTA flow after your app has presented the available update to the user. */
     fun startOtaUpdate(): OtaStartAckEvent {
+        val otaVersionUrl = resolveOtaVersionUrl(getFreshGlassesStatus())
+        return startOtaUpdate(otaVersionUrl)
+    }
+
+    private fun startOtaCommand(otaVersionUrl: String): OtaStartAckEvent {
         val pending = PendingResponse<OtaStartAckEvent>("OTA start command")
         synchronized(oneShotLock) {
             if (pendingOtaStart != null) {
@@ -916,7 +989,7 @@ class MentraBluetoothSdk private constructor(
             pendingOtaStart = pending
         }
         try {
-            deviceManager.sendOtaStart()
+            deviceManager.sendOtaStart(otaVersionUrl)
             return pending.await()
         } finally {
             synchronized(oneShotLock) {
@@ -927,15 +1000,98 @@ class MentraBluetoothSdk private constructor(
         }
     }
 
-    /** Re-run the glasses-side OTA version check, mainly after correcting clock skew/TLS failures. */
-    fun retryOtaVersionCheck(): OtaQueryResult =
+    internal fun startOtaUpdate(otaVersionUrl: String): OtaStartAckEvent =
+        startOtaCommand(otaVersionUrl)
+
+    internal fun sendOtaQueryStatus(): OtaQueryResult = queryOtaStatus()
+
+    /** Re-run the glasses-side OTA version check after an internal clock-skew recovery. */
+    @JvmSynthetic
+    internal fun retryOtaVersionCheck(): OtaQueryResult =
         performOtaQuery("OTA version retry") {
             deviceManager.retryOtaVersionCheck()
         }
 
-    internal fun sendOtaStart(): OtaStartAckEvent = startOtaUpdate()
+    private fun getFreshGlassesStatus(): GlassesStatus {
+        val status = getRawGlassesStatus()
+        if (!status.connected || status.buildNumber.isNotBlank()) {
+            return status
+        }
+
+        return try {
+            val versionInfo = requestVersionInfo()
+            status.copy(
+                androidVersion = versionInfo.androidVersion.ifBlank { status.androidVersion },
+                firmwareVersion = versionInfo.firmwareVersion.ifBlank { status.firmwareVersion },
+                besFirmwareVersion = versionInfo.besFirmwareVersion.ifBlank { status.besFirmwareVersion },
+                mtkFirmwareVersion = versionInfo.mtkFirmwareVersion.ifBlank { status.mtkFirmwareVersion },
+                buildNumber = versionInfo.buildNumber.ifBlank { status.buildNumber },
+                systemTimeMs = versionInfo.systemTimeMs ?: status.systemTimeMs,
+                otaVersionUrl = versionInfo.otaVersionUrl.ifBlank { status.otaVersionUrl },
+                appVersion = versionInfo.appVersion.ifBlank { status.appVersion },
+            )
+        } catch (_: Throwable) {
+            status
+        }
+    }
+
+    private fun waitForOtaManifestStatus(
+        initialStatus: GlassesStatus,
+        manifest: org.json.JSONObject,
+    ): GlassesStatus {
+        var status = initialStatus
+        if (OtaManifestChecker.hasBesFirmware(manifest) && status.besFirmwareVersion.isBlank()) {
+            status = waitForGlassesStatus(status, OTA_BES_VERSION_WAIT_MS) {
+                !it.connected || it.besFirmwareVersion.isNotBlank()
+            }
+        }
+
+        if (OtaManifestChecker.hasMtkPatches(manifest) && status.mtkFirmwareVersion.isBlank()) {
+            status = waitForGlassesStatus(status, OTA_MTK_VERSION_WAIT_MS) {
+                !it.connected || it.mtkFirmwareVersion.isNotBlank()
+            }
+        }
+
+        if (!status.connected) {
+            throw BluetoothException(
+                "glasses_not_connected",
+                "Cannot check OTA update because glasses disconnected.",
+            )
+        }
+        return status
+    }
 
-    internal fun sendOtaQueryStatus(): OtaQueryResult = checkForOtaUpdate()
+    private fun waitForGlassesStatus(
+        initialStatus: GlassesStatus,
+        timeoutMs: Long,
+        isReady: (GlassesStatus) -> Boolean,
+    ): GlassesStatus {
+        val deadline = System.currentTimeMillis() + timeoutMs
+        var status = initialStatus
+        while (System.currentTimeMillis() < deadline) {
+            status = getRawGlassesStatus()
+            if (isReady(status)) return status
+            val remainingMs = deadline - System.currentTimeMillis()
+            if (remainingMs <= 0L) break
+            Thread.sleep(minOf(OTA_VERSION_POLL_MS, remainingMs))
+        }
+        return getRawGlassesStatus()
+    }
+
+    private fun resolveOtaVersionUrl(status: GlassesStatus): String {
+        val deviceUrl = status.otaVersionUrl.trim()
+        if (isLegacyAsgOtaStartBuild(status.buildNumber)) {
+            return deviceUrl.ifBlank { OtaManifestDefaults.PROD_OTA_VERSION_URL }
+        }
+        // SDK consumers are pinned to the manifest built for their SDK version.
+        // A future glasses-advertised URL should not silently change that pairing.
+        return configuredOtaVersionUrl ?: OtaManifestDefaults.defaultOtaVersionUrl()
+    }
+
+    private fun isLegacyAsgOtaStartBuild(buildNumber: String): Boolean {
+        val parsed = buildNumber.toIntOrNull()
+        return parsed != null && parsed < 100_000
+    }
 
     internal fun sendShutdown() {
         deviceManager.sendShutdown()
@@ -1333,6 +1489,14 @@ class MentraBluetoothSdk private constructor(
             return streamId to pending
         }
         if (pendingStreamStarts.size == 1) {
+            // A streamId-less STOPPED is the glasses' stop-ack for a PREVIOUS
+            // stream (their stop ack carries no streamId), not a verdict on the
+            // pending start — a start_stream that replaces a running publisher
+            // emits exactly this sequence (stopped -> initializing -> streaming).
+            // Attributing it here would reject a start that is about to succeed.
+            if (event.state == StreamState.STOPPED) {
+                return null
+            }
             val entry = pendingStreamStarts.entries.first()
             return entry.key to entry.value
         }

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

@@ -0,0 +1,14 @@
+package com.mentra.bluetoothsdk
+
+object MentraBluetoothSdkDebug {
+    @JvmStatic
+    fun setOtaVersionUrl(
+        sdk: MentraBluetoothSdk,
+        otaVersionUrl: String,
+    ) {
+        sdk.setOtaVersionUrl(otaVersionUrl)
+    }
+
+    @JvmStatic
+    fun getOtaVersionUrl(sdk: MentraBluetoothSdk): String = sdk.getOtaVersionUrl()
+}

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

@@ -53,6 +53,26 @@ class ObservableStore {
         listeners.forEach { it(normalizedCategory, mapOf(key to value)) }
     }
 
+    fun remove(category: String, key: String) {
+        val normalizedCategory: String
+        val updatedSnapshot: Map<String, Any>
+        val listeners: List<(String, Map<String, Any>) -> Unit>
+
+        synchronized(this) {
+            normalizedCategory = normalizeCategory(category)
+            val fullKey = "$normalizedCategory.$key"
+            if (!values.containsKey(fullKey)) return // already absent, no notification needed
+            values.remove(fullKey)
+            val prefix = "$normalizedCategory."
+            updatedSnapshot = values.filterKeys { it.startsWith(prefix) }
+                    .mapKeys { it.key.removePrefix(prefix) }
+            listeners = emitListeners.values.toList()
+        }
+
+        // Emit the full updated category snapshot so UI listeners can clear the removed key.
+        listeners.forEach { it(normalizedCategory, updatedSnapshot) }
+    }
+
     @Synchronized
     fun get(category: String, key: String): Any? = values["${normalizeCategory(category)}.$key"]