@mentra/bluetooth-sdk 0.1.7 → 0.1.9

package/README.md

@@ -266,11 +266,17 @@ await BluetoothSdk.requestPhoto({
   authToken: 'optional-token',
   compress: 'medium',
   sound: true,
+  exposureTimeNs: null, // auto exposure; pass a positive nanosecond value for manual exposure
+  iso: null, // auto ISO; pass a positive ISO only with manual exposureTimeNs
 })
 ```
 
 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`.
+
+Use `setCameraFov({fov, roiPosition})` to configure Mentra Live camera field of view and crop position. FOV is clamped to 82-118 degrees; ROI position is `0` center, `1` bottom, or `2` top. Applying FOV/ROI restarts the camera for about 5 seconds, so wait before requesting the next photo.
+
 ## Streaming
 
 ```ts
@@ -283,16 +289,11 @@ await BluetoothSdk.startStream({
   video: {fps: 15},
 })
 
-await BluetoothSdk.keepStreamAlive({
-  type: 'keep_stream_alive',
-  streamId,
-  ackId: `ack-${Date.now()}`,
-})
-
 await BluetoothSdk.stopStream()
 ```
 
-Use `rtmp://` or `rtmps://` for RTMP, `srt://` for SRT, and `http://` or `https://` for WHIP/WebRTC ingest. Send keep-alives about every 15 seconds while streaming. The camera light is always enabled while streaming.
+Use `rtmp://` or `rtmps://` for RTMP, `srt://` for SRT, and `http://` or `https://` for WHIP/WebRTC ingest. 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.
 
 ## Events
 
@@ -304,6 +305,7 @@ import {useBluetoothEvent} from '@mentra/bluetooth-sdk/react'
 export function HardwareEventLogger() {
   useBluetoothEvent('button_press', (event) => console.log(event))
   useBluetoothEvent('touch_event', (event) => console.log(event))
+  useBluetoothEvent('photo_status', (event) => console.log(event.status, event.resolvedConfig))
   useBluetoothEvent('photo_response', (event) => console.log(event))
   useBluetoothEvent('stream_status', (event) => console.log(event))
   useBluetoothEvent('speaking_status', (event) => console.log(event.speaking))
@@ -318,9 +320,9 @@ 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`, `hotspot_status_change`, `photo_response`, `gallery_status`, `stream_status`, `keep_alive_ack`, `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`, `hotspot_status_change`, `photo_status`, `photo_response`, `gallery_status`, `stream_status`, `mic_pcm`, `mic_lc3`, `local_transcription`, `rgb_led_control_response`, `audio_connected`, `audio_disconnected`, and `log`.
 
-React Native event payload fields use camelCase. For example, `touch_event` includes `gestureName`, `photo_response` success includes `uploadUrl`, and `gallery_status` includes `hasContent` and `cameraBusy`. `mic_pcm` includes `sampleRate`, `bitsPerSample`, `channels`, and `encoding`; `mic_lc3` includes `sampleRate`, `channels`, `encoding`, `frameDurationMs`, `frameSizeBytes`, `bitrate`, and `packetizedFromGlasses`.
+React Native event payload fields use camelCase. For example, `touch_event` includes `gestureName`, `photo_response` success includes `uploadUrl`, and `gallery_status` includes `hasContent` and `cameraBusy`. `photo_status` reports intermediate photo states such as `accepted`, `queued`, `configuring`, `capturing`, `captured`, `compressing`, `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. `mic_pcm` includes `sampleRate`, `bitsPerSample`, `channels`, and `encoding`; `mic_lc3` includes `sampleRate`, `channels`, `encoding`, `frameDurationMs`, `frameSizeBytes`, `bitrate`, and `packetizedFromGlasses`.
 
 Only documented imports are supported for app developers. Undocumented package subpaths or symbols with a leading underscore can change without notice.
 

package/android/.project

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>mentra-bluetooth-sdk</name>
+	<comment>Project mentra-bluetooth-sdk created by Buildship.</comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>org.eclipse.buildship.core.gradleprojectbuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>org.eclipse.buildship.core.gradleprojectnature</nature>
+	</natures>
+	<filteredResources>
+		<filter>
+			<id>1779400133450</id>
+			<name></name>
+			<type>30</type>
+			<matcher>
+				<id>org.eclipse.core.resources.regexFilterMatcher</id>
+				<arguments>node_modules|\.git|__CREATED_BY_JAVA_LANGUAGE_SERVER__</arguments>
+			</matcher>
+		</filter>
+	</filteredResources>
+</projectDescription>

package/android/build.gradle

@@ -83,6 +83,9 @@ dependencies {
   // OkHttp for HTTP requests
   implementation 'com.squareup.okhttp3:okhttp:4.12.0'
 
+  // Local photo upload receiver
+  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1"
+
   // LC3 audio codec library
   implementation project(':lc3Lib')
 

package/android/lc3Lib/.project

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>lc3Lib</name>
+	<comment>Project lc3Lib created by Buildship.</comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>org.eclipse.buildship.core.gradleprojectbuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>org.eclipse.buildship.core.gradleprojectnature</nature>
+	</natures>
+	<filteredResources>
+		<filter>
+			<id>1779400133449</id>
+			<name></name>
+			<type>30</type>
+			<matcher>
+				<id>org.eclipse.core.resources.regexFilterMatcher</id>
+				<arguments>node_modules|\.git|__CREATED_BY_JAVA_LANGUAGE_SERVER__</arguments>
+			</matcher>
+		</filter>
+	</filteredResources>
+</projectDescription>

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

@@ -1,5 +1,6 @@
 package com.mentra.bluetoothsdk
 
+import com.mentra.bluetoothsdk.debug.BleTraceLogger
 import com.mentra.bluetoothsdk.utils.DeviceTypes
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
@@ -108,6 +109,10 @@ class BluetoothSdkModule : Module() {
                     sendEvent("photo_response", event.values)
                 }
 
+                override fun onPhotoStatus(event: PhotoStatusEvent) {
+                    sendEvent("photo_status", event.values)
+                }
+
                 override fun onStreamStatus(event: StreamStatusEvent) {
                     sendEvent("stream_status", event.values)
                 }
@@ -164,6 +169,7 @@ class BluetoothSdkModule : Module() {
             "hotspot_status_change",
             "hotspot_error",
             "photo_response",
+            "photo_status",
             "gallery_status",
             "compatible_glasses_search_stop",
             "heartbeat_sent",
@@ -203,11 +209,17 @@ class BluetoothSdkModule : Module() {
                     appContext.reactContext
                             ?: appContext.currentActivity
                                     ?: throw IllegalStateException("No context available")
+            BleTraceLogger.logLifecycle(context, "BluetoothSdkModule", "module_create")
             sdk = MentraBluetoothSdk.create(context, sdkListener)
             deviceManager = DeviceManager.getInstance()
         }
 
         OnDestroy {
+            BleTraceLogger.logLifecycle(
+                    appContext.reactContext ?: appContext.currentActivity,
+                    "BluetoothSdkModule",
+                    "module_destroy"
+            )
             sdk?.close()
             sdk = null
             deviceManager = null
@@ -376,7 +388,7 @@ 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}"
+                    "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}"
             )
             val activeSdk = sdk
             if (activeSdk == null) {
@@ -422,8 +434,8 @@ class BluetoothSdkModule : Module() {
 
         AsyncFunction("stopStream") { sdk?.stopStream() }
 
-        AsyncFunction("keepStreamAlive") { params: Map<String, Any> ->
-            sdk?.keepStreamAlive(StreamKeepAliveRequest.fromMap(params))
+        AsyncFunction("sendCloudStreamKeepAlive") { params: Map<String, Any> ->
+            sdk?.sendCloudStreamKeepAlive(StreamKeepAliveRequest.fromMap(params))
         }
 
         // MARK: - Microphone Commands

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

@@ -9,6 +9,7 @@ package com.mentra.bluetoothsdk
 
 import android.util.Base64
 import android.util.Log
+import com.mentra.bluetoothsdk.debug.BleTraceLogger
 import java.util.HashMap
 import java.util.UUID
 import kotlin.jvm.JvmStatic
@@ -347,14 +348,29 @@ public class Bridge private constructor() {
 
         @JvmStatic
         fun sendPhotoError(requestId: String, errorCode: String, errorMessage: String) {
+            val timestamp = System.currentTimeMillis()
             val event = HashMap<String, Any>()
             event["type"] = "photo_response"
             event["state"] = "error"
             event["requestId"] = requestId
             event["errorCode"] = errorCode
             event["errorMessage"] = errorMessage
-            event["timestamp"] = System.currentTimeMillis()
+            event["timestamp"] = timestamp
             sendTypedMessage("photo_response", event as Map<String, Any>)
+
+            val status = HashMap<String, Any>()
+            status["type"] = "photo_status"
+            status["status"] = "failed"
+            status["requestId"] = requestId
+            status["errorCode"] = errorCode
+            status["errorMessage"] = errorMessage
+            status["timestamp"] = timestamp
+            sendTypedMessage("photo_status", status as Map<String, Any>)
+        }
+
+        @JvmStatic
+        fun sendPhotoStatus(statusJson: Map<String, Any>) {
+            sendTypedMessage("photo_status", statusJson)
         }
 
         /** Send RGB LED control response */
@@ -645,6 +661,15 @@ public class Bridge private constructor() {
                     return
                 }
 
+                if (type != "log") {
+                    BleTraceLogger.logMap(
+                        "phone_to_app",
+                        "sdk_event_dispatch",
+                        type,
+                        mutableBody as Map<String, Any>,
+                    )
+                }
+
                 // Send directly using type as event name - no JSON serialization
                 sinks.forEach { sink ->
                     try {

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

@@ -1353,6 +1353,7 @@ class DeviceManager {
             flash: Boolean,
             sound: Boolean,
             exposureTimeNs: Double? = null,
+            iso: Int? = null,
     ) {
         val exposureNs: Long? =
                 exposureTimeNs?.takeIf { it.isFinite() && it > 0 }?.let { v ->
@@ -1361,8 +1362,9 @@ class DeviceManager {
                         else -> v.toLong()
                     }
                 }
+        val manualIso = if (exposureNs != null) iso?.takeIf { it > 0 } else null
         Bridge.log(
-                "MAN: PHOTO PIPELINE [4/6] DeviceManager.requestPhoto requestId=$requestId appId=$appId size=$size compress=$compress flash=$flash sound=$sound exposureTimeNs=$exposureNs sgc=${sgc?.javaClass?.simpleName ?: "null"}"
+                "MAN: PHOTO PIPELINE [4/6] DeviceManager.requestPhoto requestId=$requestId appId=$appId size=$size compress=$compress flash=$flash sound=$sound exposureTimeNs=$exposureNs iso=${manualIso ?: "auto"} sgc=${sgc?.javaClass?.simpleName ?: "null"}"
         )
         val activeSgc = sgc
         if (activeSgc == null) {
@@ -1371,7 +1373,7 @@ class DeviceManager {
             )
             return
         }
-        activeSgc.requestPhoto(requestId, appId, size, webhookUrl, authToken, compress, flash, sound, exposureNs)
+        activeSgc.requestPhoto(requestId, appId, size, webhookUrl, authToken, compress, flash, sound, exposureNs, manualIso)
     }
 
     fun rgbLedControl(

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

@@ -7,6 +7,7 @@ import android.os.Looper
 import com.mentra.bluetoothsdk.utils.ControllerTypes
 import com.mentra.bluetoothsdk.utils.PhoneAudioMonitor
 import java.util.Collections
+import java.util.UUID
 import java.util.concurrent.atomic.AtomicBoolean
 
 class MentraBluetoothSdk private constructor(
@@ -23,6 +24,8 @@ class MentraBluetoothSdk private constructor(
     private val bridgeEventSinkId: String
     private val storeListenerId: String
     private var suppressDefaultDeviceEvents = false
+    private val streamKeepAliveLock = Any()
+    private var activeStreamKeepAlive: ActiveStreamKeepAlive? = null
 
     init {
         listeners.add(listener)
@@ -36,6 +39,8 @@ class MentraBluetoothSdk private constructor(
         private val DEFAULT_DEVICE_KEYS = setOf("default_wearable", "device_name", "device_address")
         private val SCAN_STATE_KEYS = setOf("searching", "searchingController", "searchResults")
         private const val DEFAULT_SCAN_TIMEOUT_MS = 15_000L
+        private const val DEFAULT_STREAM_KEEP_ALIVE_INTERVAL_SECONDS = 5
+        private const val MAX_MISSED_STREAM_KEEP_ALIVE_ACKS = 3
 
         @JvmStatic
         fun create(
@@ -51,6 +56,14 @@ class MentraBluetoothSdk private constructor(
         ): MentraBluetoothSdk = MentraBluetoothSdk(context, config, listener)
     }
 
+    private data class ActiveStreamKeepAlive(
+        val streamId: String,
+        val intervalMs: Long,
+        var pendingAckId: String? = null,
+        var missedAckCount: Int = 0,
+        var nextTick: Runnable? = null,
+    )
+
     fun addListener(listener: MentraBluetoothSdkListener) {
         listeners.add(listener)
     }
@@ -427,6 +440,7 @@ class MentraBluetoothSdk private constructor(
             request.flash,
             request.sound,
             request.exposureTimeNs,
+            request.iso,
         )
     }
 
@@ -435,10 +449,18 @@ class MentraBluetoothSdk private constructor(
     }
 
     fun startStream(request: StreamRequest) {
-        deviceManager.startStream(request.toMap().toMutableMap())
+        val message = request.toMap().toMutableMap()
+        val streamId = (message["streamId"] as? String)?.takeIf { it.isNotBlank() }
+                ?: "sdk-${UUID.randomUUID()}"
+        message["streamId"] = streamId
+        stopStreamKeepAliveMonitor()
+        deviceManager.startStream(message)
+        if (request.keepAlive && !request.isExternallyManagedKeepAlive()) {
+            startStreamKeepAliveMonitor(streamId, request.keepAliveIntervalSeconds)
+        }
     }
 
-    fun keepStreamAlive(request: StreamKeepAliveRequest) {
+    internal fun sendCloudStreamKeepAlive(request: StreamKeepAliveRequest) {
         deviceManager.keepStreamAlive(request.toMap().toMutableMap())
     }
 
@@ -455,6 +477,7 @@ class MentraBluetoothSdk private constructor(
     }
 
     fun stopStream() {
+        stopStreamKeepAliveMonitor()
         deviceManager.stopStream()
     }
 
@@ -491,6 +514,7 @@ class MentraBluetoothSdk private constructor(
     }
 
     override fun close() {
+        stopStreamKeepAliveMonitor()
         Bridge.removeEventSink(bridgeEventSinkId)
         DeviceStore.store.removeListener(storeListenerId)
         listeners.clear()
@@ -644,8 +668,18 @@ class MentraBluetoothSdk private constructor(
             "hotspot_error" -> dispatchToListeners { it.onHotspotError(HotspotErrorEvent(data)) }
             "gallery_status" -> dispatchToListeners { it.onGalleryStatus(GalleryStatusEvent(data)) }
             "photo_response" -> dispatchToListeners { it.onPhotoResponse(PhotoResponseEvent(data)) }
-            "stream_status" -> dispatchToListeners { it.onStreamStatus(StreamStatusEvent(data)) }
-            "keep_alive_ack" -> dispatchToListeners { it.onKeepAliveAck(KeepAliveAckEvent(data)) }
+            "photo_status" -> dispatchToListeners { it.onPhotoStatus(PhotoStatusEvent(data)) }
+            "stream_status" -> {
+                val event = StreamStatusEvent(data)
+                handleStreamStatusForKeepAlive(event.status)
+                dispatchToListeners { it.onStreamStatus(event) }
+            }
+            "keep_alive_ack" -> {
+                val event = KeepAliveAckEvent(data)
+                if (!handleStreamKeepAliveAck(event)) {
+                    dispatchToListeners { it.onKeepAliveAck(event) }
+                }
+            }
             "mic_pcm" -> {
                 val event = MicPcmEvent(data)
                 if (event.pcm.isNotEmpty()) {
@@ -700,4 +734,102 @@ class MentraBluetoothSdk private constructor(
             deliver()
         }
     }
+
+    private fun startStreamKeepAliveMonitor(streamId: String, requestedIntervalSeconds: Int) {
+        val intervalSeconds =
+                requestedIntervalSeconds.takeIf { it > 0 } ?: DEFAULT_STREAM_KEEP_ALIVE_INTERVAL_SECONDS
+        val tracker = ActiveStreamKeepAlive(
+                streamId = streamId,
+                intervalMs = intervalSeconds * 1_000L,
+        )
+        synchronized(streamKeepAliveLock) {
+            activeStreamKeepAlive = tracker
+        }
+        sendNextStreamKeepAlive(tracker)
+    }
+
+    private fun stopStreamKeepAliveMonitor() {
+        val tracker =
+                synchronized(streamKeepAliveLock) {
+                    val current = activeStreamKeepAlive
+                    activeStreamKeepAlive = null
+                    current
+                }
+        tracker?.nextTick?.let { mainHandler.removeCallbacks(it) }
+    }
+
+    private fun sendNextStreamKeepAlive(tracker: ActiveStreamKeepAlive) {
+        var timeoutEvent: StreamStatusEvent? = null
+        var request: StreamKeepAliveRequest? = null
+
+        synchronized(streamKeepAliveLock) {
+            if (activeStreamKeepAlive !== tracker) {
+                return
+            }
+
+            if (tracker.pendingAckId != null) {
+                tracker.missedAckCount += 1
+                if (tracker.missedAckCount >= MAX_MISSED_STREAM_KEEP_ALIVE_ACKS) {
+                    activeStreamKeepAlive = null
+                    tracker.nextTick?.let { mainHandler.removeCallbacks(it) }
+                    timeoutEvent =
+                            StreamStatusEvent(
+                                    StreamStatus.Error(
+                                            streamId = tracker.streamId,
+                                            errorDetails =
+                                                    "Stream keep-alive timed out after ${tracker.missedAckCount} missed ACKs",
+                                            timestamp = System.currentTimeMillis(),
+                                            resolvedConfig = null,
+                                    )
+                            )
+                    return@synchronized
+                }
+            }
+
+            val ackId = "ack-${System.currentTimeMillis()}"
+            tracker.pendingAckId = ackId
+            request = StreamKeepAliveRequest(streamId = tracker.streamId, ackId = ackId)
+            val nextTick = Runnable { sendNextStreamKeepAlive(tracker) }
+            tracker.nextTick = nextTick
+            mainHandler.postDelayed(nextTick, tracker.intervalMs)
+        }
+
+        timeoutEvent?.let { event ->
+            dispatchToListeners { it.onStreamStatus(event) }
+            return
+        }
+
+        request?.let { keepAlive ->
+            deviceManager.keepStreamAlive(keepAlive.toMap().toMutableMap())
+        }
+    }
+
+    private fun handleStreamKeepAliveAck(event: KeepAliveAckEvent): Boolean {
+        synchronized(streamKeepAliveLock) {
+            val tracker = activeStreamKeepAlive ?: return false
+            if (event.streamId != tracker.streamId || event.ackId != tracker.pendingAckId) {
+                return false
+            }
+            tracker.pendingAckId = null
+            tracker.missedAckCount = 0
+            return true
+        }
+    }
+
+    private fun handleStreamStatusForKeepAlive(status: StreamStatus) {
+        val streamId = status.streamId
+        if (
+                streamId != null &&
+                        synchronized(streamKeepAliveLock) { activeStreamKeepAlive?.streamId } != streamId
+        ) {
+            return
+        }
+        when (status.state) {
+            StreamState.STOPPED,
+            StreamState.STOPPING,
+            StreamState.ERROR,
+            StreamState.RECONNECT_FAILED -> stopStreamKeepAliveMonitor()
+            else -> Unit
+        }
+    }
 }

package/android/src/main/java/com/mentra/bluetoothsdk/camera/CameraModels.kt

@@ -47,9 +47,21 @@ data class ButtonVideoRecordingSettings(
     val fps: Int,
 )
 
-enum class CameraFov(val fov: Int, val roiPosition: Int) {
-    STANDARD(118, 0),
-    WIDE(118, 0),
+class CameraFov @JvmOverloads constructor(
+    fov: Int = DEFAULT_FOV,
+    roiPosition: Int = DEFAULT_ROI_POSITION,
+) {
+    val fov: Int = fov.coerceIn(MIN_FOV, MAX_FOV)
+    val roiPosition: Int = roiPosition.coerceIn(MIN_ROI_POSITION, MAX_ROI_POSITION)
+
+    companion object {
+        const val MIN_FOV = 82
+        const val MAX_FOV = 118
+        const val DEFAULT_FOV = 102
+        const val MIN_ROI_POSITION = 0
+        const val MAX_ROI_POSITION = 2
+        const val DEFAULT_ROI_POSITION = 0
+    }
 }
 
 data class PhotoRequest @JvmOverloads constructor(
@@ -63,6 +75,8 @@ data class PhotoRequest @JvmOverloads constructor(
     val sound: Boolean = true,
     /** Sensor exposure time for this capture only (ns), or null for auto exposure */
     val exposureTimeNs: Double? = null,
+    /** Sensor ISO for this capture only. Only used when exposureTimeNs enables manual exposure. */
+    val iso: Int? = null,
 ) {
     companion object {
         /** Mirrors iOS `BluetoothSdkModule` defaults for keys omitted from the JS bridge. */
@@ -74,6 +88,17 @@ data class PhotoRequest @JvmOverloads constructor(
                     is Number -> rawExp.toDouble().takeIf { it.isFinite() && it > 0 }
                     else -> null
                 }
+            val rawIso = values["iso"]
+            val iso: Int? =
+                when (rawIso) {
+                    is Number -> rawIso.toDouble().takeIf { it.isFinite() && it > 0 }?.let { value ->
+                        when {
+                            value > Int.MAX_VALUE.toDouble() -> Int.MAX_VALUE
+                            else -> value.toInt()
+                        }
+                    }
+                    else -> null
+                }
             return PhotoRequest(
                 requestId = stringValue(values, "requestId", "request_id").orEmpty(),
                 appId = stringValue(values, "appId", "app_id").orEmpty(),
@@ -84,6 +109,7 @@ data class PhotoRequest @JvmOverloads constructor(
                 flash = boolValue(values, "flash") ?: true,
                 sound = boolValue(values, "sound") ?: true,
                 exposureTimeNs = exposureTimeNs,
+                iso = iso,
             )
         }
     }
@@ -207,3 +233,14 @@ data class PhotoResponseEvent(
     val requestId: String get() = response.requestId
     val values: Map<String, Any> get() = response.toEventMap()
 }
+
+data class PhotoStatusEvent(
+    val values: Map<String, Any>,
+) {
+    val requestId: String get() = stringValue(values, "requestId").orEmpty()
+    val status: String get() = stringValue(values, "status").orEmpty()
+    val timestamp: Long get() = longValue(values, "timestamp") ?: System.currentTimeMillis()
+    val resolvedConfig: Map<String, Any>? get() = stringMapValue(values["resolvedConfig"])
+    val errorCode: String? get() = stringValue(values, "errorCode")
+    val errorMessage: String? get() = stringValue(values, "errorMessage")
+}

package/android/src/main/java/com/mentra/bluetoothsdk/controllers/ControllerManager.kt

@@ -24,6 +24,7 @@ abstract class ControllerManager {
         flash: Boolean,
         sound: Boolean,
         exposureTimeNs: Long?,
+        iso: Int?,
     )
     abstract fun startStream(message: Map<String, Any>)
     abstract fun stopStream()

package/android/src/main/java/com/mentra/bluetoothsdk/controllers/R1.kt

@@ -864,7 +864,7 @@ class R1 : ControllerManager() {
     override fun requestPhoto(
         requestId: String, appId: String, size: String?, webhookUrl: String?,
         authToken: String?, compress: String?, flash: Boolean, sound: Boolean,
-        exposureTimeNs: Long?,
+        exposureTimeNs: Long?, iso: Int?,
     ) {}
     override fun startVideoRecording(requestId: String, save: Boolean, flash: Boolean, sound: Boolean) {}
     override fun stopVideoRecording(requestId: String) {}