@mentra/bluetooth-sdk 0.1.19 → 0.1.21-beta.0

package/README.md

@@ -380,12 +380,16 @@ const photo = await BluetoothSdk.requestPhoto({
 console.log('photo delivered', photo.photoUrl ?? photo.uploadUrl, photo.fileSizeBytes)
 ```
 
-`requestPhoto(...)` resolves only after the full photo action reaches terminal success: capture completed and the photo was delivered to the webhook, either directly from the glasses over Wi-Fi or through the phone's Bluetooth fallback relay. If you omit `requestId`, the SDK generates one and the terminal response includes it. It rejects if the ASG reports `state: "error"`, if phone-side fallback upload fails, if the SDK cannot send the command, or if no terminal `photo_response` arrives before the command timeout. Use `photo_status` for intermediate stages such as `accepted`, `configuring`, `capturing`, `captured`, `uploading`, `ble_fallback_compression`, `ready_for_transfer`, and `transferring`; `photo_status` is progress, while `photo_response` is terminal success/error. The raw `photo_response` event stream still includes both success and error events for subscribers. The webhook should accept multipart form data with a `photo` file and `requestId`. If `authToken` is provided, the uploader adds `Authorization: Bearer <token>`. The camera light is always enabled for photo capture.
+`requestPhoto(...)` resolves only after the full photo action reaches terminal success: capture completed and the photo was delivered to the webhook, either directly from the glasses over Wi-Fi or through the phone's Bluetooth fallback relay. If you omit `requestId`, the SDK generates one and the terminal response includes it. It rejects if the ASG reports `state: "error"`, if phone-side fallback upload fails, if the SDK cannot send the command, or if no terminal `photo_response` arrives within 30 seconds. Photo requests use this longer operation-specific deadline because max-quality BLE fallback can legitimately exceed the 15-second deadline used by ordinary commands. Use `photo_status` for intermediate stages such as `accepted`, `configuring`, `capturing`, `captured`, `uploading`, `ble_fallback_compression`, `ready_for_transfer`, and `transferring`; `photo_status` is progress, while `photo_response` is terminal success/error. The raw `photo_response` event stream still includes both success and error events for subscribers. The webhook should accept multipart form data with a `photo` file and `requestId`. If `authToken` is provided, the uploader adds `Authorization: Bearer <token>`. The camera light is always enabled for photo capture.
 
 For one-shot manual capture tuning, pass `exposureTimeNs` and `iso` together. `exposureTimeNs` is sensor exposure time in nanoseconds; `iso` is sensor ISO. If `exposureTimeNs` is omitted, `null`, invalid, or unsupported by the connected glasses, the camera uses auto exposure and ignores `iso`.
 
+To own and explicitly release a warm camera, pass a request ID to `warmUpCamera({requestId, ...})`, then call `stopCameraWarmUp(requestId)` when the foreground UI closes. Warm holds default to 15 seconds and are capped at 60 seconds. Stopping while the camera is opening rejects the pending warm-up with `camera_warm_up_cancelled`; stopping after `ready` emits `stopped`. Compatible ready leases share the camera and expire independently.
+
 Use `setCameraFov({fov, roiPosition})` to configure Mentra Live camera field of view and crop position. FOV is clamped to 62-118 degrees; ROI position is `"center"`, `"bottom"`, or `"top"`. You can also call `setCameraFov({preset: "narrow" | "standard" | "wide"})`; presets map to 82, 102, and 118 degrees with center ROI. The returned `CameraFovResult` resolves only after the ASG client reports that the setting was applied to camera hardware after the restart cooldown, and the promise rejects if the glasses report an error, persist the setting without hardware application, or time out. Raw `settings_ack` events remain available through `addListener("settings_ack", ...)` for diagnostic fields such as `hardwareApplied`. Treat FOV as a framing/ROI control; output resolution and effective detail can vary by capture path, firmware, and camera mode.
 
+The missing/factory persistent FOV base is 102 degrees with centered ROI; existing saved values are not migrated. Use `setCameraFovOverride({leaseId, fov, roiPosition, ttlMs})` for a memory-only crop and `releaseCameraFovOverride(leaseId)` to restore the persistent base. A stale release is a safe no-op, and refreshing the same lease/config extends its TTL without another HAL restart.
+
 `startVideoRecording(...)` resolves from the ASG `video_recording_status` event whose status is `recording_started`. `stopVideoRecording(...)` without a webhook resolves from `recording_stopped`; with a webhook it waits for `recording_stopped` plus a video `media_success`, and rejects on `media_error`. Raw `video_recording_status`, `media_success`, and `media_error` events remain available through listeners.
 
 ## Streaming
@@ -475,7 +479,7 @@ For bare native iOS apps, use the public SwiftPM repository:
 https://github.com/Mentra-Community/mentra-bluetooth-sdk-ios.git
 ```
 
-Select version `0.1.19`, then add the `MentraBluetoothSDK` product to your app target.
+Select version `0.1.20`, 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

@@ -1,13 +1,132 @@
+@file:Suppress("FunctionName")
+
 package com.mentra.bluetoothsdk
 
 import com.mentra.bluetoothsdk.debug.BleTraceLogger
 import com.mentra.bluetoothsdk.utils.DeviceTypes
+import com.mentra.bluetoothsdk.utils.audio.PcmStreamManager
+import expo.modules.kotlin.exception.CodedException
 import expo.modules.kotlin.functions.Coroutine
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
+import expo.modules.kotlin.modules.ModuleDefinitionBuilder
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
 
+// Expo has no module-level error mapper, so SDK-backed registrations translate
+// core exceptions here while keeping Expo types out of the native SDK API.
+private inline fun <T> withExpoSdkError(block: () -> T): T =
+        try {
+            block()
+        } catch (error: BluetoothSdkException) {
+            throw CodedException(error.code, error.message ?: error.code, error)
+        }
+
+private suspend inline fun <T> withExpoSdkErrorSuspend(crossinline block: suspend () -> T): T =
+        try {
+            block()
+        } catch (error: BluetoothSdkException) {
+            throw CodedException(error.code, error.message ?: error.code, error)
+        }
+
+private inline fun <reified R> ModuleDefinitionBuilder.SdkAsyncFunction(
+    name: String,
+    crossinline body: () -> R,
+) = AsyncFunction<R>(name) { withExpoSdkError { body() } }
+
+private inline fun <reified R, reified P0> ModuleDefinitionBuilder.SdkAsyncFunction(
+    name: String,
+    crossinline body: (P0) -> R,
+) = AsyncFunction<R, P0>(name) { p0 -> withExpoSdkError { body(p0) } }
+
+private inline fun <reified R, reified P0, reified P1> ModuleDefinitionBuilder.SdkAsyncFunction(
+    name: String,
+    crossinline body: (P0, P1) -> R,
+) = AsyncFunction<R, P0, P1>(name) { p0, p1 -> withExpoSdkError { body(p0, p1) } }
+
+private inline fun <reified R, reified P0, reified P1, reified P2> ModuleDefinitionBuilder.SdkAsyncFunction(
+    name: String,
+    crossinline body: (P0, P1, P2) -> R,
+) = AsyncFunction<R, P0, P1, P2>(name) { p0, p1, p2 -> withExpoSdkError { body(p0, p1, p2) } }
+
+private inline fun <reified R, reified P0, reified P1, reified P2, reified P3>
+    ModuleDefinitionBuilder.SdkAsyncFunction(
+        name: String,
+        crossinline body: (P0, P1, P2, P3) -> R,
+    ) = AsyncFunction<R, P0, P1, P2, P3>(name) { p0, p1, p2, p3 ->
+        withExpoSdkError { body(p0, p1, p2, p3) }
+    }
+
+private inline fun <
+    reified R,
+    reified P0,
+    reified P1,
+    reified P2,
+    reified P3,
+    reified P4,
+    reified P5,
+    reified P6,
+> ModuleDefinitionBuilder.SdkAsyncFunction(
+    name: String,
+    crossinline body: (P0, P1, P2, P3, P4, P5, P6) -> R,
+) = AsyncFunction<R, P0, P1, P2, P3, P4, P5, P6>(name) { p0, p1, p2, p3, p4, p5, p6 ->
+    withExpoSdkError { body(p0, p1, p2, p3, p4, p5, p6) }
+}
+
+private inline fun <reified R> ModuleDefinitionBuilder.SdkFunction(
+    name: String,
+    crossinline body: () -> R,
+) = Function<R>(name) { withExpoSdkError { body() } }
+
+private inline fun <reified R, reified P0> ModuleDefinitionBuilder.SdkFunction(
+    name: String,
+    crossinline body: (P0) -> R,
+) = Function<R, P0>(name) { p0 -> withExpoSdkError { body(p0) } }
+
+private inline fun <reified R> ModuleDefinitionBuilder.SdkCoroutineFunction(
+    name: String,
+    crossinline body: suspend () -> R,
+) = AsyncFunction(name) Coroutine { -> withExpoSdkErrorSuspend { body() } }
+
+private inline fun <reified R, reified P0> ModuleDefinitionBuilder.SdkCoroutineFunction(
+    name: String,
+    crossinline body: suspend (P0) -> R,
+) = AsyncFunction(name) Coroutine { p0: P0 -> withExpoSdkErrorSuspend { body(p0) } }
+
+private inline fun <reified R, reified P0, reified P1> ModuleDefinitionBuilder.SdkCoroutineFunction(
+    name: String,
+    crossinline body: suspend (P0, P1) -> R,
+) = AsyncFunction(name) Coroutine { p0: P0, p1: P1 -> withExpoSdkErrorSuspend { body(p0, p1) } }
+
+private inline fun <reified R, reified P0, reified P1, reified P2> ModuleDefinitionBuilder.SdkCoroutineFunction(
+    name: String,
+    crossinline body: suspend (P0, P1, P2) -> R,
+) = AsyncFunction(name) Coroutine { p0: P0, p1: P1, p2: P2 -> withExpoSdkErrorSuspend { body(p0, p1, p2) } }
+
+private inline fun <reified R, reified P0, reified P1, reified P2, reified P3>
+    ModuleDefinitionBuilder.SdkCoroutineFunction(
+        name: String,
+        crossinline body: suspend (P0, P1, P2, P3) -> R,
+    ) = AsyncFunction(name) Coroutine { p0: P0, p1: P1, p2: P2, p3: P3 ->
+        withExpoSdkErrorSuspend { body(p0, p1, p2, p3) }
+    }
+
+private inline fun <
+    reified R,
+    reified P0,
+    reified P1,
+    reified P2,
+    reified P3,
+    reified P4,
+    reified P5,
+    reified P6,
+> ModuleDefinitionBuilder.SdkCoroutineFunction(
+    name: String,
+    crossinline body: suspend (P0, P1, P2, P3, P4, P5, P6) -> R,
+) = AsyncFunction(name) Coroutine { p0: P0, p1: P1, p2: P2, p3: P3, p4: P4, p5: P5, p6: P6 ->
+    withExpoSdkErrorSuspend { body(p0, p1, p2, p3, p4, p5, p6) }
+}
+
 class BluetoothSdkModule : Module() {
     private var sdk: MentraBluetoothSdk? = null
     private var deviceManager: DeviceManager? = null
@@ -183,9 +302,10 @@ class BluetoothSdkModule : Module() {
 
     private fun requireSdk(): MentraBluetoothSdk =
             sdk
-                    ?: throw BluetoothSdkException(
+                    ?: throw CodedException(
                             "sdk_not_initialized",
                             "Bluetooth SDK is not initialized.",
+                            null,
                     )
 
     override fun definition() = ModuleDefinition {
@@ -280,6 +400,7 @@ class BluetoothSdkModule : Module() {
                     "module_destroy"
             )
             sdk?.close()
+            PcmStreamManager.abortAll()
             sdk = null
             deviceManager = null
         }
@@ -335,11 +456,11 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - Display Commands
 
-        AsyncFunction("displayEvent") { params: Map<String, Any> ->
+        SdkAsyncFunction("displayEvent") { params: Map<String, Any> ->
             sdk?.displayEvent(DisplayEventRequest(params))
         }
 
-        AsyncFunction("displayText") { text: String, x: Int?, y: Int?, size: Int? ->
+        SdkAsyncFunction("displayText") { text: String, x: Int?, y: Int?, size: Int? ->
             sdk?.displayText(
                     text = text,
                     x = x ?: 0,
@@ -348,34 +469,35 @@ class BluetoothSdkModule : Module() {
             )
         }
 
-        AsyncFunction("clearDisplay") { sdk?.clearDisplay() }
+        SdkAsyncFunction("clearDisplay") { -> sdk?.clearDisplay() }
 
         // MARK: - Connection Commands
 
-        AsyncFunction("connectDefault") { sdk?.connectDefault() }
+        SdkAsyncFunction("connectDefault") { -> sdk?.connectDefault() }
 
-        AsyncFunction("connectDefaultWithOptions") { options: Map<String, Any> ->
+        SdkAsyncFunction("connectDefaultWithOptions") { options: Map<String, Any> ->
             sdk?.connectDefault(options.toMentraConnectOptions())
         }
 
-        AsyncFunction("setDefaultDevice") { device: Map<String, Any>? ->
+        SdkAsyncFunction("setDefaultDevice") { device: Map<String, Any>? ->
             sdk?.setDefaultDevice(device.toMentraDevice())
         }
 
-        AsyncFunction("clearDefaultDevice") { sdk?.clearDefaultDevice() }
+        SdkAsyncFunction("clearDefaultDevice") { -> sdk?.clearDefaultDevice() }
 
-        AsyncFunction("connectWithOptions") { device: Map<String, Any>, options: Map<String, Any> ->
+        SdkAsyncFunction("connectWithOptions") { device: Map<String, Any>, options: Map<String, Any> ->
             sdk?.connect(
-                    device.toMentraDevice() ?: throw IllegalArgumentException("connect requires a Device with model and name."),
+                    device.toMentraDevice()
+                            ?: throw IllegalArgumentException("connect requires a Device with model and name."),
                     options.toMentraConnectOptions(),
             )
         }
 
-        AsyncFunction("connectSimulated") { sdk?.connectSimulated() }
+        SdkAsyncFunction("connectSimulated") { -> sdk?.connectSimulated() }
 
-        AsyncFunction("disconnect") { sdk?.disconnect() }
+        SdkAsyncFunction("disconnect") { -> sdk?.disconnect() }
 
-        AsyncFunction("forget") { sdk?.forget() }
+        SdkAsyncFunction("forget") { -> sdk?.forget() }
 
         AsyncFunction("connectDefaultController") { deviceManager?.connectDefaultController() }
 
@@ -383,15 +505,15 @@ class BluetoothSdkModule : Module() {
 
         AsyncFunction("forgetController") { deviceManager?.forgetController() }
 
-        AsyncFunction("startScan") { model: String ->
+        SdkAsyncFunction("startScan") { model: String ->
             sdk?.startScan(DeviceModel.fromDeviceType(model))
         }
 
-        AsyncFunction("stopScan") { sdk?.stopScan() }
+        SdkAsyncFunction("stopScan") { -> sdk?.stopScan() }
 
-        AsyncFunction("cancelConnectionAttempt") { sdk?.cancelConnectionAttempt() }
+        SdkAsyncFunction("cancelConnectionAttempt") { -> sdk?.cancelConnectionAttempt() }
 
-        AsyncFunction("showDashboard") { sdk?.showDashboard() }
+        SdkAsyncFunction("showDashboard") { -> sdk?.showDashboard() }
 
         AsyncFunction("ping") { deviceManager?.ping() }
 
@@ -409,51 +531,54 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - Incident Reporting
 
-        AsyncFunction("sendIncidentId") { incidentId: String, apiBaseUrl: String? ->
+        SdkAsyncFunction("sendIncidentId") { incidentId: String, apiBaseUrl: String? ->
             sdk?.sendIncidentId(incidentId, apiBaseUrl)
         }
 
         // MARK: - WiFi Commands
 
-        AsyncFunction("requestWifiScan") { requireSdk().requestWifiScan().map { it.toMap() } }
+        SdkCoroutineFunction("requestWifiScan") { -> requireSdk().requestWifiScan().map { it.toMap() } }
 
-        AsyncFunction("sendWifiCredentials") { ssid: String, password: String ->
+        SdkCoroutineFunction("sendWifiCredentials") { ssid: String, password: String ->
             requireSdk().sendWifiCredentials(ssid, password).values
         }
 
-        AsyncFunction("forgetWifiNetwork") { ssid: String -> requireSdk().forgetWifiNetwork(ssid).values }
+        SdkCoroutineFunction("forgetWifiNetwork") { ssid: String ->
+            requireSdk().forgetWifiNetwork(ssid).values
+        }
 
-        AsyncFunction("setHotspotState") { enabled: Boolean ->
+        SdkCoroutineFunction("setHotspotState") { enabled: Boolean ->
             requireSdk().setHotspotState(enabled).values
         }
 
-        AsyncFunction("setSystemTime") { timestampMs: Double ->
+        SdkAsyncFunction("setSystemTime") { timestampMs: Double ->
             sdk?.setSystemTime(timestampMs.toLong())
         }
 
         // MARK: - Gallery Commands
 
-        AsyncFunction("setGalleryModeEnabled") { enabled: Boolean ->
+        SdkCoroutineFunction("setGalleryModeEnabled") { enabled: Boolean ->
             requireSdk().setGalleryModeEnabled(enabled).values
         }
 
-        AsyncFunction("setVoiceActivityDetectionEnabled") { enabled: Boolean ->
+        SdkAsyncFunction("setVoiceActivityDetectionEnabled") { enabled: Boolean ->
             sdk?.setVoiceActivityDetectionEnabled(enabled)
         }
 
-        AsyncFunction("setPhotoCaptureDefaults") { params: Map<String, Any?> ->
+        @Suppress("DEPRECATION")
+        SdkCoroutineFunction("setPhotoCaptureDefaults") { params: Map<String, Any?> ->
             requireSdk().setPhotoCaptureDefaults(params.toPhotoCaptureDefaults()).values
         }
 
-        AsyncFunction("setVideoRecordingDefaults") { width: Int, height: Int, fps: Int ->
+        SdkCoroutineFunction("setVideoRecordingDefaults") { width: Int, height: Int, fps: Int ->
             requireSdk().setVideoRecordingDefaults(VideoRecordingDefaults(width, height, fps)).values
         }
 
-        AsyncFunction("setMaxVideoRecordingDuration") { minutes: Int ->
+        SdkCoroutineFunction("setMaxVideoRecordingDuration") { minutes: Int ->
             requireSdk().setMaxVideoRecordingDuration(minutes).values
         }
 
-        AsyncFunction("setCameraFov") { fov: Map<String, Any> ->
+        SdkCoroutineFunction("setCameraFov") { fov: Map<String, Any> ->
             val value = (fov["fov"] as? Number)?.toInt() ?: CameraFov.DEFAULT_FOV
             val roiPosition = CameraRoiPosition.fromValue(
                 (fov["roiPosition"] as? Number)?.toInt()
@@ -462,13 +587,41 @@ class BluetoothSdkModule : Module() {
             requireSdk().setCameraFov(CameraFov(value, roiPosition)).values
         }
 
-        AsyncFunction("setCameraTuningConfig") { anrOn: Boolean, gainOn: Boolean ->
+        SdkCoroutineFunction("setLegacyCameraFov") { fov: Map<String, Any> ->
+            val value = (fov["fov"] as? Number)?.toInt() ?: CameraFov.DEFAULT_FOV
+            val roiPosition = CameraRoiPosition.fromValue(
+                (fov["roiPosition"] as? Number)?.toInt()
+                    ?: (fov["roi_position"] as? Number)?.toInt(),
+            )
+            requireSdk().setLegacyCameraFov(CameraFov(value, roiPosition)).values
+        }
+
+        SdkCoroutineFunction("restoreLegacyCameraFov") { ->
+            requireSdk().restoreLegacyCameraFov()
+        }
+
+        SdkCoroutineFunction("setCameraFovOverride") { params: Map<String, Any> ->
+            val leaseId = params["leaseId"] as? String ?: throw IllegalArgumentException("leaseId is required")
+            val value = (params["fov"] as? Number)?.toInt() ?: CameraFov.DEFAULT_FOV
+            val roiPosition = CameraRoiPosition.fromValue(
+                (params["roiPosition"] as? Number)?.toInt()
+                    ?: (params["roi_position"] as? Number)?.toInt(),
+            )
+            val ttlMs = (params["ttlMs"] as? Number)?.toInt() ?: 300000
+            requireSdk().setCameraFovOverride(leaseId, CameraFov(value, roiPosition), ttlMs).values
+        }
+
+        SdkCoroutineFunction("releaseCameraFovOverride") { leaseId: String ->
+            requireSdk().releaseCameraFovOverride(leaseId).values
+        }
+
+        SdkCoroutineFunction("setCameraTuningConfig") { anrOn: Boolean, gainOn: Boolean ->
             requireSdk().setCameraTuningConfig(anrOn, gainOn).values
         }
 
-        AsyncFunction("queryGalleryStatus") { requireSdk().queryGalleryStatus().values }
+        SdkCoroutineFunction("queryGalleryStatus") { -> requireSdk().queryGalleryStatus().values }
 
-        AsyncFunction("requestPhoto") { params: Map<String, Any?> ->
+        SdkCoroutineFunction("requestPhoto") { params: Map<String, Any?> ->
             // JS may pass null for optional fields; Map<String, Any> rejects null values at the bridge.
             val sanitized =
                     params.mapNotNull { (key, value) ->
@@ -476,37 +629,42 @@ class BluetoothSdkModule : Module() {
                     }.toMap()
             val req = PhotoRequest.fromMap(sanitized)
             Bridge.log(
-                    "NATIVE: PHOTO PIPELINE [3/6] BluetoothSdk.requestPhoto requestId=${req.requestId} size=${req.size} compress=${req.compress} sound=${req.sound} exposureTimeNs=${req.exposureTimeNs} iso=${req.iso}"
+                    "NATIVE: PHOTO PIPELINE [3/6] BluetoothSdk.requestPhoto requestId=${req.requestId} size=${req.size} mode=${req.mode.value} compress=${req.compress} sound=${req.sound} exposureTimeNs=${req.exposureTimeNs} iso=${req.iso}"
             )
             requireSdk().requestPhoto(req).values
         }
 
-        AsyncFunction("warmUpCamera") { params: Map<String, Any?> ->
+        SdkCoroutineFunction("warmUpCamera") { params: Map<String, Any?> ->
             val requestId = params["requestId"] as? String
             val size = PhotoSize.fromValue(params["size"] as? String)
+            val mode = PhotoMode.fromValue(params["mode"] as? String)
             val exposureRaw = (params["exposureTimeNs"] as? Number)?.toDouble()
             val exposureTimeNs =
                 if (exposureRaw != null && exposureRaw.isFinite() && exposureRaw > 0) exposureRaw.toLong() else null
             val durationRaw = (params["durationMs"] as? Number)?.toInt() ?: 0
             val durationMs = if (durationRaw > 0) durationRaw else 15000
-            requireSdk().warmUpCamera(requestId, size, exposureTimeNs, durationMs).values
+            requireSdk().warmUpCamera(requestId, size, mode, exposureTimeNs, durationMs).values
+        }
+
+        SdkAsyncFunction("stopCameraWarmUp") { requestId: String ->
+            requireSdk().stopCameraWarmUp(requestId)
         }
 
         // MARK: - OTA Commands
 
-        Function("setOtaVersionUrl") { otaVersionUrl: String ->
+        SdkFunction("setOtaVersionUrl") { otaVersionUrl: String ->
             requireSdk().setOtaVersionUrl(otaVersionUrl)
         }
 
-        Function("getOtaVersionUrl") { requireSdk().getOtaVersionUrl() }
+        SdkFunction("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 { ->
+        SdkCoroutineFunction("checkForOtaUpdate") { ->
             withContext(Dispatchers.IO) { requireSdk().checkForOtaUpdate() }
         }
 
-        AsyncFunction("startOtaUpdate") { otaVersionUrl: String? ->
+        SdkCoroutineFunction("startOtaUpdate") { otaVersionUrl: String? ->
             val sdk = requireSdk()
             if (otaVersionUrl.isNullOrBlank()) {
                 sdk.startOtaUpdate().values
@@ -515,21 +673,21 @@ class BluetoothSdkModule : Module() {
             }
         }
 
-        AsyncFunction("sendOtaQueryStatus") { requireSdk().sendOtaQueryStatus().values }
+        SdkCoroutineFunction("sendOtaQueryStatus") { -> requireSdk().sendOtaQueryStatus().values }
 
         // MARK: - Version Info Commands
 
-        AsyncFunction("requestVersionInfo") { requireSdk().requestVersionInfo().toMap() }
+        SdkCoroutineFunction("requestVersionInfo") { -> requireSdk().requestVersionInfo().toMap() }
 
         // MARK: - Power Control Commands
 
-        AsyncFunction("sendShutdown") { sdk?.sendShutdown() }
+        SdkAsyncFunction("sendShutdown") { -> sdk?.sendShutdown() }
 
-        AsyncFunction("sendReboot") { sdk?.sendReboot() }
+        SdkAsyncFunction("sendReboot") { -> sdk?.sendReboot() }
 
         // MARK: - Video Recording Commands
 
-        AsyncFunction("startVideoRecording") {
+        SdkCoroutineFunction("startVideoRecording") {
                 requestId: String,
                 save: Boolean,
                 sound: Boolean,
@@ -553,7 +711,7 @@ class BluetoothSdkModule : Module() {
 
         // webhookUrl/authToken are supplied at stop (not start) so the token is
         // fresh when the upload runs. Empty/null webhook = keep on device.
-        AsyncFunction("stopVideoRecording") {
+        SdkCoroutineFunction("stopVideoRecording") {
                 requestId: String,
                 webhookUrl: String?,
                 authToken: String? ->
@@ -562,23 +720,23 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - Stream Commands
 
-        AsyncFunction("startStream") { params: Map<String, Any> ->
+        SdkCoroutineFunction("startStream") { params: Map<String, Any> ->
             requireSdk().startStream(StreamRequest.fromMap(params)).values
         }
 
-        AsyncFunction("startExternallyManagedStream") { params: Map<String, Any> ->
+        SdkCoroutineFunction("startExternallyManagedStream") { params: Map<String, Any> ->
             requireSdk().startExternallyManagedStream(StreamRequest.fromMap(params)).values
         }
 
-        AsyncFunction("stopStream") { requireSdk().stopStream().values }
+        SdkCoroutineFunction("stopStream") { -> requireSdk().stopStream().values }
 
-        AsyncFunction("sendExternallyManagedStreamKeepAlive") { params: Map<String, Any> ->
+        SdkAsyncFunction("sendExternallyManagedStreamKeepAlive") { params: Map<String, Any> ->
             sdk?.sendExternallyManagedStreamKeepAlive(StreamKeepAliveRequest.fromMap(params))
         }
 
         // MARK: - Microphone Commands
 
-        AsyncFunction("setMicState") {
+        SdkAsyncFunction("setMicState") {
                 enabled: Boolean,
                 useGlassesMic: Boolean?,
                 sendTranscript: Boolean?,
@@ -600,10 +758,39 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - Audio Playback Monitoring
 
-        AsyncFunction("setOwnAppAudioPlaying") { playing: Boolean ->
+        SdkAsyncFunction("setOwnAppAudioPlaying") { playing: Boolean ->
             sdk?.setOwnAppAudioPlaying(playing)
         }
 
+        // MARK: - Live PCM output stream (miniapp speaker.createStream)
+        //
+        // MentraOS-internal. 16-bit LE PCM chunks into a streaming AudioTrack
+        // (USAGE_MEDIA → follows the media route, e.g. A2DP to glasses).
+        // write/close run *blocking on Dispatchers.IO*, not the shared Expo
+        // AsyncFunctionQueue: write intentionally blocks for backpressure and
+        // close blocks until the backlog drains — either would otherwise stall
+        // every other native call queued behind them.
+
+        AsyncFunction("pcmStreamOpen") { streamId: String, sampleRate: Int, channels: Int, volume: Double ->
+            PcmStreamManager.open(streamId, sampleRate, channels, volume.toFloat())
+        }
+
+        AsyncFunction("pcmStreamWrite") Coroutine { streamId: String, base64: String ->
+            withContext(Dispatchers.IO) {
+                mapOf("bufferedMs" to PcmStreamManager.write(streamId, base64))
+            }
+        }
+
+        AsyncFunction("pcmStreamClose") Coroutine { streamId: String ->
+            withContext(Dispatchers.IO) {
+                mapOf("durationMs" to PcmStreamManager.close(streamId))
+            }
+        }
+
+        AsyncFunction("pcmStreamAbort") { streamId: String ->
+            PcmStreamManager.abort(streamId)
+        }
+
         // *Blocking on Dispatchers.IO, not the shared AsyncFunctionQueue: these wait on
         // a CountDownLatch (up to 5s) for a BLE round-trip, which would otherwise stall
         // every other native call queued behind them.
@@ -619,7 +806,7 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - RGB LED Control
 
-        AsyncFunction("rgbLedControl") {
+        SdkCoroutineFunction("rgbLedControl") {
                 requestId: String,
                 packageName: String?,
                 action: String,

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

@@ -520,30 +520,81 @@ public class Bridge private constructor() {
             sendTypedMessage("glasses_serial_number", body as Map<String, Any>)
         }
 
-        /** Send WiFi status change */
+        /**
+         * Send WiFi status change. [error] is the glasses' provisioning failure reason
+         * (e.g. "connect_timeout", "connected_to_other_network") when this status is the
+         * verdict of a failed connect attempt; null for routine link-state updates.
+         */
         @JvmStatic
-        fun sendWifiStatusChange(connected: Boolean, ssid: String?, localIp: String?) {
+        @JvmOverloads
+        fun sendWifiStatusChange(
+                connected: Boolean,
+                ssid: String?,
+                localIp: String?,
+                error: String? = null
+        ) {
             val status = WifiStatus.fromStoreFields(connected, ssid, localIp) ?: return
-            sendTypedMessage("wifi_status_change", status.toMap())
+            val payload =
+                    if (error != null) status.toMap() + mapOf("error" to error)
+                    else status.toMap()
+            sendTypedMessage("wifi_status_change", payload)
+        }
+
+        /**
+         * Claim the WiFi scan-results store for a newly requested scan. Called by the
+         * SDK when it generates the scanId, BEFORE the scan command goes out: store
+         * ownership is decided at request time, not by whichever chunk arrives first,
+         * so a delayed chunk from an older, abandoned scan can never reset or clobber
+         * the current scan's accumulator.
+         */
+        @JvmStatic
+        fun claimWifiScanResults(scanId: String) {
+            DeviceStore.apply("bluetooth", "wifiScanActiveScanId", scanId)
         }
 
         /** Send WiFi scan results */
         @JvmStatic
-        fun updateWifiScanResults(networks: List<Map<String, Any>>, scanComplete: Boolean) {
-            var storedNetworks: List<Map<String, Any>> =
-                    DeviceStore.get("bluetooth", "wifiScanResults") as? List<Map<String, Any>>
-                            ?: emptyList()
-            // add the networks to the storedNetworks array, removing duplicates by ssid
-            val updatedNetworks = storedNetworks.toMutableList()
-            for (network in networks) {
-                if (!updatedNetworks.any { it["ssid"] as? String == network["ssid"] as? String }) {
-                    updatedNetworks.add(network)
+        fun updateWifiScanResults(
+                networks: List<Map<String, Any>>,
+                scanComplete: Boolean,
+                scanId: String? = null
+        ) {
+            // Only chunks echoing the active scanId claimed at request time may mutate
+            // the store; foreign chunks are still forwarded to the SDK sink, which
+            // drops stale ids itself. Scan-id-less chunks (old firmware) keep the
+            // legacy accumulate-forever store behavior.
+            val ownsStore =
+                    scanId == null || scanId == DeviceStore.get("bluetooth", "wifiScanActiveScanId")
+            var updatedNetworks: List<Map<String, Any>> = networks
+            if (ownsStore) {
+                var storedNetworks: List<Map<String, Any>> =
+                        DeviceStore.get("bluetooth", "wifiScanResults") as? List<Map<String, Any>>
+                                ?: emptyList()
+                val lastScanId = DeviceStore.get("bluetooth", "wifiScanResultsScanId")
+                if (scanId != null && scanId != lastScanId) {
+                    // First chunk of a new scan: drop networks accumulated for a previous scan
+                    // so stale entries never carry over into this scan's store.
+                    storedNetworks = emptyList()
+                    DeviceStore.apply("bluetooth", "wifiScanResultsScanId", scanId)
                 }
+                // add the networks to the storedNetworks array, removing duplicates by ssid
+                val merged = storedNetworks.toMutableList()
+                for (network in networks) {
+                    if (!merged.any { it["ssid"] as? String == network["ssid"] as? String }) {
+                        merged.add(network)
+                    }
+                }
+                DeviceStore.apply("bluetooth", "wifiScanResults", merged)
+                updatedNetworks = merged
             }
-            DeviceStore.apply("bluetooth", "wifiScanResults", updatedNetworks)
             val body = HashMap<String, Any>()
-            body["networks"] = updatedNetworks
+            // Correlated scans: the SDK accumulates and dedupes chunks per scanId itself,
+            // so forward only this chunk; the merged store list is for UI consumers.
+            body["networks"] = if (scanId != null) networks else updatedNetworks
             body["scanComplete"] = scanComplete
+            if (scanId != null) {
+                body["scanId"] = scanId
+            }
             sendTypedMessage("wifi_scan_result", body)
         }