@mentra/bluetooth-sdk 0.1.13 → 0.1.16

package/ios/Source/camera/CameraModels.swift

@@ -1,5 +1,15 @@
 import Foundation
 
+func generatedCameraRequestId(_ prefix: String) -> String {
+    "\(prefix)-\(Int(Date().timeIntervalSince1970 * 1000))-\(UUID().uuidString.prefix(8))"
+}
+
+func nonBlankRequestId(_ requestId: String?) -> String? {
+    guard let requestId else { return nil }
+    let trimmed = requestId.trimmingCharacters(in: .whitespacesAndNewlines)
+    return trimmed.isEmpty ? nil : trimmed
+}
+
 public enum PhotoSize: String {
     case low
     case medium
@@ -47,8 +57,8 @@ public enum PhotoCompression: String {
     case heavy
 }
 
-public struct ButtonPhotoSettings {
-    public let size: ButtonPhotoSize?
+public struct PhotoCaptureDefaults {
+    public let size: PhotoSize?
     public let mfnr: Bool?
     public let zsl: Bool?
     public let noiseReduction: Bool?
@@ -62,7 +72,7 @@ public struct ButtonPhotoSettings {
     public let resetCaptureTuning: Bool?
 
     public init(
-        size: ButtonPhotoSize?,
+        size: PhotoSize? = nil,
         mfnr: Bool? = nil,
         zsl: Bool? = nil,
         noiseReduction: Bool? = nil,
@@ -89,12 +99,12 @@ public struct ButtonPhotoSettings {
         self.resetCaptureTuning = resetCaptureTuning
     }
 
-    static func from(params: [String: Any]) -> ButtonPhotoSettings {
-        let size = (params["size"] as? String).map { ButtonPhotoSize(normalizedRawValue: $0) }
+    static func from(params: [String: Any]) -> PhotoCaptureDefaults {
+        let size = (params["size"] as? String).map { PhotoSize(normalizedRawValue: $0) }
         let aeExposureDivisor =
             optionalIntValue(params, "aeExposureDivisor").flatMap { $0 > 1 ? $0 : nil }
         let isoCap = optionalIntValue(params, "isoCap").flatMap { $0 > 0 ? $0 : nil }
-        return ButtonPhotoSettings(
+        return PhotoCaptureDefaults(
             size: size,
             mfnr: optionalBoolValue(params, "mfnr"),
             zsl: optionalBoolValue(params, "zsl"),
@@ -111,7 +121,7 @@ public struct ButtonPhotoSettings {
     }
 }
 
-public struct ButtonVideoRecordingSettings {
+public struct VideoRecordingDefaults {
     public let width: Int
     public let height: Int
     public let fps: Int
@@ -200,13 +210,13 @@ public struct CameraFovResult: CustomStringConvertible {
 
     static func from(ack: SettingsAckEvent, fallback: CameraFov) throws -> CameraFovResult {
         if ack.status == "error" {
-            throw BluetoothError(
+            throw BluetoothSdkError(
                 code: ack.errorCode ?? "camera_fov_failed",
                 message: ack.errorMessage ?? "Camera FOV request failed."
             )
         }
         if !ack.hardwareApplied {
-            throw BluetoothError(
+            throw BluetoothSdkError(
                 code: "camera_fov_not_applied",
                 message: "Camera FOV was saved but not applied to hardware."
             )
@@ -223,12 +233,10 @@ public struct CameraFovResult: CustomStringConvertible {
 
 public struct PhotoRequest {
     public let requestId: String
-    public let appId: String
     public let size: PhotoSize
     public let webhookUrl: String?
     public let authToken: String?
     public let compress: PhotoCompression?
-    public let flash: Bool
     public let save: Bool
     public let sound: Bool
     /// Sensor exposure time for this capture only (ns), or nil for auto exposure
@@ -245,13 +253,11 @@ public struct PhotoRequest {
     public let ispAnalogGain: String?
 
     public init(
-        requestId: String,
-        appId: String,
+        requestId: String? = nil,
         size: PhotoSize,
         webhookUrl: String? = nil,
         authToken: String? = nil,
         compress: PhotoCompression? = nil,
-        flash: Bool = true,
         save: Bool = false,
         sound: Bool,
         exposureTimeNs: Double? = nil,
@@ -265,13 +271,11 @@ public struct PhotoRequest {
         ispDigitalGain: Int? = nil,
         ispAnalogGain: String? = nil
     ) {
-        self.requestId = requestId
-        self.appId = appId
+        self.requestId = nonBlankRequestId(requestId) ?? generatedCameraRequestId("photo")
         self.size = size
         self.webhookUrl = webhookUrl
         self.authToken = authToken
         self.compress = compress
-        self.flash = flash
         self.save = save
         self.sound = sound
         self.exposureTimeNs = exposureTimeNs
@@ -334,13 +338,11 @@ public struct PhotoRequest {
         }
 
         return PhotoRequest(
-            requestId: params["requestId"] as? String ?? "",
-            appId: params["appId"] as? String ?? "",
+            requestId: params["requestId"] as? String,
             size: PhotoSize(normalizedRawValue: sizeRaw),
             webhookUrl: params["webhookUrl"] as? String,
             authToken: (params["authToken"] as? String)?.nilIfBlank,
             compress: PhotoCompression(rawValue: compressRaw),
-            flash: params["flash"] as? Bool ?? true,
             save: (params["save"] as? Bool) ?? (params["saveToGallery"] as? Bool) ?? false,
             sound: params["sound"] as? Bool ?? true,
             exposureTimeNs: exposureTimeNs,
@@ -382,6 +384,28 @@ public struct PhotoRequest {
             json["ispAnalogGain"] = ispAnalogGain
         }
     }
+
+    func withRequestId(_ requestId: String) -> PhotoRequest {
+        PhotoRequest(
+            requestId: requestId,
+            size: size,
+            webhookUrl: webhookUrl,
+            authToken: authToken,
+            compress: compress,
+            save: save,
+            sound: sound,
+            exposureTimeNs: exposureTimeNs,
+            iso: iso,
+            aeExposureDivisor: aeExposureDivisor,
+            isoCap: isoCap,
+            noiseReduction: noiseReduction,
+            edgeEnhancement: edgeEnhancement,
+            mfnr: mfnr,
+            zsl: zsl,
+            ispDigitalGain: ispDigitalGain,
+            ispAnalogGain: ispAnalogGain
+        )
+    }
 }
 
 private extension String {
@@ -726,6 +750,44 @@ public struct PhotoStatusEvent: CustomStringConvertible {
     }
 }
 
+public struct CameraStatusEvent: CustomStringConvertible {
+    public let values: [String: Any]
+
+    public init(values: [String: Any]) {
+        var values = values
+        values["type"] = "camera_status"
+        self.values = values
+    }
+
+    public var requestId: String {
+        stringValue(values, "requestId") ?? ""
+    }
+
+    public var state: String {
+        stringValue(values, "state") ?? ""
+    }
+
+    public var timestamp: Int64 {
+        if let value = values["timestamp"] as? Int64 { return value }
+        if let value = values["timestamp"] as? Int { return Int64(value) }
+        if let value = values["timestamp"] as? Double { return Int64(value) }
+        if let value = values["timestamp"] as? NSNumber { return value.int64Value }
+        return Int64(Date().timeIntervalSince1970 * 1000)
+    }
+
+    public var errorCode: String? {
+        stringValue(values, "errorCode")
+    }
+
+    public var errorMessage: String? {
+        stringValue(values, "errorMessage")
+    }
+
+    public var description: String {
+        "CameraStatusEvent(requestId: \(requestId), state: \(state))"
+    }
+}
+
 public struct GalleryStatusEvent: CustomStringConvertible {
     public let values: [String: Any]
 

package/ios/Source/controllers/ControllerManager.swift

@@ -22,7 +22,7 @@ protocol ControllerManager {
     func startStream(_ message: [String: Any])
     func stopStream()
     func sendStreamKeepAlive(_ message: [String: Any])
-    func startVideoRecording(requestId: String, save: Bool, flash: Bool, sound: Bool)
+    func startVideoRecording(requestId: String, save: Bool, sound: Bool)
     func stopVideoRecording(requestId: String)
 
     // MARK: - Button Settings
@@ -30,7 +30,6 @@ protocol ControllerManager {
     func sendButtonPhotoSettings()
     func sendButtonVideoRecordingSettings()
     func sendButtonMaxRecordingTime()
-    func sendButtonCameraLedSetting()
 
     // MARK: - Display Control
 

package/ios/Source/controllers/R1.swift

@@ -505,7 +505,7 @@ class R1: NSObject, ControllerManager {
 
     func sendJson(_: [String: Any], wakeUp _: Bool, requireAck _: Bool) {}
     func requestPhoto(_: PhotoRequest) {}
-    func startVideoRecording(requestId _: String, save _: Bool, flash _: Bool, sound _: Bool) {}
+    func startVideoRecording(requestId _: String, save _: Bool, sound _: Bool) {}
     func stopVideoRecording(requestId _: String) {}
     func startStream(_: [String: Any]) {}
     func stopStream() {}
@@ -513,7 +513,6 @@ class R1: NSObject, ControllerManager {
     func sendButtonPhotoSettings() {}
     func sendButtonVideoRecordingSettings() {}
     func sendButtonMaxRecordingTime() {}
-    func sendButtonCameraLedSetting() {}
     func setBrightness(_: Int, autoMode _: Bool) {}
     func clearDisplay() {}
     func sendTextWall(_: String) {}

package/ios/Source/errors/{BluetoothError.swift → BluetoothSdkError.swift}

@@ -1,6 +1,6 @@
 import Foundation
 
-public struct BluetoothError: Error, LocalizedError, CustomStringConvertible {
+public struct BluetoothSdkError: Error, LocalizedError, CustomStringConvertible {
     public let code: String
     public let message: String
 

package/ios/Source/events/BluetoothEvents.swift

@@ -73,28 +73,6 @@ public struct SpeakingStatusEvent: CustomStringConvertible {
     }
 }
 
-public struct OtaUpdateAvailableEvent: CustomStringConvertible {
-    public let versionCode: Int?
-    public let versionName: String?
-    public let updates: [String]
-    public let totalSize: Int?
-    public let cacheReady: Bool?
-    public let values: [String: Any]
-
-    public init(values: [String: Any]) {
-        versionCode = intValue(values["version_code"])
-        versionName = stringValue(values, "version_name")
-        updates = values["updates"] as? [String] ?? []
-        totalSize = intValue(values["total_size"])
-        cacheReady = boolValue(values, "cache_ready")
-        self.values = values
-    }
-
-    public var description: String {
-        "OtaUpdateAvailableEvent(versionName: \(versionName ?? "unknown"), updates: \(updates.joined(separator: ",")))"
-    }
-}
-
 public struct OtaStartAckEvent: CustomStringConvertible {
     public let timestamp: Int?
     public let values: [String: Any]
@@ -243,12 +221,12 @@ public enum BluetoothEvent: CustomStringConvertible {
     case hotspotError(HotspotErrorEvent)
     case photoResponse(PhotoResponseEvent)
     case photoStatus(PhotoStatusEvent)
+    case cameraStatus(CameraStatusEvent)
     case videoRecordingStatus(VideoRecordingStatusEvent)
     case mediaUpload(MediaUploadEvent)
     case rgbLedControlResponse(RgbLedControlResponseEvent)
     case streamStatus(StreamStatusEvent)
     case keepAliveAck(KeepAliveAckEvent)
-    case otaUpdateAvailable(OtaUpdateAvailableEvent)
     case otaStartAck(OtaStartAckEvent)
     case otaStatus(OtaStatusEvent)
     case settingsAck(SettingsAckEvent)
@@ -276,6 +254,8 @@ public enum BluetoothEvent: CustomStringConvertible {
             event.description
         case let .photoStatus(event):
             event.description
+        case let .cameraStatus(event):
+            event.description
         case let .videoRecordingStatus(event):
             event.description
         case let .mediaUpload(event):
@@ -286,8 +266,6 @@ public enum BluetoothEvent: CustomStringConvertible {
             event.description
         case let .keepAliveAck(event):
             event.description
-        case let .otaUpdateAvailable(event):
-            event.description
         case let .otaStartAck(event):
             event.description
         case let .otaStatus(event):
@@ -317,7 +295,7 @@ public protocol MentraBluetoothSDKDelegate: AnyObject {
     func mentraBluetoothSDK(_ sdk: MentraBluetoothSDK, didReceiveMicLc3 event: MicLc3Event)
     func mentraBluetoothSDK(_ sdk: MentraBluetoothSDK, didChangeDefaultDevice device: Device?)
     func mentraBluetoothSDK(_ sdk: MentraBluetoothSDK, didLog message: String)
-    func mentraBluetoothSDK(_ sdk: MentraBluetoothSDK, didFail error: BluetoothError)
+    func mentraBluetoothSDK(_ sdk: MentraBluetoothSDK, didFail error: BluetoothSdkError)
 }
 
 @MainActor
@@ -333,5 +311,5 @@ public extension MentraBluetoothSDKDelegate {
     func mentraBluetoothSDK(_: MentraBluetoothSDK, didReceiveMicLc3 _: MicLc3Event) {}
     func mentraBluetoothSDK(_: MentraBluetoothSDK, didChangeDefaultDevice _: Device?) {}
     func mentraBluetoothSDK(_: MentraBluetoothSDK, didLog _: String) {}
-    func mentraBluetoothSDK(_: MentraBluetoothSDK, didFail _: BluetoothError) {}
+    func mentraBluetoothSDK(_: MentraBluetoothSDK, didFail _: BluetoothSdkError) {}
 }

package/ios/Source/internal/BluetoothAvailability.swift

@@ -49,27 +49,27 @@ final class BluetoothAvailability: NSObject, CBCentralManagerDelegate {
         case .poweredOn:
             return
         case .poweredOff:
-            throw BluetoothError(
+            throw BluetoothSdkError(
                 code: "bluetooth_powered_off",
                 message: "Turn on phone Bluetooth to \(operation)."
             )
         case .unauthorized:
-            throw BluetoothError(
+            throw BluetoothSdkError(
                 code: "bluetooth_unauthorized",
                 message: "Allow Bluetooth access to \(operation)."
             )
         case .unsupported:
-            throw BluetoothError(
+            throw BluetoothSdkError(
                 code: "bluetooth_unsupported",
                 message: "This phone does not support Bluetooth."
             )
         case .resetting, .unknown:
-            throw BluetoothError(
+            throw BluetoothSdkError(
                 code: "bluetooth_not_ready",
                 message: "Bluetooth is not ready yet. Try again."
             )
         @unknown default:
-            throw BluetoothError(
+            throw BluetoothSdkError(
                 code: "bluetooth_unavailable",
                 message: "Bluetooth is unavailable. Try again."
             )

package/ios/Source/sgcs/Frame.swift

@@ -75,8 +75,6 @@
 
 //     func sendButtonMaxRecordingTime(_: Int) {}
 
-//     func sendButtonCameraLedSetting() {}
-
 func exit() {}
 
 func sendRgbLedControl(requestId: String, packageName _: String?, action _: String, color _: String?, onDurationMs _: Int, offDurationMs _: Int, count _: Int) {

package/ios/Source/sgcs/G1.swift

@@ -284,7 +284,7 @@ class G1: NSObject, SGCManager {
 
     func sendStreamKeepAlive(_: [String: Any]) {}
 
-    func startVideoRecording(requestId _: String, save _: Bool, flash _: Bool, sound _: Bool) {}
+    func startVideoRecording(requestId _: String, save _: Bool, sound _: Bool) {}
 
     func stopVideoRecording(requestId _: String) {}
 
@@ -294,8 +294,6 @@ class G1: NSObject, SGCManager {
 
     func sendButtonMaxRecordingTime() {}
 
-    func sendButtonCameraLedSetting() {}
-
     func sendCameraFovSetting() {}
 
     func showDashboard() {}
@@ -787,7 +785,52 @@ class G1: NSObject, SGCManager {
         await sendTextWall(text)
     }
 
+    // G1-specific display throttle (300ms, last-wins). G1 firmware can't absorb rapid text-wall
+    // updates; coalesce to the latest within a 300ms window. This used to live in the cloud
+    // DisplayManager (which fronted G1 before captions moved on-device); it belongs in the G1 SGC
+    // because it's a G1 hardware quirk — G2 deliberately does NOT throttle (it must show every
+    // caption). The trailing flush always sends the most recent text, so the final caption is never
+    // dropped — only intermediate frames within a window are coalesced.
+    private var g1TextThrottlePending: String?
+    private var g1TextThrottleLastSent: Date = .distantPast
+    private var g1TextThrottleScheduled = false
+    private let g1TextThrottleWindow: TimeInterval = 0.3
+
+    /// Drop any pending throttled text-wall flush so it can't later overwrite a newer, non-text
+    /// display write (a clear, double-text-wall, or bitmap). The scheduled flush no-ops when
+    /// `g1TextThrottlePending` is nil. Called from every G1 display path that bypasses the throttle.
+    private func cancelPendingThrottledText() {
+        g1TextThrottlePending = nil
+    }
+
     func sendTextWall(_ text: String) async {
+        let now = Date()
+        let sinceLast = now.timeIntervalSince(g1TextThrottleLastSent)
+        if sinceLast >= g1TextThrottleWindow {
+            // Past the window — send now.
+            g1TextThrottleLastSent = now
+            g1TextThrottlePending = nil
+            await flushTextWall(text)
+        } else {
+            // Inside the window — keep only the latest and schedule one trailing flush.
+            g1TextThrottlePending = text
+            if !g1TextThrottleScheduled {
+                g1TextThrottleScheduled = true
+                let wait = g1TextThrottleWindow - sinceLast
+                Task { @MainActor [weak self] in
+                    try? await Task.sleep(nanoseconds: UInt64(wait * 1_000_000_000))
+                    guard let self = self else { return }
+                    self.g1TextThrottleScheduled = false
+                    guard let pending = self.g1TextThrottlePending else { return }
+                    self.g1TextThrottlePending = nil
+                    self.g1TextThrottleLastSent = Date()
+                    await self.flushTextWall(pending)
+                }
+            }
+        }
+    }
+
+    private func flushTextWall(_ text: String) async {
         let chunks = textHelper.createTextWallChunks(text)
         queueChunks(chunks, sleepAfterMs: 10)
     }
@@ -801,6 +844,7 @@ class G1: NSObject, SGCManager {
     }
 
     func sendDoubleTextWall(_ top: String, _ bottom: String) async {
+        cancelPendingThrottledText() // a newer layout supersedes any pending caption text
         let chunks = textHelper.createDoubleTextWallChunks(textTop: top, textBottom: bottom)
         queueChunks(chunks, sleepAfterMs: 10)
 
@@ -1873,6 +1917,7 @@ extension G1 {
     // MARK: - Enhanced BMP Display Methods
 
     func displayBitmap(base64ImageData: String, x _: Int32? = nil, y _: Int32? = nil, width _: Int32? = nil, height _: Int32? = nil) async -> Bool {
+        cancelPendingThrottledText() // a bitmap supersedes any pending caption text
         guard let bmpData = Data(base64Encoded: base64ImageData) else {
             Bridge.log("G1: Failed to decode base64 image data")
             return false
@@ -1887,7 +1932,10 @@ extension G1 {
 
     func clearDisplay() {
         Bridge.log("G1: clearDisplay() - Using space")
-        Task { await sendTextWall(" ") }
+        // Bypass the throttle (a clear must always land) and drop any pending caption so it can't
+        // overwrite the clear after the fact.
+        cancelPendingThrottledText()
+        Task { await flushTextWall(" ") }
     }
 
     /// Create a simple test BMP pattern in hex format