@mentra/bluetooth-sdk 0.1.21-beta.5 → 3.1.0-beta.103

package/ios/Source/MentraBluetoothSDK.swift

@@ -309,6 +309,9 @@ public final class MentraBluetoothSDK {
         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 ?? "")
+        DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "pending_device_name", "")
+        DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "pending_device_address", "")
+        DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "pending_device_secure_pairing_capable", "")
         finishDefaultDeviceApply(generation: generation)
     }
 
@@ -320,6 +323,9 @@ public final class MentraBluetoothSDK {
         DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "device_name", "")
         DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "device_address", "")
         DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "project_name", "")
+        DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "pending_device_name", "")
+        DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "pending_device_address", "")
+        DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "pending_device_secure_pairing_capable", "")
         finishDefaultDeviceApply(generation: generation)
     }
 
@@ -394,6 +400,14 @@ public final class MentraBluetoothSDK {
         }
         if options.saveAsDefault && !isController {
             setDefaultDevice(device)
+        } else if !isController {
+            DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "pending_device_name", device.name)
+            DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "pending_device_address", device.identifier ?? "")
+            DeviceStore.shared.apply(
+                ObservableStore.bluetoothCategory,
+                "pending_device_secure_pairing_capable",
+                device.securePairingCapable ?? ""
+            )
         }
         DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "pending_wearable", device.model.deviceType)
         DeviceManager.shared.connectByName(device.name)
@@ -418,6 +432,9 @@ public final class MentraBluetoothSDK {
 
     public func cancelConnectionAttempt() {
         clearBluetoothRestoreIntent()
+        DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "pending_device_name", "")
+        DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "pending_device_address", "")
+        DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "pending_device_secure_pairing_capable", "")
         DeviceManager.shared.disconnect()
     }
 
@@ -428,6 +445,9 @@ public final class MentraBluetoothSDK {
 
     public func disconnect() {
         clearBluetoothRestoreIntent()
+        DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "pending_device_name", "")
+        DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "pending_device_address", "")
+        DeviceStore.shared.apply(ObservableStore.bluetoothCategory, "pending_device_secure_pairing_capable", "")
         DeviceManager.shared.disconnect()
     }
 
@@ -890,6 +910,13 @@ public final class MentraBluetoothSDK {
         }
     }
 
+    /// Fire-and-forget Mentra Live Wi-Fi ADB toggle. Glasses do not ack this
+    /// command, so there is no pending-response wait (unlike hotspot / Wi-Fi forget).
+    public func setWifiAdbState(enabled: Bool) async throws {
+        try requireGlassesConnected(operation: "toggle Wi-Fi ADB")
+        DeviceManager.shared.setWifiAdbState(enabled)
+    }
+
     func setSystemTime(timestampMs: Int64) {
         DeviceManager.shared.setSystemTime(timestampMs)
     }
@@ -1141,6 +1168,36 @@ public final class MentraBluetoothSDK {
         }
     }
 
+    public func queryVideoRecordingStatus(requestId: String) async throws -> VideoRecordingStatusEvent {
+        guard !requestId.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+            throw BluetoothSdkError(
+                code: "missing_request_id",
+                message: "requestId is required to query video recording status."
+            )
+        }
+        try requireGlassesConnected(operation: "query video recording status")
+        let pending = PendingResponse<VideoRecordingStatusEvent>(operation: "query video recording status \(requestId)")
+        guard pendingVideoRecordingRequests[requestId] == nil else {
+            throw BluetoothSdkError(
+                code: "request_in_flight",
+                message: "A video recording command is already waiting for requestId \(requestId)."
+            )
+        }
+        pendingVideoRecordingRequests[requestId] = PendingVideoRecordingRequest(
+            expectedStatus: "recording_status",
+            pending: pending
+        )
+        DeviceManager.shared.queryVideoRecordingStatus(requestId)
+        do {
+            let event = try await pending.wait()
+            pendingVideoRecordingRequests.removeValue(forKey: requestId)
+            return event
+        } catch {
+            pendingVideoRecordingRequests.removeValue(forKey: requestId)
+            throw error
+        }
+    }
+
     public func requestVersionInfo() async throws -> VersionInfoResult {
         guard pendingVersionInfo == nil else {
             throw BluetoothSdkError(
@@ -1165,11 +1222,13 @@ public final class MentraBluetoothSDK {
         }
     }
 
-    func setOtaVersionUrl(_ otaVersionUrl: String) throws {
+    /// Select the HTTP(S) manifest used by subsequent OTA checks and installs.
+    public func setOtaVersionUrl(_ otaVersionUrl: String) throws {
         configuredOtaVersionUrl = try OtaManifestChecker.normalizeHttpUrl(otaVersionUrl)
     }
 
-    func getOtaVersionUrl() throws -> String {
+    /// Return the configured OTA manifest, or this SDK release's default manifest.
+    public func getOtaVersionUrl() throws -> String {
         try configuredOtaVersionUrl ?? OtaManifestDefaults.defaultOtaVersionUrl()
     }
 
@@ -1200,6 +1259,14 @@ public final class MentraBluetoothSDK {
         )
     }
 
+    /// Return bundled release changelogs crossed between two coordinated product versions, newest first.
+    public func getReleaseChangelogs(
+        fromVersion: String? = nil,
+        toVersion: String? = nil
+    ) throws -> [ReleaseChangelog] {
+        try ReleaseChangelogCatalog.select(fromVersion: fromVersion, toVersion: toVersion)
+    }
+
     /// Ask connected Mentra Live glasses to report the current OTA install/session status.
     private func queryOtaStatus() async throws -> OtaQueryResult {
         try await performOtaQuery(operation: "OTA status query") {
@@ -2057,6 +2124,8 @@ private func dispatchDiscoveredDevices(_ rawSearchResults: Any?) {
             if !event.lc3.isEmpty {
                 delegate?.mentraBluetoothSDK(self, didReceiveMicLc3: event)
             }
+        case "mic_health":
+            delegate?.mentraBluetoothSDK(self, didReceive: .micHealth(MicHealthEvent(values: data)))
         case "local_transcription":
             let event = LocalTranscriptionEvent(
                 text: data["text"] as? String ?? "",
@@ -2105,6 +2174,10 @@ private func dispatchDiscoveredDevices(_ rawSearchResults: Any?) {
             let event = GalleryStatusEvent(values: data)
             pendingGalleryStatus?.resolve(event)
             delegate?.mentraBluetoothSDK(self, didReceive: .raw(name: "gallery_status", values: event.values))
+        case "pairing_info":
+            delegate?.mentraBluetoothSDK(self, didReceive: .raw(name: "pairing_info", values: data))
+        case "entering_pairing_mode", "owner_replaced":
+            delegate?.mentraBluetoothSDK(self, didReceive: .raw(name: eventName, values: data))
         case "photo_response":
             let event = PhotoResponseEvent(values: data)
             handlePhotoResponseForRequests(event)
@@ -2147,7 +2220,13 @@ private func dispatchDiscoveredDevices(_ rawSearchResults: Any?) {
             var resultValues = data
             resultValues["type"] = "ota_status"
             pendingOtaQuery?.resolve(OtaQueryResult(values: resultValues))
-            delegate?.mentraBluetoothSDK(self, didReceive: .otaStatus(OtaStatusEvent(values: resultValues)))
+            let event = OtaStatusEvent(values: resultValues)
+            if let errorCode = otaStartRejectionErrorCode(event) {
+                pendingOtaStart?.reject(
+                    BluetoothSdkError(code: errorCode, message: "Glasses rejected OTA start: \(errorCode)")
+                )
+            }
+            delegate?.mentraBluetoothSDK(self, didReceive: .otaStatus(event))
         case "settings_ack":
             let event = SettingsAckEvent(values: data)
             handleSettingsAckForRequests(event)
@@ -2172,6 +2251,12 @@ private func dispatchDiscoveredDevices(_ rawSearchResults: Any?) {
     }
 }
 
-
-
-
+/// OTA status messages are not request-correlated, so only known pre-ack failures settle a start.
+private func otaStartRejectionErrorCode(_ event: OtaStatusEvent) -> String? {
+    guard event.status.lowercased() == "failed",
+          event.errorMessage?.lowercased() == "battery_low"
+    else {
+        return nil
+    }
+    return "battery_low"
+}

package/ios/Source/OtaManifest.swift

@@ -1,21 +1,19 @@
 import Foundation
 
 enum OtaManifestDefaults {
-    private static let sdkOtaReleaseBaseUrl = "https://github.com/Mentra-Community/MentraOS/releases/download/bluetooth-sdk-ota"
     // ASG builds before 39 ignore ota_start.ota_version_url, so SDK checks must
     // use the same legacy production manifest those glasses will install from.
     static let legacyProdOtaVersionUrl = "https://ota.mentraglass.com/prod_live_version.json"
 
     static func defaultOtaVersionUrl() throws -> String {
-        guard let sdkVersion = BluetoothSdkDefaults.sdkVersion,
-              !sdkVersion.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
-        else {
+        let manifestUrl = GeneratedReleaseMetadata.otaManifestUrl.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !manifestUrl.isEmpty else {
             throw BluetoothSdkError(
-                code: "missing_sdk_version",
-                message: "Cannot determine Bluetooth SDK version for the default OTA manifest URL."
+                code: "ota_manifest_unconfigured",
+                message: "This source-built Bluetooth SDK has no embedded OTA manifest. Configure one with the debug API."
             )
         }
-        return "\(sdkOtaReleaseBaseUrl)/bluetooth-sdk-\(sdkVersion)-version.json"
+        return manifestUrl
     }
 }
 

package/ios/Source/ReleaseChangelog.swift

@@ -0,0 +1,65 @@
+import Foundation
+
+/// One coordinated Mentra release note authored in /changelogs/<version>.md.
+public struct ReleaseChangelog: Equatable, Sendable {
+    public let version: String
+    public let markdown: String
+
+    public init(version: String, markdown: String) {
+        self.version = version
+        self.markdown = markdown
+    }
+}
+
+enum ReleaseChangelogCatalog {
+    static func select(fromVersion: String?, toVersion: String?) throws -> [ReleaseChangelog] {
+        let fallbackTarget = GeneratedReleaseMetadata.familyBaseVersion.isEmpty
+            ? (generatedReleaseChangelogs.first?.version ?? "")
+            : GeneratedReleaseMetadata.familyBaseVersion
+        if fallbackTarget.isEmpty, toVersion == nil { return [] }
+        let target = try baseVersion(toVersion ?? fallbackTarget, label: "toVersion")
+        guard generatedReleaseChangelogs.contains(where: { $0.version == target }) else {
+            throw BluetoothSdkError(code: "missing_changelog", message: "No changelog is bundled for target version \(target).")
+        }
+        guard let fromVersion else {
+            return generatedReleaseChangelogs.filter { $0.version == target }
+        }
+
+        let source = try baseVersion(fromVersion, label: "fromVersion")
+        let direction = compareVersions(target, source)
+        return generatedReleaseChangelogs.filter { entry in
+            if direction == 0 { return entry.version == target }
+            if direction > 0 {
+                return compareVersions(entry.version, source) > 0 && compareVersions(entry.version, target) <= 0
+            }
+            return compareVersions(entry.version, source) < 0 && compareVersions(entry.version, target) >= 0
+        }
+    }
+
+    private static func baseVersion(_ version: String, label: String) throws -> String {
+        let value = version.trimmingCharacters(in: .whitespacesAndNewlines)
+        let suffixStart = value.firstIndex(where: { $0 == "-" || $0 == "+" }) ?? value.endIndex
+        let components = value[..<suffixStart].split(separator: ".", omittingEmptySubsequences: false)
+        let isValid = components.count == 3 && components.allSatisfy { component in
+            !component.isEmpty
+                && (component == "0" || !component.hasPrefix("0"))
+                && component.utf8.allSatisfy { byte in byte >= 48 && byte <= 57 }
+        }
+        guard isValid else {
+            throw BluetoothSdkError(
+                code: "invalid_changelog_version",
+                message: "\(label) must be a semantic version such as 3.1.0, 3.1.0-dev.4, or 3.1.0-beta.2."
+            )
+        }
+        return components.joined(separator: ".")
+    }
+
+    private static func compareVersions(_ left: String, _ right: String) -> Int {
+        let a = left.split(separator: ".").map { Int($0) ?? 0 }
+        let b = right.split(separator: ".").map { Int($0) ?? 0 }
+        for index in 0 ..< 3 where a[index] != b[index] {
+            return a[index] - b[index]
+        }
+        return 0
+    }
+}

package/ios/Source/audio/AudioModels.swift

@@ -7,6 +7,23 @@ public enum MicPreference: String {
     case bluetooth
 }
 
+struct MicHealth {
+    let sequenceGapEvents: Int64
+    let decodeFailures: Int64
+    let lastLc3ReceivedAt: Int64?
+    let lastPcmProducedAt: Int64?
+
+    var dictionary: [String: Any] {
+        var values: [String: Any] = [
+            "sequenceGapEvents": sequenceGapEvents,
+            "decodeFailures": decodeFailures,
+        ]
+        if let lastLc3ReceivedAt { values["lastLc3ReceivedAt"] = lastLc3ReceivedAt }
+        if let lastPcmProducedAt { values["lastPcmProducedAt"] = lastPcmProducedAt }
+        return values
+    }
+}
+
 public struct LocalTranscriptionEvent: CustomStringConvertible {
     public let text: String
     public let isFinal: Bool

package/ios/Source/camera/CameraModels.swift

@@ -863,3 +863,4 @@ public struct GalleryStatusEvent: CustomStringConvertible {
         "GalleryStatusEvent(total: \(total), photos: \(photos), videos: \(videos))"
     }
 }
+

package/ios/Source/events/BluetoothEvents.swift

@@ -73,6 +73,30 @@ public struct SpeakingStatusEvent: CustomStringConvertible {
     }
 }
 
+public struct MicHealthEvent: CustomStringConvertible {
+    public let reason: String
+    public let sequenceGapEvents: Int
+    public let decodeFailures: Int
+    public let lastLc3ReceivedAt: Int?
+    public let lastPcmProducedAt: Int?
+    public let timestamp: Int
+    public let values: [String: Any]
+
+    public init(values: [String: Any]) {
+        reason = stringValue(values, "reason") ?? ""
+        sequenceGapEvents = intValue(values["sequenceGapEvents"]) ?? 0
+        decodeFailures = intValue(values["decodeFailures"]) ?? 0
+        lastLc3ReceivedAt = intValue(values["lastLc3ReceivedAt"])
+        lastPcmProducedAt = intValue(values["lastPcmProducedAt"])
+        timestamp = intValue(values["timestamp"]) ?? Int(Date().timeIntervalSince1970 * 1000)
+        self.values = values
+    }
+
+    public var description: String {
+        "MicHealthEvent(reason: \(reason), sequenceGapEvents: \(sequenceGapEvents), decodeFailures: \(decodeFailures))"
+    }
+}
+
 public struct OtaStartAckEvent: CustomStringConvertible {
     public let timestamp: Int?
     public let values: [String: Any]
@@ -216,6 +240,7 @@ public enum BluetoothEvent: CustomStringConvertible {
     case touch(TouchEvent)
     case voiceActivityDetectionStatus(VoiceActivityDetectionStatusEvent)
     case speakingStatus(SpeakingStatusEvent)
+    case micHealth(MicHealthEvent)
     case wifiStatus(WifiStatusEvent)
     case hotspotStatus(HotspotStatusEvent)
     case hotspotError(HotspotErrorEvent)
@@ -244,6 +269,8 @@ public enum BluetoothEvent: CustomStringConvertible {
             event.description
         case let .speakingStatus(event):
             event.description
+        case let .micHealth(event):
+            event.description
         case let .wifiStatus(event):
             event.description
         case let .hotspotStatus(event):