@mentra/bluetooth-sdk 3.3.0-dev.548 → 3.3.0-dev.551

package/android/src/main/java/com/mentra/bluetoothsdk/GeneratedReleaseMetadata.kt

@@ -3,9 +3,9 @@ package com.mentra.bluetoothsdk
 /** Generated by release CI. Do not edit in a release checkout. */
 internal object GeneratedReleaseMetadata {
     const val FAMILY_BASE_VERSION: String = "3.3.0"
-    const val RELEASE_IDENTITY: String = "3.3.0-dev.548"
-    const val RELEASE_SET_ID: String = "mentra-3.3.0-dev.548"
-    const val SOURCE_COMMIT: String = "b0f8be74e1aae531836532a849cd402c10d2e5ae"
-    const val OTA_MANIFEST_URL: String = "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-dev.548.json"
-    const val OTA_MANIFEST_SHA256: String = "372a283a731bf08e6c5070ab867cd2b86a87ee29a993d47c1a5f5c17a5d1596e"
+    const val RELEASE_IDENTITY: String = "3.3.0-dev.551"
+    const val RELEASE_SET_ID: String = "mentra-3.3.0-dev.551"
+    const val SOURCE_COMMIT: String = "f48a6c59f06665dd41924670434f47d359be0eb3"
+    const val OTA_MANIFEST_URL: String = "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-dev.551.json"
+    const val OTA_MANIFEST_SHA256: String = "9b17306f36c2610c818c112402d1491903cfa2f4ae3ded4ffc7a358ca5e7ad2e"
 }

package/build/generated/releaseMetadata.js

@@ -1,10 +1,10 @@
 export const BLUETOOTH_SDK_RELEASE_METADATA = Object.freeze({
     "schemaVersion": 1,
     "familyBaseVersion": "3.3.0",
-    "releaseIdentity": "3.3.0-dev.548",
-    "releaseSetId": "mentra-3.3.0-dev.548",
-    "sourceCommit": "b0f8be74e1aae531836532a849cd402c10d2e5ae",
-    "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-dev.548.json",
-    "otaManifestSha256": "372a283a731bf08e6c5070ab867cd2b86a87ee29a993d47c1a5f5c17a5d1596e"
+    "releaseIdentity": "3.3.0-dev.551",
+    "releaseSetId": "mentra-3.3.0-dev.551",
+    "sourceCommit": "f48a6c59f06665dd41924670434f47d359be0eb3",
+    "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-dev.551.json",
+    "otaManifestSha256": "9b17306f36c2610c818c112402d1491903cfa2f4ae3ded4ffc7a358ca5e7ad2e"
 });
 //# sourceMappingURL=releaseMetadata.js.map

package/build/generated/releaseMetadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"releaseMetadata.js","sourceRoot":"","sources":["../../src/generated/releaseMetadata.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,8BAA8B,GAA0C,MAAM,CAAC,MAAM,CAAC;IACjG,eAAe,EAAE,CAAC;IAClB,mBAAmB,EAAE,OAAO;IAC5B,iBAAiB,EAAE,eAAe;IAClC,cAAc,EAAE,sBAAsB;IACtC,cAAc,EAAE,0CAA0C;IAC1D,gBAAgB,EAAE,iIAAiI;IACnJ,mBAAmB,EAAE,kEAAkE;CACxF,CAAC,CAAA","sourcesContent":["/** Generated by release CI. Do not edit in a release checkout. */\nexport interface BluetoothSdkReleaseMetadata {\n  schemaVersion: 1\n  familyBaseVersion: string | null\n  releaseIdentity: string | null\n  releaseSetId: string | null\n  sourceCommit: string | null\n  otaManifestUrl: string | null\n  otaManifestSha256: string | null\n}\n\nexport const BLUETOOTH_SDK_RELEASE_METADATA: Readonly<BluetoothSdkReleaseMetadata> = Object.freeze({\n  \"schemaVersion\": 1,\n  \"familyBaseVersion\": \"3.3.0\",\n  \"releaseIdentity\": \"3.3.0-dev.548\",\n  \"releaseSetId\": \"mentra-3.3.0-dev.548\",\n  \"sourceCommit\": \"b0f8be74e1aae531836532a849cd402c10d2e5ae\",\n  \"otaManifestUrl\": \"https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-dev.548.json\",\n  \"otaManifestSha256\": \"372a283a731bf08e6c5070ab867cd2b86a87ee29a993d47c1a5f5c17a5d1596e\"\n})\n"]}
+{"version":3,"file":"releaseMetadata.js","sourceRoot":"","sources":["../../src/generated/releaseMetadata.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,8BAA8B,GAA0C,MAAM,CAAC,MAAM,CAAC;IACjG,eAAe,EAAE,CAAC;IAClB,mBAAmB,EAAE,OAAO;IAC5B,iBAAiB,EAAE,eAAe;IAClC,cAAc,EAAE,sBAAsB;IACtC,cAAc,EAAE,0CAA0C;IAC1D,gBAAgB,EAAE,iIAAiI;IACnJ,mBAAmB,EAAE,kEAAkE;CACxF,CAAC,CAAA","sourcesContent":["/** Generated by release CI. Do not edit in a release checkout. */\nexport interface BluetoothSdkReleaseMetadata {\n  schemaVersion: 1\n  familyBaseVersion: string | null\n  releaseIdentity: string | null\n  releaseSetId: string | null\n  sourceCommit: string | null\n  otaManifestUrl: string | null\n  otaManifestSha256: string | null\n}\n\nexport const BLUETOOTH_SDK_RELEASE_METADATA: Readonly<BluetoothSdkReleaseMetadata> = Object.freeze({\n  \"schemaVersion\": 1,\n  \"familyBaseVersion\": \"3.3.0\",\n  \"releaseIdentity\": \"3.3.0-dev.551\",\n  \"releaseSetId\": \"mentra-3.3.0-dev.551\",\n  \"sourceCommit\": \"f48a6c59f06665dd41924670434f47d359be0eb3\",\n  \"otaManifestUrl\": \"https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-dev.551.json\",\n  \"otaManifestSha256\": \"9b17306f36c2610c818c112402d1491903cfa2f4ae3ded4ffc7a358ca5e7ad2e\"\n})\n"]}

package/ios/Source/BluetoothBackgroundMode.swift

@@ -0,0 +1,32 @@
+import Foundation
+
+/// Whether the host app lets iOS keep the glasses link working while the app is suspended.
+///
+/// The SDK keeps a pending reconnection open after the glasses drop the link (for example while
+/// their Bluetooth chip restarts during a software update). iOS completes it, and delivers BLE
+/// events, only to apps that declare the `bluetooth-central` background mode. A Swift package
+/// cannot declare it for the app, so the SDK checks it and warns instead.
+enum BluetoothBackgroundMode {
+    static let requiredMode = "bluetooth-central"
+
+    /// Platform-independent plist check, so tests exercise it on every host.
+    static func declaresBluetoothCentral(_ infoDictionary: [String: Any]?) -> Bool {
+        guard let modes = infoDictionary?["UIBackgroundModes"] as? [String] else { return false }
+        return modes.contains(requiredMode)
+    }
+
+    static func isDeclared(in infoDictionary: [String: Any]?) -> Bool {
+        #if os(iOS)
+            return declaresBluetoothCentral(infoDictionary)
+        #else
+            // macOS apps are not suspended the same way and have no background modes.
+            return true
+        #endif
+    }
+
+    static let missingWarning =
+        "MentraBluetoothSDK: WARNING Info.plist is missing UIBackgroundModes `bluetooth-central`. "
+            + "While the phone is locked or the app is in the background, iOS will not reconnect to "
+            + "the glasses after a link drop (for example during a software update) until the app "
+            + "is opened. See https://docs.mentraglass.com/bluetooth-sdk/ios#background-operation"
+}

package/ios/Source/BluetoothSdkDefaults.swift

@@ -16,7 +16,7 @@ enum BluetoothSdkDefaults {
     /// silently disable it on every pair the app touches.
     static let autoPowerOffEnabled = false
     private static let infoSdkVersionKey = "MentraBluetoothSdkVersion"
-    private static let swiftPackageSdkVersion = "3.3.0-dev.548"
+    private static let swiftPackageSdkVersion = "3.3.0-dev.551"
     private static let swiftPackageSdkVersionPlaceholder = "__MENTRA" + "_BLUETOOTH_SDK_VERSION__"
 
     private static func normalizedSdkVersion(_ value: String?) -> String? {

package/ios/Source/GeneratedReleaseMetadata.swift

@@ -3,9 +3,9 @@ import Foundation
 /// Generated by release CI. Do not edit in a release checkout.
 enum GeneratedReleaseMetadata {
     static let familyBaseVersion = "3.3.0"
-    static let releaseIdentity = "3.3.0-dev.548"
-    static let releaseSetId = "mentra-3.3.0-dev.548"
-    static let sourceCommit = "b0f8be74e1aae531836532a849cd402c10d2e5ae"
-    static let otaManifestUrl = "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-dev.548.json"
-    static let otaManifestSha256 = "372a283a731bf08e6c5070ab867cd2b86a87ee29a993d47c1a5f5c17a5d1596e"
+    static let releaseIdentity = "3.3.0-dev.551"
+    static let releaseSetId = "mentra-3.3.0-dev.551"
+    static let sourceCommit = "f48a6c59f06665dd41924670434f47d359be0eb3"
+    static let otaManifestUrl = "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-dev.551.json"
+    static let otaManifestSha256 = "9b17306f36c2610c818c112402d1491903cfa2f4ae3ded4ffc7a358ca5e7ad2e"
 }

package/ios/Source/MentraBluetoothSDK.swift

@@ -299,8 +299,22 @@ public final class MentraBluetoothSDK {
     private let wifiSessionCapabilities = WifiSessionCapabilities()
     private var configuredOtaVersionUrl: String?
 
+    /// Whether the app declares the `bluetooth-central` background mode. When false on iOS, the
+    /// glasses stay disconnected after a link drop until the user opens the app, so a software
+    /// update started on a locked phone stalls. Always true on macOS.
+    public static var supportsBackgroundReconnect: Bool {
+        BluetoothBackgroundMode.isDeclared(in: Bundle.main.infoDictionary)
+    }
+
+    private static var didWarnMissingBackgroundMode = false
+
     public init(configuration: MentraBluetoothSDKConfiguration = .default) {
         self.configuration = configuration
+        // Once per process: apps may create the SDK more than once.
+        if !Self.didWarnMissingBackgroundMode, !Self.supportsBackgroundReconnect {
+            Self.didWarnMissingBackgroundMode = true
+            Bridge.log(BluetoothBackgroundMode.missingWarning)
+        }
         analytics = BluetoothSdkAnalytics(configuration: configuration.analytics)
         bluetoothAvailabilityListenerId = BluetoothAvailability.shared.addStateListener { [weak self] state in
             Task { @MainActor [weak self] in

package/ios/Source/sgcs/MentraLive.swift

@@ -862,6 +862,7 @@ extension MentraLive: CBCentralManagerDelegate {
             Bridge.log("Connected to GATT server, discovering services...")
 
             self.stopConnectionTimeout()
+            self.clearPendingReconnectTracking()
             self.isConnecting = false
             self.connectingPeripheral = nil
             self.connectedPeripheral = peripheral
@@ -916,6 +917,7 @@ extension MentraLive: CBCentralManagerDelegate {
                 return
             }
             self.connectingPeripheral = nil
+            self.clearPendingReconnectTracking()
             Bridge.log("LIVE: Disconnected from GATT server")
 
             self.isConnecting = false
@@ -945,8 +947,9 @@ extension MentraLive: CBCentralManagerDelegate {
                 return
             }
 
-            // Attempt reconnection if not killed
-            if !self.isKilled {
+            // Prefer a pending direct reconnect: it is the only path iOS completes while the
+            // app is suspended. Fall back to the scan backoff when it does not apply.
+            if !self.isKilled, !self.reconnectDirectly(to: peripheral) {
                 self.handleReconnection()
             }
         }
@@ -966,6 +969,7 @@ extension MentraLive: CBCentralManagerDelegate {
             Bridge.log("LIVE: Failed to connect to peripheral: \(errorDescription)")
 
             self.stopConnectionTimeout()
+            self.clearPendingReconnectTracking()
             self.isConnecting = false
             self.closeL2capFileChannel()
             self.connectedPeripheral = nil
@@ -1646,6 +1650,10 @@ class MentraLive: NSObject, SGCManager {
     private static let glassesMediaVolumeTimeoutSec: TimeInterval = 2.0
 
     private var connectionTimeoutTimer: Timer?
+    /// Peripheral of an armed pending reconnect (see `reconnectDirectly`).
+    private var pendingReconnectPeripheral: CBPeripheral?
+    private var pendingReconnect = MentraLivePendingReconnect()
+    private var pendingReconnectSettleWorkItem: DispatchWorkItem?
     private var reconnectionWorkItem: DispatchWorkItem?
     private var requiresAncs = true
 
@@ -1713,6 +1721,7 @@ class MentraLive: NSObject, SGCManager {
 
             // clear the saved device name:
             UserDefaults.standard.set("", forKey: PREFS_DEVICE_NAME)
+            cancelPendingReconnect(reason: "discovery")
 
             manualDiscoveryActive = true
             startScan()
@@ -1725,6 +1734,7 @@ class MentraLive: NSObject, SGCManager {
     }
 
     private func enterPairingYield(windowMs: Int) {
+        cancelPendingReconnect(reason: "pairing_yield")
         pairingYieldActive = true
         pairingYieldAwaitingReclaim = false
         pairingYieldEndWorkItem?.cancel()
@@ -1805,6 +1815,7 @@ class MentraLive: NSObject, SGCManager {
             return
         }
         Bridge.log("connectById: \(deviceName)")
+        cancelPendingReconnect(reason: "connect_by_id")
         // Save the device name for future reconnection
         UserDefaults.standard.set(deviceName, forKey: PREFS_DEVICE_NAME)
 
@@ -2357,15 +2368,59 @@ class MentraLive: NSObject, SGCManager {
         }
         Bridge.log("LIVE: Connecting to device: \(peripheral.identifier.uuidString)")
 
+        // A timed attempt supersedes any pending reconnect: withdraw one aimed at other
+        // glasses, and drop tracking for this one so its settle timer cannot touch this attempt.
+        if let pending = pendingReconnectPeripheral, pending !== peripheral {
+            cancelPendingReconnect(reason: "superseded")
+        } else {
+            clearPendingReconnectTracking()
+        }
+
         isConnecting = true
         updateConnectionState(ConnTypes.CONNECTING)
         connectingPeripheral = peripheral
         connectedPeripheral = peripheral
-        peripheral.delegate = self
 
         // Set connection timeout
         startConnectionTimeout()
 
+        issueConnect(peripheral)
+    }
+
+    /// Re-arms a pending connection to the glasses that just dropped. Unlike `connectToDevice`,
+    /// it sets no timeout: CoreBluetooth keeps the request open until the glasses advertise
+    /// again (for example after a BES firmware reset), completes it in the background and wakes
+    /// the app. Discovery, connect-by-id, pairing yield and `destroy()` cancel it through
+    /// `cancelPendingReconnect`. Returns false when the policy does not apply, so the caller can
+    /// fall back to scanning.
+    private func reconnectDirectly(to peripheral: CBPeripheral) -> Bool {
+        guard let centralManager,
+              MentraLiveConnectionAttemptPolicy.shouldReconnectDirectly(
+                  isKilled: isKilled,
+                  pairingYieldActive: pairingYieldActive,
+                  bluetoothPoweredOn: centralManager.state == .poweredOn,
+                  peripheralName: peripheral.name,
+                  savedDeviceName: UserDefaults.standard.string(forKey: PREFS_DEVICE_NAME)
+              )
+        else {
+            return false
+        }
+        Bridge.log(
+            "LIVE: Pending direct reconnect to \(peripheral.identifier.uuidString) (no timeout, completes in background)"
+        )
+        isConnecting = true
+        updateConnectionState(ConnTypes.CONNECTING)
+        connectingPeripheral = peripheral
+        connectedPeripheral = peripheral
+        pendingReconnectPeripheral = peripheral
+        issueConnect(peripheral)
+        schedulePendingReconnectSettle(attempt: pendingReconnect.arm())
+        return true
+    }
+
+    /// The single CoreBluetooth connect call, shared by user-initiated and pending reconnects.
+    private func issueConnect(_ peripheral: CBPeripheral) {
+        peripheral.delegate = self
         #if os(macOS)
             centralManager?.connect(peripheral, options: nil)
         #else
@@ -2380,6 +2435,58 @@ class MentraLive: NSObject, SGCManager {
         #endif
     }
 
+    /// A pending connect never times out, so the glasses may simply never return (battery
+    /// dead, left behind). After the old scan backoff's span, report DISCONNECTED like that
+    /// backoff did, but keep the request armed: iOS still completes it whenever the glasses
+    /// advertise, and `didConnect` accepts it through `connectingPeripheral`.
+    private func schedulePendingReconnectSettle(attempt: Int) {
+        pendingReconnectSettleWorkItem?.cancel()
+        let work = DispatchWorkItem { [weak self] in
+            // Only the attempt that armed this timer may settle state; a failure, fallback
+            // connect or re-arm clears or replaces it.
+            guard let self, self.pendingReconnect.owns(attempt),
+                  self.connectionState != ConnTypes.CONNECTED
+            else { return }
+            Bridge.log("LIVE: Glasses still unreachable; reporting disconnected, pending reconnect stays armed")
+            self.pendingReconnectSettleWorkItem = nil
+            self.isConnecting = false
+            self.connectedPeripheral = nil
+            self.updateConnectionState(ConnTypes.DISCONNECTED)
+        }
+        pendingReconnectSettleWorkItem = work
+        DispatchQueue.main.asyncAfter(
+            deadline: .now() + .milliseconds(MentraLiveConnectionAttemptPolicy.pendingReconnectSettleMs),
+            execute: work
+        )
+    }
+
+    /// Stops tracking a pending reconnect after it connected; no CoreBluetooth call needed.
+    private func clearPendingReconnectTracking() {
+        pendingReconnectSettleWorkItem?.cancel()
+        pendingReconnectSettleWorkItem = nil
+        pendingReconnect.clear()
+        pendingReconnectPeripheral = nil
+    }
+
+    /// Withdraws a pending reconnect before the user retargets (discovery, connect-by-id,
+    /// pairing yield) or tears down, so iOS cannot later complete it to the previous glasses.
+    private func cancelPendingReconnect(reason: String) {
+        guard let peripheral = pendingReconnectPeripheral else {
+            clearPendingReconnectTracking()
+            return
+        }
+        clearPendingReconnectTracking()
+        Bridge.log("LIVE: Cancelling pending reconnect to \(peripheral.identifier.uuidString) (\(reason))")
+        if connectingPeripheral === peripheral {
+            connectingPeripheral = nil
+        }
+        if connectedPeripheral === peripheral, connectionState != ConnTypes.CONNECTED {
+            connectedPeripheral = nil
+        }
+        isConnecting = false
+        centralManager?.cancelPeripheralConnection(peripheral)
+    }
+
     /// Opt the firmware into ANCS only after iOS has authorized this accessory.
     /// Old firmware safely ignores the command, while new firmware stays inert
     /// for old mobile clients that never send it.
@@ -5897,6 +6004,7 @@ class MentraLive: NSObject, SGCManager {
         closeL2capFileChannel()
 
         // Disconnect BLE
+        cancelPendingReconnect(reason: "destroy")
         if let peripheral = connectedPeripheral {
             centralManager?.cancelPeripheralConnection(peripheral)
         }

package/ios/Source/sgcs/MentraLivePairingAdvertisement.swift

@@ -61,4 +61,51 @@ enum MentraLiveConnectionAttemptPolicy {
     ) -> Bool {
         !pairingYieldActive && matchesActiveAttempt
     }
+
+    /// How long a pending reconnect reports CONNECTING before settling to DISCONNECTED. Matches
+    /// the span of the scan backoff it replaces (1+2+4+8+16 s, then 30 s × 5 attempts).
+    static let pendingReconnectSettleMs = 181_000
+
+    /// Whether an unexpected link loss should re-arm a pending connection to the same
+    /// peripheral. iOS completes a pending `connect` whenever the glasses advertise again,
+    /// even while the app is suspended (phone locked), and wakes the app to handle it. A scan
+    /// without service filters returns nothing in the background, and the backoff timers that
+    /// drive it stop while the app is suspended, so the scan path alone never reconnects there.
+    static func shouldReconnectDirectly(
+        isKilled: Bool,
+        pairingYieldActive: Bool,
+        bluetoothPoweredOn: Bool,
+        peripheralName: String?,
+        savedDeviceName: String?
+    ) -> Bool {
+        guard !isKilled, !pairingYieldActive, bluetoothPoweredOn,
+              let peripheralName, !peripheralName.isEmpty,
+              let savedDeviceName
+        else {
+            return false
+        }
+        return peripheralName == savedDeviceName
+    }
+}
+
+/// Ownership of the one armed pending reconnect. Each arm returns a new attempt number, so a
+/// timer captured for an earlier attempt can tell it no longer owns the connection state after
+/// a failure, a fallback connect or a re-arm.
+struct MentraLivePendingReconnect {
+    private(set) var attempt = 0
+    private(set) var isArmed = false
+
+    mutating func arm() -> Int {
+        attempt += 1
+        isArmed = true
+        return attempt
+    }
+
+    mutating func clear() {
+        isArmed = false
+    }
+
+    func owns(_ candidate: Int) -> Bool {
+        isArmed && candidate == attempt
+    }
 }

package/ios/Tests/BluetoothBackgroundModeTests.swift

@@ -0,0 +1,32 @@
+@testable import MentraBluetoothSDK
+import XCTest
+
+final class BluetoothBackgroundModeTests: XCTestCase {
+    func testDetectsDeclaredBluetoothCentral() {
+        XCTAssertTrue(
+            BluetoothBackgroundMode.declaresBluetoothCentral(
+                ["UIBackgroundModes": ["audio", "bluetooth-central"]]
+            )
+        )
+    }
+
+    func testReportsMissingOrMalformedBackgroundModes() {
+        XCTAssertFalse(BluetoothBackgroundMode.declaresBluetoothCentral(nil))
+        XCTAssertFalse(BluetoothBackgroundMode.declaresBluetoothCentral([:]))
+        XCTAssertFalse(BluetoothBackgroundMode.declaresBluetoothCentral(["UIBackgroundModes": ["audio"]]))
+        XCTAssertFalse(
+            BluetoothBackgroundMode.declaresBluetoothCentral(["UIBackgroundModes": "bluetooth-central"])
+        )
+    }
+
+    func testMacOSHasNoBackgroundModeRequirement() {
+        #if os(macOS)
+            XCTAssertTrue(BluetoothBackgroundMode.isDeclared(in: nil))
+        #endif
+    }
+
+    func testWarningPointsToTheDocs() {
+        XCTAssertTrue(BluetoothBackgroundMode.missingWarning.contains("bluetooth-central"))
+        XCTAssertTrue(BluetoothBackgroundMode.missingWarning.contains("#background-operation"))
+    }
+}

package/ios/Tests/MentraLiveReconnectPolicyTests.swift

@@ -0,0 +1,58 @@
+@testable import MentraBluetoothSDK
+import XCTest
+
+final class MentraLiveReconnectPolicyTests: XCTestCase {
+    private func decide(
+        isKilled: Bool = false,
+        pairingYieldActive: Bool = false,
+        bluetoothPoweredOn: Bool = true,
+        peripheralName: String? = "Mentra_Live_D910",
+        savedDeviceName: String? = "Mentra_Live_D910"
+    ) -> Bool {
+        MentraLiveConnectionAttemptPolicy.shouldReconnectDirectly(
+            isKilled: isKilled,
+            pairingYieldActive: pairingYieldActive,
+            bluetoothPoweredOn: bluetoothPoweredOn,
+            peripheralName: peripheralName,
+            savedDeviceName: savedDeviceName
+        )
+    }
+
+    func testRemembersLostGlassesWithPendingConnect() {
+        XCTAssertTrue(decide())
+    }
+
+    func testDoesNotReconnectAfterUserDisconnectOrKill() {
+        XCTAssertFalse(decide(isKilled: true))
+    }
+
+    func testYieldsToAnotherPhonePairing() {
+        XCTAssertFalse(decide(pairingYieldActive: true))
+    }
+
+    func testFallsBackWhenBluetoothIsOff() {
+        XCTAssertFalse(decide(bluetoothPoweredOn: false))
+    }
+
+    func testDoesNotReconnectForgottenOrDifferentGlasses() {
+        XCTAssertFalse(decide(savedDeviceName: nil))
+        XCTAssertFalse(decide(savedDeviceName: "Mentra_Live_023B"))
+        XCTAssertFalse(decide(peripheralName: nil))
+        XCTAssertFalse(decide(peripheralName: "", savedDeviceName: ""))
+    }
+
+    func testFailureThenFallbackLeavesTheStaleSettleTimerPowerless() {
+        var pending = MentraLivePendingReconnect()
+        let first = pending.arm()
+        XCTAssertTrue(pending.owns(first))
+
+        // didFailToConnect or a fallback connectToDevice clears tracking.
+        pending.clear()
+        XCTAssertFalse(pending.owns(first))
+
+        // A later re-arm does not revive the earlier attempt's timer.
+        let second = pending.arm()
+        XCTAssertFalse(pending.owns(first))
+        XCTAssertTrue(pending.owns(second))
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/bluetooth-sdk",
-  "version": "3.3.0-dev.548",
+  "version": "3.3.0-dev.551",
   "description": "SDK for communicating with smart glasses",
   "main": "build/index.js",
   "react-native": "src/index.ts",
@@ -114,7 +114,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@mentra/cloud-protocol": "3.3.0-dev.548"
+    "@mentra/cloud-protocol": "3.3.0-dev.551"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",

package/plugin/build/withIos.d.ts

@@ -2,5 +2,7 @@ import { IOSConfig, type ConfigPlugin } from "expo/config-plugins";
 import { type BluetoothSdkPluginProps } from "./index";
 export declare const INFO_ANALYTICS_ENVIRONMENT = "MentraBluetoothSdkAnalyticsEnvironment";
 export declare const INFO_SDK_VERSION = "MentraBluetoothSdkVersion";
+/** Lets iOS complete the SDK's pending reconnect, and deliver BLE events, while the app is suspended. */
+export declare const IOS_BLUETOOTH_BACKGROUND_MODE = "bluetooth-central";
 export declare function applyBluetoothSdkInfoPlist(infoPlist: IOSConfig.InfoPlist, props: BluetoothSdkPluginProps | undefined): IOSConfig.InfoPlist;
 export declare const withIosConfiguration: ConfigPlugin<BluetoothSdkPluginProps>;

package/plugin/build/withIos.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.withIosConfiguration = exports.INFO_SDK_VERSION = exports.INFO_ANALYTICS_ENVIRONMENT = void 0;
+exports.withIosConfiguration = exports.IOS_BLUETOOTH_BACKGROUND_MODE = exports.INFO_SDK_VERSION = exports.INFO_ANALYTICS_ENVIRONMENT = void 0;
 exports.applyBluetoothSdkInfoPlist = applyBluetoothSdkInfoPlist;
 const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
@@ -17,6 +17,8 @@ exports.INFO_ANALYTICS_ENVIRONMENT = "MentraBluetoothSdkAnalyticsEnvironment";
 exports.INFO_SDK_VERSION = "MentraBluetoothSdkVersion";
 const STALE_INFO_POSTHOG_API_KEY = "MentraBluetoothSdkPostHogApiKey";
 const STALE_INFO_POSTHOG_HOST = "MentraBluetoothSdkPostHogHost";
+/** Lets iOS complete the SDK's pending reconnect, and deliver BLE events, while the app is suspended. */
+exports.IOS_BLUETOOTH_BACKGROUND_MODE = "bluetooth-central";
 const ensureBluetoothSdkExpoAdapterPodEnv = (podfile) => {
     if (podfile.includes(BLUETOOTH_SDK_EXPO_ADAPTER_ENV)) {
         return podfile;
@@ -70,6 +72,15 @@ function applyBluetoothSdkInfoPlist(infoPlist, props) {
     delete infoPlist[STALE_INFO_POSTHOG_API_KEY];
     delete infoPlist[STALE_INFO_POSTHOG_HOST];
     infoPlist[exports.INFO_SDK_VERSION] = sdkVersion;
+    // Merge, never replace: apps may also declare audio, location or other modes.
+    const declaredModes = infoPlist.UIBackgroundModes;
+    if (declaredModes !== undefined && !Array.isArray(declaredModes)) {
+        throw new Error("ios.infoPlist.UIBackgroundModes must be an array of background mode strings");
+    }
+    const backgroundModes = declaredModes ?? [];
+    if (!backgroundModes.includes(exports.IOS_BLUETOOTH_BACKGROUND_MODE)) {
+        infoPlist.UIBackgroundModes = [...backgroundModes, exports.IOS_BLUETOOTH_BACKGROUND_MODE];
+    }
     if (analytics.disabled !== undefined) {
         infoPlist[INFO_ANALYTICS_DISABLED] = analytics.disabled;
     }

package/src/generated/releaseMetadata.ts

@@ -12,9 +12,9 @@ export interface BluetoothSdkReleaseMetadata {
 export const BLUETOOTH_SDK_RELEASE_METADATA: Readonly<BluetoothSdkReleaseMetadata> = Object.freeze({
   "schemaVersion": 1,
   "familyBaseVersion": "3.3.0",
-  "releaseIdentity": "3.3.0-dev.548",
-  "releaseSetId": "mentra-3.3.0-dev.548",
-  "sourceCommit": "b0f8be74e1aae531836532a849cd402c10d2e5ae",
-  "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-dev.548.json",
-  "otaManifestSha256": "372a283a731bf08e6c5070ab867cd2b86a87ee29a993d47c1a5f5c17a5d1596e"
+  "releaseIdentity": "3.3.0-dev.551",
+  "releaseSetId": "mentra-3.3.0-dev.551",
+  "sourceCommit": "f48a6c59f06665dd41924670434f47d359be0eb3",
+  "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-dev.551.json",
+  "otaManifestSha256": "9b17306f36c2610c818c112402d1491903cfa2f4ae3ded4ffc7a358ca5e7ad2e"
 })