@mentra/bluetooth-sdk 0.1.20 → 0.1.21-beta.1

package/README.md

@@ -152,11 +152,13 @@ reordering rows just because RSSI metadata arrives later.
 
 ## Mentra SDK Usage Analytics
 
-The SDK sends two anonymous usage events to Mentra's PostHog project by default
-so Mentra can understand SDK adoption and successful glasses connections:
+The SDK sends three usage events to Mentra's PostHog project by default so
+Mentra can understand SDK adoption, successful glasses connections, and
+enterprise device deployments:
 
 - `bluetooth_sdk_started`: sent once per app runtime after the native SDK starts.
 - `bluetooth_sdk_glasses_connected`: sent when SDK status transitions from not connected to connected.
+- `bluetooth_sdk_glasses_identified`: sent once per connection after the SDK receives a valid manufacturing serial from the glasses. This fires for every supported model that reports a serial. G1 and Ar99 decode the serial from the glasses' BLE advertisement, so they emit this event as soon as this SDK version ships. Mentra Live instead reports the serial provisioned in BES NV storage, which requires compatible BES firmware and `asg_client` software.
 
 Analytics delivery is fire-and-forget: events are submitted asynchronously, do
 not block Bluetooth SDK behavior, and are not retried if delivery fails.
@@ -190,14 +192,23 @@ write token, not a private PostHog personal API key. Apps do not configure the
 analytics destination; these SDK usage events are always sent to Mentra's
 PostHog project unless analytics are disabled.
 
-Captured properties are limited to non-sensitive SDK/app metadata:
-`event_source`, `sdk_platform`, `sdk_surface`, `sdk_version`, the app package or
-bundle identifier, OS platform/version, `event_kind`, and for connection events
-only `fully_booted` plus a glasses model value when the SDK knows it. The SDK
-does not upload BLE MAC addresses, CoreBluetooth identifiers, serial numbers,
-Bluetooth device names, user ids, tokens, Wi-Fi credentials, microphone data,
-photos, or transcripts. PostHog receives a locally generated anonymous SDK
-install id as `distinct_id`, and events include `$process_person_profile: false`.
+Captured properties include `event_source`, `sdk_platform`, `sdk_surface`,
+`sdk_version`, `app_identifier` (the Android package or iOS bundle identifier),
+the platform-specific `app_package` or `app_bundle_identifier`, OS
+platform/version, and `event_kind`. Connection events also include
+`fully_booted` and a glasses model value when known. The identification event
+intentionally includes the glasses manufacturing serial as `glasses_device_id`,
+with `glasses_device_id_type=manufacturing_serial`, so Mentra can correlate
+fleet deployments across supported models. This serial identifies the glasses
+hardware, not the user or the host phone. Its source depends on the model:
+Mentra Live reports the serial provisioned in BES NV storage, while G1 and Ar99
+decode it from the glasses' BLE advertisement / manufacturer data.
+
+Apart from that glasses serial, the SDK does not upload BLE MAC addresses,
+CoreBluetooth identifiers, the host phone's Android device serial, Bluetooth
+device names, user ids, tokens, Wi-Fi credentials, microphone data, photos, or
+transcripts. PostHog receives a locally generated anonymous SDK install id as
+`distinct_id`, and events include `$process_person_profile: false`.
 
 ## React Hooks
 
@@ -380,12 +391,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
@@ -404,7 +419,7 @@ await BluetoothSdk.stopStream()
 ```
 
 Use `rtmp://` or `rtmps://` for RTMP, `srt://` for SRT, and `http://` or `https://` for WHIP/WebRTC ingest. `startStream()` resolves with the correlated `stream_status` event once the glasses report `status: "streaming"`; `stopStream()` resolves when the glasses report `status: "stopped"` or confirms the stream was already stopped / not streaming. `stopStream()` returns a normalized stopped event for that already-stopped case. Stream starts reject if the glasses report an error before streaming; stream stops reject for real stop errors, send failure, another stop in flight, or timeout. Stream video input fields are `width`, `height`, `bitrate`, and `fps`. The SDK sends stream keep-alives automatically while streaming and reports keep-alive failures through `stream_status`. The camera light is always enabled while streaming.
-`stream_status` events may include `resolvedConfig`, which reports the effective transport, video, and audio settings after glasses defaults, clamps, and camera preflight. The resolved effective frame rate is reported as `resolvedConfig.video.fps`.
+`stream_status` events may include `resolvedConfig`, which reports the effective transport, video, and audio settings after glasses defaults, clamps, and camera preflight. The resolved effective frame rate is reported as `resolvedConfig.video.fps`. While live, supported firmware emits periodic `streaming` events whose `stats` object contains `bitrate` (bits per second), `fps`, `droppedFrames`, `duration` (seconds), and `temperatureC` when the CPU sensor is available.
 
 ## Events
 

package/android/build.gradle

@@ -279,6 +279,9 @@ dependencies {
   // Local photo upload receiver
   implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1"
 
+  // AR99 GATT Opus to PCM decoder.
+  implementation 'io.github.jaredmdobson:concentus:1.0.1'
+
   // LC3 audio codec library
   implementation project(':lc3Lib')
 

package/android/src/main/AndroidManifest.xml

@@ -28,6 +28,8 @@
   <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
   <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE"/>
   <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC"/>
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION"/>
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK"/>
   <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE"/>
 
   <!-- Other permissions -->
@@ -35,6 +37,6 @@
   <uses-permission android:name="android.permission.VIBRATE"/>
 
   <application>
-    <service android:name="com.mentra.bluetoothsdk.services.ForegroundService" android:exported="false" android:foregroundServiceType="dataSync|connectedDevice|microphone"/>
+    <service android:name="com.mentra.bluetoothsdk.services.ForegroundService" android:exported="false" android:foregroundServiceType="dataSync|connectedDevice|location|mediaPlayback|microphone"/>
   </application>
 </manifest>

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

@@ -48,10 +48,17 @@ internal class BluetoothSdkAnalytics(
     private val config = initialConfig.toRuntimeConfig().resolvedForApp(appContext)
     private var startedCaptured = false
     private var lastConnected = false
+    private var identifiedCapturedForConnection = false
 
     @Synchronized
     fun initializeGlassesStatus(status: GlassesStatus) {
         lastConnected = status.analyticsConnected
+        // Only treat identification as already captured when a valid serial is
+        // present at init. If the glasses are connected but the serial has not
+        // arrived yet (Mentra Live fills it via version_info after connect), leave
+        // this false so the identify event still fires once the serial arrives.
+        identifiedCapturedForConnection =
+            status.analyticsConnected && status.serialNumber.validManufacturingSerial() != null
     }
 
     @Synchronized
@@ -67,7 +74,12 @@ internal class BluetoothSdkAnalytics(
         val wasConnected = lastConnected
         lastConnected = isConnected
         if (!config.isReady) return
+        if (!isConnected) {
+            identifiedCapturedForConnection = false
+            return
+        }
         if (isConnected && !wasConnected) {
+            identifiedCapturedForConnection = false
             capture(
                 "bluetooth_sdk_glasses_connected",
                 buildMap {
@@ -76,6 +88,24 @@ internal class BluetoothSdkAnalytics(
                     status.deviceModel.takeIf { it.isNotBlank() }?.let { put("glasses_model", it) }
                 },
             )
+            // Fall through: a serial already present at connect time (G1/Ar99 report
+            // it in the advertisement) should be identified now rather than waiting
+            // for some later, unrelated glasses-store update to run.
+        }
+
+        val serialNumber = status.serialNumber.validManufacturingSerial() ?: return
+        if (!identifiedCapturedForConnection) {
+            identifiedCapturedForConnection = true
+            capture(
+                "bluetooth_sdk_glasses_identified",
+                buildMap {
+                    put("event_kind", "glasses_identified")
+                    put("fully_booted", status.fullyBooted)
+                    put("glasses_device_id", serialNumber)
+                    put("glasses_device_id_type", "manufacturing_serial")
+                    status.deviceModel.takeIf { it.isNotBlank() }?.let { put("glasses_model", it) }
+                },
+            )
         }
     }
 
@@ -131,6 +161,7 @@ internal class BluetoothSdkAnalytics(
             put("sdk_platform", "android")
             put("sdk_surface", activeConfig.surface)
             put("sdk_version", BuildConfig.SDK_VERSION)
+            put("app_identifier", appContext.packageName)
             put("app_package", appContext.packageName)
             put("os_platform", "android")
             put("os_version", Build.VERSION.SDK_INT)
@@ -180,3 +211,6 @@ private fun BluetoothSdkAnalyticsRuntimeConfig.resolvedForApp(context: Context):
 
 private val GlassesStatus.analyticsConnected: Boolean
     get() = connectionState.isConnected || connected || fullyBooted
+
+private fun String.validManufacturingSerial(): String? =
+    trim().takeIf { it.isNotEmpty() && !it.matches(Regex("0+")) }

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

@@ -3,4 +3,5 @@ package com.mentra.bluetoothsdk
 /** Defaults for the public Bluetooth SDK surface. */
 object BluetoothSdkDefaults {
     const val VOICE_ACTIVITY_DETECTION_ENABLED = false
+    const val LOUDNESS_GATE_ENABLED = true
 }

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

@@ -2,8 +2,11 @@
 
 package com.mentra.bluetoothsdk
 
+import androidx.lifecycle.Lifecycle
+import androidx.lifecycle.LifecycleOwner
 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
@@ -11,6 +14,7 @@ import expo.modules.kotlin.modules.ModuleDefinition
 import expo.modules.kotlin.modules.ModuleDefinitionBuilder
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
+import java.security.MessageDigest
 
 // 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.
@@ -87,6 +91,45 @@ private inline fun <reified R> ModuleDefinitionBuilder.SdkCoroutineFunction(
     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
@@ -325,10 +368,12 @@ class BluetoothSdkModule : Module() {
             "stream_status",
             "keep_alive_ack",
             "mtk_update_complete",
+            "glasses_session_changed",
             "ota_progress",
             "ota_start_ack",
             "ota_status",
-            // Nex / BLE debug (NexEventUtils → Bridge.sendTypedMessage)
+            "ar99_ota_status",
+            // Nex / BLE debug (NexEventUtils —Bridge.sendTypedMessage)
             "send_command_to_ble",
             "receive_command_from_ble",
             "miniapp_selected",
@@ -351,6 +396,21 @@ class BluetoothSdkModule : Module() {
                             sdkListener,
                     )
             deviceManager = DeviceManager.getInstance()
+            val activity = appContext.currentActivity
+            val activityIsResumed =
+                    (activity as? LifecycleOwner)
+                            ?.lifecycle
+                            ?.currentState
+                            ?.isAtLeast(Lifecycle.State.RESUMED) == true
+            if (activityIsResumed) {
+                deviceManager?.refreshForegroundServiceTypes()
+            }
+        }
+
+        OnActivityEntersForeground {
+            // Re-run after runtime permission dialogs and every app resume. This is the safe
+            // point to add Android's while-in-use location foreground-service type.
+            deviceManager?.refreshForegroundServiceTypes()
         }
 
         OnDestroy {
@@ -360,6 +420,7 @@ class BluetoothSdkModule : Module() {
                     "module_destroy"
             )
             sdk?.close()
+            PcmStreamManager.abortAll()
             sdk = null
             deviceManager = null
         }
@@ -496,17 +557,17 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - WiFi Commands
 
-        SdkAsyncFunction("requestWifiScan") { -> requireSdk().requestWifiScan().map { it.toMap() } }
+        SdkCoroutineFunction("requestWifiScan") { -> requireSdk().requestWifiScan().map { it.toMap() } }
 
-        SdkAsyncFunction("sendWifiCredentials") { ssid: String, password: String ->
+        SdkCoroutineFunction("sendWifiCredentials") { ssid: String, password: String ->
             requireSdk().sendWifiCredentials(ssid, password).values
         }
 
-        SdkAsyncFunction("forgetWifiNetwork") { ssid: String ->
+        SdkCoroutineFunction("forgetWifiNetwork") { ssid: String ->
             requireSdk().forgetWifiNetwork(ssid).values
         }
 
-        SdkAsyncFunction("setHotspotState") { enabled: Boolean ->
+        SdkCoroutineFunction("setHotspotState") { enabled: Boolean ->
             requireSdk().setHotspotState(enabled).values
         }
 
@@ -516,7 +577,7 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - Gallery Commands
 
-        SdkAsyncFunction("setGalleryModeEnabled") { enabled: Boolean ->
+        SdkCoroutineFunction("setGalleryModeEnabled") { enabled: Boolean ->
             requireSdk().setGalleryModeEnabled(enabled).values
         }
 
@@ -524,20 +585,24 @@ class BluetoothSdkModule : Module() {
             sdk?.setVoiceActivityDetectionEnabled(enabled)
         }
 
+        SdkAsyncFunction("setLoudnessGateEnabled") { enabled: Boolean ->
+            sdk?.setLoudnessGateEnabled(enabled)
+        }
+
         @Suppress("DEPRECATION")
-        SdkAsyncFunction("setPhotoCaptureDefaults") { params: Map<String, Any?> ->
+        SdkCoroutineFunction("setPhotoCaptureDefaults") { params: Map<String, Any?> ->
             requireSdk().setPhotoCaptureDefaults(params.toPhotoCaptureDefaults()).values
         }
 
-        SdkAsyncFunction("setVideoRecordingDefaults") { width: Int, height: Int, fps: Int ->
+        SdkCoroutineFunction("setVideoRecordingDefaults") { width: Int, height: Int, fps: Int ->
             requireSdk().setVideoRecordingDefaults(VideoRecordingDefaults(width, height, fps)).values
         }
 
-        SdkAsyncFunction("setMaxVideoRecordingDuration") { minutes: Int ->
+        SdkCoroutineFunction("setMaxVideoRecordingDuration") { minutes: Int ->
             requireSdk().setMaxVideoRecordingDuration(minutes).values
         }
 
-        SdkAsyncFunction("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()
@@ -546,13 +611,41 @@ class BluetoothSdkModule : Module() {
             requireSdk().setCameraFov(CameraFov(value, roiPosition)).values
         }
 
-        SdkAsyncFunction("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
         }
 
-        SdkAsyncFunction("queryGalleryStatus") { -> requireSdk().queryGalleryStatus().values }
+        SdkCoroutineFunction("queryGalleryStatus") { -> requireSdk().queryGalleryStatus().values }
 
-        SdkAsyncFunction("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) ->
@@ -565,15 +658,22 @@ class BluetoothSdkModule : Module() {
             requireSdk().requestPhoto(req).values
         }
 
-        SdkAsyncFunction("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
+            val zsl = params["zsl"] as? Boolean
+            val mfnr = params["mfnr"] as? Boolean
+            requireSdk().warmUpCamera(requestId, size, mode, exposureTimeNs, durationMs, zsl, mfnr).values
+        }
+
+        SdkAsyncFunction("stopCameraWarmUp") { requestId: String ->
+            requireSdk().stopCameraWarmUp(requestId)
         }
 
         // MARK: - OTA Commands
@@ -586,11 +686,11 @@ class BluetoothSdkModule : Module() {
 
         // Runs on Dispatchers.IO, not the shared Expo AsyncFunctionQueue:
         // manifest fetches and version waits can block for several seconds.
-        SdkCoroutineFunction("checkForOtaUpdate") {
+        SdkCoroutineFunction("checkForOtaUpdate") { ->
             withContext(Dispatchers.IO) { requireSdk().checkForOtaUpdate() }
         }
 
-        SdkAsyncFunction("startOtaUpdate") { otaVersionUrl: String? ->
+        SdkCoroutineFunction("startOtaUpdate") { otaVersionUrl: String? ->
             val sdk = requireSdk()
             if (otaVersionUrl.isNullOrBlank()) {
                 sdk.startOtaUpdate().values
@@ -599,11 +699,23 @@ class BluetoothSdkModule : Module() {
             }
         }
 
-        SdkAsyncFunction("sendOtaQueryStatus") { -> requireSdk().sendOtaQueryStatus().values }
+        SdkCoroutineFunction("sendOtaQueryStatus") { -> requireSdk().sendOtaQueryStatus().values }
+
+        AsyncFunction("startAr99OtaFromFile") { path: String -> requireSdk().startAr99OtaFromFile(path) }
+
+        AsyncFunction("cancelAr99Ota") { requireSdk().cancelAr99Ota() }
+
+        AsyncFunction("sendAr99FactoryReset") { requireSdk().sendAr99FactoryReset() }
+
 
+        Function("buildAr99OtaSignature") { secret: String, appName: String, currentVersion: String, serialNumber: String, nonce: String ->
+            val raw = secret + appName + "juxinOTA" + currentVersion + serialNumber.trim() + nonce
+            val digest = MessageDigest.getInstance("MD5").digest(raw.toByteArray(Charsets.UTF_8))
+            digest.joinToString("") { "%02x".format(it.toInt() and 0xff) }
+        }
         // MARK: - Version Info Commands
 
-        SdkAsyncFunction("requestVersionInfo") { -> requireSdk().requestVersionInfo().toMap() }
+        SdkCoroutineFunction("requestVersionInfo") { -> requireSdk().requestVersionInfo().toMap() }
 
         // MARK: - Power Control Commands
 
@@ -613,7 +725,7 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - Video Recording Commands
 
-        SdkAsyncFunction("startVideoRecording") {
+        SdkCoroutineFunction("startVideoRecording") {
                 requestId: String,
                 save: Boolean,
                 sound: Boolean,
@@ -637,7 +749,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.
-        SdkAsyncFunction("stopVideoRecording") {
+        SdkCoroutineFunction("stopVideoRecording") {
                 requestId: String,
                 webhookUrl: String?,
                 authToken: String? ->
@@ -646,15 +758,15 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - Stream Commands
 
-        SdkAsyncFunction("startStream") { params: Map<String, Any> ->
+        SdkCoroutineFunction("startStream") { params: Map<String, Any> ->
             requireSdk().startStream(StreamRequest.fromMap(params)).values
         }
 
-        SdkAsyncFunction("startExternallyManagedStream") { params: Map<String, Any> ->
+        SdkCoroutineFunction("startExternallyManagedStream") { params: Map<String, Any> ->
             requireSdk().startExternallyManagedStream(StreamRequest.fromMap(params)).values
         }
 
-        SdkAsyncFunction("stopStream") { -> requireSdk().stopStream().values }
+        SdkCoroutineFunction("stopStream") { -> requireSdk().stopStream().values }
 
         SdkAsyncFunction("sendExternallyManagedStreamKeepAlive") { params: Map<String, Any> ->
             sdk?.sendExternallyManagedStreamKeepAlive(StreamKeepAliveRequest.fromMap(params))
@@ -688,6 +800,35 @@ class BluetoothSdkModule : Module() {
             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.
@@ -703,7 +844,7 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - RGB LED Control
 
-        SdkAsyncFunction("rgbLedControl") {
+        SdkCoroutineFunction("rgbLedControl") {
                 requestId: String,
                 packageName: String?,
                 action: String,
@@ -755,7 +896,7 @@ class BluetoothSdkModule : Module() {
         }
 
         // Runs on Dispatchers.IO, not the shared Expo AsyncFunctionQueue: bz2/tar
-        // extraction of the 100–350MB model is a multi-minute, CPU-bound job. On the
+        // extraction of the 100—50MB model is a multi-minute, CPU-bound job. On the
         // shared queue it froze every other native call in the app until it finished.
         AsyncFunction("extractTarBz2") Coroutine { sourcePath: String, destinationPath: String ->
             withContext(Dispatchers.IO) {
@@ -832,12 +973,14 @@ private fun Map<String, Any>?.toMentraDevice(): Device? {
     val model = values["model"] as? String ?: return null
     val name = values["name"] as? String ?: return null
     val address = values["address"] as? String
+    val projectName = values["projectName"] as? String
     val rssi = (values["rssi"] as? Number)?.toInt()
     val id = values["id"] as? String
     return Device(
             model = DeviceModel.fromDeviceType(model),
             name = name,
             address = address?.takeIf { it.isNotBlank() },
+            projectName = projectName?.takeIf { it.isNotBlank() },
             rssi = rssi,
             id = id?.takeIf { it.isNotBlank() } ?: address?.takeIf { it.isNotBlank() } ?: "$model:$name",
     )