@mentra/bluetooth-sdk 3.2.1 → 3.3.0-beta.954

package/ios/Tests/VersionInfoCommandTests.swift

@@ -4,6 +4,9 @@ import XCTest
 @MainActor
 private final class VersionInfoCommandTransport: MentraLive {
     var requestId: String?
+    var reply = true
+    var includeResponseId = true
+    var metadataOverrides: [String: Any] = [:]
 
     override func sendJson(_ jsonOriginal: [String: Any], wakeUp: Bool, requireAck: Bool) {
         XCTAssertEqual(jsonOriginal["type"] as? String, "request_version")
@@ -14,7 +17,9 @@ private final class VersionInfoCommandTransport: MentraLive {
             let command = try XCTUnwrap(JSONSerialization.jsonObject(with: bytes) as? [String: Any])
             let id = try XCTUnwrap(command["request_id"] as? String)
             requestId = id
-            let common: [String: Any] = ["request_id": id, "sid": "asg-1", "chunkCount": 2]
+            guard reply else { return }
+            var common: [String: Any] = ["sid": "asg-1", "chunkCount": 2]
+            if includeResponseId { common["request_id"] = id }
             for chunk: [String: Any] in [
                 ["type": "version_info_1", "chunkIndex": 1, "final": false,
                  "build_number": "303000008", "app_version": "3.3.0"],
@@ -22,6 +27,7 @@ private final class VersionInfoCommandTransport: MentraLive {
                  "bes_fw_version": "26.9.23.0", "mtk_fw_version": "MentraLive_20260921.0"],
             ] {
                 let response = common.merging(chunk) { _, value in value }
+                    .merging(metadataOverrides) { _, value in value }
                 try processReceivedData(JSONSerialization.data(withJSONObject: response))
             }
         } catch {
@@ -37,7 +43,12 @@ final class VersionInfoCommandTests: XCTestCase {
         let transport = VersionInfoCommandTransport()
         DeviceManager.shared.sgc = transport
         let sdk = MentraBluetoothSDK()
+        var diagnostics: [[String: Any]] = []
+        let sink = Bridge.addEventSink { event, body in
+            if let diagnostic = self.diagnostic(event, body) { diagnostics.append(diagnostic) }
+        }
         defer {
+            Bridge.removeEventSink(sink)
             sdk.invalidate()
             DeviceManager.shared.sgc = previous
         }
@@ -49,5 +60,135 @@ final class VersionInfoCommandTests: XCTestCase {
         XCTAssertEqual(result.appVersion, "3.3.0")
         XCTAssertEqual(result.besFirmwareVersion, "26.9.23.0")
         XCTAssertEqual(result.mtkFirmwareVersion, "MentraLive_20260921.0")
+        XCTAssertEqual(diagnostics.compactMap { $0["stage"] as? String }, [
+            "registered", "response-waiting", "response-complete", "resolved",
+        ])
+        XCTAssertTrue(diagnostics.allSatisfy { $0["requestId"] as? String == transport.requestId })
+        XCTAssertEqual(diagnostics[1]["responseRequestId"] as? String, transport.requestId)
+        XCTAssertEqual(diagnostics[2]["responseChunk"] as? String, "version_info_3")
+        XCTAssertEqual(diagnostics[1]["_responseChunkIndex"] as? String, "number:1")
+        XCTAssertEqual(diagnostics[2]["_responseChunkIndex"] as? String, "number:2")
+        XCTAssertEqual(diagnostics[1]["_responseFinal"] as? String, "boolean:false")
+        XCTAssertFalse(diagnostics.contains { $0["besFirmwareVersion"] != nil || $0["serialNumber"] != nil })
+    }
+
+    func testUncorrelatedResponseAndCancellationRetainThePendingUuidAndOriginalError() async throws {
+        let previous = DeviceManager.shared.sgc
+        let transport = VersionInfoCommandTransport()
+        transport.includeResponseId = false
+        DeviceManager.shared.sgc = transport
+        let sdk = MentraBluetoothSDK()
+        var diagnostics: [[String: Any]] = []
+        let sink = Bridge.addEventSink { event, body in
+            if let diagnostic = self.diagnostic(event, body) { diagnostics.append(diagnostic) }
+        }
+        defer {
+            Bridge.removeEventSink(sink)
+            sdk.invalidate()
+            DeviceManager.shared.sgc = previous
+        }
+        let task = Task { try await sdk.requestVersionInfo() }
+        while transport.requestId == nil {
+            await Task.yield()
+        }
+        do {
+            _ = try await sdk.requestVersionInfo()
+            XCTFail("The original pending request must retain its slot")
+        } catch let error as BluetoothSdkError {
+            XCTAssertEqual(error.code, "request_in_flight")
+        }
+        task.cancel()
+        do {
+            _ = try await task.value
+            XCTFail("Uncorrelated responses must not complete the request")
+        } catch let error as BluetoothSdkError {
+            XCTAssertEqual(error.code, "request_cancelled")
+            let rejected = try XCTUnwrap(diagnostics.last)
+            XCTAssertEqual(rejected["stage"] as? String, "rejected")
+            XCTAssertEqual(rejected["code"] as? String, error.code)
+            XCTAssertEqual(rejected["message"] as? String, error.message)
+        }
+        XCTAssertEqual(diagnostics.compactMap { $0["stage"] as? String }, [
+            "registered", "response-ignored", "response-ignored", "refused", "rejected",
+        ])
+        XCTAssertTrue(diagnostics.allSatisfy { $0["requestId"] as? String == transport.requestId })
+        XCTAssertEqual(diagnostics[1]["responseRequestId"] as? String, "")
+    }
+
+    func testNoResponseRetainsTheOriginalTimeoutAndElapsedTime() async throws {
+        let previous = DeviceManager.shared.sgc
+        let transport = VersionInfoCommandTransport()
+        transport.reply = false
+        DeviceManager.shared.sgc = transport
+        let sdk = MentraBluetoothSDK()
+        var diagnostics: [[String: Any]] = []
+        let sink = Bridge.addEventSink { event, body in
+            if let diagnostic = self.diagnostic(event, body) { diagnostics.append(diagnostic) }
+        }
+        defer {
+            Bridge.removeEventSink(sink)
+            sdk.invalidate()
+            DeviceManager.shared.sgc = previous
+        }
+        do {
+            _ = try await sdk.requestVersionInfo()
+            XCTFail("An absent response must time out")
+        } catch let error as BluetoothSdkError {
+            XCTAssertEqual(error.code, "request_timeout")
+            let rejected = try XCTUnwrap(diagnostics.last)
+            XCTAssertEqual(rejected["code"] as? String, error.code)
+            XCTAssertEqual(rejected["message"] as? String, error.message)
+            XCTAssertGreaterThanOrEqual(try XCTUnwrap(rejected["elapsedMs"] as? Int), 15000)
+        }
+        XCTAssertEqual(diagnostics.compactMap { $0["stage"] as? String }, ["registered", "rejected"])
+        XCTAssertTrue(diagnostics.allSatisfy { $0["requestId"] as? String == transport.requestId })
+    }
+
+    func testMalformedMetadataRetainsItsTypeThroughTheActualBridgeLog() async throws {
+        let previous = DeviceManager.shared.sgc
+        let transport = VersionInfoCommandTransport()
+        DeviceManager.shared.sgc = transport
+        let sdk = MentraBluetoothSDK()
+        var diagnostics: [[String: Any]] = []
+        let sink = Bridge.addEventSink { event, body in
+            if let diagnostic = self.diagnostic(event, body) { diagnostics.append(diagnostic) }
+        }
+        defer {
+            Bridge.removeEventSink(sink)
+            sdk.invalidate()
+            DeviceManager.shared.sgc = previous
+        }
+        for (wireKey, logKey, value, expected) in [
+            ("chunkIndex", "_responseChunkIndex", true as Any, "boolean:true"),
+            ("chunkCount", "_responseChunkCount", true as Any, "boolean:true"),
+            ("final", "_responseFinal", 1 as Any, "number:1"),
+        ] {
+            diagnostics.removeAll()
+            transport.requestId = nil
+            transport.metadataOverrides = [wireKey: value]
+            let task = Task { try await sdk.requestVersionInfo() }
+            while transport.requestId == nil {
+                await Task.yield()
+            }
+            task.cancel()
+            do {
+                _ = try await task.value
+                XCTFail("Malformed metadata must not resolve")
+            } catch let error as BluetoothSdkError {
+                XCTAssertEqual(error.code, "request_cancelled")
+            }
+            let ignored = diagnostics.filter { $0["stage"] as? String == "response-ignored" }
+            XCTAssertEqual(ignored.count, 2)
+            XCTAssertTrue(ignored.allSatisfy { $0[logKey] as? String == expected })
+        }
+    }
+
+    private func diagnostic(_ event: String, _ body: [String: Any]) -> [String: Any]? {
+        guard event == "log", let message = body["message"] as? String,
+              message.contains("layer=sdk_version_request"),
+              let payload = message.range(of: " payload="),
+              let data = String(message[payload.upperBound...]).data(using: .utf8)
+        else { return nil }
+        return try? JSONSerialization.jsonObject(with: data) as? [String: Any]
     }
 }

package/ios/Tests/WifiCredentialLoggingTests.swift

@@ -0,0 +1,42 @@
+@testable import MentraBluetoothSDK
+import XCTest
+
+/// Captures packed BLE writes instead of sending them, so the real device dispatch,
+/// command serialization and transport logging run without a radio.
+@MainActor
+private final class CapturingMentraLive: MentraLive {
+    var writes: [Data] = []
+
+    override func queueSend(_ data: Data, id _: String, trace _: BleWriteTrace?) {
+        writes.append(data)
+    }
+}
+
+@MainActor
+final class WifiCredentialLoggingTests: XCTestCase {
+    func testWifiCredentialsReachTheBleQueueWithoutBeingLogged() {
+        let ssid = "synthetic-\(UUID().uuidString)"
+        let password = UUID().uuidString
+        var logs: [String] = []
+        let sink = Bridge.addEventSink { event, body in
+            if event == "log", let message = body["message"] as? String {
+                logs.append(message)
+            }
+        }
+        defer { Bridge.removeEventSink(sink) }
+        let manager = DeviceManager()
+        let live = CapturingMentraLive()
+        manager.sgc = live
+
+        manager.sendWifiCredentials(ssid, password)
+
+        XCTAssertFalse(logs.contains { $0.contains(password) }, "password logged")
+        XCTAssertTrue(logs.contains("MAN: Sending wifi credentials: \(ssid)"))
+        XCTAssertTrue(logs.contains("LIVE: Sending data to glasses: <set_wifi_credentials with credentials omitted>"))
+        // The glasses still receive the unchanged credentials.
+        let wire = live.writes.map { String(decoding: $0, as: UTF8.self) }.joined()
+        XCTAssertTrue(wire.contains("set_wifi_credentials"))
+        XCTAssertTrue(wire.contains(ssid))
+        XCTAssertTrue(wire.contains(password))
+    }
+}

package/package.json

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

package/src/BluetoothSdk.types.ts

@@ -1125,6 +1125,7 @@ export type BluetoothSdkModuleEvents = {
   glasses_status: (changed: Partial<GlassesStatus>) => void
   bluetooth_status: (changed: Partial<BluetoothStatus>) => void
   log: (event: LogEvent) => void
+  sdk_update_notice: (event: {message: string}) => void
   device_discovered: (device: Device) => void
   default_device_changed: (event: {device?: Device}) => void
   // Individual event handlers

package/src/_private/BluetoothSdkModule.ts

@@ -2,7 +2,7 @@ import {createScanSession} from "./scanSession"
 import {NativeModule, requireNativeModule} from "expo"
 import {Platform} from "react-native"
 
-import {installNativeLogConsole} from "./nativeLogConsole"
+import {installNativeLogConsole, installSdkUpdateNotice} from "./nativeLogConsole"
 
 import {
   BluetoothSettingsUpdate,
@@ -350,6 +350,7 @@ export type BluetoothSdkInternalModule = BluetoothSdkNativeModule
 // NativeModule<BluetoothSdkModuleEvents> already extends EventEmitter<BluetoothSdkModuleEvents>
 const NativeBluetoothSdkModule = requireNativeModule<BluetoothSdkNativeModule>("BluetoothSdk")
 installNativeLogConsole(NativeBluetoothSdkModule, Platform.OS)
+installSdkUpdateNotice(NativeBluetoothSdkModule)
 
 const DEFAULT_CONNECT_OPTIONS: Required<ConnectOptions> = {
   saveAsDefault: true,

package/src/_private/MentraLocalNetworkModule.ts

@@ -1,5 +1,32 @@
 import {NativeModule, requireOptionalNativeModule} from "expo"
 
+export type NetworkCapabilitiesDiagnostic = {
+  wifi: boolean
+  cellular: boolean
+  ethernet: boolean
+  vpn: boolean
+  internet: boolean
+  validated: boolean
+  captivePortal: boolean
+}
+
+export type NetworkObservation = {
+  present: boolean
+  // A present network with null capabilities has disappeared or cannot be inspected.
+  capabilities: NetworkCapabilitiesDiagnostic | null
+}
+
+export type NetworkDiagnostics = {
+  sampledAtMs: number
+  processBound: NetworkObservation
+  // ConnectivityManager.activeNetwork is the caller's active default, not a privileged global read.
+  activeNetwork: NetworkObservation
+  glassesLocal: NetworkObservation
+  processBoundMatchesActive: boolean
+  processBoundMatchesGlassesLocal: boolean
+  activeNetworkMatchesGlassesLocal: boolean
+}
+
 export type LocalNetworkResponse = {
   status: number
   headers: Record<string, string>
@@ -26,6 +53,7 @@ type LocalNetworkEvents = {
 }
 
 declare class MentraLocalNetworkNativeModule extends NativeModule<LocalNetworkEvents> {
+  getNetworkDiagnostics(): NetworkDiagnostics
   connect(ssid: string, password: string): Promise<{connected: boolean; ssid: string; localAddress?: string}>
   request(
     requestId: string,

package/src/_private/nativeLogConsole.ts

@@ -22,3 +22,22 @@ export function installNativeLogConsole(source: SubscribedLogSource, platform: s
     console.log(`[native:${platform}]`, nativeLogMessage(message))
   })
 }
+
+type UpdateNoticeSource = {
+  addListener(event: "sdk_update_notice", listener: (event: {message: string}) => void): {remove(): void}
+}
+
+const updateNoticeKey = Symbol.for("mentra.bluetooth-sdk.update-notice")
+type SubscribedUpdateNoticeSource = UpdateNoticeSource & {[updateNoticeKey]?: {remove(): void}}
+
+/**
+ * The native SDK checks for a newer Mentra Bluetooth SDK at startup and emits
+ * its banner when this app is behind. A console warning reaches the developer
+ * in Metro and, in debug builds, as a LogBox warning; release builds show no UI.
+ */
+export function installSdkUpdateNotice(source: SubscribedUpdateNoticeSource): void {
+  source[updateNoticeKey]?.remove()
+  source[updateNoticeKey] = source.addListener("sdk_update_notice", ({message}) => {
+    console.warn(message)
+  })
+}

package/src/generated/changelogCatalog.ts

@@ -1,13 +1,17 @@
 /** Generated from /changelogs. Do not edit directly. */
 export const GENERATED_RELEASE_CHANGELOGS = Object.freeze(
 [
+  {
+    "version": "3.3.0",
+    "markdown": "This release is under active development. User-facing changes will be documented as they land."
+  },
   {
     "version": "3.2.1",
     "markdown": "- **Livestreamer:** \"Stream Here\" now works without a Wi-Fi network. Improved stream startup and connection reliability.\n- **Photos and gallery:** More reliable photo capture and gallery syncing.\n- **Mentra AI:** Reliability improvements and bug fixes.\n- **Miniapps:** Smoother transitions, with back buttons and gestures that take you to the previous screen inside a miniapp.\n- **Pairing and connections:** Improved G1 pairing and G2 background reconnection.\n- **Glasses updates:** Fixed repeated update checks and improved recovery after interrupted updates.\n- **Mentra Maps:** Bug fixes.\n- **NIMO:** Improved text and map layouts.\n- **Self-hosting:** Connect the Mentra App to your own self-hosted Mentra backend."
   },
   {
     "version": "3.2.0",
-    "markdown": "- Improved glasses connectivity and Wi-Fi setup."
+    "markdown": "- Improved glasses connectivity and Wi-Fi setup.\n\n- Breaking Bluetooth SDK change: `forgetWifiNetwork(ssid)` now returns `WifiForgetResult` instead of `WifiStatusChangeEvent`. Migrate status-only consumers to the semantic `outcome`; the requested network remains `ssid`, while optional post-command connectivity is reported by `connected`, `currentSsid`, and `localIp`."
   },
   {
     "version": "3.1.1",

package/src/generated/releaseMetadata.ts

@@ -11,10 +11,10 @@ export interface BluetoothSdkReleaseMetadata {
 
 export const BLUETOOTH_SDK_RELEASE_METADATA: Readonly<BluetoothSdkReleaseMetadata> = Object.freeze({
   "schemaVersion": 1,
-  "familyBaseVersion": "3.2.1",
-  "releaseIdentity": "3.2.1",
-  "releaseSetId": "mentra-3.2.1",
-  "sourceCommit": "be56e1456c69f681985642f376ed3d397ec022cc",
-  "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.2.1/mentra-live-ota-3.2.1-beta.578.json",
-  "otaManifestSha256": "21af62269e29fd2ee6b9737745a895694bc221672b191d80795057b5a832f400"
+  "familyBaseVersion": "3.3.0",
+  "releaseIdentity": "3.3.0-beta.954",
+  "releaseSetId": "mentra-3.3.0-beta.954",
+  "sourceCommit": "25f6b1d70ce39dfe5d454021542f1627e256775a",
+  "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-beta.954.json",
+  "otaManifestSha256": "03d976cb897215b97b5c40a53dabbc8356a045d1fbb57d5ad2c95bbc21203e21"
 })

package/src/ota-transport/index.ts

@@ -1,9 +1,16 @@
 // This public adapter is the package-owned boundary over its native implementation.
 // eslint-disable-next-line no-restricted-imports
-import MentraLocalNetwork from "../_private/MentraLocalNetworkModule"
+import MentraLocalNetwork, {type NetworkDiagnostics} from "../_private/MentraLocalNetworkModule"
 // eslint-disable-next-line no-restricted-imports
 import MentraOtaServer from "../ota-server"
 
+// eslint-disable-next-line no-restricted-imports
+export type {
+  NetworkCapabilitiesDiagnostic,
+  NetworkDiagnostics,
+  NetworkObservation,
+} from "../_private/MentraLocalNetworkModule"
+
 export type OtaTransportSubscription = {remove(): void}
 
 export type OtaLocalNetworkConnection = {
@@ -55,6 +62,8 @@ export type OtaServerResult = {
  */
 export const otaLocalNetwork = Object.freeze({
   isAvailable: (): boolean => MentraLocalNetwork != null,
+  /** Synchronous local observation; no network I/O, route changes or network identities. */
+  getNetworkDiagnostics: (): NetworkDiagnostics | null => MentraLocalNetwork?.getNetworkDiagnostics() ?? null,
   connect: async (ssid: string, password: string): Promise<OtaLocalNetworkConnection> => {
     if (!MentraLocalNetwork) throw new Error("Scoped local networking is not available in this native build")
     return MentraLocalNetwork.connect(ssid, password)