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

package/README.md

@@ -158,7 +158,7 @@ enterprise device deployments:
 
 - `bluetooth_sdk_started`: sent once per app runtime after the native SDK starts.
 - `bluetooth_sdk_glasses_connected`: sent when SDK status transitions from not connected to connected.
-- `bluetooth_sdk_glasses_identified`: sent once per connection after the SDK receives a valid manufacturing serial from the glasses. This fires for every supported model that reports a serial. G1 and Ar99 decode the serial from the glasses' BLE advertisement, so they emit this event as soon as this SDK version ships. Mentra Live instead reports the serial provisioned in BES NV storage, which requires compatible BES firmware and `asg_client` software.
+- `bluetooth_sdk_glasses_identified`: sent once per connection after the SDK receives a valid manufacturing serial from the glasses. This fires for every supported model that reports a serial. G1 and Ar99 decode the serial from the glasses' BLE advertisement. Mentra Live reports the product serial provisioned by its Android firmware through `asg_client`.
 
 Analytics delivery is fire-and-forget: events are submitted asynchronously, do
 not block Bluetooth SDK behavior, and are not retried if delivery fails.

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

@@ -2050,11 +2050,13 @@ class DeviceManager {
         shouldSendBootingMessage = true // Reset for next first connect
         // clear glasses properties:
         DeviceStore.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.apply("glasses", "serialNumber", "")
+        DeviceStore.apply("glasses", "bluetoothMacAddress", "")
+        DeviceStore.apply("glasses", "leftMacAddress", "")
+        DeviceStore.apply("glasses", "rightMacAddress", "")
+        DeviceStore.apply("glasses", "macAddress", "")
         DeviceStore.apply("glasses", "fullyBooted", false)
         DeviceStore.apply("glasses", "connected", false)
         DeviceStore.apply(
@@ -2164,4 +2166,3 @@ class DeviceManager {
         }
     }
 }
-

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

@@ -73,6 +73,10 @@ object 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", "macAddress", "")
         store.set("glasses", "serialNumber", "")
         store.set("glasses", "style", "")
         store.set("glasses", "color", "")

package/android/src/main/java/com/mentra/bluetoothsdk/sgcs/MentraLive.kt

@@ -817,12 +817,13 @@ class MentraLive : SGCManager() {
         }
 
         if (state == ConnTypes.DISCONNECTED) {
-            // A manufacturing serial is session-bound. Clear it on disconnect so a previous
-            // pair's serial can never 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.
+            // Device identity is session-bound. Clear it on disconnect so a previous pair's
+            // identifiers can never 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.
             DeviceStore.apply("glasses", "serialNumber", "")
+            DeviceStore.apply("glasses", "bluetoothMacAddress", "")
         }
 
         // Actually update the connection state!
@@ -3729,9 +3730,11 @@ class MentraLive : SGCManager() {
                         if (otaVersionUrlLegacy != null) otaVersionUrlLegacy else ""
                 )
                 DeviceStore.apply("glasses", "firmwareVersion", firmwareVersionLegacy)
-                DeviceStore.apply("glasses", "bluetoothMacAddress", btMacAddressLegacy)
-                if (serialNumberLegacy.isNotBlank()) {
-                    DeviceStore.apply("glasses", "serialNumber", serialNumberLegacy)
+                btMacAddressLegacy.trim().takeIf { it.isNotEmpty() }?.let {
+                    DeviceStore.apply("glasses", "bluetoothMacAddress", it)
+                }
+                serialNumberLegacy.trim().takeIf { it.isNotEmpty() }?.let {
+                    DeviceStore.apply("glasses", "serialNumber", it)
                 }
 
                 val versionInfoLegacy = HashMap<String, Any>()
@@ -3994,16 +3997,11 @@ class MentraLive : SGCManager() {
                                 fields["mtk_fw_version"] as String
                         )
                     }
-                    if (fields.containsKey("bt_mac_address")) {
-                        DeviceStore.apply(
-                                "glasses",
-                                "bluetoothMacAddress",
-                                fields["bt_mac_address"] as String
-                        )
+                    (fields["bt_mac_address"] as? String)?.trim()?.takeIf { it.isNotEmpty() }?.let {
+                        DeviceStore.apply("glasses", "bluetoothMacAddress", it)
                     }
-                    val serialNumber = fields["serial_number"] as? String
-                    if (!serialNumber.isNullOrBlank()) {
-                        DeviceStore.apply("glasses", "serialNumber", serialNumber)
+                    (fields["serial_number"] as? String)?.trim()?.takeIf { it.isNotEmpty() }?.let {
+                        DeviceStore.apply("glasses", "serialNumber", it)
                     }
                     if (fields.containsKey("system_time_ms")) {
                         val v = fields["system_time_ms"]

package/ios/Source/BluetoothSdkDefaults.swift

@@ -8,7 +8,7 @@ enum BluetoothSdkDefaults {
 
     static let voiceActivityDetectionEnabled = false
     static let loudnessGateEnabled = true
-    private static let swiftPackageSdkVersion = "0.1.21-beta.2"
+    private static let swiftPackageSdkVersion = "0.1.21-beta.3"
     private static let swiftPackageSdkVersionPlaceholder = "__MENTRA" + "_BLUETOOTH_SDK_VERSION__"
 
     private static func normalizedSdkVersion(_ value: String?) -> String? {

package/ios/Source/DeviceManager.swift

@@ -1712,11 +1712,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 +1809,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)
@@ -2760,10 +2761,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 {
@@ -3441,15 +3442,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 +3465,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 ?? ""
         )
     }
 

package/package.json

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