@mentra/bluetooth-sdk 0.1.11 → 0.1.13

package/ios/Source/OtaManifest.swift

@@ -0,0 +1,170 @@
+import Foundation
+
+enum OtaManifestDefaults {
+    private static let sdkOtaReleaseBaseUrl = "https://github.com/Mentra-Community/MentraOS/releases/download/bluetooth-sdk-ota"
+    // Keep prod as the legacy-device fallback: pre-override ASG builds ignore
+    // ota_start.ota_version_url and use their compiled MentraOS default.
+    static let prodOtaVersionUrl = "https://ota.mentraglass.com/prod_live_version.json"
+
+    static func defaultOtaVersionUrl() throws -> String {
+        guard let sdkVersion = BluetoothSdkDefaults.sdkVersion,
+              !sdkVersion.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+        else {
+            throw BluetoothError(
+                code: "missing_sdk_version",
+                message: "Cannot determine Bluetooth SDK version for the default OTA manifest URL."
+            )
+        }
+        return "\(sdkOtaReleaseBaseUrl)/bluetooth-sdk-\(sdkVersion)-version.json"
+    }
+}
+
+struct OtaManifestApp: Decodable {
+    let versionCode: Int?
+}
+
+struct MtkPatch: Decodable {
+    let startFirmware: String
+
+    enum CodingKeys: String, CodingKey {
+        case startFirmware = "start_firmware"
+    }
+}
+
+struct BesFirmware: Decodable {
+    let version: String?
+}
+
+struct OtaManifest: Decodable {
+    let apps: [String: OtaManifestApp]?
+    let mtkPatches: [MtkPatch]?
+    let besFirmware: BesFirmware?
+    let versionCode: Int?
+
+    enum CodingKeys: String, CodingKey {
+        case apps
+        case mtkPatches = "mtk_patches"
+        case besFirmware = "bes_firmware"
+        case versionCode
+    }
+}
+
+enum OtaManifestChecker {
+    private static let asgClientPackage = "com.mentra.asg_client"
+
+    static func normalizeHttpUrl(_ value: String) throws -> String {
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else {
+            throw BluetoothError(code: "invalid_ota_url", message: "OTA version URL must be a non-empty http(s) URL.")
+        }
+        guard let url = URL(string: trimmed),
+              let scheme = url.scheme?.lowercased(),
+              (scheme == "http" || scheme == "https"),
+              url.host?.isEmpty == false
+        else {
+            throw BluetoothError(code: "invalid_ota_url", message: "OTA version URL must be a valid http(s) URL.")
+        }
+        return url.absoluteString
+    }
+
+    static func fetch(_ otaVersionUrl: String) async throws -> OtaManifest {
+        guard let url = URL(string: otaVersionUrl) else {
+            throw BluetoothError(code: "invalid_ota_url", message: "OTA version URL must be a valid http(s) URL.")
+        }
+        let (data, response) = try await URLSession.shared.data(from: url)
+        guard let httpResponse = response as? HTTPURLResponse else {
+            throw BluetoothError(code: "ota_manifest_request_failed", message: "OTA manifest request failed.")
+        }
+        guard (200 ... 299).contains(httpResponse.statusCode) else {
+            throw BluetoothError(
+                code: "ota_manifest_request_failed",
+                message: "OTA manifest request failed with HTTP \(httpResponse.statusCode)."
+            )
+        }
+        return try JSONDecoder().decode(OtaManifest.self, from: data)
+    }
+
+    static func hasUpdate(
+        currentBuildNumber: String,
+        currentMtkVersion: String,
+        currentBesVersion: String,
+        manifest: OtaManifest
+    ) throws -> Bool {
+        try hasApkUpdate(currentBuildNumber: currentBuildNumber, manifest: manifest) ||
+            hasMtkUpdate(patches: manifest.mtkPatches, currentVersion: currentMtkVersion) ||
+            hasBesUpdate(besFirmware: manifest.besFirmware, currentVersion: currentBesVersion)
+    }
+
+    static func hasMtkPatches(_ manifest: OtaManifest) -> Bool {
+        !(manifest.mtkPatches?.isEmpty ?? true)
+    }
+
+    static func hasBesFirmware(_ manifest: OtaManifest) -> Bool {
+        manifest.besFirmware != nil
+    }
+
+    private static func latestAppInfo(_ manifest: OtaManifest) throws -> OtaManifestApp {
+        if let app = manifest.apps?[asgClientPackage], app.versionCode != nil {
+            return app
+        }
+        if let versionCode = manifest.versionCode {
+            return OtaManifestApp(versionCode: versionCode)
+        }
+        throw BluetoothError(code: "invalid_ota_manifest", message: "OTA manifest is missing ASG app versionCode.")
+    }
+
+    private static func hasApkUpdate(currentBuildNumber: String, manifest: OtaManifest) throws -> Bool {
+        guard let currentVersion = Int(currentBuildNumber) else {
+            throw BluetoothError(
+                code: "invalid_glasses_version",
+                message: "Cannot check OTA update because glasses build number is invalid."
+            )
+        }
+        guard let serverVersion = try latestAppInfo(manifest).versionCode else {
+            throw BluetoothError(code: "invalid_ota_manifest", message: "OTA manifest is missing ASG app versionCode.")
+        }
+        return serverVersion > currentVersion
+    }
+
+    private static func hasMtkUpdate(patches: [MtkPatch]?, currentVersion: String) throws -> Bool {
+        guard let patches, !patches.isEmpty else { return false }
+        guard !currentVersion.isEmpty else { return false }
+
+        return patches.contains { patch in
+            if patch.startFirmware == currentVersion {
+                return true
+            }
+            let serverDate = patch.startFirmware.contains("_")
+                ? String(patch.startFirmware.split(separator: "_").last ?? "")
+                : patch.startFirmware
+            return serverDate == currentVersion
+        }
+    }
+
+    private static func hasBesUpdate(besFirmware: BesFirmware?, currentVersion: String) throws -> Bool {
+        guard let besFirmware else { return false }
+        guard let serverVersion = besFirmware.version, !serverVersion.isEmpty else {
+            throw BluetoothError(code: "invalid_ota_manifest", message: "OTA manifest bes_firmware.version is missing.")
+        }
+        if currentVersion.isEmpty {
+            return true
+        }
+        return compareVersions(serverVersion, currentVersion) > 0
+    }
+
+    private static func compareVersions(_ version1: String, _ version2: String) -> Int {
+        if version1.contains("."), version2.contains(".") {
+            let parts1 = version1.split(separator: ".").map { Int($0) ?? 0 }
+            let parts2 = version2.split(separator: ".").map { Int($0) ?? 0 }
+            for index in 0 ..< max(parts1.count, parts2.count) {
+                let value1 = index < parts1.count ? parts1[index] : 0
+                let value2 = index < parts2.count ? parts2[index] : 0
+                if value1 != value2 {
+                    return value1 - value2
+                }
+            }
+            return 0
+        }
+        return version1.compare(version2).rawValue
+    }
+}

package/ios/Source/camera/CameraModels.swift

@@ -1,17 +1,44 @@
 import Foundation
 
 public enum PhotoSize: String {
-    case small
+    case low
     case medium
-    case large
-    case full
+    case high
+    case max
+
+    public static func normalizeLegacy(_ value: String?) -> String {
+        switch value {
+        case "small":
+            return PhotoSize.low.rawValue
+        case "large":
+            return PhotoSize.high.rawValue
+        case "full":
+            return PhotoSize.max.rawValue
+        default:
+            return value ?? PhotoSize.medium.rawValue
+        }
+    }
+
+    public init(normalizedRawValue value: String?) {
+        let normalized = PhotoSize.normalizeLegacy(value)
+        self = PhotoSize(rawValue: normalized) ?? .medium
+    }
 }
 
 public enum ButtonPhotoSize: String {
-    case small
+    case low
     case medium
-    case large
+    case high
     case max
+
+    public static func normalizeLegacy(_ value: String?) -> String {
+        PhotoSize.normalizeLegacy(value)
+    }
+
+    public init(normalizedRawValue value: String?) {
+        let normalized = ButtonPhotoSize.normalizeLegacy(value)
+        self = ButtonPhotoSize(rawValue: normalized) ?? .medium
+    }
 }
 
 public enum PhotoCompression: String {
@@ -21,10 +48,66 @@ public enum PhotoCompression: String {
 }
 
 public struct ButtonPhotoSettings {
-    public let size: ButtonPhotoSize
+    public let size: ButtonPhotoSize?
+    public let mfnr: Bool?
+    public let zsl: Bool?
+    public let noiseReduction: Bool?
+    public let edgeEnhancement: Bool?
+    public let ispDigitalGain: Int?
+    public let ispAnalogGain: String?
+    public let aeExposureDivisor: Int?
+    public let isoCap: Int?
+    public let compress: String?
+    public let sound: Bool?
+    public let resetCaptureTuning: Bool?
 
-    public init(size: ButtonPhotoSize) {
+    public init(
+        size: ButtonPhotoSize?,
+        mfnr: Bool? = nil,
+        zsl: Bool? = nil,
+        noiseReduction: Bool? = nil,
+        edgeEnhancement: Bool? = nil,
+        ispDigitalGain: Int? = nil,
+        ispAnalogGain: String? = nil,
+        aeExposureDivisor: Int? = nil,
+        isoCap: Int? = nil,
+        compress: String? = nil,
+        sound: Bool? = nil,
+        resetCaptureTuning: Bool? = nil
+    ) {
         self.size = size
+        self.mfnr = mfnr
+        self.zsl = zsl
+        self.noiseReduction = noiseReduction
+        self.edgeEnhancement = edgeEnhancement
+        self.ispDigitalGain = ispDigitalGain
+        self.ispAnalogGain = ispAnalogGain
+        self.aeExposureDivisor = aeExposureDivisor
+        self.isoCap = isoCap
+        self.compress = compress
+        self.sound = sound
+        self.resetCaptureTuning = resetCaptureTuning
+    }
+
+    static func from(params: [String: Any]) -> ButtonPhotoSettings {
+        let size = (params["size"] as? String).map { ButtonPhotoSize(normalizedRawValue: $0) }
+        let aeExposureDivisor =
+            optionalIntValue(params, "aeExposureDivisor").flatMap { $0 > 1 ? $0 : nil }
+        let isoCap = optionalIntValue(params, "isoCap").flatMap { $0 > 0 ? $0 : nil }
+        return ButtonPhotoSettings(
+            size: size,
+            mfnr: optionalBoolValue(params, "mfnr"),
+            zsl: optionalBoolValue(params, "zsl"),
+            noiseReduction: optionalBoolValue(params, "noiseReduction"),
+            edgeEnhancement: optionalBoolValue(params, "edgeEnhancement"),
+            ispDigitalGain: optionalIntValue(params, "ispDigitalGain"),
+            ispAnalogGain: optionalStringValue(params, "ispAnalogGain"),
+            aeExposureDivisor: aeExposureDivisor,
+            isoCap: isoCap,
+            compress: optionalStringValue(params, "compress"),
+            sound: optionalBoolValue(params, "sound"),
+            resetCaptureTuning: optionalBoolValue(params, "resetCaptureTuning")
+        )
     }
 }
 
@@ -152,6 +235,14 @@ public struct PhotoRequest {
     public let exposureTimeNs: Double?
     /// Sensor ISO for this capture only. Only used when exposureTimeNs enables manual exposure.
     public let iso: Int?
+    public let aeExposureDivisor: Int?
+    public let isoCap: Int?
+    public let noiseReduction: Bool?
+    public let edgeEnhancement: Bool?
+    public let mfnr: Bool?
+    public let zsl: Bool?
+    public let ispDigitalGain: Int?
+    public let ispAnalogGain: String?
 
     public init(
         requestId: String,
@@ -164,7 +255,15 @@ public struct PhotoRequest {
         save: Bool = false,
         sound: Bool,
         exposureTimeNs: Double? = nil,
-        iso: Int? = nil
+        iso: Int? = nil,
+        aeExposureDivisor: Int? = nil,
+        isoCap: Int? = nil,
+        noiseReduction: Bool? = nil,
+        edgeEnhancement: Bool? = nil,
+        mfnr: Bool? = nil,
+        zsl: Bool? = nil,
+        ispDigitalGain: Int? = nil,
+        ispAnalogGain: String? = nil
     ) {
         self.requestId = requestId
         self.appId = appId
@@ -177,6 +276,117 @@ public struct PhotoRequest {
         self.sound = sound
         self.exposureTimeNs = exposureTimeNs
         self.iso = iso
+        self.aeExposureDivisor = aeExposureDivisor
+        self.isoCap = isoCap
+        self.noiseReduction = noiseReduction
+        self.edgeEnhancement = edgeEnhancement
+        self.mfnr = mfnr
+        self.zsl = zsl
+        self.ispDigitalGain = ispDigitalGain
+        self.ispAnalogGain = ispAnalogGain
+    }
+
+    public static func from(params: [String: Any]) -> PhotoRequest {
+        let sizeRaw = params["size"] as? String ?? "medium"
+        let compressRaw = params["compress"] as? String ?? "none"
+        let exposureTimeNs: Double?
+        switch params["exposureTimeNs"] {
+        case let value as Double:
+            exposureTimeNs = value.isFinite && value > 0 ? value : nil
+        case let value as Int:
+            exposureTimeNs = value > 0 ? Double(value) : nil
+        case let value as NSNumber:
+            let d = value.doubleValue
+            exposureTimeNs = d.isFinite && d > 0 ? d : nil
+        default:
+            exposureTimeNs = nil
+        }
+        let iso: Int?
+        switch params["iso"] {
+        case let value as Int:
+            iso = value > 0 ? value : nil
+        case let value as Double:
+            iso = value.isFinite && value > 0 && value < Double(Int.max) ? Int(value) : nil
+        case let value as NSNumber:
+            let intValue = value.intValue
+            iso = intValue > 0 ? intValue : nil
+        default:
+            iso = nil
+        }
+        func optionalInt(_ key: String, min: Int = Int.min, filter: (Int) -> Bool = { _ in true }) -> Int? {
+            guard params.keys.contains(key) else { return nil }
+            switch params[key] {
+            case let value as Int:
+                return filter(value) ? value : nil
+            case let value as Double:
+                guard value.isFinite, value >= Double(min) else { return nil }
+                return filter(Int(value)) ? Int(value) : nil
+            case let value as NSNumber:
+                let intValue = value.intValue
+                return filter(intValue) ? intValue : nil
+            default:
+                return nil
+            }
+        }
+        func optionalBool(_ key: String) -> Bool? {
+            guard params.keys.contains(key) else { return nil }
+            return params[key] as? Bool
+        }
+
+        return PhotoRequest(
+            requestId: params["requestId"] as? String ?? "",
+            appId: params["appId"] 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,
+            iso: iso,
+            aeExposureDivisor: optionalInt("aeExposureDivisor", min: 2) { $0 > 1 },
+            isoCap: optionalInt("isoCap", min: 1) { $0 > 0 },
+            noiseReduction: optionalBool("noiseReduction"),
+            edgeEnhancement: optionalBool("edgeEnhancement"),
+            mfnr: optionalBool("mfnr"),
+            zsl: optionalBool("zsl"),
+            ispDigitalGain: optionalInt("ispDigitalGain"),
+            ispAnalogGain: params["ispAnalogGain"] as? String
+        )
+    }
+
+    func appendScanFields(to json: inout [String: Any]) {
+        if let aeExposureDivisor {
+            json["aeExposureDivisor"] = aeExposureDivisor
+        }
+        if let isoCap {
+            json["isoCap"] = isoCap
+        }
+        if let noiseReduction {
+            json["noiseReduction"] = noiseReduction
+        }
+        if let edgeEnhancement {
+            json["edgeEnhancement"] = edgeEnhancement
+        }
+        if let mfnr {
+            json["mfnr"] = mfnr
+        }
+        if let zsl {
+            json["zsl"] = zsl
+        }
+        if let ispDigitalGain {
+            json["ispDigitalGain"] = ispDigitalGain
+        }
+        if let ispAnalogGain {
+            json["ispAnalogGain"] = ispAnalogGain
+        }
+    }
+}
+
+private extension String {
+    var nilIfBlank: String? {
+        isEmpty ? nil : self
     }
 }
 
@@ -229,9 +439,12 @@ public struct VideoRecordingRequest {
     public let width: Int
     public let height: Int
     public let fps: Int
+    // Optional auto-stop timer in minutes; 0 = record until stopped/interrupted.
+    public let maxRecordingTimeMinutes: Int
 
     public init(
-        requestId: String, save: Bool, sound: Bool, width: Int = 0, height: Int = 0, fps: Int = 0
+        requestId: String, save: Bool, sound: Bool, width: Int = 0, height: Int = 0, fps: Int = 0,
+        maxRecordingTimeMinutes: Int = 0
     ) {
         self.requestId = requestId
         self.save = save
@@ -239,6 +452,7 @@ public struct VideoRecordingRequest {
         self.width = width
         self.height = height
         self.fps = fps
+        self.maxRecordingTimeMinutes = maxRecordingTimeMinutes
     }
 }
 
@@ -280,6 +494,50 @@ public struct VideoRecordingStatusEvent: CustomStringConvertible {
     }
 }
 
+public struct MediaUploadEvent: CustomStringConvertible {
+    public let values: [String: Any]
+
+    public init(values: [String: Any]) {
+        self.values = values
+    }
+
+    public var type: String {
+        stringValue(values, "type") ?? ""
+    }
+
+    public var requestId: String {
+        stringValue(values, "requestId") ?? ""
+    }
+
+    public var mediaUrl: String? {
+        stringValue(values, "mediaUrl")
+    }
+
+    public var errorMessage: String? {
+        stringValue(values, "errorMessage")
+    }
+
+    public var mediaType: Int? {
+        intValue(values["mediaType"])
+    }
+
+    public var timestamp: Int {
+        intValue(values["timestamp"]) ?? Int(Date().timeIntervalSince1970 * 1000)
+    }
+
+    public var isSuccess: Bool {
+        type == "media_success"
+    }
+
+    public var isVideo: Bool {
+        mediaType == 2
+    }
+
+    public var description: String {
+        "MediaUploadEvent(requestId: \(requestId), type: \(type), mediaType: \(mediaType ?? -1))"
+    }
+}
+
 public enum PhotoResponse: CustomStringConvertible, Equatable {
     public enum State: String {
         case success

package/ios/Source/controllers/ControllerManager.swift

@@ -18,10 +18,7 @@ protocol ControllerManager {
 
     // MARK: - Camera & Media
 
-    func requestPhoto(
-        _ requestId: String, appId: String, size: String?, webhookUrl: String?, authToken: String?,
-        compress: String?, flash: Bool, save: Bool, sound: Bool, exposureTimeNs: Double?, iso: Int?
-    )
+    func requestPhoto(_ request: PhotoRequest)
     func startStream(_ message: [String: Any])
     func stopStream()
     func sendStreamKeepAlive(_ message: [String: Any])
@@ -75,7 +72,7 @@ protocol ControllerManager {
     func sendWifiCredentials(_ ssid: String, _ password: String)
     func forgetWifiNetwork(_ ssid: String)
     func sendHotspotState(_ enabled: Bool)
-    func sendOtaStart()
+    func sendOtaStart(otaVersionUrl: String?)
     func sendOtaQueryStatus()
 
     // MARK: - User Context (for crash reporting)

package/ios/Source/controllers/R1.swift

@@ -504,10 +504,7 @@ class R1: NSObject, ControllerManager {
     }
 
     func sendJson(_: [String: Any], wakeUp _: Bool, requireAck _: Bool) {}
-    func requestPhoto(
-        _: String, appId _: String, size _: String?, webhookUrl _: String?, authToken _: String?,
-        compress _: String?, flash _: Bool, save _: Bool, sound _: Bool, exposureTimeNs _: Double?, iso _: Int?
-    ) {}
+    func requestPhoto(_: PhotoRequest) {}
     func startVideoRecording(requestId _: String, save _: Bool, flash _: Bool, sound _: Bool) {}
     func stopVideoRecording(requestId _: String) {}
     func startStream(_: [String: Any]) {}
@@ -543,7 +540,7 @@ class R1: NSObject, ControllerManager {
     func sendWifiCredentials(_: String, _: String) {}
     func forgetWifiNetwork(_: String) {}
     func sendHotspotState(_: Bool) {}
-    func sendOtaStart() {}
+    func sendOtaStart(otaVersionUrl: String?) {}
     func sendOtaQueryStatus() {}
     func sendUserEmailToGlasses(_: String) {}
     func queryGalleryStatus() {}

package/ios/Source/events/BluetoothEvents.swift

@@ -244,6 +244,7 @@ public enum BluetoothEvent: CustomStringConvertible {
     case photoResponse(PhotoResponseEvent)
     case photoStatus(PhotoStatusEvent)
     case videoRecordingStatus(VideoRecordingStatusEvent)
+    case mediaUpload(MediaUploadEvent)
     case rgbLedControlResponse(RgbLedControlResponseEvent)
     case streamStatus(StreamStatusEvent)
     case keepAliveAck(KeepAliveAckEvent)
@@ -277,6 +278,8 @@ public enum BluetoothEvent: CustomStringConvertible {
             event.description
         case let .videoRecordingStatus(event):
             event.description
+        case let .mediaUpload(event):
+            event.description
         case let .rgbLedControlResponse(event):
             event.description
         case let .streamStatus(event):

package/ios/Source/internal/BluetoothAvailability.swift

@@ -6,6 +6,7 @@ final class BluetoothAvailability: NSObject, CBCentralManagerDelegate {
 
     private var centralManager: CBCentralManager?
     private var state: CBManagerState = .unknown
+    private var listeners: [UUID: (CBManagerState) -> Void] = [:]
 
     override private init() {
         super.init()
@@ -19,6 +20,25 @@ final class BluetoothAvailability: NSObject, CBCentralManagerDelegate {
 
     func centralManagerDidUpdateState(_ central: CBCentralManager) {
         state = central.state
+        for listener in Array(listeners.values) {
+            listener(state)
+        }
+    }
+
+    @discardableResult
+    func addStateListener(_ listener: @escaping (CBManagerState) -> Void) -> UUID {
+        // `listeners` is unsynchronized; it is only safe because the central
+        // manager queue is `.main` and all callers are main-thread bound.
+        dispatchPrecondition(condition: .onQueue(.main))
+        let id = UUID()
+        listeners[id] = listener
+        listener(state)
+        return id
+    }
+
+    func removeStateListener(_ id: UUID) {
+        dispatchPrecondition(condition: .onQueue(.main))
+        listeners[id] = nil
     }
 
     func requirePoweredOn(operation: String) throws {