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

package/ios/Source/sgcs/MentraLive.swift

@@ -810,6 +810,7 @@ private struct FileTransferSession {
 }
 
 private struct BlePhotoTransfer {
+    var isThumbnail = false
     let bleImgId: String
     let requestId: String
     let webhookUrl: String
@@ -2059,6 +2060,7 @@ class MentraLive: NSObject, SGCManager {
             "I" + String(format: "%09d", Int(Date().timeIntervalSince1970 * 1000) % 100_000_000)
         json["bleImgId"] = bleImgId
         json["transferMethod"] = request.transferMethod
+        if request.presendThumbnail { json["presend_thumbnail"] = true }
 
         if let webhookUrl = request.webhookUrl, !webhookUrl.isEmpty {
             json["webhookUrl"] = webhookUrl
@@ -2085,7 +2087,7 @@ class MentraLive: NSObject, SGCManager {
         json["size"] = allowedSizes.contains(size) ? size : "medium"
         json["mode"] = request.mode.rawValue
 
-        json["compress"] = request.compress?.rawValue ?? "none"
+        json["compress"] = request.compress.rawValue
         json["save"] = request.save
         json["sound"] = request.sound
 
@@ -4003,6 +4005,20 @@ class MentraLive: NSObject, SGCManager {
         let bleImgId = json["bleImgId"] as? String ?? ""
         let requestId = json["requestId"] as? String ?? ""
         let compressionDurationMs = json["compressionDurationMs"] as? Int64 ?? 0
+        if json["thumbnail"] as? Bool == true, !bleImgId.isEmpty, !requestId.isEmpty {
+            guard blePhotoTransfers.values.contains(where: {
+                !$0.isThumbnail && $0.requestId == requestId && bleImgId == "T" + $0.bleImgId.dropFirst()
+            }) else {
+                Bridge.log("LIVE: Ignoring thumbnail for an unknown photo request")
+                return
+            }
+            // Preserve any packets already received when the ready message is repeated.
+            if blePhotoTransfers[bleImgId] == nil {
+                var transfer = BlePhotoTransfer(bleImgId: bleImgId, requestId: requestId, webhookUrl: "")
+                transfer.isThumbnail = true
+                blePhotoTransfers[bleImgId] = transfer
+            }
+        }
 
         Bridge.log(
             "LIVE: 📸 BLE photo ready notification: bleImgId=\(bleImgId), requestId=\(requestId)"
@@ -4480,6 +4496,17 @@ class MentraLive: NSObject, SGCManager {
     }
 
     private func processAndUploadBlePhoto(_ transfer: BlePhotoTransfer, imageData: Data) {
+        if transfer.isThumbnail {
+            Bridge.sendPhotoStatus([
+                "type": "photo_status",
+                "requestId": transfer.requestId,
+                "status": "thumbnail_received",
+                "timestamp": Int64(Date().timeIntervalSince1970 * 1000),
+                "thumbnailUrl": "data:image/jpeg;base64," + imageData.base64EncodedString(),
+                "fileSizeBytes": imageData.count,
+            ])
+            return
+        }
         Bridge.log("LIVE: Processing BLE photo for upload. RequestId: \(transfer.requestId)")
 
         BlePhotoUploadService.processAndUploadPhoto(
@@ -6888,6 +6915,10 @@ extension MentraLive {
         let aeExposureDivisor = DeviceStore.shared.get("bluetooth", "button_photo_ae_exposure_divisor") as? Int
         let isoCap = DeviceStore.shared.get("bluetooth", "button_photo_iso_cap") as? Int
         let compressStr = DeviceStore.shared.get("bluetooth", "button_photo_compress") as? String
+        if let compressStr, PhotoCompression(rawValue: compressStr) == nil {
+            Bridge.log("LIVE: Invalid stored photo compression: \(compressStr)")
+            return
+        }
         let sound = DeviceStore.shared.get("bluetooth", "button_photo_sound") as? Bool
 
         let settings = PhotoCaptureDefaults(
@@ -6900,7 +6931,7 @@ extension MentraLive {
             ispAnalogGain: ispAnalogGain,
             aeExposureDivisor: aeExposureDivisor,
             isoCap: isoCap,
-            compress: compressStr,
+            compress: compressStr.flatMap(PhotoCompression.init(rawValue:)),
             sound: sound,
             resetCaptureTuning: false
         )
@@ -6984,8 +7015,8 @@ extension MentraLive {
         if let isoCap = settings.isoCap, isoCap > 0 {
             json["isoCap"] = isoCap
         }
-        if let compress = settings.compress, !compress.isEmpty {
-            json["compress"] = compress
+        if let compress = settings.compress {
+            json["compress"] = compress.rawValue
         }
         if let sound = settings.sound {
             json["sound"] = sound

package/ios/Tests/PhotoCompressionTests.swift

@@ -0,0 +1,21 @@
+@testable import MentraBluetoothSDK
+import XCTest
+
+final class PhotoCompressionTests: XCTestCase {
+    func testCompressionIsPreservedAndDefaultsToNone() throws {
+        for raw in ["none", "low", "medium", "high"] {
+            XCTAssertEqual(try PhotoRequest.from(params: ["compress": raw]).compress.rawValue, raw)
+            XCTAssertEqual(try PhotoCaptureDefaults.from(params: ["compress": raw]).compress?.rawValue, raw)
+        }
+        XCTAssertEqual(PhotoRequest(size: .medium, sound: true).compress, .none)
+        XCTAssertEqual(try PhotoRequest.from(params: [:]).compress, .none)
+        XCTAssertNil(try PhotoCaptureDefaults.from(params: [:]).compress)
+    }
+
+    func testInvalidCompressionIsRejected() {
+        for invalid: Any in ["heavy", "", "HIGH", NSNull(), 1, false] {
+            XCTAssertThrowsError(try PhotoRequest.from(params: ["compress": invalid]))
+            XCTAssertThrowsError(try PhotoCaptureDefaults.from(params: ["compress": invalid]))
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/bluetooth-sdk",
-  "version": "3.2.0-dev.235",
+  "version": "3.2.0-dev.247",
   "description": "SDK for communicating with smart glasses",
   "main": "build/index.js",
   "react-native": "src/index.ts",
@@ -113,7 +113,9 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "dependencies": {},
+  "dependencies": {
+    "@mentra/cloud-protocol": "3.2.0-dev.247"
+  },
   "devDependencies": {
     "@types/node": "^25.9.3",
     "expo-module-scripts": "^55.0.2",

package/src/BluetoothSdk.types.ts

@@ -1,3 +1,6 @@
+import type {PhotoCompression} from "@mentra/cloud-protocol/photo-compression"
+export type {PhotoCompression} from "@mentra/cloud-protocol/photo-compression"
+
 // Bluetooth SDK Event Types
 export type GlassesNotReadyEvent = {
   type: "glasses_not_ready"
@@ -284,6 +287,7 @@ export type PhotoStatusState =
   | "uploaded"
   | "ready_for_transfer"
   | "transferring"
+  | "thumbnail_received"
   | "failed"
 
 export type PhotoResolvedConfig = {
@@ -294,7 +298,7 @@ export type PhotoResolvedConfig = {
   requestedSize?: PhotoSize | string
   source?: "sdk" | "button" | string
   transferMethod?: "webhook" | "ble" | "local" | string
-  compression?: PhotoCompression | string
+  compression?: PhotoCompression
   saveToGallery?: boolean
   exposureTimeNs?: number
   iso?: number
@@ -360,6 +364,9 @@ export type PhotoStatusEvent = {
   captureMetadata?: PhotoCaptureMetadata
   errorCode?: string
   errorMessage?: string
+  /** Present on thumbnail_received: a JPEG data URI, not the final photo. */
+  thumbnailUrl?: string
+  fileSizeBytes?: number
 }
 
 export type CameraStatusEvent = {
@@ -561,7 +568,6 @@ export type PhotoCaptureDefaults = {
   /** When true, clears stored NR/edge/ISP presets on the glasses before applying other fields. */
   resetCaptureTuning?: boolean
 }
-export type PhotoCompression = "none" | "medium" | "heavy"
 
 export type VideoRecordingDefaults = {
   width: number
@@ -653,6 +659,11 @@ export type MicPreference = "auto" | "phone" | "glasses" | "bluetooth"
 export type MicMode = "phone" | "glasses" | "bluetoothClassic" | "bluetooth"
 
 export type PhotoRequestParams = {
+  /**
+   * Send an oriented <=500px, quality-50 JPEG preview before the full photo. Default false.
+   * Enables a 110-second end-to-end native deadline (ordinary requests: 30 seconds).
+   */
+  presend_thumbnail?: boolean
   requestId?: string
   appId?: string
   size: PhotoSize
@@ -661,7 +672,7 @@ export type PhotoRequestParams = {
   transferMethod?: PhotoTransferMethod
   webhookUrl: string | null
   authToken: string | null
-  compress: PhotoCompression
+  compress?: PhotoCompression
   save?: boolean
   sound: boolean
   exposureTimeNs?: number | null
@@ -688,7 +699,7 @@ export type WarmUpCameraParams = {
   size: PhotoSize
   mode?: PhotoMode
   exposureTimeNs?: number | null
-  /** Ready-state hold; defaults to 15 seconds and is capped at 60 seconds by ASG. */
+  /** Ready-state hold; defaults to 15 seconds and is capped at 5 minutes by ASG. */
   durationMs?: number
   /** ZSL preview buffering for the warm-up session. */
   zsl?: boolean

package/src/_private/photoRequestPayload.ts

@@ -1,3 +1,4 @@
+import {parsePhotoCompression} from "@mentra/cloud-protocol/photo-compression"
 import type {PhotoRequestParams, PhotoSize, PhotoTransferMethod} from "../BluetoothSdk.types"
 
 const PHOTO_TRANSFER_METHODS = new Set<PhotoTransferMethod>(["auto", "direct", "ble"])
@@ -41,10 +42,13 @@ export function photoRequestParamsForNative(params: PhotoRequestParams): Record<
     mode: params.mode ?? "photo",
     transferMethod: photoTransferMethodForNative(params.transferMethod),
     webhookUrl: params.webhookUrl ?? "",
-    compress: params.compress,
+    compress: parsePhotoCompression(params.compress),
     sound: params.sound,
   }
   const requestId = nonBlankString(params.requestId)
+  if (params.presend_thumbnail === true) {
+    payload.presend_thumbnail = true
+  }
   if (requestId != null) {
     payload.requestId = requestId
   }

package/src/generated/changelogCatalog.ts

@@ -5,6 +5,10 @@ export const GENERATED_RELEASE_CHANGELOGS = Object.freeze(
     "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`."
   },
+  {
+    "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."
+  },
   {
     "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/src/generated/releaseMetadata.ts

@@ -12,9 +12,9 @@ export interface BluetoothSdkReleaseMetadata {
 export const BLUETOOTH_SDK_RELEASE_METADATA: Readonly<BluetoothSdkReleaseMetadata> = Object.freeze({
   "schemaVersion": 1,
   "familyBaseVersion": "3.2.0",
-  "releaseIdentity": "3.2.0-dev.235",
-  "releaseSetId": "mentra-3.2.0-dev.235",
-  "sourceCommit": "5f25e2687788b3d964e19d17fd6cd4139e3e677e",
-  "otaManifestUrl": "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.235.json",
-  "otaManifestSha256": "a9e9ebec66e2f638ab89f446d87925cdc2c85abf3091ed33e76f01986e658ca7"
+  "releaseIdentity": "3.2.0-dev.247",
+  "releaseSetId": "mentra-3.2.0-dev.247",
+  "sourceCommit": "2be1b25e83b0c8db5cef39294c93b0a3f9ec7aef",
+  "otaManifestUrl": "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.247.json",
+  "otaManifestSha256": "cba0e05a180f92e98e3bf47d0acdba2ae81cc79788da1393e80334fb5b26093b"
 })

package/src/index.ts

@@ -1,8 +1,10 @@
+import {parsePhotoCompression} from "@mentra/cloud-protocol/photo-compression"
 import PrivateBluetoothSdkModule from "./_private/BluetoothSdkModule"
 import type {
   BluetoothSdkEventListener,
   BluetoothSdkEventName,
   BluetoothSdkPublicModule,
+  PhotoCaptureDefaults,
   PublicBluetoothStatus,
   PublicGlassesStatus,
   VideoRecordingDefaults,
@@ -133,7 +135,10 @@ export const BluetoothSdk: BluetoothSdkPublicModule = Object.freeze({
    * `requestPhoto(...)` options (e.g. `mode: "text"` for text sensor size/crop, or explicit per-shot
    * fields). Still functional until removed in a future release.
    */
-  setPhotoCaptureDefaults: bindPublicMethod("setPhotoCaptureDefaults"),
+  setPhotoCaptureDefaults: (settings: PhotoCaptureDefaults) => {
+    if (settings.compress !== undefined) parsePhotoCompression(settings.compress)
+    return bindPublicMethod("setPhotoCaptureDefaults")(settings)
+  },
   setVideoRecordingDefaults: ({width, height, fps}: VideoRecordingDefaults) => {
     const method = (PrivateBluetoothSdkModule as unknown as Record<string, unknown>).setVideoRecordingDefaults
     if (typeof method !== "function") {