@mentra/bluetooth-sdk 0.1.21-beta.0 → 0.1.21-beta.2

package/ios/Source/DeviceStore.swift

@@ -88,12 +88,13 @@ class DeviceStore {
         store.set("bluetooth", "contextual_dashboard", true)
         store.set("bluetooth", "gallery_mode", true)
         store.set("bluetooth", "voice_activity_detection_enabled", BluetoothSdkDefaults.voiceActivityDetectionEnabled)
+        store.set("bluetooth", "loudness_gate_enabled", BluetoothSdkDefaults.loudnessGateEnabled)
         // Mentra Nex feature flag (off by default; toggled from Nex Developer Settings):
         store.set("bluetooth", "nex_chinese_captions", false)
         store.set("bluetooth", "screen_disabled", false)
         store.set("bluetooth", "button_photo_size", "max")
         store.set("bluetooth", "button_max_recording_time", 10)
-        store.set("bluetooth", "camera_fov", ["fov": 102, "roi_position": 0])
+        store.set("bluetooth", "camera_fov", ["fov": 118, "roi_position": 0])
         store.set("bluetooth", "button_video_width", 1280)
         store.set("bluetooth", "button_video_height", 720)
         store.set("bluetooth", "button_video_fps", 30)
@@ -245,6 +246,9 @@ class DeviceStore {
         case ("bluetooth", "voice_activity_detection_enabled"):
             DeviceManager.shared.sgc?.sendVoiceActivityDetectionSetting()
 
+        case ("bluetooth", "loudness_gate_enabled"):
+            DeviceManager.shared.sgc?.sendLoudnessGateSetting()
+
         case ("bluetooth", "screen_disabled"):
             if let disabled = value as? Bool {
                 if disabled {

package/ios/Source/MentraBluetoothSDK.swift

@@ -190,7 +190,7 @@ public final class MentraBluetoothSDK {
     private var shouldRestoreControllerOnBluetoothRestore = false
     private var bridgeEventSinkId: String?
     private var storeListenerId: String?
-    private let defaultDeviceKeys: Set<String> = ["default_wearable", "device_name", "device_address"]
+    private let defaultDeviceKeys: Set<String> = ["default_wearable", "device_name", "device_address", "project_name"]
     private let videoUploadStopTimeoutMs = 10 * 60 * 1000
     private var suppressDefaultDeviceEvents = false
     private var defaultDeviceApplyGeneration = 0
@@ -308,6 +308,7 @@ public final class MentraBluetoothSDK {
         DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "default_wearable", device.model.deviceType)
         DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "device_name", device.name)
         DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "device_address", device.identifier ?? "")
+        DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "project_name", device.projectName ?? "")
         finishDefaultDeviceApply(generation: generation)
     }
 
@@ -318,6 +319,7 @@ public final class MentraBluetoothSDK {
         DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "default_wearable", "")
         DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "device_name", "")
         DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "device_address", "")
+        DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "project_name", "")
         finishDefaultDeviceApply(generation: generation)
     }
 
@@ -534,7 +536,11 @@ public final class MentraBluetoothSDK {
         DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "voice_activity_detection_enabled", enabled)
     }
 
-    @available(*, deprecated, message: "Sticky action-button photo presets are deprecated. Prefer per-request requestPhoto(...) options (e.g. mode .text for AE ÷3, or explicit per-shot fields). This method still works but will be removed in a future release.")
+    public func setLoudnessGateEnabled(_ enabled: Bool) async throws {
+        DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "loudness_gate_enabled", enabled)
+    }
+
+    @available(*, deprecated, message: "Sticky action-button photo presets are deprecated. Prefer per-request requestPhoto(...) options (e.g. mode .text for text sensor size/crop, or explicit per-shot fields). This method still works but will be removed in a future release.")
     public func setPhotoCaptureDefaults(_ settings: PhotoCaptureDefaults) async throws -> SettingsAckEvent {
         try await performSettingsCommand(
             setting: "button_photo",
@@ -543,7 +549,7 @@ public final class MentraBluetoothSDK {
                     // Mirror Android: clear all cached scan-tuning keys so reconnect sync
                     // does not replay stale values after a reset.
                     let cat = ObservableStore.bluetoothCategory
-                    for key in ["button_photo_mfnr", "button_photo_zsl", "button_photo_noise_reduction",
+                    for key in ["button_photo_zsl_mfnr", "button_photo_mfnr", "button_photo_zsl", "button_photo_noise_reduction",
                                 "button_photo_edge_enhancement", "button_photo_isp_digital_gain",
                                 "button_photo_isp_analog_gain", "button_photo_ae_exposure_divisor",
                                 "button_photo_iso_cap", "button_photo_compress", "button_photo_sound"] {
@@ -912,7 +918,9 @@ public final class MentraBluetoothSDK {
         size: PhotoSize,
         mode: PhotoMode = .photo,
         exposureTimeNs: Double?,
-        durationMs: Int
+        durationMs: Int,
+        zsl: Bool? = nil,
+        mfnr: Bool? = nil
     ) async throws -> CameraStatusEvent {
         let effectiveRequestId = nonBlankRequestId(requestId) ?? generatedCameraRequestId("warm")
         let pending = PendingResponse<CameraStatusEvent>(operation: "camera warm up \(effectiveRequestId)")
@@ -924,7 +932,9 @@ public final class MentraBluetoothSDK {
                 size: size,
                 mode: mode,
                 exposureTimeNs: exposureTimeNs,
-                durationMs: durationMs
+                durationMs: durationMs,
+                zsl: zsl,
+                mfnr: mfnr
             )
             let event = try await pending.wait()
             pendingCameraStatusRequests.removeValue(forKey: effectiveRequestId)
@@ -1261,6 +1271,20 @@ public final class MentraBluetoothSDK {
 
     func sendOtaQueryStatus() async throws -> OtaQueryResult { try await queryOtaStatus() }
 
+    func startAr99OtaFromFile(_ path: String) throws -> Bool {
+        try requireGlassesConnected(operation: "start AR99 OTA")
+        return try DeviceManager.shared.startAr99OtaFromFile(path)
+    }
+
+    func cancelAr99Ota() {
+        DeviceManager.shared.cancelAr99Ota()
+    }
+
+    func sendAr99FactoryReset() throws {
+        try requireGlassesConnected(operation: "factory reset AR99")
+        try DeviceManager.shared.sendAr99FactoryReset()
+    }
+
     private func getFreshGlassesStatus() async -> GlassesStatus {
         let status = glassesStatus
         if !status.connected || !status.buildNumber.isEmpty {
@@ -1967,14 +1991,15 @@ public final class MentraBluetoothSDK {
         guard let model = core["default_wearable"] as? String, !model.isEmpty else { return nil }
         guard let name = core["device_name"] as? String, !name.isEmpty else { return nil }
         let identifier = (core["device_address"] as? String).flatMap { $0.isEmpty ? nil : $0 }
+        let projectName = (core["project_name"] as? String).flatMap { $0.isEmpty ? nil : $0 }
         return Device(
             model: DeviceModel.fromDeviceType(model),
             name: name,
-            identifier: identifier
+            identifier: identifier,
+            projectName: projectName
         )
     }
-
-    private func dispatchDiscoveredDevices(_ rawSearchResults: Any?) {
+private func dispatchDiscoveredDevices(_ rawSearchResults: Any?) {
         guard let results = rawSearchResults as? [[String: Any]] else { return }
         for result in results {
             guard let name = result["name"] as? String else { continue }
@@ -2146,3 +2171,7 @@ public final class MentraBluetoothSDK {
         }
     }
 }
+
+
+
+

package/ios/Source/OtaManifest.swift

@@ -88,9 +88,18 @@ enum OtaManifestChecker {
         currentBuildNumber: String,
         currentMtkVersion: String,
         currentBesVersion: String,
-        manifest: OtaManifest
+        manifest: OtaManifest,
+        // Downgrade floor: a non-positive value (the default) disables downgrades entirely,
+        // matching ASG's fail-closed DowngradeGate and the engine. OEM SDK consumers that do not
+        // set a floor get upgrade-only behavior and are never told a downgrade is available that
+        // the glasses would refuse.
+        downgradeFloorVersionCode: Int = 0
     ) throws -> Bool {
-        try hasApkUpdate(currentBuildNumber: currentBuildNumber, manifest: manifest) ||
+        try hasApkUpdate(
+            currentBuildNumber: currentBuildNumber,
+            manifest: manifest,
+            downgradeFloorVersionCode: downgradeFloorVersionCode
+        ) ||
             hasMtkUpdate(patches: manifest.mtkPatches, currentVersion: currentMtkVersion) ||
             hasBesUpdate(besFirmware: manifest.besFirmware, currentVersion: currentBesVersion)
     }
@@ -113,7 +122,11 @@ enum OtaManifestChecker {
         throw BluetoothSdkError(code: "invalid_ota_manifest", message: "OTA manifest is missing ASG app versionCode.")
     }
 
-    private static func hasApkUpdate(currentBuildNumber: String, manifest: OtaManifest) throws -> Bool {
+    private static func hasApkUpdate(
+        currentBuildNumber: String,
+        manifest: OtaManifest,
+        downgradeFloorVersionCode: Int
+    ) throws -> Bool {
         guard let currentVersion = Int(currentBuildNumber) else {
             throw BluetoothSdkError(
                 code: "invalid_glasses_version",
@@ -123,7 +136,37 @@ enum OtaManifestChecker {
         guard let serverVersion = try latestAppInfo(manifest).versionCode else {
             throw BluetoothSdkError(code: "invalid_ota_manifest", message: "OTA manifest is missing ASG app versionCode.")
         }
-        return serverVersion > currentVersion
+        // Only apps-shaped manifests are exact pins. A legacy top-level manifest (versionCode at
+        // the root, no apps entry) is NOT a pin and stays strictly upgrade-only, matching the
+        // engine TS checker and Kotlin.
+        let isExactPin = manifest.apps?[asgClientPackage]?.versionCode != nil
+        if !isExactPin {
+            return serverVersion > currentVersion
+        }
+        // Exact pin: any mismatch is an update in either direction (downgrades take the
+        // uninstall-then-reinstall detour on the glasses). A non-positive pin is only legitimate
+        // in the frozen legacy rescue manifests that pre-39 glasses are checked against; for
+        // modern glasses it means the manifest cannot verify anything, and that must surface as
+        // an error — never as "no update". Mirrors the Kotlin OtaManifestChecker.
+        if serverVersion <= 0 {
+            if currentVersion >= 39 {
+                throw BluetoothSdkError(
+                    code: "invalid_ota_manifest",
+                    message: "OTA manifest ASG pin is missing or zero; cannot verify update state."
+                )
+            }
+            return false
+        }
+        if serverVersion > currentVersion {
+            return true
+        }
+        // Exact match: already on the pin, no update.
+        if serverVersion == currentVersion {
+            return false
+        }
+        // Downgrade: only actionable at/above the enabled floor; a non-positive floor disables
+        // downgrades (fail closed, matching ASG and the engine).
+        return downgradeFloorVersionCode > 0 && serverVersion >= downgradeFloorVersionCode
     }
 
     private static func hasMtkUpdate(patches: [MtkPatch]?, currentVersion: String) throws -> Bool {

package/ios/Source/camera/CameraModels.swift

@@ -169,15 +169,16 @@ public enum CameraRoiPosition: Int {
 public struct CameraFov {
     public static let minFov = 62
     public static let maxFov = 118
-    public static let defaultFov = 102
+    public static let defaultFov = 118
     public static let narrowFov = 82
+    public static let standardFov = 102
     public static let defaultRoiPosition = CameraRoiPosition.center
     public static let narrow = CameraFov(
         fov: CameraFov.narrowFov,
         roiPosition: CameraFov.defaultRoiPosition
     )
     public static let standard = CameraFov(
-        fov: CameraFov.defaultFov,
+        fov: CameraFov.standardFov,
         roiPosition: CameraFov.defaultRoiPosition
     )
     public static let wide = CameraFov(
@@ -302,12 +303,26 @@ public struct PhotoRequest {
         self.ispDigitalGain = ispDigitalGain
         self.ispAnalogGain = ispAnalogGain
         self.mode = mode
-        self.transferMethod = transferMethod == "ble" ? "ble" : "auto"
+        self.transferMethod = transferMethod
     }
 
-    public static func from(params: [String: Any]) -> PhotoRequest {
+    public static func from(params: [String: Any]) throws -> PhotoRequest {
         let sizeRaw = params["size"] as? String ?? "medium"
         let compressRaw = params["compress"] as? String ?? "none"
+        let transferMethod: String
+        if let rawValue = params["transferMethod"] {
+            guard let rawString = rawValue as? String,
+                  rawString == "auto" || rawString == "direct" || rawString == "ble"
+            else {
+                throw BluetoothSdkError(
+                    code: "invalid_photo_transfer_method",
+                    message: "Invalid transferMethod \(String(describing: rawValue)). Expected auto, direct, or ble."
+                )
+            }
+            transferMethod = rawString
+        } else {
+            transferMethod = "auto"
+        }
         let exposureTimeNs: Double?
         switch params["exposureTimeNs"] {
         case let value as Double:
@@ -371,7 +386,7 @@ public struct PhotoRequest {
             ispDigitalGain: optionalInt("ispDigitalGain"),
             ispAnalogGain: params["ispAnalogGain"] as? String,
             mode: PhotoMode(normalizedRawValue: params["mode"] as? String),
-            transferMethod: params["transferMethod"] as? String ?? "auto"
+            transferMethod: transferMethod
         )
     }
 

package/ios/Source/internal/BleTraceLogger.swift

@@ -6,7 +6,7 @@ enum BleTraceLogger {
     private static let log = OSLog(subsystem: "com.mentra.bluetoothsdk", category: "MentraBleTrace")
     private static let maxPayloadChars = 3000
     private static let k900Type = "k900"
-    private static let sensitiveKeyParts = ["password", "pass", "token", "secret", "authorization", "auth", "email"]
+    private static let sensitiveKeyParts = ["password", "pass", "token", "secret", "authorization", "auth", "email", "serial"]
 
     static func logJson(
         direction: String,

package/ios/Source/internal/BluetoothSdkAnalytics.swift

@@ -39,6 +39,7 @@ final class BluetoothSdkAnalytics {
     private let configuration: BluetoothSdkAnalyticsConfiguration
     private var startedCaptured = false
     private var lastConnected = false
+    private var identifiedCapturedForConnection = false
 
     init(configuration: BluetoothSdkAnalyticsConfiguration) {
         self.configuration = configuration.resolvedForApp()
@@ -47,6 +48,12 @@ final class BluetoothSdkAnalytics {
     func initializeGlassesStatus(_ status: GlassesStatus) {
         stateQueue.sync {
             lastConnected = status.analyticsConnected
+            // Only treat identification as already captured when a valid serial is
+            // present at init. If the glasses are connected but the serial has not
+            // arrived yet (Mentra Live fills it via version_info after connect), leave
+            // this false so the identify event still fires once the serial arrives.
+            identifiedCapturedForConnection =
+                status.analyticsConnected && status.serialNumber.validManufacturingSerial != nil
         }
     }
 
@@ -72,7 +79,12 @@ final class BluetoothSdkAnalytics {
             let wasConnected = lastConnected
             lastConnected = isConnected
             guard configuration.isReady else { return }
+            guard isConnected else {
+                identifiedCapturedForConnection = false
+                return
+            }
             if isConnected, !wasConnected {
+                identifiedCapturedForConnection = false
                 var properties: [String: Any] = [
                     "event_kind": "glasses_connected",
                     "fully_booted": status.fullyBooted,
@@ -81,7 +93,25 @@ final class BluetoothSdkAnalytics {
                     properties["glasses_model"] = status.deviceModel
                 }
                 capture(event: "bluetooth_sdk_glasses_connected", properties: properties, configuration: configuration)
+                // Fall through: a serial already present at connect time (G1/Ar99
+                // report it in the advertisement) should be identified now rather than
+                // waiting for some later, unrelated glasses-store update to run.
+            }
+
+            guard !identifiedCapturedForConnection,
+                  let serialNumber = status.serialNumber.validManufacturingSerial
+            else { return }
+            identifiedCapturedForConnection = true
+            var properties: [String: Any] = [
+                "event_kind": "glasses_identified",
+                "fully_booted": status.fullyBooted,
+                "glasses_device_id": serialNumber,
+                "glasses_device_id_type": "manufacturing_serial",
+            ]
+            if !status.deviceModel.isEmpty {
+                properties["glasses_model"] = status.deviceModel
             }
+            capture(event: "bluetooth_sdk_glasses_identified", properties: properties, configuration: configuration)
         }
     }
 
@@ -116,6 +146,7 @@ final class BluetoothSdkAnalytics {
             "event_source": "mentra_bluetooth_sdk",
             "sdk_platform": "ios",
             "sdk_surface": configuration.surface,
+            "app_identifier": Bundle.main.bundleIdentifier ?? "",
             "app_bundle_identifier": Bundle.main.bundleIdentifier ?? "",
             "os_platform": "ios",
             "os_version": ProcessInfo.processInfo.operatingSystemVersionString,
@@ -148,6 +179,14 @@ private extension GlassesStatus {
     }
 }
 
+private extension String {
+    var validManufacturingSerial: String? {
+        let normalized = trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalized.isEmpty, normalized.contains(where: { $0 != "0" }) else { return nil }
+        return normalized
+    }
+}
+
 private extension BluetoothSdkAnalyticsConfiguration {
     func resolvedForApp() -> BluetoothSdkAnalyticsConfiguration {
         let disabledByApp = Bundle.main.object(forInfoDictionaryKey: "MentraBluetoothSdkAnalyticsDisabled") as? Bool == true