@mentra/bluetooth-sdk 3.2.0-dev.235 → 3.2.0-dev.247

package/README.md

@@ -583,13 +583,34 @@ 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 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.
+`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 (110 seconds when `presend_thumbnail` is enabled). 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.
+
+Set `presend_thumbnail: true` to receive a JPEG preview over Bluetooth before the
+full photo (default: `false`). Listen for `photo_status` with
+`status: "thumbnail_received"`; `thumbnailUrl` is a JPEG data URI and
+`fileSizeBytes` is the preview size. The preview preserves aspect ratio, is at
+most 500 pixels on its longest edge, never upscales, and uses JPEG quality 50.
+Preview pixels match the full delivered image's display orientation, including
+EXIF rotation/mirroring on direct uploads; no EXIF-aware preview renderer is needed.
+It does not resolve `requestPhoto()` or replace the full webhook delivery.
+The opted-in end-to-end deadline is 110 seconds: capture (45) + preview
+transfer/retries and ACK (30) + full delivery (30) + response transit margin (5).
+Both native SDK facades mirror ASG's constants; the glasses job watchdog is 105
+seconds. Progress and preview ACK never restart these timers.
+An upload target is required; save-only capture does not support previews.
+Compatible ASG firmware is required; older firmware may ignore this option.
+
+On the BLE delivery path, full-image encoding overlaps preview transmission,
+but the full image is sent only after the phone acknowledges the preview.
+Preview send failure or a missing acknowledgement fails the request rather than
+starting a competing transfer. ASG timing logs use `BlePhotoTiming`; thumbnail
+transmission and CPU processing overlap, so their durations are not additive.
 
 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.
+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 5 minutes. 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.
+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. FOV calls use a 45-second deadline covering one active and one coalesced pending update on ASG, including camera re-registration. Replaced pending commands reject with `fov_superseded`. 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.
 
@@ -726,3 +747,27 @@ secrets, not in the repository.
 ## Starter Example App
 
 The [Mentra Bluetooth SDK Starter Kit](https://github.com/Mentra-Community/Mentra-Bluetooth-SDK-Starter-Kit) includes starter example apps for Android, iOS, and React Native / Expo. The React Native starter demonstrates scan/connect, display, camera photo upload, RTMP/SRT/WebRTC streaming, Wi-Fi/hotspot, microphone PCM, RGB LED, gallery mode, and console event inspection.
+
+BLE JPEG photo compression supports `none` (Q95), `low` (Q88), `medium` (Q78), and `high` (Q60) on updated glasses firmware. Omitted compression defaults to `none`. Values are sent unchanged and invalid values are rejected. Pixel limits are controlled separately by `size`.
+
+### Breaking change: photo compression
+
+Photo compression now accepts exactly `none`, `low`, `medium`, and `high`, sent
+unchanged across the Mentra Miniapp SDK, Bluetooth SDKs, and glasses.
+The default is `none` everywhere. Glasses encode these as JPEG Q95, Q88, Q78,
+and Q60 respectively; `size` controls dimensions separately. `none` still uses
+lossy JPEG encoding. Unknown values are rejected.
+
+Cloud only allocates upload/download URLs: it takes no photo options and ignores
+any request body. Photo compression is handled by the phone and glasses.
+
+The former `heavy` spelling is removed; callers must use `high`. Android's native
+default changes from `medium` to `none`. Existing miniapps may therefore produce
+different JPEG quality or payload sizes. There are no compatibility aliases or wire translations.
+
+Photo compression omission is distinct from an explicit `null`: requests default
+omission to `none`, and partial preset updates leave an omitted compression field
+unchanged. A supplied `null` or other invalid value is rejected. Stored presets
+containing removed values are invalid; replace their compression with one of the
+four supported values before replaying the complete preset. There is no automatic
+migration or substitution. Fresh valid preset updates remain available.

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

@@ -643,7 +643,7 @@ class BluetoothSdkModule : Module() {
 
         @Suppress("DEPRECATION")
         SdkCoroutineFunction("setPhotoCaptureDefaults") { params: Map<String, Any?> ->
-            requireSdk().setPhotoCaptureDefaults(params.toPhotoCaptureDefaults()).values
+            requireSdk().setPhotoCaptureDefaults(PhotoCaptureDefaults.fromMap(params)).values
         }
 
         SdkCoroutineFunction("setVideoRecordingDefaults") { width: Int, height: Int, fps: Int ->
@@ -698,12 +698,7 @@ class BluetoothSdkModule : Module() {
         SdkCoroutineFunction("queryGalleryStatus") { -> requireSdk().queryGalleryStatus().values }
 
         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) ->
-                        if (value == null) null else key to value
-                    }.toMap()
-            val req = PhotoRequest.fromMap(sanitized)
+            val req = PhotoRequest.fromMap(params)
             Bridge.log(
                     "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}"
             )
@@ -1044,22 +1039,6 @@ 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/DeviceManager.kt

@@ -1996,7 +1996,7 @@ class DeviceManager {
             settings.ispAnalogGain,
             settings.aeExposureDivisor,
             settings.isoCap,
-            settings.compress,
+            settings.compress?.value,
             settings.sound,
             settings.resetCaptureTuning == true,
         )

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

@@ -4,5 +4,6 @@ package com.mentra.bluetoothsdk
 internal val GENERATED_RELEASE_CHANGELOGS: List<ReleaseChangelog> =
     listOf(
         ReleaseChangelog(version = "3.2.0", markdown = "This release is under active development. User-facing changes will be documented as they land.\n\n- Breaking Bluetooth SDK change: `forgetWifiNetwork(ssid)` now returns `WifiForgetResult` instead of `WifiStatusChangeEvent`. Migrate status-only consumers to the semantic `outcome`; the requested network remains `ssid`, while optional post-command connectivity is reported by `connected`, `currentSsid`, and `localIp`."),
+        ReleaseChangelog(version = "3.1.1", markdown = "Software updates are more reliable, with clearer progress and recovery when the glasses restart.\n\n- MentraOS, Mentra Engine, the Bluetooth SDK, and the glasses client now share one coordinated release version.\n- Mentra Live updates can continue across APK, system, and firmware restarts without asking the user to start the same update again.\n- Bluetooth photo capture and transfer diagnostics are more precise and less disruptive to normal glasses traffic.\n- Bluetooth SDK usage analytics now report the host app's version, build type, and install source (store, TestFlight, sideload, simulator), plus the glasses firmware versions on identification, so store usage can be measured separately from development builds.\n- Bluetooth SDK usage analytics now identify G2 glasses by serial, keep long-lived connections visible across day boundaries, and retry failed uploads instead of dropping them."),
         ReleaseChangelog(version = "3.1.0", markdown = "Software updates are more reliable, with clearer progress and recovery when the glasses restart.\n\n- MentraOS, Mentra Engine, the Bluetooth SDK, and the glasses client now share one coordinated release version.\n- Mentra Live updates can continue across APK, system, and firmware restarts without asking the user to start the same update again.\n- Bluetooth photo capture and transfer diagnostics are more precise and less disruptive to normal glasses traffic.\n- Bluetooth SDK usage analytics now report the host app's version, build type, and install source (store, TestFlight, sideload, simulator), plus the glasses firmware versions on identification, so store usage can be measured separately from development builds.\n- Bluetooth SDK usage analytics now identify G2 glasses by serial, keep long-lived connections visible across day boundaries, and retry failed uploads instead of dropping them."),
     )

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

@@ -3,9 +3,9 @@ package com.mentra.bluetoothsdk
 /** Generated by release CI. Do not edit in a release checkout. */
 internal object GeneratedReleaseMetadata {
     const val FAMILY_BASE_VERSION: String = "3.2.0"
-    const val RELEASE_IDENTITY: String = "3.2.0-dev.235"
-    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.235"
-    const val SOURCE_COMMIT: String = "5f25e2687788b3d964e19d17fd6cd4139e3e677e"
-    const val OTA_MANIFEST_URL: String = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.235.json"
-    const val OTA_MANIFEST_SHA256: String = "a9e9ebec66e2f638ab89f446d87925cdc2c85abf3091ed33e76f01986e658ca7"
+    const val RELEASE_IDENTITY: String = "3.2.0-dev.247"
+    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.247"
+    const val SOURCE_COMMIT: String = "2be1b25e83b0c8db5cef39294c93b0a3f9ec7aef"
+    const val OTA_MANIFEST_URL: String = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.247.json"
+    const val OTA_MANIFEST_SHA256: String = "cba0e05a180f92e98e3bf47d0acdba2ae81cc79788da1393e80334fb5b26093b"
 }

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

@@ -19,6 +19,8 @@ import java.util.concurrent.atomic.AtomicLong
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CompletableDeferred
 import kotlinx.coroutines.delay
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
 import kotlinx.coroutines.withTimeoutOrNull
 
 class MentraBluetoothSdk private constructor(
@@ -73,6 +75,7 @@ class MentraBluetoothSdk private constructor(
     private var pendingWifiStatus: PendingWifiStatusRequest? = null
     private var pendingWifiForget: PendingWifiForgetRequest? = null
     private var pendingHotspotStatus: PendingHotspotStatusRequest? = null
+    private val hotspotMutex = Mutex()
     private var pendingVersionInfo: PendingVersionInfoRequest? = null
     private val wifiSessionCapabilities = WifiSessionCapabilities()
     @Volatile private var configuredOtaVersionUrl: String? = null
@@ -100,9 +103,24 @@ class MentraBluetoothSdk private constructor(
         private val SCAN_STATE_KEYS = setOf("searching", "searchingController", "searchResults")
         private const val DEFAULT_SCAN_TIMEOUT_MS = 15_000L
         private const val DEFAULT_REQUEST_TIMEOUT_MS = 15_000L
+        // Mirrors AsgConstants: one active + one coalesced pending FOV update, plus BLE margin.
+        // Keep in sync with ios/Source/MentraBluetoothSDK.swift and the ASG readiness budget.
+        private const val CAMERA_FOV_READY_TIMEOUT_MS = 20_000L
+        private const val CAMERA_FOV_DELIVERY_MARGIN_MS = 5_000L
+        private const val CAMERA_FOV_REQUEST_TIMEOUT_MS =
+            2 * CAMERA_FOV_READY_TIMEOUT_MS + CAMERA_FOV_DELIVERY_MARGIN_MS
         // A photo response is terminal only after capture, encoding, transport, and upload.
         // Max-quality BLE fallback can legitimately exceed the generic command deadline.
         private const val PHOTO_REQUEST_TIMEOUT_MS = 30_000L
+        // Mirrors AsgConstants.PHOTO_THUMBNAIL_REQUEST_TIMEOUT_MS and the iOS facade.
+        // Reserve capture, preview ACK/retries, full delivery, then terminal-event transit.
+        private const val PHOTO_CAPTURE_TIMEOUT_MS = 45_000L
+        private const val PHOTO_THUMBNAIL_TIMEOUT_SECONDS = 30L
+        private const val PHOTO_DELIVERY_TIMEOUT_MS = 30_000L
+        private const val PHOTO_RESPONSE_MARGIN_MS = 5_000L
+        private const val PHOTO_THUMBNAIL_REQUEST_TIMEOUT_MS =
+            PHOTO_CAPTURE_TIMEOUT_MS + PHOTO_THUMBNAIL_TIMEOUT_SECONDS * 1000L +
+                PHOTO_DELIVERY_TIMEOUT_MS + PHOTO_RESPONSE_MARGIN_MS
         private const val WIFI_SCAN_TIMEOUT_MS = 20_000L
         private const val VIDEO_UPLOAD_STOP_TIMEOUT_MS = 10 * 60 * 1000L
         private const val STREAM_START_TIMEOUT_MS = 30_000L
@@ -597,7 +615,12 @@ class MentraBluetoothSdk private constructor(
         pendingSettingsRequests[requestId] = pending
         try {
             send(requestId)
-            val ack = pending.await()
+            val timeoutMs = if (setting == "camera_fov" || setting == "camera_fov_override") {
+                CAMERA_FOV_REQUEST_TIMEOUT_MS
+            } else {
+                DEFAULT_REQUEST_TIMEOUT_MS
+            }
+            val ack = pending.await(timeoutMs)
             updateStore(ack)
             return ack
         } finally {
@@ -664,7 +687,7 @@ class MentraBluetoothSdk private constructor(
                     DeviceStore.set(ObservableStore.BLUETOOTH_CATEGORY, "button_photo_iso_cap", it)
                 }
                 settings.compress?.let {
-                    DeviceStore.set(ObservableStore.BLUETOOTH_CATEGORY, "button_photo_compress", it)
+                    DeviceStore.set(ObservableStore.BLUETOOTH_CATEGORY, "button_photo_compress", it.value)
                 }
                 settings.sound?.let {
                     DeviceStore.set(ObservableStore.BLUETOOTH_CATEGORY, "button_photo_sound", it)
@@ -1010,23 +1033,23 @@ class MentraBluetoothSdk private constructor(
     }
 
     suspend fun setHotspotState(enabled: Boolean): HotspotStatusEvent {
-        val pending = PendingResponse<HotspotStatusEvent>("hotspot ${if (enabled) "enable" else "disable"} request")
-        synchronized(oneShotLock) {
-            if (pendingHotspotStatus != null) {
-                throw BluetoothSdkException(
-                    "request_in_flight",
-                    "A hotspot command is already waiting for a glasses response.",
-                )
-            }
-            pendingHotspotStatus = PendingHotspotStatusRequest(enabled, pending)
-        }
-        try {
-            deviceManager.setHotspotState(enabled)
-            return pending.await()
-        } finally {
+        // SoftAP teardown disables from the transport and again from the host
+        // barrier. Throwing request_in_flight on the second disable recorded a
+        // cleanup error that refused the next join. Queue instead: same-state
+        // and opposite-state both wait their turn, then send.
+        return hotspotMutex.withLock {
+            val pending = PendingResponse<HotspotStatusEvent>("hotspot ${if (enabled) "enable" else "disable"} request")
             synchronized(oneShotLock) {
-                if (pendingHotspotStatus?.pending === pending) {
-                    pendingHotspotStatus = null
+                pendingHotspotStatus = PendingHotspotStatusRequest(enabled, pending)
+            }
+            try {
+                deviceManager.setHotspotState(enabled)
+                pending.await()
+            } finally {
+                synchronized(oneShotLock) {
+                    if (pendingHotspotStatus?.pending === pending) {
+                        pendingHotspotStatus = null
+                    }
                 }
             }
         }
@@ -1052,7 +1075,9 @@ class MentraBluetoothSdk private constructor(
         pendingPhotoRequests[routedRequest.requestId] = pending
         try {
             deviceManager.requestPhoto(routedRequest)
-            return pending.await(PHOTO_REQUEST_TIMEOUT_MS)
+            return pending.await(
+                if (routedRequest.presendThumbnail) PHOTO_THUMBNAIL_REQUEST_TIMEOUT_MS else PHOTO_REQUEST_TIMEOUT_MS,
+            )
         } finally {
             pendingPhotoRequests.remove(routedRequest.requestId, pending)
         }

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

@@ -53,13 +53,15 @@ enum class ButtonPhotoSize(val value: String) {
 
 enum class PhotoCompression(val value: String) {
     NONE("none"),
+    LOW("low"),
     MEDIUM("medium"),
-    HEAVY("heavy");
+    HIGH("high");
 
     companion object {
         @JvmStatic
-        fun fromValue(value: String?): PhotoCompression =
-            values().firstOrNull { it.value == value } ?: NONE
+        fun fromValue(value: Any?): PhotoCompression =
+            values().firstOrNull { it.value == value }
+                ?: throw IllegalArgumentException("Invalid photo compression $value. Expected none, low, medium, or high.")
     }
 }
 
@@ -73,10 +75,29 @@ data class PhotoCaptureDefaults(
     val ispAnalogGain: String? = null,
     val aeExposureDivisor: Int? = null,
     val isoCap: Int? = null,
-    val compress: String? = null,
+    val compress: PhotoCompression? = null,
     val sound: Boolean? = null,
     val resetCaptureTuning: Boolean = false,
-)
+) {
+    companion object {
+        @JvmStatic
+        fun fromMap(values: Map<String, Any?>): PhotoCaptureDefaults =
+            PhotoCaptureDefaults(
+                size = (values["size"] as? String)?.let { PhotoSize.fromValue(it) },
+                mfnr = values["mfnr"] as? Boolean,
+                zsl = values["zsl"] as? Boolean,
+                noiseReduction = values["noiseReduction"] as? Boolean,
+                edgeEnhancement = values["edgeEnhancement"] as? Boolean,
+                ispDigitalGain = (values["ispDigitalGain"] as? Number)?.toInt(),
+                ispAnalogGain = values["ispAnalogGain"] as? String,
+                aeExposureDivisor = (values["aeExposureDivisor"] as? Number)?.toInt(),
+                isoCap = (values["isoCap"] as? Number)?.toInt(),
+                compress = if (values.containsKey("compress")) PhotoCompression.fromValue(values["compress"]) else null,
+                sound = values["sound"] as? Boolean,
+                resetCaptureTuning = values["resetCaptureTuning"] as? Boolean == true,
+            )
+    }
+}
 
 data class VideoRecordingDefaults(
     val width: Int,
@@ -184,7 +205,7 @@ data class PhotoRequest @JvmOverloads constructor(
     val size: PhotoSize,
     val webhookUrl: String,
     val authToken: String? = null,
-    val compress: PhotoCompression = PhotoCompression.MEDIUM,
+    val compress: PhotoCompression = PhotoCompression.NONE,
     val save: Boolean = false,
     val sound: Boolean = true,
     /** Sensor exposure time for this capture only (ns), or null for auto exposure */
@@ -203,6 +224,7 @@ data class PhotoRequest @JvmOverloads constructor(
     val mode: PhotoMode = PhotoMode.PHOTO,
     /** `direct` disables BLE fallback; `ble` skips direct upload; `auto` tries both. */
     val transferMethod: String = "auto",
+    val presendThumbnail: Boolean = false,
 ) {
     companion object {
         private fun transferMethodFromValue(value: Any?): String {
@@ -219,7 +241,7 @@ data class PhotoRequest @JvmOverloads constructor(
 
         /** Mirrors iOS `BluetoothSdkModule` defaults for keys omitted from the JS bridge. */
         @JvmStatic
-        fun fromMap(values: Map<String, Any>): PhotoRequest {
+        fun fromMap(values: Map<String, Any?>): PhotoRequest {
             val rawExp = values["exposureTimeNs"] ?: values["exposure_time_ns"]
             val exposureTimeNs: Double? =
                 when (rawExp) {
@@ -249,11 +271,12 @@ data class PhotoRequest @JvmOverloads constructor(
                 size = PhotoSize.fromValue(stringValue(values, "size") ?: "medium"),
                 webhookUrl = stringValue(values, "webhookUrl", "webhook_url").orEmpty(),
                 authToken = stringValue(values, "authToken", "auth_token")?.takeIf { it.isNotBlank() },
-                compress = PhotoCompression.fromValue(stringValue(values, "compress") ?: "none"),
+                compress = if (values.containsKey("compress")) PhotoCompression.fromValue(values["compress"]) else PhotoCompression.NONE,
                 save = boolValue(values, "save", "saveToGallery") ?: false,
                 sound = boolValue(values, "sound") ?: true,
                 mode = PhotoMode.fromValue(stringValue(values, "mode")),
                 transferMethod = transferMethodFromValue(values["transferMethod"]),
+                presendThumbnail = boolValue(values, "presend_thumbnail") ?: false,
                 exposureTimeNs = exposureTimeNs,
                 iso = iso,
                 aeExposureDivisor = aeDivisor,
@@ -464,6 +487,8 @@ data class PhotoResponseEvent(
 data class PhotoStatusEvent(
     val values: Map<String, Any>,
 ) {
+    val thumbnailUrl: String? get() = stringValue(values, "thumbnailUrl")
+    val fileSizeBytes: Long? get() = longValue(values, "fileSizeBytes")
     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()

package/android/src/main/java/com/mentra/bluetoothsdk/internal/MapParsing.kt

@@ -1,7 +1,7 @@
 package com.mentra.bluetoothsdk
 
 internal fun numberValue(
-    values: Map<String, Any>,
+    values: Map<String, Any?>,
     vararg keys: String,
 ): Int? =
     keys.firstNotNullOfOrNull { key ->
@@ -9,7 +9,7 @@ internal fun numberValue(
     }
 
 internal fun doubleValue(
-    values: Map<String, Any>,
+    values: Map<String, Any?>,
     vararg keys: String,
 ): Double? =
     keys.firstNotNullOfOrNull { key ->
@@ -17,7 +17,7 @@ internal fun doubleValue(
     }
 
 internal fun stringValue(
-    values: Map<String, Any>,
+    values: Map<String, Any?>,
     vararg keys: String,
 ): String? =
     keys.firstNotNullOfOrNull { key ->
@@ -25,7 +25,7 @@ internal fun stringValue(
     }
 
 internal fun boolValue(
-    values: Map<String, Any>,
+    values: Map<String, Any?>,
     vararg keys: String,
 ): Boolean? =
     keys.firstNotNullOfOrNull { key ->
@@ -33,7 +33,7 @@ internal fun boolValue(
     }
 
 internal fun longValue(
-    values: Map<String, Any>,
+    values: Map<String, Any?>,
     vararg keys: String,
 ): Long? =
     keys.firstNotNullOfOrNull { key ->
@@ -41,7 +41,7 @@ internal fun longValue(
     }
 
 internal fun hasAnyKey(
-    values: Map<String, Any>,
+    values: Map<String, Any?>,
     vararg keys: String,
 ): Boolean = keys.any(values::containsKey)
 
@@ -53,7 +53,7 @@ internal fun Map<*, *>.stringKeyedMap(): Map<String, Any> =
     }.toMap()
 
 internal fun optionalNumberValue(
-    values: Map<String, Any>,
+    values: Map<String, Any?>,
     vararg keys: String,
 ): Int? =
     if (hasAnyKey(values, *keys)) {
@@ -63,7 +63,7 @@ internal fun optionalNumberValue(
     }
 
 internal fun optionalLongValue(
-    values: Map<String, Any>,
+    values: Map<String, Any?>,
     vararg keys: String,
 ): Long? =
     if (hasAnyKey(values, *keys)) {
@@ -73,7 +73,7 @@ internal fun optionalLongValue(
     }
 
 internal fun optionalStringValue(
-    values: Map<String, Any>,
+    values: Map<String, Any?>,
     vararg keys: String,
 ): String? =
     if (hasAnyKey(values, *keys)) {
@@ -83,7 +83,7 @@ internal fun optionalStringValue(
     }
 
 internal fun optionalBoolValue(
-    values: Map<String, Any>,
+    values: Map<String, Any?>,
     vararg keys: String,
 ): Boolean? =
     if (hasAnyKey(values, *keys)) {
@@ -93,12 +93,12 @@ internal fun optionalBoolValue(
     }
 
 internal fun stringListValue(
-    values: Map<String, Any>,
+    values: Map<String, Any?>,
     key: String,
 ): List<String> = (values[key] as? List<*>)?.mapNotNull { it as? String } ?: emptyList()
 
 internal fun optionalStringListValue(
-    values: Map<String, Any>,
+    values: Map<String, Any?>,
     key: String,
 ): List<String>? =
     if (values.containsKey(key)) {
@@ -108,13 +108,13 @@ internal fun optionalStringListValue(
     }
 
 internal fun mapListValue(
-    values: Map<String, Any>,
+    values: Map<String, Any?>,
     key: String,
 ): List<Map<String, Any>> =
     (values[key] as? List<*>)?.mapNotNull(::stringMapValue) ?: emptyList()
 
 internal fun optionalMapListValue(
-    values: Map<String, Any>,
+    values: Map<String, Any?>,
     key: String,
 ): List<Map<String, Any>>? =
     if (values.containsKey(key)) {

package/android/src/main/java/com/mentra/bluetoothsdk/sgcs/MentraLive.kt

@@ -1,5 +1,7 @@
 package com.mentra.bluetoothsdk.sgcs
 
+import com.mentra.bluetoothsdk.PhotoCompression
+
 // Mentra
 // old augmentos imports:
 import android.Manifest
@@ -729,6 +731,7 @@ class MentraLive : SGCManager() {
             var requestId: String,
             var webhookUrl: String?
     ) {
+        var isThumbnail: Boolean = false
         var authToken: String? = null
         var session: FileTransferSession? = null
         var phoneStartTime: Long = System.currentTimeMillis() // When phone received the request
@@ -5203,6 +5206,20 @@ class MentraLive : SGCManager() {
             val bleImgId = json.optString("bleImgId", "")
             val requestId = json.optString("requestId", "")
             val compressionDurationMs = json.optLong("compressionDurationMs", 0)
+            if (json.optBoolean("thumbnail", false) && bleImgId.isNotEmpty() && requestId.isNotEmpty()) {
+                val parent = blePhotoTransfers.values.firstOrNull {
+                    !it.isThumbnail && it.requestId == requestId &&
+                        bleImgId == "T" + it.bleImgId.drop(1)
+                }
+                if (parent == null) {
+                    Log.w(TAG, "Ignoring thumbnail for an unknown photo request")
+                    return
+                }
+                // Duplicate ready messages must not erase packets already received.
+                blePhotoTransfers.getOrPut(bleImgId) {
+                    BlePhotoTransfer(bleImgId, requestId, null).apply { isThumbnail = true }
+                }
+            }
 
             Bridge.log(
                     "LIVE: 📸 BLE photo ready notification: bleImgId=" +
@@ -6699,13 +6716,10 @@ class MentraLive : SGCManager() {
                 json.put("size", size)
             }
             json.put("mode", mode)
-            if (compress != null && !compress.isEmpty()) {
-                json.put("compress", compress)
-            } else {
-                json.put("compress", "none")
-            }
+            json.put("compress", compress)
             json.put("save", save)
             json.put("sound", sound)
+            if (request.presendThumbnail) json.put("presend_thumbnail", true)
             if (exposureTimeNs != null && exposureTimeNs > 0L) {
                 Bridge.log(
                         "LIVE: Using manual exposure time for photo request " +
@@ -7918,7 +7932,7 @@ class MentraLive : SGCManager() {
                 command.put("isoCap", isoCap)
             }
             if (!compress.isNullOrEmpty()) {
-                command.put("compress", compress)
+                command.put("compress", PhotoCompression.fromValue(compress).value)
             }
             if (sound != null) {
                 command.put("sound", sound)
@@ -10408,6 +10422,17 @@ class MentraLive : SGCManager() {
 
     /** Process and upload a BLE photo transfer */
     private fun processAndUploadBlePhoto(transfer: BlePhotoTransfer, imageData: ByteArray) {
+        if (transfer.isThumbnail) {
+            Bridge.sendPhotoStatus(mapOf(
+                "type" to "photo_status",
+                "requestId" to transfer.requestId,
+                "status" to "thumbnail_received",
+                "timestamp" to System.currentTimeMillis(),
+                "thumbnailUrl" to ("data:image/jpeg;base64," + android.util.Base64.encodeToString(imageData, android.util.Base64.NO_WRAP)),
+                "fileSizeBytes" to imageData.size,
+            ))
+            return
+        }
         Bridge.log("LIVE: Processing BLE photo for upload. RequestId: " + transfer.requestId)
         val uploadStartTime = System.currentTimeMillis()
 

package/android/src/test/java/com/mentra/bluetoothsdk/camera/PhotoRequestTest.kt

@@ -1,5 +1,6 @@
 package com.mentra.bluetoothsdk.camera
 
+import com.mentra.bluetoothsdk.PhotoCaptureDefaults
 import com.mentra.bluetoothsdk.PhotoCompression
 import com.mentra.bluetoothsdk.PhotoMode
 import com.mentra.bluetoothsdk.PhotoRequest
@@ -9,6 +10,37 @@ import org.assertj.core.api.Assertions.assertThatThrownBy
 import org.junit.Test
 
 class PhotoRequestTest {
+    @Test
+    fun `compression has four exact wire values and defaults to none`() {
+        assertThat(PhotoCompression.values().map { it.value }).containsExactly("none", "low", "medium", "high")
+        for (compression in PhotoCompression.values()) {
+            assertThat(PhotoRequest.fromMap(mapOf("compress" to compression.value)).compress).isEqualTo(compression)
+        }
+        assertThat(PhotoRequest(size = PhotoSize.MEDIUM, webhookUrl = "https://example.com/upload", sound = true).compress).isEqualTo(PhotoCompression.NONE)
+        assertThat(PhotoRequest.fromMap(emptyMap()).compress).isEqualTo(PhotoCompression.NONE)
+        for (invalid in listOf("heavy", "", "HIGH", 1, false, null)) {
+            assertThatThrownBy { PhotoRequest.fromMap(mapOf("compress" to invalid)) }
+                .isInstanceOf(IllegalArgumentException::class.java)
+            assertThatThrownBy { PhotoCaptureDefaults.fromMap(mapOf("compress" to invalid)) }
+                .isInstanceOf(IllegalArgumentException::class.java)
+        }
+        assertThat(PhotoCaptureDefaults.fromMap(emptyMap()).compress).isNull()
+        for (compression in PhotoCompression.values()) {
+            assertThat(PhotoCaptureDefaults.fromMap(mapOf("compress" to compression.value)).compress).isEqualTo(compression)
+        }
+        // Nullable non-compression fields still follow the existing omission convention.
+        assertThat(PhotoRequest.fromMap(mapOf("authToken" to null)).compress).isEqualTo(PhotoCompression.NONE)
+    }
+
+    @Test
+    fun `thumbnail is opt in and survives request routing copies`() {
+        val fields = mapOf("size" to "medium", "webhookUrl" to "https://example.com/upload")
+        assertThat(PhotoRequest.fromMap(fields).presendThumbnail).isFalse()
+        assertThat(PhotoRequest.fromMap(fields + ("presend_thumbnail" to false)).presendThumbnail).isFalse()
+        val request = PhotoRequest.fromMap(fields + ("presend_thumbnail" to true))
+        assertThat(request.copy(requestId = "routed").presendThumbnail).isTrue()
+        assertThat(request.transferMethod).isEqualTo("auto")
+    }
     @Test
     fun `constructor generates requestId when omitted`() {
         val request =