@mentra/bluetooth-sdk 0.1.13 → 0.1.16

package/README.md

@@ -315,7 +315,7 @@ console.log(ledAck.state)
 Settings commands that return `SettingsAckSuccessEvent` reject when the ASG reports an error ack. The SDK updates its local settings store only after that ASG ack resolves successfully, so observed SDK state reflects the acknowledged glasses state rather than a queued request. Raw `settings_ack` listener events still use `SettingsAckEvent` because they can include both success and failure statuses. `rgbLedControl(...)` resolves from a successful ASG `rgb_led_control_response` and rejects when the ASG reports `state: "error"`; raw `settings_ack` and `rgb_led_control_response` events remain available through listeners.
 
 WiFi, hotspot, and version-info commands resolve from the ASG response path, not local dispatch:
-`requestWifiScan()` resolves from the ASG `wifi_scan_result` completion response with the updated scan list, including `[]` when no networks are found. Intermediate `wifi_scan_result` events can arrive with `scanComplete: false` while the glasses stream discovered networks; the final event uses `scanComplete: true`. `sendWifiCredentials()` resolves when the requested SSID is connected, `forgetWifiNetwork()` resolves when that SSID is no longer connected, `setHotspotState()` resolves when the requested hotspot state is reported, and `requestVersionInfo()` resolves from the ASG `version_info` response instead of local store changes.
+`requestWifiScan()` resolves from the ASG `wifi_scan_result` completion response with the updated scan list, including `[]` when no networks are found. Intermediate `wifi_scan_result` events can arrive with `scanComplete: false` while the glasses stream discovered networks; the final event uses `scanComplete: true`. If older glasses stream non-empty scan results but never send the completion event, the request resolves with the accumulated scan list when the request times out. `sendWifiCredentials()` resolves when the requested SSID is connected, `forgetWifiNetwork()` resolves when that SSID is no longer connected, `setHotspotState()` resolves when the requested hotspot state is reported, and `requestVersionInfo()` resolves from the ASG `version_info` response instead of local store changes.
 
 React Native narrows returned values to success shapes where the raw listener event can also report errors:
 
@@ -327,7 +327,7 @@ React Native narrows returned values to success shapes where the raw listener ev
 | `rgbLedControl(...)` | `RgbLedControlSuccessResponseEvent` with `state: "success"`. | Rejects when raw `rgb_led_control_response.state === "error"` or the response times out. |
 | `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.
+Android and iOS async APIs use `BluetoothSdkException` / `BluetoothSdkError` 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.
 
 `setMicState(true)` defaults to continuous microphone PCM from the glasses. The SDK does not apply phone-side Voice Activity Detection gating to microphone audio events. Glasses-side Voice Activity Detection is disabled by default for public SDK consumers; use `setVoiceActivityDetectionEnabled(true)` when you want supported glasses to gate microphone audio and emit live speaking status. `voice_activity_detection_status` reports whether glasses-side Voice Activity Detection is enabled, and `speaking_status` reports speaking/not-speaking when supported. Microphone events include the latest `voiceActivityDetectionEnabled` value.
 
@@ -369,8 +369,6 @@ OTA requires Mentra Live glasses firmware that supports the ASG OTA protocol and
 
 ```ts
 const photo = await BluetoothSdk.requestPhoto({
-  requestId: `photo-${Date.now()}`,
-  appId: 'com.example.app',
   size: 'medium',
   webhookUrl: 'https://api.example.com/mentra/photo',
   authToken: 'optional-token',
@@ -382,7 +380,7 @@ 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. 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 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.
 
 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`.
 
@@ -405,8 +403,8 @@ await BluetoothSdk.startStream({
 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. 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.
+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`.
 
 ## Events
 
@@ -459,13 +457,25 @@ MENTRA_BLUETOOTH_SDK_PACKAGE_PATH=/path/to/MentraOS/mobile/modules/bluetooth-sdk
 
 Use `bunx expo run:android` for Android. Keep local paths in your shell or CI environment, not in committed app config.
 
+For local Android source compile checks inside this monorepo, run from the
+MentraOS repo root:
+
+```sh
+./scripts/check-android-compile.sh bluetooth-sdk
+```
+
+The `android/` folder in this package is source for the generated Expo Android
+project, not the local Gradle entrypoint. The check script prepares
+`mobile/android` and uses its Gradle wrapper with `-PmentraPublicSdk=true`,
+matching the CI release workflow's public SDK dependency mode.
+
 For bare native iOS apps, use the public SwiftPM repository:
 
 ```text
 https://github.com/Mentra-Community/mentra-bluetooth-sdk-ios.git
 ```
 
-Select version `0.1.13`, then add the `MentraBluetoothSDK` product to your app target.
+Select version `0.1.16`, 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

@@ -116,6 +116,10 @@ class BluetoothSdkModule : Module() {
                     sendEvent("photo_status", event.values)
                 }
 
+                override fun onCameraStatus(event: CameraStatusEvent) {
+                    sendEvent("camera_status", event.values)
+                }
+
                 override fun onVideoRecordingStatus(event: VideoRecordingStatusEvent) {
                     sendEvent("video_recording_status", event.values)
                 }
@@ -136,10 +140,6 @@ class BluetoothSdkModule : Module() {
                     sendEvent("keep_alive_ack", event.values)
                 }
 
-                override fun onOtaUpdateAvailable(event: OtaUpdateAvailableEvent) {
-                    sendEvent("ota_update_available", event.values)
-                }
-
                 override fun onOtaStartAck(event: OtaStartAckEvent) {
                     sendEvent("ota_start_ack", event.values)
                 }
@@ -183,7 +183,7 @@ class BluetoothSdkModule : Module() {
 
     private fun requireSdk(): MentraBluetoothSdk =
             sdk
-                    ?: throw BluetoothException(
+                    ?: throw BluetoothSdkException(
                             "sdk_not_initialized",
                             "Bluetooth SDK is not initialized.",
                     )
@@ -216,6 +216,7 @@ class BluetoothSdkModule : Module() {
             "hotspot_error",
             "photo_response",
             "photo_status",
+            "camera_status",
             "video_recording_status",
             "media_success",
             "media_error",
@@ -244,7 +245,6 @@ class BluetoothSdkModule : Module() {
             "stream_status",
             "keep_alive_ack",
             "mtk_update_complete",
-            "ota_update_available",
             "ota_progress",
             "ota_start_ack",
             "ota_status",
@@ -441,49 +441,16 @@ class BluetoothSdkModule : Module() {
             sdk?.setVoiceActivityDetectionEnabled(enabled)
         }
 
-        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 ->
-            requireSdk().setButtonVideoRecordingSettings(width, height, fps).values
+        AsyncFunction("setPhotoCaptureDefaults") { params: Map<String, Any?> ->
+            requireSdk().setPhotoCaptureDefaults(params.toPhotoCaptureDefaults()).values
         }
 
-        AsyncFunction("setButtonCameraLed") { enabled: Boolean ->
-            requireSdk().setButtonCameraLed(enabled).values
+        AsyncFunction("setVideoRecordingDefaults") { width: Int, height: Int, fps: Int ->
+            requireSdk().setVideoRecordingDefaults(VideoRecordingDefaults(width, height, fps)).values
         }
 
-        AsyncFunction("setButtonMaxRecordingTime") { minutes: Int ->
-            requireSdk().setButtonMaxRecordingTime(minutes).values
+        AsyncFunction("setMaxVideoRecordingDuration") { minutes: Int ->
+            requireSdk().setMaxVideoRecordingDuration(minutes).values
         }
 
         AsyncFunction("setCameraFov") { fov: Map<String, Any> ->
@@ -495,6 +462,10 @@ class BluetoothSdkModule : Module() {
             requireSdk().setCameraFov(CameraFov(value, roiPosition)).values
         }
 
+        AsyncFunction("setCameraTuningConfig") { anrOn: Boolean, gainOn: Boolean ->
+            requireSdk().setCameraTuningConfig(anrOn, gainOn).values
+        }
+
         AsyncFunction("queryGalleryStatus") { requireSdk().queryGalleryStatus().values }
 
         AsyncFunction("requestPhoto") { params: Map<String, Any?> ->
@@ -505,11 +476,22 @@ class BluetoothSdkModule : Module() {
                     }.toMap()
             val req = PhotoRequest.fromMap(sanitized)
             Bridge.log(
-                    "NATIVE: PHOTO PIPELINE [3/6] BluetoothSdk.requestPhoto requestId=${req.requestId} appId=${req.appId} size=${req.size} compress=${req.compress} flash=${req.flash} sound=${req.sound} exposureTimeNs=${req.exposureTimeNs} iso=${req.iso}"
+                    "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}"
             )
             requireSdk().requestPhoto(req).values
         }
 
+        AsyncFunction("warmUpCamera") { params: Map<String, Any?> ->
+            val requestId = params["requestId"] as? String
+            val size = PhotoSize.fromValue(params["size"] 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
+        }
+
         // MARK: - OTA Commands
 
         Function("setOtaVersionUrl") { otaVersionUrl: String ->
@@ -535,8 +517,6 @@ class BluetoothSdkModule : Module() {
 
         AsyncFunction("sendOtaQueryStatus") { requireSdk().sendOtaQueryStatus().values }
 
-        AsyncFunction("retryOtaVersionCheck") { requireSdk().retryOtaVersionCheck().values }
-
         // MARK: - Version Info Commands
 
         AsyncFunction("requestVersionInfo") { requireSdk().requestVersionInfo().toMap() }
@@ -586,6 +566,10 @@ class BluetoothSdkModule : Module() {
             requireSdk().startStream(StreamRequest.fromMap(params)).values
         }
 
+        AsyncFunction("startExternallyManagedStream") { params: Map<String, Any> ->
+            requireSdk().startExternallyManagedStream(StreamRequest.fromMap(params)).values
+        }
+
         AsyncFunction("stopStream") { requireSdk().stopStream().values }
 
         AsyncFunction("sendExternallyManagedStreamKeepAlive") { params: Map<String, Any> ->
@@ -775,6 +759,22 @@ private fun Map<String, Any>?.toMentraDevice(): Device? {
     )
 }
 
+private fun Map<String, Any?>.toPhotoCaptureDefaults(): PhotoCaptureDefaults =
+        PhotoCaptureDefaults(
+                size = (this["size"] as? String)?.let { PhotoSize.fromValue(it) },
+                mfnr = this["mfnr"] as? Boolean,
+                zsl = this["zsl"] as? Boolean,
+                noiseReduction = this["noiseReduction"] as? Boolean,
+                edgeEnhancement = this["edgeEnhancement"] as? Boolean,
+                ispDigitalGain = (this["ispDigitalGain"] as? Number)?.toInt(),
+                ispAnalogGain = this["ispAnalogGain"] as? String,
+                aeExposureDivisor = (this["aeExposureDivisor"] as? Number)?.toInt(),
+                isoCap = (this["isoCap"] as? Number)?.toInt(),
+                compress = this["compress"] as? String,
+                sound = this["sound"] as? Boolean,
+                resetCaptureTuning = this["resetCaptureTuning"] as? Boolean == true,
+        )
+
 private fun Map<String, Any>?.toMentraConnectOptions(): ConnectOptions {
     val values = this ?: return ConnectOptions()
     return ConnectOptions(

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

@@ -374,6 +374,11 @@ public class Bridge private constructor() {
             sendTypedMessage("photo_status", statusJson)
         }
 
+        @JvmStatic
+        fun sendCameraStatus(statusJson: Map<String, Any>) {
+            sendTypedMessage("camera_status", statusJson)
+        }
+
         @JvmStatic
         fun sendPhotoResponse(responseJson: Map<String, Any>) {
             sendTypedMessage("photo_response", responseJson)
@@ -587,26 +592,6 @@ public class Bridge private constructor() {
             sendTypedMessage("mtk_update_complete", eventBody as Map<String, Any>)
         }
 
-        /**
-         * Send OTA update available notification - glasses have detected an available update
-         * (background mode)
-         */
-        @JvmStatic
-        fun sendOtaUpdateAvailable(
-                versionCode: Long,
-                versionName: String,
-                updates: List<String>,
-                totalSize: Long
-        ) {
-            val eventBody = HashMap<String, Any>()
-            eventBody["version_code"] = versionCode
-            eventBody["version_name"] = versionName
-            eventBody["updates"] = updates
-            eventBody["total_size"] = totalSize
-
-            sendTypedMessage("ota_update_available", eventBody as Map<String, Any>)
-        }
-
         /** Send ota_start_ack — glasses confirmed receipt of ota_start command */
         @JvmStatic
         fun sendOtaStartAck() {