@mentra/bluetooth-sdk 3.4.0-dev.993 → 3.4.0-dev.998

package/ios/Source/sgcs/MentraLivePairingStateStore.swift

@@ -0,0 +1,121 @@
+import Foundation
+
+/// Process-wide owner of the `MentraLivePairingStateMachine`. It outlives each `MentraLive`
+/// instance so a disconnect or SGC replacement keeps the pause and the rejection, persists the
+/// record natively (never through the replayed settings), and publishes
+/// `GlassesStatus.pairingState` plus `pairing_state_changed`. Mirrors Android
+/// `MentraLivePairingStateStore`.
+@MainActor
+final class MentraLivePairingStateStore {
+    static let shared = MentraLivePairingStateStore()
+
+    /// The persisted record lives under one UserDefaults key; unknown inner keys are ignored.
+    static let defaultsKey = "mentra_live_pairing_v4"
+
+    private let defaults: UserDefaults
+    private let publishes: Bool
+    private var machine = MentraLivePairingStateMachine()
+    private var restored = false
+
+    /// `publishes == false` keeps tests away from DeviceStore and the bridge.
+    init(defaults: UserDefaults = .standard, publishes: Bool = true) {
+        self.defaults = defaults
+        self.publishes = publishes
+    }
+
+    var state: MentraLivePairingState { machine.state }
+    var allowsAutomaticReconnect: Bool { machine.allowsAutomaticReconnect }
+    var isPaused: Bool { machine.isPaused }
+    var isRejected: Bool { machine.state == .rejected }
+    var verificationArmed: Bool { machine.verificationArmed }
+    /// A window this phone paused for ended and its advertisement has not been read yet.
+    var awaitingTakeoverCheck: Bool { machine.awaitingTakeoverCheck }
+
+    func remainingPauseMs(nowMs: Int = MentraLivePairingStateStore.nowMs()) -> Int {
+        machine.remainingPauseMs(nowMs: nowMs)
+    }
+
+    /// Restore once per process. Later calls only republish the status field.
+    @discardableResult
+    func ensureRestored(savedDeviceId: String, nowMs: Int = MentraLivePairingStateStore.nowMs()) -> MentraLivePairingTransition? {
+        if restored {
+            publish(emitEvent: false)
+            return nil
+        }
+        restored = true
+        var values = defaults.dictionary(forKey: Self.defaultsKey) ?? [:]
+        for key in MentraLivePairingStateMachine.legacyKeys {
+            if let legacy = defaults.object(forKey: key) { values[key] = legacy }
+        }
+        let transition = machine.restore(values: values, savedDeviceId: savedDeviceId, nowMs: nowMs)
+        for key in MentraLivePairingStateMachine.legacyKeys {
+            defaults.removeObject(forKey: key)
+        }
+        persist()
+        publish()
+        Bridge.log("PAIRFLOW: pairing_state restore note=\(transition.note) state=\(describe())")
+        return transition
+    }
+
+    /// Run one machine input, persist the record, and publish when the public state changed.
+    @discardableResult
+    func update(
+        _ source: String,
+        _ input: (inout MentraLivePairingStateMachine) -> MentraLivePairingTransition
+    ) -> MentraLivePairingTransition {
+        let before = machine.state
+        let beforeRecord = machine.persisted() as NSDictionary
+        let transition = input(&machine)
+        // Duplicate-reporting scans feed every advertisement through here.
+        if !beforeRecord.isEqual(to: machine.persisted()) { persist() }
+        if machine.state != before { publish() }
+        if transition.effect != .none || machine.state != before {
+            Bridge.log(
+                "PAIRFLOW: pairing_state source=\(source) effect=\(transition.effect) note=\(transition.note) state=\(describe())"
+            )
+        }
+        return transition
+    }
+
+    func describe() -> String {
+        switch machine.state {
+        case .normal: return "normal"
+        case let .pairingMode(windowId, endsAtMs): return "pairing_mode(window=\(windowId), endsAtMs=\(endsAtMs))"
+        case .rejected: return "pairing_rejected"
+        }
+    }
+
+    /// Drops the in-memory state as a process restart would. Persisted values stay.
+    func resetForTest() {
+        machine = MentraLivePairingStateMachine()
+        restored = false
+    }
+
+    nonisolated static func nowMs() -> Int {
+        Int(Date().timeIntervalSince1970 * 1000)
+    }
+
+    private func persist() {
+        var stored = defaults.dictionary(forKey: Self.defaultsKey) ?? [:]
+        for key in MentraLivePairingStateMachine.keys {
+            stored.removeValue(forKey: key)
+        }
+        for (key, value) in machine.persisted() {
+            stored[key] = value
+        }
+        if stored.isEmpty {
+            defaults.removeObject(forKey: Self.defaultsKey)
+        } else {
+            defaults.set(stored, forKey: Self.defaultsKey)
+        }
+    }
+
+    private func publish(emitEvent: Bool = true) {
+        guard publishes else { return }
+        let map = machine.state.toMap()
+        DeviceStore.shared.apply("glasses", "pairingState", map)
+        if emitEvent {
+            Bridge.sendTypedMessage("pairing_state_changed", body: ["state": map])
+        }
+    }
+}

package/ios/Source/sgcs/SGCManager.swift

@@ -50,6 +50,9 @@ protocol SGCManager {
 
     var type: String { get set }
     var hasMic: Bool { get }
+    /// The driver publishes `GlassesStatus.audioSetup` itself. Otherwise the status layer
+    /// reports `not_applicable` while connected and `idle` otherwise.
+    var publishesAudioSetup: Bool { get }
 
     // MARK: - Audio Control
 
@@ -278,6 +281,10 @@ extension SGCManager {
         false
     }
 
+    var publishesAudioSetup: Bool {
+        false
+    }
+
     func replayStreamControlReady() {}
 
     @discardableResult func requestSavedWifiNetworks(requestId _: String, sid _: String) -> Bool {

package/ios/Source/sgcs/Simulated.swift

@@ -18,6 +18,8 @@ class Simulated: SGCManager {
             BluetoothSdkDefaults.voiceActivityDetectionEnabled
         )
         DeviceStore.shared.apply("glasses", "bluetoothClassicConnected", false)
+        DeviceStore.shared.apply("glasses", "bluetoothClassicProfilesConnected", false)
+        DeviceStore.shared.apply("glasses", "bluetoothAudioRouted", false)
     }
 
     // MARK: - Device Information

package/ios/Source/status/DeviceStatus.swift

@@ -124,6 +124,7 @@ struct GlassesStatus: CustomStringConvertible {
             "signalStrength": -1,
             "signalStrengthUpdatedAt": 0,
             "g2MissingArm": NSNull(),
+            "audioSetup": GlassesAudioSetupState.idle.toMap(),
         ]))
     }
 
@@ -151,6 +152,14 @@ struct GlassesStatus: CustomStringConvertible {
         boolValue(values, "bluetoothClassicConnected") ?? false
     }
 
+    var bluetoothClassicProfilesConnected: Bool {
+        boolValue(values, "bluetoothClassicProfilesConnected") ?? false
+    }
+
+    var bluetoothAudioRouted: Bool {
+        boolValue(values, "bluetoothAudioRouted") ?? false
+    }
+
     var signalStrength: Int {
         intValue(values["signalStrength"]) ?? -1
     }
@@ -302,6 +311,16 @@ struct GlassesStatus: CustomStringConvertible {
         intValue(values["ringSignalStrength"]) ?? -1
     }
 
+    /// Mentra Live `MentraLivePairingState` (`{state, windowId?, endsAtMs?}`); nil for other glasses.
+    var pairingState: [String: Any]? {
+        values["pairingState"] as? [String: Any]
+    }
+
+    /// `GlassesAudioSetupState` (`{state, action?}`). Every model publishes it.
+    var audioSetup: [String: Any]? {
+        values["audioSetup"] as? [String: Any]
+    }
+
     var description: String {
         values.description
     }
@@ -688,6 +707,14 @@ struct GlassesStatusUpdate: CustomStringConvertible {
         optionalBoolValue(values, "bluetoothClassicConnected")
     }
 
+    var bluetoothClassicProfilesConnected: Bool? {
+        optionalBoolValue(values, "bluetoothClassicProfilesConnected")
+    }
+
+    var bluetoothAudioRouted: Bool? {
+        optionalBoolValue(values, "bluetoothAudioRouted")
+    }
+
     var signalStrength: Int? {
         optionalIntValue(values, "signalStrength")
     }
@@ -848,6 +875,14 @@ struct GlassesStatusUpdate: CustomStringConvertible {
         optionalIntValue(values, "ringSignalStrength")
     }
 
+    var pairingState: [String: Any]? {
+        values["pairingState"] as? [String: Any]
+    }
+
+    var audioSetup: [String: Any]? {
+        values["audioSetup"] as? [String: Any]
+    }
+
     var description: String {
         values.description
     }

package/ios/Source/types/DeviceModels.swift

@@ -172,14 +172,21 @@ public struct ConnectOptions {
     /// Mentra Live on iOS only. Whether CoreBluetooth should require ANCS
     /// authorization while establishing the connection.
     public let requiresAncs: Bool
+    /// Mentra Live on iOS only. Ask CoreBluetooth to bring up the Classic
+    /// profiles (A2DP/HFP) after the BLE connection. On by default: iOS derives
+    /// the Classic key at the BLE bond but never starts Classic, and the glasses
+    /// commit `no_classic`, so pairing waits forever for an audio route without it.
+    public let enableTransportBridging: Bool
 
     public init(
         saveAsDefault: Bool = true,
         cancelExistingConnectionAttempt: Bool = true,
-        requiresAncs: Bool = true
+        requiresAncs: Bool = true,
+        enableTransportBridging: Bool = true
     ) {
         self.saveAsDefault = saveAsDefault
         self.cancelExistingConnectionAttempt = cancelExistingConnectionAttempt
         self.requiresAncs = requiresAncs
+        self.enableTransportBridging = enableTransportBridging
     }
 }

package/ios/Source/utils/AudioSessionMonitor.swift

@@ -22,6 +22,14 @@ class AudioSessionMonitor {
     static var isMonitoring = false
     static var devicePattern: String?
     static var callback: ((Bool, String?) -> Void)?
+    /// Last pair-audio decision line. The check runs on a timer; log only changes.
+    private static var lastPairFlow = ""
+    /// SoloAmbient hides paired HFP inputs. One short category probe per second is enough.
+    private static var lastBluetoothProbe: (at: Date, outputs: [AVAudioSessionPortDescription], inputs: [AVAudioSessionPortDescription]?)?
+    /// The glasses sent `classic_link` in the current BLE session. Their report replaces the
+    /// category probe, which can see a route that is not the glasses'. Old firmware never sends
+    /// it and keeps the probe.
+    static var glassesReportClassicLink = false
 
     private init() {
         Bridge.log("AudioMonitor: Initialized")
@@ -93,18 +101,134 @@ class AudioSessionMonitor {
         return false
     }
 
+    private struct BluetoothSessionSnapshot {
+        let categoryLabel: String
+        let outputs: [AVAudioSessionPortDescription]
+        let availableInputs: [AVAudioSessionPortDescription]?
+    }
+
+    /// The default SoloAmbient session lists only the built-in mic, so glasses that are
+    /// already connected in Settings look absent and pairing waits out the auto-audio timer.
+    /// Read HFP inputs with a category that can see them, then put the previous category back.
+    /// Does not activate the session or select an input.
+    private static func bluetoothSessionSnapshot() -> BluetoothSessionSnapshot {
+        if !Thread.isMainThread {
+            return DispatchQueue.main.sync { bluetoothSessionSnapshot() }
+        }
+        let session = AVAudioSession.sharedInstance()
+        if categoryShowsBluetoothInputs(session.category) {
+            return BluetoothSessionSnapshot(
+                categoryLabel: session.category.rawValue,
+                outputs: session.currentRoute.outputs,
+                availableInputs: session.availableInputs
+            )
+        }
+        if glassesReportClassicLink {
+            // Passive route observation only: never switch the category.
+            return BluetoothSessionSnapshot(
+                categoryLabel: "passive:\(session.category.rawValue)",
+                outputs: session.currentRoute.outputs,
+                availableInputs: session.availableInputs
+            )
+        }
+        if let lastBluetoothProbe, Date().timeIntervalSince(lastBluetoothProbe.at) < 1 {
+            return BluetoothSessionSnapshot(
+                categoryLabel: "probed:\(AVAudioSession.Category.playAndRecord.rawValue)",
+                outputs: lastBluetoothProbe.outputs,
+                availableInputs: lastBluetoothProbe.inputs
+            )
+        }
+        let savedCategory = session.category
+        let savedMode = session.mode
+        let savedOptions = session.categoryOptions
+        do {
+            try session.setCategory(
+                .playAndRecord, mode: .default, options: [.allowBluetooth, .allowBluetoothA2DP]
+            )
+        } catch {
+            return BluetoothSessionSnapshot(
+                categoryLabel: session.category.rawValue,
+                outputs: session.currentRoute.outputs,
+                availableInputs: session.availableInputs
+            )
+        }
+        let outputs = session.currentRoute.outputs
+        let inputs = session.availableInputs
+        lastBluetoothProbe = (Date(), outputs, inputs)
+        try? session.setCategory(savedCategory, mode: savedMode, options: savedOptions)
+        return BluetoothSessionSnapshot(
+            categoryLabel: "probed:\(AVAudioSession.Category.playAndRecord.rawValue)",
+            outputs: outputs,
+            availableInputs: inputs
+        )
+    }
+
+    private static func categoryShowsBluetoothInputs(_ category: AVAudioSession.Category) -> Bool {
+        category == .playAndRecord || category == .record || category == .multiRoute
+    }
+
+    /// Glasses' Classic audio facts without selecting an input or activating the session.
+    /// `profilesConnected` matches `isDevicePaired`; `audioRouted` is the stricter
+    /// "audio is flowing to the glasses" signal.
+    static func observeProfiles(devicePattern: String) -> BluetoothAudioRoute.ProfileObservation {
+        let snapshot = bluetoothSessionSnapshot()
+        let profiles = profileObservation(
+            devicePattern: devicePattern, outputs: snapshot.outputs, availableInputs: snapshot.availableInputs
+        )
+        logPairFlow(
+            category: snapshot.categoryLabel, devicePattern: devicePattern, outputs: snapshot.outputs,
+            availableInputs: snapshot.availableInputs, profiles: profiles
+        )
+        return profiles
+    }
+
+    private static func profileObservation(
+        devicePattern: String,
+        outputs: [AVAudioSessionPortDescription],
+        availableInputs: [AVAudioSessionPortDescription]?
+    ) -> BluetoothAudioRoute.ProfileObservation {
+        BluetoothAudioRoute.observeProfiles(
+            outputs: outputs.map { (name: $0.portName, portType: $0.portType.rawValue) },
+            inputs: availableInputs?.map { (name: $0.portName, portType: $0.portType.rawValue) },
+            target: devicePattern, isIOSAppOnMac: ProcessInfo.processInfo.isiOSAppOnMac
+        )
+    }
+
+    /// One PAIRFLOW line per transition of category, inputs availability, ports, and both facts.
+    /// Port names are the glasses' advertised name or other audio devices; no credentials are logged.
+    private static func logPairFlow(
+        category: String,
+        devicePattern: String,
+        outputs: [AVAudioSessionPortDescription],
+        availableInputs: [AVAudioSessionPortDescription]?,
+        profiles: BluetoothAudioRoute.ProfileObservation
+    ) {
+        let decision = profiles.audioRouted
+            ? "advance_active_output"
+            : (profiles.profilesConnected ? "advance_hfp_input" : "wait_no_route")
+        let outputNames = outputs.map { "\($0.portType.rawValue):\($0.portName)" }.joined(separator: ",")
+        let inputNames = (availableInputs ?? []).map { "\($0.portType.rawValue):\($0.portName)" }.joined(separator: ",")
+        let pairFlow =
+            "PAIRFLOW: pair_audio decision=\(decision) pattern=\(devicePattern) category=\(category) inputsNil=\(availableInputs == nil) outputs=[\(outputNames)] inputs=[\(inputNames)] profilesConnected=\(profiles.profilesConnected) audioRouted=\(profiles.audioRouted)"
+        if pairFlow != lastPairFlow {
+            lastPairFlow = pairFlow
+            Bridge.log(pairFlow)
+        }
+    }
+
     /// Check if a Bluetooth device matching the pattern is paired (appears in availableInputs)
     /// Returns true if device is found (paired), WITHOUT activating it
     /// This avoids switching A2DP music playback to HFP microphone mode
     static func isDevicePaired(devicePattern: String) -> Bool {
-        let session = AVAudioSession.sharedInstance()
-        let outputs = session.currentRoute.outputs
+        let snapshot = bluetoothSessionSnapshot()
+        let outputs = snapshot.outputs
         let route = BluetoothAudioRoute.observe(
             outputs: outputs.map { (name: $0.portName, portType: $0.portType.rawValue) },
             target: devicePattern, isIOSAppOnMac: ProcessInfo.processInfo.isiOSAppOnMac
         )
         let activeTarget = route.matchingOutputCount > 0
-        let availableInputs = session.availableInputs
+        let availableInputs = snapshot.availableInputs
+        let profiles = profileObservation(devicePattern: devicePattern, outputs: outputs, availableInputs: availableInputs)
         let bluetoothInput = availableInputs?.first { input in
             input.portType == .bluetoothHFP
                 && input.portName.localizedCaseInsensitiveContains(devicePattern)
@@ -112,8 +236,12 @@ class AudioSessionMonitor {
 
         // NSLog messages redact the native route checks in retained Mac logs.
         // Keep categorical evidence at notice level without exposing names or
-        // selecting an input, activating the session, or changing audio routing.
-        readinessLog.notice("Pair audio: iosOnMac=\(ProcessInfo.processInfo.isiOSAppOnMac, privacy: .public) targetPresent=\(!devicePattern.isEmpty, privacy: .public) category=\(session.category.rawValue, privacy: .public) outputs=\(outputs.count, privacy: .public) bluetoothOutputs=\(route.bluetoothOutputCount, privacy: .public) targetNameOutputs=\(route.targetNameOutputCount, privacy: .public) inputs=\(availableInputs?.count ?? -1, privacy: .public) activeTarget=\(activeTarget, privacy: .public) hfpTarget=\(bluetoothInput != nil, privacy: .public)")
+        // selecting an input or activating the session.
+        readinessLog.notice("Pair audio: iosOnMac=\(ProcessInfo.processInfo.isiOSAppOnMac, privacy: .public) targetPresent=\(!devicePattern.isEmpty, privacy: .public) category=\(snapshot.categoryLabel, privacy: .public) outputs=\(outputs.count, privacy: .public) bluetoothOutputs=\(route.bluetoothOutputCount, privacy: .public) targetNameOutputs=\(route.targetNameOutputCount, privacy: .public) inputs=\(availableInputs?.count ?? -1, privacy: .public) activeTarget=\(activeTarget, privacy: .public) hfpTarget=\(bluetoothInput != nil, privacy: .public)")
+        logPairFlow(
+            category: snapshot.categoryLabel, devicePattern: devicePattern, outputs: outputs,
+            availableInputs: availableInputs, profiles: profiles
+        )
 
         // Check if already active (using A2DP for music or HFP for calls)
         if activeTarget {
@@ -320,6 +448,31 @@ enum BluetoothAudioRoute {
         )
     }
 
+    /// Separate facts about the glasses' Classic audio link. Neither implies a bond:
+    /// a bonded device with no connected audio profile is invisible to AVAudioSession.
+    struct ProfileObservation: Equatable {
+        /// An HFP input is available, or a matching Bluetooth output is active.
+        let profilesConnected: Bool
+        /// A matching Bluetooth output is the active route (A2DP or HFP).
+        let audioRouted: Bool
+    }
+
+    /// `inputs` is nil when `AVAudioSession.availableInputs` is nil (it depends on the session category).
+    static func observeProfiles(
+        outputs: [(name: String, portType: String)],
+        inputs: [(name: String, portType: String)]?,
+        target: String,
+        isIOSAppOnMac: Bool
+    ) -> ProfileObservation {
+        let audioRouted = outputs.contains {
+            matches(name: $0.name, portType: $0.portType, target: target, isIOSAppOnMac: isIOSAppOnMac)
+        }
+        let hfpInput = inputs?.contains {
+            $0.portType == "BluetoothHFP" && matchesName($0.name, target: target)
+        } ?? false
+        return ProfileObservation(profilesConnected: audioRouted || hfpInput, audioRouted: audioRouted)
+    }
+
     static func matches(name: String, portType: String, target: String, isIOSAppOnMac: Bool) -> Bool {
         matchesName(name, target: target) && isBluetoothTransport(portType, isIOSAppOnMac: isIOSAppOnMac)
     }

package/ios/Tests/BluetoothAudioRouteTests.swift

@@ -60,4 +60,86 @@ final class BluetoothAudioRouteTests: XCTestCase {
             ))
         }
     }
+
+    // MARK: - Profile observation
+
+    private func profiles(
+        outputs: [(name: String, portType: String)] = [],
+        inputs: [(name: String, portType: String)]? = [],
+        isIOSAppOnMac: Bool = false
+    ) -> BluetoothAudioRoute.ProfileObservation {
+        BluetoothAudioRoute.observeProfiles(
+            outputs: outputs, inputs: inputs, target: "03BE", isIOSAppOnMac: isIOSAppOnMac
+        )
+    }
+
+    func testActiveA2dpOutputIsConnectedAndRouted() {
+        let result = profiles(outputs: [(name: "Mentra_Live_03BE", portType: "BluetoothA2DPOutput")], inputs: nil)
+        XCTAssertEqual(result, .init(profilesConnected: true, audioRouted: true))
+    }
+
+    func testHfpInputOnlyIsConnectedButNotRouted() {
+        let result = profiles(
+            outputs: [(name: "Speaker", portType: "Speaker")],
+            inputs: [(name: "Mentra_Live_03BE", portType: "BluetoothHFP")]
+        )
+        XCTAssertEqual(result, .init(profilesConnected: true, audioRouted: false))
+    }
+
+    func testNoMatchIsNeitherConnectedNorRouted() {
+        let result = profiles(
+            outputs: [(name: "Speaker", portType: "Speaker")],
+            inputs: [(name: "iPhone Microphone", portType: "MicrophoneBuiltIn")]
+        )
+        XCTAssertEqual(result, .init(profilesConnected: false, audioRouted: false))
+        XCTAssertEqual(profiles(), .init(profilesConnected: false, audioRouted: false))
+    }
+
+    func testNilInputsDoNotHideActiveOutputAndAreNotAMatch() {
+        XCTAssertEqual(
+            profiles(outputs: [(name: "Speaker", portType: "Speaker")], inputs: nil),
+            .init(profilesConnected: false, audioRouted: false)
+        )
+        XCTAssertEqual(
+            profiles(outputs: [(name: "Mentra_Live_03BE", portType: "BluetoothHFP")], inputs: nil),
+            .init(profilesConnected: true, audioRouted: true)
+        )
+    }
+
+    func testOtherDevicesDoNotMatch() {
+        let result = profiles(
+            outputs: [(name: "Mentra_Live_023B", portType: "BluetoothA2DPOutput")],
+            inputs: [(name: "Mentra_Live_023B", portType: "BluetoothHFP")]
+        )
+        XCTAssertEqual(result, .init(profilesConnected: false, audioRouted: false))
+    }
+
+    func testIdentityAndTransportBothRequiredForInputsAndOutputs() {
+        let result = profiles(
+            outputs: [(name: "Mentra_Live_03BE", portType: "USBAudio")],
+            inputs: [(name: "Mentra_Live_03BE", portType: "BluetoothA2DPOutput")]
+        )
+        XCTAssertEqual(result, .init(profilesConnected: false, audioRouted: false))
+    }
+
+    func testIOSOnMacBluetoothPortIsRoutedOnlyOnMac() {
+        let output = [(name: "Mentra_Live_03BE", portType: "Bluetooth")]
+        XCTAssertEqual(
+            profiles(outputs: output, isIOSAppOnMac: true),
+            .init(profilesConnected: true, audioRouted: true)
+        )
+        XCTAssertEqual(
+            profiles(outputs: output, isIOSAppOnMac: false),
+            .init(profilesConnected: false, audioRouted: false)
+        )
+    }
+
+    func testEmptyTargetNeverMatches() {
+        let result = BluetoothAudioRoute.observeProfiles(
+            outputs: [(name: "Mentra_Live_03BE", portType: "BluetoothA2DPOutput")],
+            inputs: [(name: "Mentra_Live_03BE", portType: "BluetoothHFP")],
+            target: "", isIOSAppOnMac: false
+        )
+        XCTAssertEqual(result, .init(profilesConnected: false, audioRouted: false))
+    }
 }