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

package/ios/Source/DeviceManager.swift

@@ -704,14 +704,16 @@ struct ViewState {
             let layoutType = currentViewState.layoutType
             switch layoutType {
             case "text_wall":
-                let text = currentViewState.text
+                let text = parsePlaceholders(currentViewState.text)
                 await sgc?.sendTextWall(text)
             case "double_text_wall":
-                let topText = currentViewState.topText
-                let bottomText = currentViewState.bottomText
+                let topText = parsePlaceholders(currentViewState.topText)
+                let bottomText = parsePlaceholders(currentViewState.bottomText)
                 await sgc?.sendDoubleTextWall(topText, bottomText)
             case "reference_card":
-                await sgc?.sendTextWall(currentViewState.title + "\n\n" + currentViewState.text)
+                let title = parsePlaceholders(currentViewState.title)
+                let text = parsePlaceholders(currentViewState.text)
+                await sgc?.sendTextWall(title + "\n\n" + text)
             case "bitmap_view":
                 // Bridge.log("MAN: Processing bitmap_view layout")
                 guard let data = currentViewState.data else {
@@ -727,11 +729,12 @@ struct ViewState {
                     height: currentViewState.bmpHeight
                 )
             case "positioned_text":
+                let text = parsePlaceholders(currentViewState.text)
                 Bridge.log(
-                    "MAN: positioned_text -> text='\(currentViewState.text)' rect=\(currentViewState.bmpX ?? 0),\(currentViewState.bmpY ?? 0) \(currentViewState.bmpWidth ?? 576)x\(currentViewState.bmpHeight ?? 288)"
+                    "MAN: positioned_text -> text='\(text)' rect=\(currentViewState.bmpX ?? 0),\(currentViewState.bmpY ?? 0) \(currentViewState.bmpWidth ?? 576)x\(currentViewState.bmpHeight ?? 288)"
                 )
                 await sgc?.sendPositionedText(
-                    currentViewState.text,
+                    text,
                     x: currentViewState.bmpX ?? 0,
                     y: currentViewState.bmpY ?? 0,
                     width: currentViewState.bmpWidth ?? 576,
@@ -753,6 +756,8 @@ struct ViewState {
     }
 
     func parsePlaceholders(_ text: String) -> String {
+        guard text.contains("$") else { return text }
+
         let dateFormatter = DateFormatter()
         dateFormatter.dateFormat = "M/dd, h:mm"
         let formattedDate = dateFormatter.string(from: Date())
@@ -1712,11 +1717,13 @@ struct ViewState {
         shouldSendBootingMessage = true // Reset for next first connect
         // clear glasses properties:
         DeviceStore.shared.apply("glasses", "deviceModel", "")
-        // A manufacturing serial is session-bound. Clear it on every disconnect so a
-        // previously connected pair's serial can never be reported for the next
-        // connection (e.g. switching from G1/Ar99, which populate it from the
-        // advertisement, to a model that never writes it, like G2).
+        // Device identifiers are session-bound. Clear them on every disconnect so a
+        // previously connected pair can never be reported for the next connection.
         DeviceStore.shared.apply("glasses", "serialNumber", "")
+        DeviceStore.shared.apply("glasses", "bluetoothMacAddress", "")
+        DeviceStore.shared.apply("glasses", "leftMacAddress", "")
+        DeviceStore.shared.apply("glasses", "rightMacAddress", "")
+        DeviceStore.shared.apply("glasses", "macAddress", "")
         DeviceStore.shared.apply("glasses", "fullyBooted", false)
         DeviceStore.shared.apply("glasses", "connected", false)
         DeviceStore.shared.apply("glasses", "connectionState", ConnTypes.DISCONNECTED)
@@ -1807,4 +1814,3 @@ struct ViewState {
         cancellables.removeAll()
     }
 }
-

package/ios/Source/DeviceStore.swift

@@ -35,6 +35,9 @@ class DeviceStore {
         store.set("glasses", "caseCharging", false)
         store.set("glasses", "caseBatteryLevel", -1)
         store.set("glasses", "headUp", false)
+        store.set("glasses", "bluetoothMacAddress", "")
+        store.set("glasses", "leftMacAddress", "")
+        store.set("glasses", "rightMacAddress", "")
         store.set("glasses", "serialNumber", "")
         store.set("glasses", "style", "")
         store.set("glasses", "color", "")

package/ios/Source/sgcs/G2.swift

@@ -11,6 +11,14 @@ import CoreBluetooth
 import Foundation
 import UIKit
 
+/// Keep a low-rate, non-audio EvenHub sensor stream active so iOS continues receiving BLE
+/// notifications while the Mentra App is backgrounded. The samples stay internal unless IMU was
+/// explicitly enabled through Mentra's developer-facing setting.
+private let g2ImuKeepaliveEnabled = true
+private let g2ImuKeepaliveReportPace: Int32 = 1000
+private let g2ImuConfirmationDelay: TimeInterval = 2
+private let g2ImuMaxControlAttempts = 3
+
 // MARK: - Data Little-Endian Helpers (for BMP construction)
 
 extension Data {
@@ -1524,6 +1532,8 @@ class G2: NSObject, SGCManager {
     private var foregroundObserver: NSObjectProtocol?
     private var startupPageCreated: Bool = false  // createStartUpPageContainer can only be called once
     private var pageCreated: Bool = false
+    private var pageGeneration: UInt64 = 0
+    private var lastImuReportTimestamp: Int64?
     // Live hardware truth: is the firmware mic actually streaming. DISTINCT from the
     // glasses/micEnabled DeviceStore flag, which is *intent* (does the user want the mic on).
     // Cleared on every page teardown (the firmware kills the mic with the page) WITHOUT touching
@@ -2959,11 +2969,17 @@ class G2: NSObject, SGCManager {
         }
         signalDisplayDirty()
 
-        try? await Task.sleep(nanoseconds: 300_000_000)  // 300ms to settle
+        try? await Task.sleep(nanoseconds: 300_000_000) // 300ms to settle
+        syncImuReportingWithIntent()
+        confirmImuReporting(
+            forPageGeneration: pageGeneration,
+            commandSentAt: Int64(Date().timeIntervalSince1970 * 1000),
+            attemptsRemaining: g2ImuMaxControlAttempts - 1
+        )
         restartMicIfAlreadyEnabled()
     }
 
-    /// Single coalesced recovery: rebuild the page + re-arm the mic from intent, but never
+    /// Single coalesced recovery: rebuild the page + re-arm sensor streams from intent, but never
     /// stack rebuilds. The firmware spams systemExit/dashboard-close ~1×/sec; without this
     /// guard each one triggered a rebuild that was torn down again → rebuild→exit→rebuild
     /// storm. At most one rebuild in flight, and at most one per RECOVERY_DEBOUNCE_MS.
@@ -3481,6 +3497,8 @@ class G2: NSObject, SGCManager {
                 appId: activeMenuAppId
             )
         }
+        pageGeneration &+= 1
+        lastImuReportTimestamp = nil
         sendEvenHubCommand(msg)
         pageCreated = true
     }
@@ -3492,6 +3510,62 @@ class G2: NSObject, SGCManager {
         }
     }
 
+    /// Keep the firmware IMU stream alive at its slowest supported pace even when no miniapp
+    /// requested motion data. Incoming keepalive samples are discarded in `handleTouchEvent`.
+    private func syncImuReportingWithIntent(
+        _ intentEnabled: Bool? = nil,
+        requestedReportPace: Int32 = EvenHubProto.imuPaceP100
+    ) {
+        guard pageCreated else { return }
+
+        let shouldForwardSamples =
+            intentEnabled
+                ?? (DeviceStore.shared.get("bluetooth", "imu_enabled") as? Bool ?? false)
+        let shouldStream = shouldForwardSamples || g2ImuKeepaliveEnabled
+        let reportPace =
+            shouldForwardSamples ? requestedReportPace : g2ImuKeepaliveReportPace
+
+        Bridge.log(
+            "G2: syncing IMU stream — hardware=\(shouldStream), forward=\(shouldForwardSamples), pace=\(reportPace)"
+        )
+        let msg = EvenHubProto.imuControlMessage(
+            enable: shouldStream,
+            reportFrq: reportPace,
+            magicRandom: sendManager.nextMagicRandom()
+        )
+        sendEvenHubCommand(msg)
+    }
+
+    /// EvenHub does not ACK IMU control commands, so use the data stream itself as confirmation.
+    /// A page-generation guard prevents a delayed retry from targeting a replacement page.
+    private func confirmImuReporting(
+        forPageGeneration generation: UInt64,
+        commandSentAt: Int64,
+        attemptsRemaining: Int
+    ) {
+        guard attemptsRemaining > 0 else { return }
+
+        DispatchQueue.main.asyncAfter(deadline: .now() + g2ImuConfirmationDelay) { [weak self] in
+            guard let self,
+                  self.pageCreated,
+                  self.pageGeneration == generation,
+                  g2ImuKeepaliveEnabled
+                  || (DeviceStore.shared.get("bluetooth", "imu_enabled") as? Bool ?? false),
+                  !(self.lastImuReportTimestamp.map { $0 >= commandSentAt } ?? false)
+            else { return }
+
+            Bridge.log(
+                "G2: no IMU report received for page generation \(generation); retrying control (\(attemptsRemaining) remaining)"
+            )
+            self.syncImuReportingWithIntent()
+            self.confirmImuReporting(
+                forPageGeneration: generation,
+                commandSentAt: Int64(Date().timeIntervalSince1970 * 1000),
+                attemptsRemaining: attemptsRemaining - 1
+            )
+        }
+    }
+
     func restartMic() {
         // Intent is "mic on". The mic only exists inside a live EvenHub page, so we
         // toggle it off then back on (the firmware needs the off→on edge to re-arm).
@@ -3829,21 +3903,7 @@ class G2: NSObject, SGCManager {
             await rebuildState()
         }
 
-        let send = { [weak self] in
-            guard let self = self else { return }
-            let msg = EvenHubProto.imuControlMessage(
-                enable: enabled, reportFrq: reportFrq,
-                magicRandom: self.sendManager.nextMagicRandom()
-            )
-            self.sendEvenHubCommand(msg)
-        }
-
-        // If we just asked for a page, give it a moment to be created first.
-        if enabled, !pageCreated {
-            DispatchQueue.main.asyncAfter(deadline: .now() + 0.5, execute: send)
-        } else {
-            send()
-        }
+        syncImuReportingWithIntent(enabled, requestedReportPace: reportFrq)
     }
 
     // MARK: - SGCManager: Device Control
@@ -4367,16 +4427,9 @@ class G2: NSObject, SGCManager {
             return
         }
 
-
         if cmdValue == EvenHubResponseCmd.osNotifyEventToApp.rawValue {
-            // Touch/gesture event from glasses
+            // Device event from glasses (touch/gesture or sensor data)
             guard let devEventData = fields[13] as? Data else { return }
-            let timestamp = Int64(Date().timeIntervalSince1970 * 1000)
-            if lastClickTimestamp != nil && timestamp - lastClickTimestamp! < 100 {
-                // Bridge.log("G2: Double click ignored (too soon)")
-                return
-            }
-            lastClickTimestamp = timestamp
             handleTouchEvent(devEventData)
         } else if cmdValue == 17 {
             // Miniapp selection from glasses dashboard menu (cmdId=17)
@@ -4526,6 +4579,35 @@ class G2: NSObject, SGCManager {
 
         let timestamp = Int64(Date().timeIntervalSince1970 * 1000)
 
+        // Classify IMU reports before applying the click debounce. Keepalive samples arrive
+        // continuously and must not update `lastClickTimestamp`, or a real gesture delivered
+        // within 100 ms of a sample can be dropped.
+        var parsedSysFields: [Int: Any]?
+        if let sysData = fields[3] as? Data {
+            var sysReader = ProtobufReader(sysData)
+            let sysFields = sysReader.parseFields()
+            if (sysFields[1] as? Int32) == OsEventType.imuDataReport.rawValue {
+                lastImuReportTimestamp = timestamp
+                let shouldForwardSamples =
+                    DeviceStore.shared.get("bluetooth", "imu_enabled") as? Bool ?? false
+                if shouldForwardSamples,
+                   let imuData = sysFields[3] as? Data,
+                   let imu = parseImuReportData(imuData)
+                {
+                    Bridge.log("G2: IMU data report: \(imu.x), \(imu.y), \(imu.z)")
+                    Bridge.sendAccelEvent(x: imu.x, y: imu.y, z: imu.z, timestamp: timestamp)
+                }
+                return
+            }
+            parsedSysFields = sysFields
+        }
+
+        if lastClickTimestamp != nil && timestamp - lastClickTimestamp! < 100 {
+            // Bridge.log("G2: Double click ignored (too soon)")
+            return
+        }
+        lastClickTimestamp = timestamp
+
         // if we are receiving touch events we are fully booted:
         setFullyConnected()
 
@@ -4534,22 +4616,7 @@ class G2: NSObject, SGCManager {
         //     "G2: handleTouchEvent: \(devEventData.map { String(format: "%02X", $0) }.joined())")
 
         // SysEvent (field 3) - system-level gestures
-        if let sysData = fields[3] as? Data {
-            var sysReader = ProtobufReader(sysData)
-            let sysFields = sysReader.parseFields()
-
-            // IMU data report: eventType == IMU_DATA_REPORT (8), imuData in field 3
-            // (IMU_Report_Data { x, y, z } as 32-bit floats). Handle and return before
-            // the gesture-mapping path.
-            if (sysFields[1] as? Int32) == OsEventType.imuDataReport.rawValue,
-                let imuData = sysFields[3] as? Data,
-                let imu = parseImuReportData(imuData)
-            {
-                Bridge.log("G2: IMU data report: \(imu.x), \(imu.y), \(imu.z)")
-                Bridge.sendAccelEvent(x: imu.x, y: imu.y, z: imu.z, timestamp: timestamp)
-                return
-            }
-
+        if let sysFields = parsedSysFields {
             var eventType: OsEventType? = nil
             var eventSource: Int32? = nil
             if let normalType = sysFields[1] as? Int32 {

package/ios/Source/sgcs/MentraLive.swift

@@ -1282,13 +1282,14 @@ class MentraLive: NSObject, SGCManager {
     /// Mirrors Android `updateConnectionState` — RN home reads `glasses.connectionState` for reconnecting UI.
     private func updateConnectionState(_ state: String) {
         if state == ConnTypes.DISCONNECTED {
-            // A manufacturing serial is session-bound. Clear it on disconnect so a previous
-            // pair's serial cannot be associated with the next connection. Connect must NOT
-            // clear it: DeviceManager.disconnect already wipes it before any new connection, and
-            // clearing on CONNECTED would wipe a still-valid serial mid-session when a same-link
-            // glasses_ready (e.g. ASG restart) re-publishes CONNECTED (iOS has no equal-state
-            // early return, unlike Android).
+            // Device identity is session-bound. Clear it on disconnect so a previous pair's
+            // identifiers cannot be associated with the next connection. Connect must NOT clear
+            // them: DeviceManager.disconnect already wipes them before any new connection, and
+            // clearing on CONNECTED would wipe still-valid identity mid-session when a same-link
+            // glasses_ready (e.g. ASG restart) re-publishes CONNECTED (iOS has no equal-state early
+            // return, unlike Android).
             DeviceStore.shared.apply("glasses", "serialNumber", "")
+            DeviceStore.shared.apply("glasses", "bluetoothMacAddress", "")
         }
         connectionState = state
         DeviceStore.shared.apply("glasses", "connectionState", state)
@@ -1296,6 +1297,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
@@ -1451,6 +1453,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
@@ -1545,6 +1548,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?
@@ -1940,6 +1944,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] = []
 
@@ -2668,6 +2684,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)%")
 
@@ -2701,6 +2718,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)%"
             )
@@ -2760,10 +2778,10 @@ class MentraLive: NSObject, SGCManager {
                 if let systemTimeMs = fields["system_time_ms"] as? NSNumber {
                     DeviceStore.shared.apply("glasses", "systemTimeMs", systemTimeMs.int64Value)
                 }
-                if let bluetoothMacAddress = fields["bt_mac_address"] as? String {
+                if let bluetoothMacAddress = nonEmptyStringValue(fields, "bt_mac_address") {
                     DeviceStore.shared.apply("glasses", "bluetoothMacAddress", bluetoothMacAddress)
                 }
-                if let serialNumber = fields["serial_number"] as? String, !serialNumber.isEmpty {
+                if let serialNumber = nonEmptyStringValue(fields, "serial_number") {
                     DeviceStore.shared.apply("glasses", "serialNumber", serialNumber)
                 }
                 if let systemTimeMs = fields["system_time_ms"] as? NSNumber {
@@ -2828,6 +2846,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.
@@ -2999,62 +3030,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
@@ -3441,15 +3451,17 @@ class MentraLive: NSObject, SGCManager {
         let androidVersion = json["android_version"] as? String ?? ""
         let otaVersionUrl = json["ota_version_url"] as? String ?? ""
         let firmwareVersion = json["firmware_version"] as? String ?? ""
-        let bluetoothMacAddress = json["bt_mac_address"] as? String ?? ""
-        let serialNumber = json["serial_number"] as? String ?? ""
+        let bluetoothMacAddress = nonEmptyStringValue(json, "bt_mac_address")
+        let serialNumber = nonEmptyStringValue(json, "serial_number")
 
         DeviceStore.shared.apply("glasses", "appVersion", appVersion)
         DeviceStore.shared.apply("glasses", "buildNumber", buildNumber)
         DeviceStore.shared.apply("glasses", "otaVersionUrl", otaVersionUrl)
         DeviceStore.shared.apply("glasses", "firmwareVersion", firmwareVersion)
-        DeviceStore.shared.apply("glasses", "bluetoothMacAddress", bluetoothMacAddress)
-        if !serialNumber.isEmpty {
+        if let bluetoothMacAddress {
+            DeviceStore.shared.apply("glasses", "bluetoothMacAddress", bluetoothMacAddress)
+        }
+        if let serialNumber {
             DeviceStore.shared.apply("glasses", "serialNumber", serialNumber)
         }
         isNewVersion = (Int(buildNumber) ?? 0) >= 5
@@ -3462,14 +3474,14 @@ class MentraLive: NSObject, SGCManager {
         // hasMic = supportsLC3Audio
 
         Bridge.log(
-            "Glasses Version - App: \(appVersion), Build: \(buildNumber), Device: \(deviceModel), Android: \(androidVersion), Firmware: \(firmwareVersion), BT MAC: \(bluetoothMacAddress), OTA URL: \(otaVersionUrl)"
+            "Glasses Version - App: \(appVersion), Build: \(buildNumber), Device: \(deviceModel), Android: \(androidVersion), Firmware: \(firmwareVersion), BT MAC available: \(bluetoothMacAddress != nil), OTA URL: \(otaVersionUrl)"
         )
         Bridge.log("LIVE: LC3 Audio Support: \(supportsLC3Audio), Has Mic: \(hasMic)")
         emitVersionInfo(
             appVersion: appVersion, buildNumber: buildNumber, deviceModel: deviceModel,
             androidVersion: androidVersion, otaVersionUrl: otaVersionUrl,
             firmwareVersion: firmwareVersion,
-            bluetoothMacAddress: bluetoothMacAddress
+            bluetoothMacAddress: bluetoothMacAddress ?? ""
         )
     }
 
@@ -5065,6 +5077,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"]
@@ -5178,8 +5194,7 @@ class MentraLive: NSObject, SGCManager {
         stopReadinessCheckLoop()
         stopConnectionTimeout()
         stopMicBeat() // Stop LC3 audio micbeat
-        pendingMessageTimer?.invalidate()
-        pendingMessageTimer = nil
+        resetPendingAckState(reason: "transport timers stopped")
         reconnectionWorkItem?.cancel()
         reconnectionWorkItem = nil
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/bluetooth-sdk",
-  "version": "0.1.21-beta.2",
+  "version": "0.1.21-beta.5",
   "description": "SDK for communicating with smart glasses",
   "main": "build/index.js",
   "react-native": "src/index.ts",

package/src/BluetoothSdk.types.ts

@@ -1201,6 +1201,8 @@ export interface OtaUpdateInfo {
   updates: string[] // ["apk", "mtk", "bes"]
   totalSize: number
   cacheReady?: boolean
+  /** Exact BES target selected from the OTA manifest, when a BES step is pending. */
+  besVersion?: string
   /** True when the APK step installs an older build than the glasses currently run (exact-pin manifests only). */
   isDowngrade?: boolean
 }