@mentra/bluetooth-sdk 3.2.1-beta.506 → 3.2.1-beta.512

package/ios/Source/sgcs/Nimo.swift

@@ -40,6 +40,8 @@ enum NimoProtocol {
     static let CMD_SET_PARAMETER = 0x03
     static let CMD_INSTRUCTION_REPORT = 0x06
     static let CMD_CONTROL_INSTRUCTION = 0x07
+    static let CMD_CONTROL_FACTORY = 0x08
+    static let FACTORY_RECOVER = 0x03
     static let CMD_CONTROL_NOTIFICATION = 0x09
 
     // get parameter keys
@@ -58,6 +60,9 @@ enum NimoProtocol {
     static let SET_DISPLAY_OFF = 0x0F
     static let SET_PHONE_TYPE = 0x14
     static let SET_HEIGHT_LEVEL = 0x17
+    // Dynamic-v1 firmware: 1-based UI locale; 1 selects English.
+    static let SET_SYSTEM_LANGUAGE = 0x24
+    static let LANGUAGE_ENGLISH: UInt8 = 0x01
 
     // control instruction keys
     static let CTRL_ENTER_APP = 0x01
@@ -742,6 +747,27 @@ class Nimo: NSObject, SGCManager {
         DeviceStore.shared.apply("glasses", "connectionState", ConnTypes.DISCONNECTED)
     }
 
+    /// Explicit Unpair only; passive forget/cleanup must never reset the glasses.
+    func resetForUnpair(onResult: @escaping (Bool) -> Void) {
+        guard peripheral != nil, txChar != nil, handshakeState == .ready else {
+            Bridge.log("NIMO: unpair while offline; remote reset unavailable")
+            onResult(false)
+            return
+        }
+        isDisconnecting = true
+        stopTimers()
+        Task { await reconnectionManager.stop() }
+        canvasEncoder.invalidate()
+        canvas.disconnected()
+        Bridge.log("NIMO: sending factory reset for explicit Unpair")
+        sendAwaitingAck(cmd: NimoProtocol.CMD_CONTROL_FACTORY, key: NimoProtocol.FACTORY_RECOVER,
+                        payload: Data())
+        { success in
+            Bridge.log("NIMO: factory reset acknowledged=\(success)")
+            onResult(success)
+        }
+    }
+
     func forget() {
         Bridge.log("NIMO: forget()")
         disconnect()
@@ -1287,6 +1313,9 @@ class Nimo: NSObject, SGCManager {
                 needsAck: false
             )
         )
+        // Optional setting: older firmware may reject it without preventing connection.
+        sendFrame(NimoFrameCodec.encodeFrame(cmd: NimoProtocol.CMD_SET_PARAMETER,
+                                             key: NimoProtocol.SET_SYSTEM_LANGUAGE, payload: Data([NimoProtocol.LANGUAGE_ENGLISH])))
         getBatteryStatus()
         requestVersionInfo()
 
@@ -1296,7 +1325,10 @@ class Nimo: NSObject, SGCManager {
         DeviceStore.shared.apply("glasses", "fullyBooted", true)
         DeviceStore.shared.apply("glasses", "connectionState", ConnTypes.CONNECTED)
         startTimers()
-        canvas.readiness(twsConnected && peerCompanionReady == true)
+        // The Launch ACK validates peer readiness without waiting for the first
+        // unsolicited heartbeat (which can arrive a minute after connection).
+        canvas.activate()
+        canvas.readiness(twsConnected && peerCompanionReady != false)
     }
 
     private func handshakeFailed() {
@@ -1365,6 +1397,7 @@ class Nimo: NSObject, SGCManager {
     private func handleRxPacket(_ packet: Data) {
         if packet.count >= 10, packet[8] == 7, [1, 3, 4].contains(packet[9]) {
             if let response = NimoCanvasCodec.response(packet) {
+                if response.key == 1 { Bridge.log("NIMO: canvas Launch response status=\(response.payload.first.map(Int.init) ?? -1)") }
                 canvas.response(key: response.key, payload: response.payload)
             }
             return
@@ -1398,9 +1431,9 @@ class Nimo: NSObject, SGCManager {
                 Bridge.log("NIMO: app state report appId=\(appId) phase=\(phase)")
                 switch phase {
                 case NimoProtocol.STATE_ENTER:
-                    if canvas.nativeApp(appId, entered: true) { canvasEncoder.invalidate() }
+                    canvas.nativeApp(appId, entered: true)
                 case NimoProtocol.STATE_EXIT:
-                    if canvas.nativeApp(appId, entered: false) { canvasEncoder.invalidate() }
+                    canvas.nativeApp(appId, entered: false)
                 default:
                     break
                 }
@@ -1430,7 +1463,7 @@ class Nimo: NSObject, SGCManager {
                 peerCompanionReady = v[9] != 0
                 onTwsState(Int(v[8]) >= 1)
                 if handshakeState == .ready {
-                    canvas.readiness(twsConnected && peerCompanionReady == true, confirmed: true)
+                    canvas.readiness(twsConnected && peerCompanionReady != false, confirmed: true)
                 }
             }
         case NimoProtocol.BUSINESS_BATTERY:
@@ -1453,7 +1486,7 @@ class Nimo: NSObject, SGCManager {
         if !connected, handshakeState == .ready {
             Bridge.log("NIMO: TWS service dropped mid-session (arm removed/off?)")
         }
-        if handshakeState == .ready { canvas.readiness(connected && peerCompanionReady == true) }
+        if handshakeState == .ready { canvas.readiness(connected && peerCompanionReady != false) }
     }
 
     private func handleInputEvent(_ code: Int) {
@@ -1489,6 +1522,9 @@ class Nimo: NSObject, SGCManager {
     }
 
     private func handleResponse(cmd: Int, key: Int, statusCode: Int, data: Data) {
+        if cmd == NimoProtocol.CMD_SET_PARAMETER, key == NimoProtocol.SET_SYSTEM_LANGUAGE {
+            Bridge.log("NIMO: English menu setting acknowledged=\(statusCode == 0) status=\(statusCode)")
+        }
         resolvePendingAck(cmd: cmd, key: key, success: statusCode == 0)
 
         guard cmd == NimoProtocol.CMD_GET_PARAMETER, statusCode == 0 else { return }

package/ios/Source/sgcs/NimoCanvasCoordinator.swift

@@ -21,6 +21,7 @@ final class NimoCanvasCoordinator {
     private let rejected: (Int) -> Void
     private let session = NimoCanvasSession()
     private var flight: Flight?
+    private var cancelRetry: (() -> Void)?
     private var cancelDeadline: (() -> Void)?
 
     init(schedule: @escaping NimoScheduler, writeCapacity: @escaping () -> Int,
@@ -35,23 +36,26 @@ final class NimoCanvasCoordinator {
         run(session.offer(bytes, scope: scope, force: force))
     }
 
+    func activate() {
+        run(session.activate())
+    }
+
     func readiness(_ value: Bool, confirmed: Bool = false) {
+        if !value { cancelRetry?(); cancelRetry = nil }
         run(session.readiness(value, confirmed: confirmed))
     }
 
     func exit() {
+        cancelRetry?(); cancelRetry = nil
         run(session.exit())
     }
 
-    /// An expected Exit report must not discard a newer host encode queued behind Exit.
-    func nativeApp(_ appId: Int, entered: Bool) -> Bool {
-        let takeover = (appId == NimoCanvasCodec.appId && !entered) || (appId != NimoCanvasCodec.appId && entered)
-        let expectedExit = appId == NimoCanvasCodec.appId && !entered && flight?.key == 3
+    func nativeApp(_ appId: Int, entered: Bool) {
         run(session.nativeApp(appId, entered: entered))
-        return takeover && !expectedExit
     }
 
     func disconnected() {
+        cancelRetry?(); cancelRetry = nil
         cancelDeadline?(); cancelDeadline = nil
         flight = nil
         session.disconnected()
@@ -72,6 +76,7 @@ final class NimoCanvasCoordinator {
         for action in actions {
             switch action {
             case let .send(key, frame, ticket):
+                cancelRetry?(); cancelRetry = nil
                 cancelDeadline?()
                 let current = Flight(key: key)
                 flight = current
@@ -93,7 +98,16 @@ final class NimoCanvasCoordinator {
                     disconnected(); reconnect("Canvas framing failed: \(error)")
                 }
             case let .reconnect(reason): disconnected(); reconnect(reason)
-            case let .rejected(status): rejected(status)
+            case let .rejected(status):
+                rejected(status)
+                if status == 7 {
+                    cancelRetry?()
+                    cancelRetry = schedule(1) { [weak self] in
+                        guard let self else { return }
+                        self.cancelRetry = nil
+                        self.run(self.session.retryNotReady())
+                    }
+                }
             }
         }
     }

package/ios/Source/sgcs/NimoCanvasSession.swift

@@ -15,12 +15,14 @@ final class NimoCanvasSession {
     }
 
     private var ready = false
+    private var transportReady = false
     private var active = false
     private var locked = false
     private var launchBlocked = false
     private var waitingReadiness = false
     private var observedNotReady = false
     private var readinessRetries = 0
+    private var probeRetries = 0
     private var exitRequested = false
     private var desired: Data?
     private var accepted: Data?
@@ -39,9 +41,27 @@ final class NimoCanvasSession {
         return pump()
     }
 
+    /// Enter a blank canvas unless a newer host scene survived the connection change.
+    func activate() -> [Action] {
+        if desired == nil { desired = Data([0, 0, 1]) }
+        exitRequested = false
+        return pump()
+    }
+
+    /// The firmware validates peer readiness on Launch. Only an explicit NOT_READY
+    /// permits a bounded retry; an ambiguous ACK still requires a new transport.
+    func retryNotReady() -> [Action] {
+        guard transportReady, waitingReadiness, desired != nil, probeRetries < 3 else { return [] }
+        probeRetries += 1
+        waitingReadiness = false
+        ready = true
+        return pump()
+    }
+
     /// Only a fresh heartbeat samples both TWS and peer Companion readiness.
     func readiness(_ value: Bool, confirmed: Bool = false) -> [Action] {
-        if !value { readinessRetries = 0 }
+        transportReady = value
+        if !value { readinessRetries = 0; probeRetries = 0 }
         if !value, flight != nil { return resetLink("Readiness lost during canvas command") }
         if waitingReadiness {
             if !value { observedNotReady = true }
@@ -58,8 +78,8 @@ final class NimoCanvasSession {
 
     /// Keep only the latest desired scene across a new transport generation.
     func disconnected() {
-        ready = false; active = false; locked = false; launchBlocked = false
-        waitingReadiness = false; observedNotReady = false; readinessRetries = 0
+        ready = false; transportReady = false; active = false; locked = false; launchBlocked = false
+        waitingReadiness = false; observedNotReady = false; readinessRetries = 0; probeRetries = 0
         accepted = nil; rejected = nil; flight = nil
         ticket &+= 1; forceRevision &+= 1
     }
@@ -69,16 +89,12 @@ final class NimoCanvasSession {
         return pump()
     }
 
+    /// Stock UI reports do not relinquish host ownership. Replay after the current ACK.
     func nativeApp(_ appId: Int, entered: Bool) -> [Action] {
         if (appId == NimoCanvasCodec.appId && !entered) || (appId != NimoCanvasCodec.appId && entered) {
-            if flight?.key == 3 {
-                active = false; accepted = nil
-                if appId != NimoCanvasCodec.appId, entered { desired = nil; rejected = nil; scope = nil }
-                return []
-            }
-            let ambiguous = flight != nil
-            desired = nil; accepted = nil; rejected = nil; active = false; exitRequested = false; scope = nil
-            if ambiguous { return resetLink("Native app transition interrupted canvas command") }
+            active = false
+            accepted = nil
+            return pump()
         }
         return []
     }
@@ -112,8 +128,8 @@ final class NimoCanvasSession {
             return [.rejected(status)] + pump()
         }
         switch key {
-        case 1: active = true
-        case 4: accepted = current.frame; rejected = nil; readinessRetries = 0
+        case 1: active = true; accepted = nil
+        case 4: accepted = current.frame; rejected = nil; readinessRetries = 0; probeRetries = 0
         case 3: active = false; accepted = nil; exitRequested = false
         default: break
         }
@@ -126,7 +142,7 @@ final class NimoCanvasSession {
     }
 
     private func resetLink(_ reason: String) -> [Action] {
-        ready = false; active = false; accepted = nil; flight = nil
+        ready = false; transportReady = false; active = false; accepted = nil; flight = nil
         ticket &+= 1; forceRevision &+= 1
         return [.reconnect(reason)]
     }

package/ios/Tests/DeviceManagerReconnectTests.swift

@@ -5,6 +5,25 @@ import XCTest
 final class DeviceManagerReconnectTests: XCTestCase {
     private let requests = ["should_send_lc3", "should_send_pcm", "should_send_transcript", "local_stt_fallback_active"]
 
+    func testDelayedReconnectReplayPreservesNimoDepthEndpoints() {
+        for depth in [0, 10] {
+            withRecordingDevice { manager, store in
+                let device = manager.sgc as! ReconnectRecordingDevice
+                device.type = DeviceTypes.NIMO
+                store.set("bluetooth", "dashboard_height", 7)
+                store.set("bluetooth", "dashboard_depth", depth)
+                let replayed = expectation(description: "Delayed NIMO depth \(depth)")
+                replayed.assertForOverFulfill = false
+                device.onPosition = { replayed.fulfill() }
+                manager.handleDeviceReady()
+                XCTAssertTrue(device.positions.isEmpty)
+                wait(for: [replayed], timeout: 3)
+                XCTAssertEqual(device.positions.last?.0, 7)
+                XCTAssertEqual(device.positions.last?.1, depth)
+            }
+        }
+    }
+
     private func withRecordingDevice(_ body: (DeviceManager, DeviceStore) -> Void) {
         let manager = DeviceManager.shared
         let store = DeviceStore.shared
@@ -265,6 +284,8 @@ private final class ReconnectRecordingDevice: SGCManager {
     let hasMic = true
     let showConnectionConfirmation = false
     var micChanges: [Bool] = []
+    var positions: [(Int, Int)] = []
+    var onPosition: (() -> Void)?
     var isMicSuspendedForAudio = false
 
     func clearSceneElements(_: [String]) async {}
@@ -300,7 +321,11 @@ private final class ReconnectRecordingDevice: SGCManager {
     }
 
     func showDashboard() {}
-    func setDashboardPosition(_: Int, _: Int) {}
+    func setDashboardPosition(_ height: Int, _ depth: Int) {
+        positions.append((height, depth))
+        onPosition?()
+    }
+
     func setHeadUpAngle(_: Int) {}
     func getBatteryStatus() {}
     func setSilentMode(_: Bool) {}

package/ios/Tests/NimoCanvasSessionTests.swift

@@ -102,11 +102,80 @@ final class NimoCanvasSessionTests: XCTestCase {
         XCTAssertEqual(frame, b)
     }
 
-    func testNativeTakeoverSuppressesReplayUntilHostOffersAgain() {
+    func testNativeTakeoverReplaysWithoutNewHostFrame() {
         let session = NimoCanvasSession(); connected(session)
-        XCTAssertTrue(session.nativeApp(1, entered: true).isEmpty)
-        XCTAssertTrue(session.readiness(true, confirmed: true).isEmpty)
-        XCTAssertEqual(sentKey(session.offer(b, scope: "new")), 1)
-        XCTAssertEqual(session.nativeApp(1, entered: true), [.reconnect("Native app transition interrupted canvas command")])
+        XCTAssertEqual(sentKey(session.nativeApp(0, entered: true)), 1)
+        XCTAssertTrue(session.nativeApp(0, entered: true).isEmpty)
+        guard case let .send(_, frame, _) = ack(session, 1).first else { return XCTFail() }
+        XCTAssertEqual(frame, a)
+        XCTAssertTrue(session.nativeApp(0xFD, entered: false).isEmpty)
+        XCTAssertEqual(sentKey(ack(session, 4)), 1)
+    }
+
+    func testTakeoverDuringUpdateReplaysIdenticalFrameAfterRelaunch() {
+        let session = NimoCanvasSession()
+        _ = session.offer(a, scope: "app:1"); _ = session.readiness(true)
+        XCTAssertEqual(sentKey(ack(session, 1)), 4)
+        XCTAssertTrue(session.nativeApp(0, entered: true).isEmpty)
+        XCTAssertEqual(sentKey(ack(session, 4)), 1)
+        guard case let .send(_, frame, _) = ack(session, 1).first else { return XCTFail("Missing replay Update") }
+        XCTAssertEqual(frame, a)
+        XCTAssertTrue(ack(session, 4).isEmpty)
+        XCTAssertTrue(session.offer(a, scope: "app:1").isEmpty)
+    }
+
+    func testStartupStockUiPreservesReconnectScene() {
+        let session = NimoCanvasSession(); connected(session)
+        session.disconnected()
+        XCTAssertTrue(session.nativeApp(0, entered: true).isEmpty)
+        XCTAssertTrue(session.activate().isEmpty)
+        XCTAssertEqual(sentKey(session.readiness(true)), 1)
+        guard case let .send(_, frame, _) = ack(session, 1).first else { return XCTFail() }
+        XCTAssertEqual(frame, a)
+    }
+
+    func testActivationEntersBlankCanvasBeforeAnyMiniapp() {
+        let session = NimoCanvasSession()
+        XCTAssertTrue(session.activate().isEmpty)
+        XCTAssertEqual(sentKey(session.readiness(true)), 1)
+        guard case let .send(_, frame, _) = ack(session, 1).first else { return XCTFail() }
+        XCTAssertEqual(frame, Data([0, 0, 1]))
+    }
+
+    func testExplicitExitStopsRestorationUntilAnotherConnection() {
+        let session = NimoCanvasSession(); connected(session)
+        XCTAssertEqual(sentKey(session.exit()), 3)
+        XCTAssertTrue(session.nativeApp(0, entered: true).isEmpty)
+        XCTAssertTrue(ack(session, 3).isEmpty)
+        XCTAssertTrue(session.nativeApp(0xFD, entered: false).isEmpty)
+        session.disconnected()
+        _ = session.activate()
+        XCTAssertEqual(sentKey(session.readiness(true)), 1)
+    }
+
+    func testSuccessfulUpdateRestoresProbeBudgetForNextRecovery() {
+        let session = NimoCanvasSession()
+        _ = session.activate(); _ = session.readiness(true)
+        for episode in 0 ..< 2 {
+            if episode > 0 { XCTAssertEqual(sentKey(session.nativeApp(0, entered: true)), 1) }
+            for _ in 0 ..< 3 {
+                _ = ack(session, 1, status: 7)
+                XCTAssertEqual(sentKey(session.retryNotReady()), 1)
+            }
+            XCTAssertEqual(sentKey(ack(session, 1)), 4)
+            XCTAssertTrue(ack(session, 4).isEmpty)
+        }
+    }
+
+    func testProbesAreBoundedAndHeartbeatCanStillRecover() {
+        let session = NimoCanvasSession()
+        _ = session.activate(); _ = session.readiness(true)
+        for _ in 0 ..< 3 {
+            _ = ack(session, 1, status: 7)
+            XCTAssertEqual(sentKey(session.retryNotReady()), 1)
+        }
+        _ = ack(session, 1, status: 7)
+        XCTAssertTrue(session.retryNotReady().isEmpty)
+        XCTAssertEqual(sentKey(session.readiness(true, confirmed: true)), 1)
     }
 }

package/ios/Tests/NimoCanvasTransportTests.swift

@@ -33,6 +33,31 @@ private final class NimoTestClock {
 final class NimoCanvasTransportTests: XCTestCase {
     private let frame = Data([0, 0, 1])
 
+    func testNotReadyProbesAreTimedBoundedAndCancelled() {
+        for stop in ["budget", "disconnect", "exit", "notReady"] {
+            let clock = NimoTestClock()
+            var keys: [Int] = []
+            let canvas = NimoCanvasCoordinator(schedule: clock.schedule, writeCapacity: { 512 }, enqueue: { frames, start, complete in
+                keys.append(Int(frames[0][9])); start(); complete(); return true
+            }, reconnect: { XCTFail($0) }, rejected: { _ in })
+            canvas.activate(); canvas.readiness(true)
+            for attempt in 0 ..< 4 {
+                canvas.response(key: 1, payload: Data([7]))
+                if stop == "disconnect" { canvas.disconnected() }
+                if stop == "exit" { canvas.exit() }
+                if stop == "notReady" { canvas.readiness(false) }
+                let before = keys.count
+                clock.advance(0.999)
+                XCTAssertEqual(keys.count, before)
+                clock.advance(0.001)
+                XCTAssertEqual(keys.count, before + (stop == "budget" && attempt < 3 ? 1 : 0))
+                if stop != "budget" { break }
+            }
+            clock.advance(60)
+            XCTAssertEqual(keys.count, stop == "budget" ? 4 : 1)
+        }
+    }
+
     func testEarlyAckOnlyAdvancesAfterFinalWriteCompletes() {
         let clock = NimoTestClock()
         var chains: [[Data]] = [], starts: [() -> Void] = [], completes: [() -> Void] = []

package/ios/Tests/NimoDeviceCommandsTests.swift

@@ -0,0 +1,16 @@
+import Foundation
+@testable import MentraBluetoothSDK
+import XCTest
+
+final class NimoDeviceCommandsTests: XCTestCase {
+    func testSystemEnglishAndFactoryResetMatchFirmwareWireCommands() {
+        func hex(_ bytes: Data) -> String {
+            bytes.map { String(format: "%02X", $0) }.joined()
+        }
+        XCTAssertEqual(hex(NimoFrameCodec.encodeFrame(cmd: NimoProtocol.CMD_SET_PARAMETER,
+                                                      key: NimoProtocol.SET_SYSTEM_LANGUAGE, payload: Data([NimoProtocol.LANGUAGE_ENGLISH]))),
+                       "BF020500702500000324010001")
+        XCTAssertEqual(hex(NimoFrameCodec.encodeFrame(cmd: NimoProtocol.CMD_CONTROL_FACTORY,
+                                                      key: NimoProtocol.FACTORY_RECOVER, payload: Data())), "BF0204005358000008030000")
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/bluetooth-sdk",
-  "version": "3.2.1-beta.506",
+  "version": "3.2.1-beta.512",
   "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.2.1-beta.506"
+    "@mentra/cloud-protocol": "3.2.1-beta.512"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",

package/src/_private/BluetoothSdkModule.ts

@@ -109,6 +109,8 @@ declare class BluetoothSdkNativeModule extends NativeModule<BluetoothSdkModuleEv
   connectSimulated(): Promise<void>
   disconnect(): Promise<void>
   forget(): Promise<void>
+  /** Explicit Unpair also resets connected NIMO glasses before forgetting. */
+  unpair(): Promise<void>
   forgetController(): Promise<void>
   showDashboard(): Promise<void>
   setBrightness(level: number, autoMode?: boolean | null): Promise<void>

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.2.1",
-  "releaseIdentity": "3.2.1-beta.506",
-  "releaseSetId": "mentra-3.2.1-beta.506",
-  "sourceCommit": "cb87ecd9de2a0d253e54728493f1e8002c128207",
-  "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.2.1/mentra-live-ota-3.2.1-beta.506.json",
-  "otaManifestSha256": "af76d286c921c9c8f22b938a92b0b13aa983f1983c377006df51a1ad7646eed7"
+  "releaseIdentity": "3.2.1-beta.512",
+  "releaseSetId": "mentra-3.2.1-beta.512",
+  "sourceCommit": "e09a07ee7b71972e75a5051003ec561c12e6cb9b",
+  "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.2.1/mentra-live-ota-3.2.1-beta.512.json",
+  "otaManifestSha256": "bd24cbd8279319912d643699eeb435df3ca88582194953583491a3625799ec01"
 })