@mentra/bluetooth-sdk 0.1.21-beta.3 → 3.1.0-beta.100

package/ios/Source/sgcs/MentraLive.swift

@@ -25,6 +25,35 @@ struct MentraLiveDevice {
     let address: String
 }
 
+enum MentraLivePendingPairingTarget {
+    static func matches(
+        connectedName: String,
+        connectedIdentifier: String,
+        pendingName: String,
+        pendingIdentifier: String
+    ) -> Bool {
+        if !pendingIdentifier.isEmpty {
+            return connectedIdentifier.caseInsensitiveCompare(pendingIdentifier) == .orderedSame
+        }
+        return !pendingName.isEmpty && connectedName == pendingName
+    }
+
+    static func shouldRecover(
+        isConnected: Bool,
+        connectedName: String,
+        connectedIdentifier: String,
+        pendingName: String,
+        pendingIdentifier: String
+    ) -> Bool {
+        isConnected && matches(
+            connectedName: connectedName,
+            connectedIdentifier: connectedIdentifier,
+            pendingName: pendingName,
+            pendingIdentifier: pendingIdentifier
+        )
+    }
+}
+
 // MARK: - BlePhotoUploadService
 
 class BlePhotoUploadService {
@@ -857,20 +886,66 @@ extension MentraLive: CBCentralManagerDelegate {
         }
     }
 
-    func handleDiscoveredPeripheral(_ peripheral: CBPeripheral, rssi: NSNumber? = nil) {
+    func handleDiscoveredPeripheral(
+        _ peripheral: CBPeripheral,
+        advertisementData: [String: Any] = [:],
+        rssi: NSNumber? = nil
+    ) {
         guard let name = peripheral.name else { return }
 
         // Check for compatible device names
         if name == "Xy_A" || name.hasPrefix("XyBLE_") || name.hasPrefix("MENTRA_LIVE_BLE")
             || name.hasPrefix("MENTRA_LIVE_BT") || name.lowercased().hasPrefix("mentra_live")
         {
+            let savedDeviceName = UserDefaults.standard.string(forKey: PREFS_DEVICE_NAME)
+            let isReconnectTarget = savedDeviceName != nil && savedDeviceName == name
+            if !isReconnectTarget && advertisesPairingFlag(advertisementData)
+                && !isPairingDiscoverable(advertisementData)
+            {
+                // Keep nearby secure units visible with pairing-mode guidance, while RN blocks
+                // the connection until a pairable advertisement arrives.
+                Bridge.log(
+                    "LIVE: Nearby \(name) is secure firmware not in pairing mode — exposing as non-pairable"
+                )
+                discoveredPeripherals[name] = peripheral
+                cacheAdvPairing(
+                    name,
+                    pairingMode: false,
+                    pairingCode: nil,
+                    securePairingCapable: true
+                )
+                emitDiscoveredDeviceFromCache(
+                    name,
+                    identifier: peripheral.identifier.uuidString,
+                    rssi: rssi?.intValue
+                )
+                return
+            }
+
             let glassType = name == "Xy_A" ? "Standard" : "K900"
-            Bridge.log("Found compatible \(glassType) glasses device: \(name)")
+            let trailer = parseSecurePairingTrailer(advertisementData)
+            Bridge.log(
+                trailer.secureCapable
+                    ? "Found compatible \(glassType) glasses device: \(name) (pairingMode=\(trailer.pairingMode))"
+                    : "Found compatible \(glassType) glasses device: \(name) (legacy firmware, pairable)"
+            )
 
             // Store the peripheral
             discoveredPeripherals[name] = peripheral
 
-            emitDiscoveredDevice(name, identifier: peripheral.identifier.uuidString, rssi: rssi?.intValue)
+            cacheAdvPairing(
+                name,
+                // Field firmware has no pairing flag. Treat it as pairable so the
+                // new Mentra App can still find old glasses.
+                pairingMode: trailer.secureCapable ? trailer.pairingMode : true,
+                pairingCode: trailer.pairingCode,
+                securePairingCapable: trailer.secureCapable
+            )
+            emitDiscoveredDeviceFromCache(
+                name,
+                identifier: peripheral.identifier.uuidString,
+                rssi: rssi?.intValue
+            )
 
             // Check if this is the device we want to connect to
             if let savedDeviceName = UserDefaults.standard.string(forKey: PREFS_DEVICE_NAME),
@@ -887,21 +962,42 @@ extension MentraLive: CBCentralManagerDelegate {
 
     nonisolated func centralManager(
         _: CBCentralManager, didDiscover peripheral: CBPeripheral,
-        advertisementData _: [String: Any], rssi: NSNumber
+        advertisementData: [String: Any], rssi: NSNumber
     ) {
         DispatchQueue.main.async { [weak self] in
-            self?.handleDiscoveredPeripheral(peripheral, rssi: rssi)
+            self?.handleDiscoveredPeripheral(peripheral, advertisementData: advertisementData, rssi: rssi)
         }
     }
 
     nonisolated func centralManager(_: CBCentralManager, didConnect peripheral: CBPeripheral) {
         DispatchQueue.main.async { [weak self] in
             guard let self else { return }
+            let matchesActiveAttempt = self.connectingPeripheral === peripheral
+            guard MentraLiveConnectionAttemptPolicy.shouldAcceptDidConnect(
+                pairingYieldActive: self.pairingYieldActive,
+                matchesActiveAttempt: matchesActiveAttempt
+            ) else {
+                Bridge.log(
+                    "LIVE: Rejecting stale connection callback during pairing yield or after attempt replacement: \(peripheral.identifier)"
+                )
+                self.stopConnectionTimeout()
+                if self.connectingPeripheral === peripheral {
+                    self.connectingPeripheral = nil
+                }
+                if self.connectedPeripheral === peripheral {
+                    self.connectedPeripheral = nil
+                }
+                self.isConnecting = false
+                self.centralManager?.cancelPeripheralConnection(peripheral)
+                return
+            }
             Bridge.log("Connected to GATT server, discovering services...")
 
             self.stopConnectionTimeout()
             self.isConnecting = false
+            self.connectingPeripheral = nil
             self.connectedPeripheral = peripheral
+            self.emitConnectedPendingDeviceForPairingScan()
 
             // Save device name and address for future reconnection
             if let name = peripheral.name {
@@ -939,10 +1035,17 @@ extension MentraLive: CBCentralManagerDelegate {
     }
 
     nonisolated func centralManager(
-        _: CBCentralManager, didDisconnectPeripheral _: CBPeripheral, error _: Error?
+        _: CBCentralManager, didDisconnectPeripheral peripheral: CBPeripheral, error: Error?
     ) {
         DispatchQueue.main.async { [weak self] in
             guard let self else { return }
+            let isCurrent =
+                self.connectedPeripheral === peripheral || self.connectingPeripheral === peripheral
+            if !isCurrent {
+                Bridge.log("LIVE: Ignoring stale disconnect for \(peripheral.identifier)")
+                return
+            }
+            self.connectingPeripheral = nil
             Bridge.log("LIVE: Disconnected from GATT server")
 
             self.isConnecting = false
@@ -962,6 +1065,11 @@ extension MentraLive: CBCentralManagerDelegate {
             self.txCharacteristic = nil
             self.rxCharacteristic = nil
 
+            if self.pairingYieldAwaitingReclaim, Self.isPairingAuthFailure(error) {
+                self.clearSavedGlassesAfterOwnerLoss(reason: "ios_auth_fail")
+                return
+            }
+
             // Attempt reconnection if not killed
             if !self.isKilled {
                 self.handleReconnection()
@@ -969,10 +1077,17 @@ extension MentraLive: CBCentralManagerDelegate {
         }
     }
 
-    nonisolated func centralManager(_: CBCentralManager, didFailToConnect _: CBPeripheral, error: Error?) {
+    nonisolated func centralManager(_: CBCentralManager, didFailToConnect peripheral: CBPeripheral, error: Error?) {
         let errorDescription = error?.localizedDescription ?? "Unknown error"
         DispatchQueue.main.async { [weak self] in
             guard let self else { return }
+            let isCurrent =
+                self.connectedPeripheral === peripheral || self.connectingPeripheral === peripheral
+            if !isCurrent {
+                Bridge.log("LIVE: Ignoring stale connect failure for \(peripheral.identifier)")
+                return
+            }
+            self.connectingPeripheral = nil
             Bridge.log("LIVE: Failed to connect to peripheral: \(errorDescription)")
 
             self.stopConnectionTimeout()
@@ -981,6 +1096,11 @@ extension MentraLive: CBCentralManagerDelegate {
             self.connectedPeripheral = nil
             self.updateConnectionState(ConnTypes.DISCONNECTED)
 
+            if self.pairingYieldAwaitingReclaim, Self.isPairingAuthFailure(error) {
+                self.clearSavedGlassesAfterOwnerLoss(reason: "ios_auth_fail")
+                return
+            }
+
             if !self.isKilled {
                 self.handleReconnection()
             }
@@ -1276,6 +1396,39 @@ class MentraLive: NSObject, SGCManager {
     private let BLOCK_AUDIO_DUPLEX = false
     private static let voiceActivityDetectionSwitchType = 8
     private static let loudnessGateSwitchType = 10
+    private func pairingAdvertisement(
+        _ advertisementData: [String: Any]
+    ) -> MentraLivePairingAdvertisement? {
+        MentraLivePairingAdvertisement.parse(
+            coreBluetoothManufacturerData:
+            advertisementData[CBAdvertisementDataManufacturerDataKey] as? Data
+        )
+    }
+
+    private func isPairingDiscoverable(_ advertisementData: [String: Any]) -> Bool {
+        pairingAdvertisement(advertisementData)?.pairingMode == true
+    }
+
+    private struct SecurePairingTrailer {
+        let pairingMode: Bool
+        let pairingCode: String?
+        let secureCapable: Bool
+    }
+
+    private func parseSecurePairingTrailer(_ advertisementData: [String: Any]) -> SecurePairingTrailer {
+        guard let advertisement = pairingAdvertisement(advertisementData) else {
+            return SecurePairingTrailer(pairingMode: false, pairingCode: nil, secureCapable: false)
+        }
+        return SecurePairingTrailer(
+            pairingMode: advertisement.pairingMode,
+            pairingCode: advertisement.pairingCode,
+            secureCapable: true
+        )
+    }
+
+    private func advertisesPairingFlag(_ advertisementData: [String: Any]) -> Bool {
+        pairingAdvertisement(advertisementData) != nil
+    }
 
     var connectionState: String = ConnTypes.DISCONNECTED
 
@@ -1290,6 +1443,8 @@ class MentraLive: NSObject, SGCManager {
             // return, unlike Android).
             DeviceStore.shared.apply("glasses", "serialNumber", "")
             DeviceStore.shared.apply("glasses", "bluetoothMacAddress", "")
+            DeviceStore.shared.apply("glasses", "wifiMacAddress", "")
+            DeviceStore.shared.apply("glasses", "hotspotOtaVersion", 0)
         }
         connectionState = state
         DeviceStore.shared.apply("glasses", "connectionState", state)
@@ -1297,6 +1452,7 @@ class MentraLive: NSObject, SGCManager {
         // a previous pairing into the next one (would otherwise surface as wrong overall_percent
         // or stale lastBesOtaProgress on the next OTA).
         if state == ConnTypes.DISCONNECTED {
+            resetPendingAckState(reason: "BLE session ended")
             resetWireNegotiationState()
             resetAncsRelayState()
             // Queued writes are session-bound: transmitting them into the NEXT session
@@ -1342,14 +1498,26 @@ class MentraLive: NSObject, SGCManager {
     func forget() {
         Bridge.log("LIVE: Forgetting Mentra Live glasses")
 
+        // Clear saved device name so the pairing filter is not bypassed on rescan
+        UserDefaults.standard.removeObject(forKey: PREFS_DEVICE_NAME)
+
         // Stop scanning first
         if isScanning {
             stopScan()
             emitStopScanEvent()
         }
 
-        // Then do full cleanup (disconnect + clear all references)
-        destroy()
+        // Then do full cleanup after the unpair write can leave GATT.
+        sendJson(["type": "unpair"], wakeUp: true, requireAck: false)
+        unpairFlushWorkItem?.cancel()
+        unpairFlushPending = true
+        let work = DispatchWorkItem { [self] in
+            self.unpairFlushPending = false
+            self.unpairFlushWorkItem = nil
+            self.destroy()
+        }
+        unpairFlushWorkItem = work
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.4, execute: work)
     }
 
     var type = "Mentra Live"
@@ -1427,7 +1595,6 @@ class MentraLive: NSObject, SGCManager {
     private var lc3ReadCharacteristic: CBCharacteristic?
     private var lc3WriteCharacteristic: CBCharacteristic?
     private var supportsLC3Audio = true
-    private var lastReceivedLc3Sequence: Int8 = -1
     private let LC3_FRAME_SIZE = 40 // bytes per LC3 frame
     private let MICBEAT_INTERVAL_MS: TimeInterval = 30 * 60 // 30 minutes in seconds
     private var micBeatTimer: Timer?
@@ -1452,6 +1619,7 @@ class MentraLive: NSObject, SGCManager {
     private let KEEP_ALIVE_INTERVAL_MS: UInt64 = 5_000_000_000 // 5 seconds
     private let CONNECTION_TIMEOUT_MS: UInt64 = 100_000_000_000 // 100 seconds
     private let HEARTBEAT_INTERVAL_MS: TimeInterval = 30.0 // 30 seconds
+    private let BES_OTA_HEARTBEAT_LEASE_SEC: TimeInterval = 120.0
     private let BATTERY_REQUEST_EVERY_N_HEARTBEATS = 10
     private let SIGNAL_STRENGTH_READ_INTERVAL_MS: TimeInterval = 10.0
     private let MIN_SEND_DELAY_MS: UInt64 = 160_000_000 // 160ms in nanoseconds
@@ -1472,6 +1640,8 @@ class MentraLive: NSObject, SGCManager {
     private var centralManager: CBCentralManager?
 
     private var connectedPeripheral: CBPeripheral?
+    /// Peripheral for the in-flight connect; used to ignore stale disconnect/fail callbacks.
+    private var connectingPeripheral: CBPeripheral?
     private var txCharacteristic: CBCharacteristic?
     private var rxCharacteristic: CBCharacteristic?
     private let bes2700MtuLimit = 509
@@ -1479,8 +1649,16 @@ class MentraLive: NSObject, SGCManager {
 
     // State Tracking
     private var isScanning = false
+    private var manualDiscoveryActive = false
     private var isConnecting = false
     private var isKilled = false
+    /// Glasses opened pairing window — stand down without forgetting identity/bonds.
+    private var pairingYieldActive = false
+    private var pairingYieldAwaitingReclaim = false
+    private var pairingYieldEndWorkItem: DispatchWorkItem?
+    /// Hold GATT teardown until the unpair write can leave the phone.
+    private var unpairFlushPending = false
+    private var unpairFlushWorkItem: DispatchWorkItem?
     private var reconnectAttempts = 0
     private var isNewVersion = false
     private var peerWireProtocolVersion = 0
@@ -1546,6 +1724,7 @@ class MentraLive: NSObject, SGCManager {
 
     /// BES OTA progress tracking - only send to UI on 5% increments
     private var lastBesOtaProgress = -1
+    private var besOtaHeartbeatSuppressedUntil: TimeInterval = 0
 
     // Cached OTA session context from last ota_status — used to fill in session fields for sr_adota
     private var cachedOtaSessionId: String?
@@ -1598,6 +1777,16 @@ class MentraLive: NSObject, SGCManager {
     // MARK: - React Native Interface
 
     private var discoveredPeripherals = [String: CBPeripheral]() // name -> peripheral
+    /// Last advertisement pairing trailer for a discovered name. Re-emits (already-
+    /// connected / scan replay) must not drop these flags: omitting them makes a
+    /// secure idle unit look like pairable legacy firmware.
+    private var discoveredAdvPairing = [String: CachedAdvPairing]()
+
+    private struct CachedAdvPairing {
+        let pairingMode: Bool
+        let pairingCode: String?
+        let securePairingCapable: Bool
+    }
 
     func findCompatibleDevices() {
         Bridge.log("Finding compatible Mentra Live glasses")
@@ -1615,11 +1804,95 @@ class MentraLive: NSObject, SGCManager {
             // clear the saved device name:
             UserDefaults.standard.set("", forKey: PREFS_DEVICE_NAME)
 
+            manualDiscoveryActive = true
             startScan()
+            emitConnectedPendingDeviceForPairingScan()
         }
     }
 
+    func isPairingYieldActive() -> Bool {
+        pairingYieldActive
+    }
+
+    private func enterPairingYield(windowMs: Int) {
+        pairingYieldActive = true
+        pairingYieldAwaitingReclaim = false
+        pairingYieldEndWorkItem?.cancel()
+        if isScanning {
+            stopScan()
+        }
+        // Publish disconnect immediately for Phone A UI. didDisconnectPeripheral may lag
+        // or race with cancelPeripheralConnection; do not wait on it for stand-down.
+        isConnecting = false
+        connected = false
+        fullyBooted = false
+        glassesSessionId = nil
+        readinessCompletedThisBleSession = false
+        rgbLedAuthorityClaimed = false
+        stopAllTimers()
+        closeL2capFileChannel()
+        txCharacteristic = nil
+        rxCharacteristic = nil
+        updateConnectionState(ConnTypes.DISCONNECTED)
+        if let peripheral = connectedPeripheral {
+            centralManager?.cancelPeripheralConnection(peripheral)
+        }
+        connectedPeripheral = nil
+        connectingPeripheral = nil
+        // Stand down for the whole window. Probing GATT during yield races the new
+        // phone for the single BLE slot and is exactly what entering_pairing_mode forbids.
+
+        let work = DispatchWorkItem { [weak self] in
+            guard let self else { return }
+            Bridge.log("LIVE: Pairing yield ended — resume reconnect if still owned")
+            self.pairingYieldActive = false
+            self.pairingYieldAwaitingReclaim = true
+            self.pairingYieldEndWorkItem = nil
+            if !self.isKilled, self.connectedPeripheral == nil {
+                self.handleReconnection()
+            }
+        }
+        pairingYieldEndWorkItem = work
+        DispatchQueue.main.asyncAfter(deadline: .now() + .milliseconds(windowMs), execute: work)
+    }
+
+    /// Pairing/auth failures after yield — CoreBluetooth codes, not localized strings.
+    /// Connection timeouts are not owner-loss.
+    private static func isPairingAuthFailure(_ error: Error?) -> Bool {
+        guard let error = error as NSError? else { return false }
+        if error.domain == CBATTErrorDomain {
+            return error.code == CBATTError.insufficientAuthentication.rawValue
+                || error.code == CBATTError.insufficientEncryption.rawValue
+        }
+        if error.domain == CBErrorDomain {
+            return error.code == CBError.peerRemovedPairingInformation.rawValue
+        }
+        return false
+    }
+
+    private func clearSavedGlassesAfterOwnerLoss(reason: String) {
+        Bridge.log("LIVE: Owner loss (\(reason)) — clearing saved glasses")
+        pairingYieldAwaitingReclaim = false
+        pairingYieldActive = false
+        pairingYieldEndWorkItem?.cancel()
+        pairingYieldEndWorkItem = nil
+        forget()
+        Task { @MainActor in
+            DeviceStore.shared.apply("bluetooth", "default_wearable", "")
+            DeviceStore.shared.apply("bluetooth", "device_name", "")
+            DeviceStore.shared.apply("bluetooth", "device_address", "")
+        }
+        Bridge.saveSetting("default_wearable", "")
+        Bridge.saveSetting("device_name", "")
+        Bridge.saveSetting("device_address", "")
+        Bridge.sendTypedMessage("owner_replaced", body: ["reason": reason])
+    }
+
     func connectById(_ deviceName: String) {
+        if pairingYieldActive {
+            Bridge.log("LIVE: connectById blocked — pairing yield active")
+            return
+        }
         Bridge.log("connectById: \(deviceName)")
         // Save the device name for future reconnection
         UserDefaults.standard.set(deviceName, forKey: PREFS_DEVICE_NAME)
@@ -1644,7 +1917,7 @@ class MentraLive: NSObject, SGCManager {
             {
                 Bridge.log("Found already-connected peripheral: \(name)")
                 discoveredPeripherals[name] = peripheral
-                emitDiscoveredDevice(name)
+                emitDiscoveredDeviceFromCache(name)
 
                 // Check if this is the device we want
                 if let savedDeviceName = UserDefaults.standard.string(
@@ -1670,6 +1943,10 @@ class MentraLive: NSObject, SGCManager {
     }
 
     @objc func disconnect() {
+        if unpairFlushPending {
+            Bridge.log("LIVE: disconnect deferred — waiting for unpair write")
+            return
+        }
         Bridge.log("LIVE: disconnect() -Disconnecting from Mentra Live glasses")
 
         // if rgbLedAuthorityClaimed {
@@ -1695,6 +1972,8 @@ class MentraLive: NSObject, SGCManager {
 
     /// Start the micbeat mechanism to keep LC3 audio streaming active
     private func startMicBeat() {
+        // A resumed custom-audio stream starts a new sequence domain.
+        DeviceManager.shared.resetMicSequenceBaseline()
         Bridge.log("LIVE: 🎤 Starting micbeat mechanism")
         micBeatCount = 0
 
@@ -1941,6 +2220,18 @@ class MentraLive: NSObject, SGCManager {
     private var pending: PendingMessage?
     private var pendingMessageTimer: Timer?
 
+    /// ACK state belongs to the BLE session that sent the message. If the link drops while an ACK
+    /// is outstanding, keeping `pending` set permanently blocks the command queue because the
+    /// timeout timer is stopped during disconnect. Release both together before reconnecting.
+    private func resetPendingAckState(reason: String) {
+        pendingMessageTimer?.invalidate()
+        pendingMessageTimer = nil
+
+        guard let pendingMessage = pending else { return }
+        pending = nil
+        Bridge.log("LIVE: Cleared pending ACK mId \(pendingMessage.id) because \(reason)")
+    }
+
     actor CommandQueue {
         private var commands: [PendingMessage] = []
 
@@ -2079,7 +2370,10 @@ class MentraLive: NSObject, SGCManager {
     // MARK: - BLE Scanning
 
     private func startScan() {
-        // guard !isScanning else { return }
+        if pairingYieldActive {
+            Bridge.log("LIVE: startScan blocked — pairing yield active")
+            return
+        }
 
         guard centralManager!.state == .poweredOn else {
             Bridge.log("Attempting to scan but bluetooth is not powered on.")
@@ -2087,6 +2381,7 @@ class MentraLive: NSObject, SGCManager {
         }
 
         Bridge.log("Starting BLE scan for Mentra Live glasses")
+        discoveredAdvPairing.removeAll()
         isScanning = true
 
         startReadinessCheckLoop()
@@ -2103,12 +2398,6 @@ class MentraLive: NSObject, SGCManager {
 
         centralManager?.scanForPeripherals(withServices: nil, options: scanOptions)
 
-        // emit already discovered peripherals:
-        for (_, peripheral) in discoveredPeripherals {
-            Bridge.log("LIVE: (Already discovered) peripheral: \(peripheral.name ?? "Unknown")")
-            emitDiscoveredDevice(peripheral.name!)
-        }
-
         // var dName = DeviceManager.shared.deviceName
         // if dName.isEmpty {
         //     dName = "MENTRA_LIVE"
@@ -2126,6 +2415,7 @@ class MentraLive: NSObject, SGCManager {
     }
 
     func stopScan() {
+        manualDiscoveryActive = false
         guard isScanning else { return }
 
         centralManager?.stopScan()
@@ -2137,10 +2427,16 @@ class MentraLive: NSObject, SGCManager {
     // MARK: - Connection Management
 
     private func connectToDevice(_ peripheral: CBPeripheral) {
+        if pairingYieldActive {
+            Bridge.log("LIVE: connectToDevice blocked — pairing yield active")
+            isConnecting = false
+            return
+        }
         Bridge.log("LIVE: Connecting to device: \(peripheral.identifier.uuidString)")
 
         isConnecting = true
         updateConnectionState(ConnTypes.CONNECTING)
+        connectingPeripheral = peripheral
         connectedPeripheral = peripheral
         peripheral.delegate = self
 
@@ -2185,6 +2481,11 @@ class MentraLive: NSObject, SGCManager {
             return
         }
 
+        if pairingYieldActive {
+            Bridge.log("LIVE: Reconnection aborted - pairing yield active")
+            return
+        }
+
         // Check if we've exceeded max attempts
         if reconnectAttempts >= MAX_RECONNECT_ATTEMPTS {
             Bridge.log("LIVE: Maximum reconnection attempts reached (\(MAX_RECONNECT_ATTEMPTS))")
@@ -2217,6 +2518,10 @@ class MentraLive: NSObject, SGCManager {
             guard let self = self else { return }
 
             // Use peripheral presence, not connectionState: we stay CONNECTING during backoff until scan/connect.
+            if self.pairingYieldActive {
+                Bridge.log("LIVE: Reconnection aborted - pairing yield active")
+                return
+            }
             if self.connectedPeripheral == nil, !self.isKilled {
                 // Check for last known device name to start scan
                 if let lastDeviceName = UserDefaults.standard.string(
@@ -2446,11 +2751,21 @@ class MentraLive: NSObject, SGCManager {
 
         switch type {
         case "glasses_ready":
+            // A queued glasses_ready from the connection we just cancelled for yield
+            // must not close the pairing window. Only accept readiness on a live GATT.
+            if pairingYieldActive && connectedPeripheral == nil {
+                Bridge.log("LIVE: Ignoring stale glasses_ready during pairing yield")
+                return
+            }
             // glasses_ready is a REMOTE wire-session reset: the glasses ran
             // onTransportReset() before sending it, so their side is back on legacy
             // framing regardless of what this side negotiated earlier. Start a fresh
             // wire epoch (clears v2-active state that would otherwise gate the
             // handshake off), then negotiate from the caps this message advertises.
+            pairingYieldAwaitingReclaim = false
+            pairingYieldActive = false
+            pairingYieldEndWorkItem?.cancel()
+            pairingYieldEndWorkItem = nil
             resetWireNegotiationState()
             parsePeerWireCaps(json)
             maybeSendWireHandshake()
@@ -2602,6 +2917,26 @@ class MentraLive: NSObject, SGCManager {
         case "pong":
             Bridge.log("LIVE: Received pong response - connection healthy")
 
+        case "entering_pairing_mode":
+            let windowMs = max(5_000, min(180_000, json["window_ms"] as? Int ?? 120_000))
+            Bridge.log("LIVE: Glasses entering pairing mode — yield \(windowMs)ms (no forget)")
+            enterPairingYield(windowMs: windowMs)
+            let body: [String: Any] = [
+                "window_ms": windowMs,
+                "reason": json["reason"] as? String ?? "user_gesture",
+            ]
+            Bridge.sendTypedMessage("entering_pairing_mode", body: body)
+
+        case "pairing_info":
+            Bridge.sendPairingInfo(
+                hadPreviousBond: json["had_previous_bond"] as? Bool ?? false,
+                pairingCode: json["pairing_code"] as? String,
+                classicBondReady: json["classic_bond_ready"] as? Bool ?? false,
+                // Legacy firmware that omits this field is not secure-capable.
+                securePairingCapable: json["secure_pairing_capable"] as? Bool ?? false,
+                protocolVersion: json["protocol_version"] as? Int ?? 1
+            )
+
         case "imu_response", "imu_stream_response", "imu_gesture_response",
              "imu_gesture_subscribed", "imu_ack", "imu_error":
             // Handle IMU-related responses
@@ -2669,6 +3004,7 @@ class MentraLive: NSObject, SGCManager {
             if let seq = json["sq"] as? [String] ?? json["step_sequence"] as? [String], !seq.isEmpty {
                 cachedOtaStepSequence = seq
             }
+            updateBesOtaHeartbeatGuard(stepType: osStepType, phase: osPhase, status: osStatus)
 
             Bridge.log("LIVE: 📱 OTA status - step \(osCurrentStep)/\(osTotalSteps) \(osPhase) \(osStatus) \(osOverallPercent)%")
 
@@ -2702,6 +3038,7 @@ class MentraLive: NSObject, SGCManager {
             } else {
                 unified = "in_progress"
             }
+            updateBesOtaHeartbeatGuard(stepType: currentUpdate, phase: legacyPhase, status: unified)
             Bridge.log(
                 "LIVE: 📱 Legacy ota_progress → ota_status: \(legacyStage) \(legacyStatus) \(legacyProgress)%"
             )
@@ -2761,9 +3098,19 @@ class MentraLive: NSObject, SGCManager {
                 if let systemTimeMs = fields["system_time_ms"] as? NSNumber {
                     DeviceStore.shared.apply("glasses", "systemTimeMs", systemTimeMs.int64Value)
                 }
+                if let hotspotOtaVersion = fields["hotspot_ota_version"] as? NSNumber {
+                    DeviceStore.shared.apply(
+                        "glasses",
+                        "hotspotOtaVersion",
+                        hotspotOtaVersion.intValue
+                    )
+                }
                 if let bluetoothMacAddress = nonEmptyStringValue(fields, "bt_mac_address") {
                     DeviceStore.shared.apply("glasses", "bluetoothMacAddress", bluetoothMacAddress)
                 }
+                if let wifiMacAddress = nonEmptyStringValue(fields, "wifi_mac_address") {
+                    DeviceStore.shared.apply("glasses", "wifiMacAddress", wifiMacAddress)
+                }
                 if let serialNumber = nonEmptyStringValue(fields, "serial_number") {
                     DeviceStore.shared.apply("glasses", "serialNumber", serialNumber)
                 }
@@ -2829,6 +3176,19 @@ class MentraLive: NSObject, SGCManager {
         cachedOtaCurrentStep = 0
         cachedOtaStepSequence = nil
         lastBesOtaProgress = -1
+        // The bounded UART-ownership lease is transport state, not session-cache state. Keep it
+        // through a BLE reconnect so heartbeats cannot resume while BES still owns the UART.
+    }
+
+    private func updateBesOtaHeartbeatGuard(stepType: String, phase: String, status: String) {
+        guard stepType.lowercased() == "bes", phase.lowercased() == "install" else { return }
+        switch status.lowercased() {
+        case "failed", "complete", "step_complete", "finished", "success":
+            besOtaHeartbeatSuppressedUntil = 0
+        default:
+            besOtaHeartbeatSuppressedUntil =
+                ProcessInfo.processInfo.systemUptime + BES_OTA_HEARTBEAT_LEASE_SEC
+        }
     }
 
     /// Falls back to raw besProgress when step sequence is unavailable.
@@ -3000,62 +3360,41 @@ class MentraLive: NSObject, SGCManager {
                 var progress = ((rawProgress + 2) / 5) * 5
                 if progress > 100 { progress = 100 }
 
-                // Only send if progress changed to a new 5% increment
                 let isTerminalStatus = type == "success" || type == "error" || type == "fail"
-                if progress == lastBesOtaProgress && !isTerminalStatus {
-                    break // Skip duplicate progress
-                }
-                lastBesOtaProgress = progress
-
-                Bridge.log(
-                    "LIVE: 📱 BES OTA progress via sr_adota - type: \(type), raw: \(rawProgress)%, rounded: \(progress)%"
-                )
-
-                // Determine status and error message based on type
-                var besOtaStatus: String
                 var besOtaProgressVal: Int
                 var besOtaErrorMessage: String? = nil
 
-                // Order matters here: check completion (rawProgress >= 100 OR success) BEFORE
-                // type=="update", because some BES firmware emits the final 100% tick with
-                // type=="update" rather than type=="success". Treating that as PROGRESS would
-                // leave the UI stuck at 100% forever.
-                if type == "success" || rawProgress >= 100 {
-                    besOtaStatus = "FINISHED"
+                let failed = type == "error" || type == "fail"
+                let succeeded = type == "success"
+                if isTerminalStatus {
+                    besOtaHeartbeatSuppressedUntil = 0
+                } else {
+                    // Refresh before progress de-duplication: raw progress proves the BES
+                    // transfer is active even when the rounded UI value is unchanged.
+                    besOtaHeartbeatSuppressedUntil =
+                        ProcessInfo.processInfo.systemUptime + BES_OTA_HEARTBEAT_LEASE_SEC
+                }
+                if succeeded {
                     besOtaProgressVal = 100
-                    lastBesOtaProgress = -1 // Reset for next OTA
-                } else if type == "error" || type == "fail" {
-                    besOtaStatus = "FAILED"
+                } else if failed {
                     besOtaProgressVal = progress
                     besOtaErrorMessage = bodyObj["message"] as? String ?? "BES update failed"
-                    lastBesOtaProgress = -1 // Reset for next OTA
-                } else if type == "update" {
-                    besOtaStatus = "PROGRESS"
-                    besOtaProgressVal = progress
                 } else {
-                    // Unknown type, treat as progress
-                    besOtaStatus = "PROGRESS"
-                    besOtaProgressVal = progress
+                    // A raw update:100 precedes whole-image CRC/apply and is not terminal.
+                    besOtaProgressVal = min(progress, 95)
                 }
 
-                let syntheticStatus: String
-                if besOtaStatus == "FINISHED" {
-                    // The glasses power-cycle right after the final BES tick, so a session
-                    // whose BES step is the LAST step never gets a follow-up ota_status from
-                    // the glasses — consumers mapping on this synthetic status would otherwise
-                    // never see a terminal state. Emit "complete" for the final step;
-                    // mid-session BES steps keep "step_complete" so session-level trackers
-                    // advance normally. Unknown sessions (cachedOtaTotalSteps == 0, e.g.
-                    // legacy glasses that never sent an ota_status) conservatively keep
-                    // "step_complete".
-                    syntheticStatus = (cachedOtaTotalSteps > 0 && cachedOtaCurrentStep >= cachedOtaTotalSteps)
-                        ? "complete"
-                        : "step_complete"
-                } else if besOtaStatus == "FAILED" {
-                    syntheticStatus = "failed"
-                } else {
-                    syntheticStatus = "in_progress"
+                // Only send if nonterminal display progress changed to a new 5% increment.
+                if besOtaProgressVal == lastBesOtaProgress && !isTerminalStatus {
+                    break
                 }
+                lastBesOtaProgress = isTerminalStatus ? -1 : besOtaProgressVal
+
+                Bridge.log(
+                    "LIVE: 📱 BES OTA progress via sr_adota - type: \(type), raw: \(rawProgress)%, rounded: \(progress)%, display: \(besOtaProgressVal)%"
+                )
+
+                let syntheticStatus = succeeded ? "step_complete" : (failed ? "failed" : "in_progress")
                 let sid = cachedOtaSessionId ?? ""
                 let totalSteps = cachedOtaTotalSteps > 0 ? cachedOtaTotalSteps : 1
                 let currentStep = cachedOtaCurrentStep > 0 ? cachedOtaCurrentStep : 1
@@ -3210,6 +3549,17 @@ class MentraLive: NSObject, SGCManager {
         sendJson(json, wakeUp: true)
     }
 
+    func sendWifiAdbState(_ enabled: Bool) {
+        Bridge.log("LIVE: 🔧 Sending Wi-Fi ADB state: \(enabled)")
+
+        let json: [String: Any] = [
+            "type": "set_wifi_adb_state",
+            "enabled": enabled,
+        ]
+
+        sendJson(json, wakeUp: true)
+    }
+
     func sendSetSystemTime(_ timestampMs: Int64) {
         Bridge.log("LIVE: ⏰ Sending set_system_time: \(timestampMs)")
 
@@ -3329,7 +3679,6 @@ class MentraLive: NSObject, SGCManager {
         {
             json["ota_version_url"] = otaVersionUrl
         }
-
         sendJson(json, wakeUp: true)
     }
 
@@ -3500,17 +3849,9 @@ class MentraLive: NSObject, SGCManager {
             return
         }
 
-        let sequenceNumber = Int8(bitPattern: data[1])
+        let sequenceNumber = Int(data[1])
         let lc3Data = data.subdata(in: 2 ..< data.count)
 
-        // Validate sequence number for packet loss detection
-        if lastReceivedLc3Sequence != -1 && (lastReceivedLc3Sequence &+ 1) != sequenceNumber {
-            Bridge.log(
-                "LIVE: LC3 packet sequence mismatch. Expected: \(lastReceivedLc3Sequence &+ 1), Got: \(sequenceNumber)"
-            )
-        }
-        lastReceivedLc3Sequence = sequenceNumber
-
         // // Decode LC3 to PCM using existing PcmConverter
         // let pcmConverter = PcmConverter()
         // guard let pcmData = pcmConverter.decode(lc3Data) as? Data, pcmData.count > 0 else {
@@ -3524,7 +3865,7 @@ class MentraLive: NSObject, SGCManager {
         // Bridge.log(
         //     "LIVE: Processed LC3 audio seq=\(sequenceNumber), \(lc3Data.count) bytes"
         // )
-        DeviceManager.shared.handleGlassesMicData(lc3Data, 40)
+        DeviceManager.shared.handleGlassesMicData(lc3Data, 40, sequenceNumber: sequenceNumber)
 
         // Bridge.log(
         //     "LIVE: Processed LC3 audio seq=\(sequenceNumber), \(lc3Data.count)→\(pcmData.count) bytes"
@@ -5068,6 +5409,10 @@ class MentraLive: NSObject, SGCManager {
             Bridge.log("LIVE: Skipping heartbeat - glasses not fully booted or not connected")
             return
         }
+        if ProcessInfo.processInfo.systemUptime < besOtaHeartbeatSuppressedUntil {
+            Bridge.log("LIVE: Skipping heartbeat while BES OTA owns the UART")
+            return
+        }
 
         // Send ping message to glasses hardware (no ACK needed for heartbeats)
         let pingJson: [String: Any] = ["type": "ping"]
@@ -5181,16 +5526,89 @@ class MentraLive: NSObject, SGCManager {
         stopReadinessCheckLoop()
         stopConnectionTimeout()
         stopMicBeat() // Stop LC3 audio micbeat
-        pendingMessageTimer?.invalidate()
-        pendingMessageTimer = nil
+        resetPendingAckState(reason: "transport timers stopped")
         reconnectionWorkItem?.cancel()
         reconnectionWorkItem = nil
     }
 
     // MARK: - Event Emission
 
-    private func emitDiscoveredDevice(_ name: String, identifier: String = "", rssi: Int? = nil) {
-        Bridge.sendDiscoveredDevice("Mentra Live", name, deviceAddress: identifier, rssi: rssi)
+    /// A selected pairing target can stop advertising once GATT connects, before readiness
+    /// promotes it to the default device. Re-emit only that explicit pending target; an
+    /// established owner's connected glasses have no pending identity and remain hidden.
+    private func emitConnectedPendingDeviceForPairingScan() {
+        guard manualDiscoveryActive, !pairingYieldActive, let peripheral = connectedPeripheral,
+              let name = peripheral.name,
+              MentraLivePendingPairingTarget.shouldRecover(
+                  isConnected: peripheral.state == .connected,
+                  connectedName: name,
+                  connectedIdentifier: peripheral.identifier.uuidString,
+                  pendingName: DeviceStore.shared.get("bluetooth", "pending_device_name") as? String ?? "",
+                  pendingIdentifier: DeviceStore.shared.get("bluetooth", "pending_device_address") as? String ?? ""
+              )
+        else {
+            return
+        }
+
+        Bridge.log("LIVE: Pairing scan: recovering connected pending target \(name) (\(peripheral.identifier))")
+        emitDiscoveredDevice(
+            name,
+            identifier: peripheral.identifier.uuidString,
+            pairingMode: true,
+            pairingCode: nil,
+            securePairingCapable: DeviceStore.shared.get(
+                "bluetooth",
+                "pending_device_secure_pairing_capable"
+            ) as? Bool
+        )
+    }
+
+    private func cacheAdvPairing(
+        _ name: String,
+        pairingMode: Bool,
+        pairingCode: String?,
+        securePairingCapable: Bool
+    ) {
+        discoveredAdvPairing[name] = CachedAdvPairing(
+            pairingMode: pairingMode,
+            pairingCode: pairingCode,
+            securePairingCapable: securePairingCapable
+        )
+    }
+
+    private func emitDiscoveredDeviceFromCache(
+        _ name: String,
+        identifier: String = "",
+        rssi: Int? = nil
+    ) {
+        let cached = discoveredAdvPairing[name]
+        emitDiscoveredDevice(
+            name,
+            identifier: identifier,
+            rssi: rssi,
+            pairingMode: cached?.pairingMode,
+            pairingCode: cached?.pairingCode,
+            securePairingCapable: cached?.securePairingCapable
+        )
+    }
+
+    private func emitDiscoveredDevice(
+        _ name: String,
+        identifier: String = "",
+        rssi: Int? = nil,
+        pairingMode: Bool? = nil,
+        pairingCode: String? = nil,
+        securePairingCapable: Bool? = nil
+    ) {
+        Bridge.sendDiscoveredDevice(
+            "Mentra Live",
+            name,
+            deviceAddress: identifier,
+            rssi: rssi,
+            pairingMode: pairingMode,
+            pairingCode: pairingCode,
+            securePairingCapable: securePairingCapable
+        )
     }
 
     private func emitStopScanEvent() {
@@ -5279,6 +5697,9 @@ class MentraLive: NSObject, SGCManager {
         Bridge.log("Destroying MentraLiveManager")
 
         isKilled = true
+        unpairFlushWorkItem?.cancel()
+        unpairFlushWorkItem = nil
+        unpairFlushPending = false
 
         // Stop scanning
         if isScanning {
@@ -5312,6 +5733,8 @@ class MentraLive: NSObject, SGCManager {
         DeviceStore.shared.apply("glasses", "hotspotGatewayIp", "")
 
         connectedPeripheral = nil
+        discoveredPeripherals.removeAll()
+        discoveredAdvPairing.removeAll()
         centralManager?.delegate = nil
         centralManager = nil
 
@@ -6521,6 +6944,17 @@ extension MentraLive {
         stopVideoRecording(requestId: requestId, webhookUrl: nil, authToken: nil)
     }
 
+    func queryVideoRecordingStatus(requestId: String) {
+        guard connectionState == ConnTypes.CONNECTED else {
+            Bridge.log("Cannot query video recording status - not connected")
+            return
+        }
+        sendJson([
+            "type": "get_video_recording_status",
+            "requestId": requestId,
+        ])
+    }
+
     func stopVideoRecording(requestId: String, webhookUrl: String?, authToken: String?) {
         Bridge.log(
             "Stopping video recording on glasses: requestId=\(requestId), webhook=\((webhookUrl?.isEmpty ?? true) ? "none" : "set")"