@mentra/bluetooth-sdk 3.2.0-dev.200 → 3.2.0-dev.203

package/README.md

@@ -152,21 +152,19 @@ iOS apps should include usage descriptions:
 Use `scan()` when your app needs to show a picker. It calls `onResults` every time the discovered list changes, then resolves with the final list after the timeout.
 
 ```ts
-import BluetoothSdk, {
-  DeviceModels,
-} from '@mentra/bluetooth-sdk'
+import BluetoothSdk, {DeviceModels} from "@mentra/bluetooth-sdk"
 
 const devices = await BluetoothSdk.scan(DeviceModels.MentraLive, {
   timeoutMs: 10_000,
   onResults: (nextDevices) => {
-    console.log('Nearby glasses:', nextDevices)
+    console.log("Nearby glasses:", nextDevices)
   },
   onDiagnostic: (hint) => showScanHint(hint.message),
 })
 
 const device = await chooseDevice(devices)
 if (!device) {
-  throw new Error('No Mentra Live glasses selected')
+  throw new Error("No Mentra Live glasses selected")
 }
 
 await BluetoothSdk.connect(device)
@@ -275,9 +273,9 @@ subpath for common lifecycle plumbing. Use the root `BluetoothSdk` object for
 commands such as `requestPhoto()`, `startStream()`, and `setMicState()`.
 
 ```tsx
-import {Button, Text, View} from 'react-native'
-import {DeviceModels} from '@mentra/bluetooth-sdk'
-import {useBluetoothEvent, useMentraBluetooth} from '@mentra/bluetooth-sdk/react'
+import {Button, Text, View} from "react-native"
+import {DeviceModels} from "@mentra/bluetooth-sdk"
+import {useBluetoothEvent, useMentraBluetooth} from "@mentra/bluetooth-sdk/react"
 
 export function DeviceScreen() {
   const mentra = useMentraBluetooth({
@@ -285,13 +283,13 @@ export function DeviceScreen() {
     scanTimeoutMs: 10_000,
   })
 
-  useBluetoothEvent('button_press', (event) => {
-    console.log('Glasses button:', event.buttonId, event.pressType)
+  useBluetoothEvent("button_press", (event) => {
+    console.log("Glasses button:", event.buttonId, event.pressType)
   })
 
   return (
     <View>
-      <Text>{mentra.glasses.connected ? 'Connected' : 'Disconnected'}</Text>
+      <Text>{mentra.glasses.connected ? "Connected" : "Disconnected"}</Text>
       <Button disabled={mentra.busy} title="Scan" onPress={() => mentra.scan.start()} />
       {mentra.scan.devices.map((device) => (
         <Button key={device.id} title={device.name} onPress={() => mentra.connect(device)} />
@@ -314,11 +312,11 @@ The React hook exposes `glasses.connection` as a discriminated union:
 
 ```ts
 type GlassesConnectionStatus =
-  | {state: 'disconnected'}
-  | {state: 'scanning'}
-  | {state: 'connecting'}
-  | {state: 'bonding'}
-  | {state: 'connected'; fullyBooted: boolean}
+  | {state: "disconnected"}
+  | {state: "scanning"}
+  | {state: "connecting"}
+  | {state: "bonding"}
+  | {state: "connected"; fullyBooted: boolean}
 ```
 
 Use `connection.state` for link progress. `fullyBooted` only exists when `state === 'connected'`. Android and iOS native APIs also keep `connectionState`, `connected`, and `fullyBooted` as native status properties for Kotlin and Swift callers.
@@ -374,11 +372,14 @@ await BluetoothSdk.setDashboardPosition(4, 2)
 const networks = await BluetoothSdk.requestWifiScan()
 console.log(networks.map((network) => network.ssid))
 
-const wifiStatus = await BluetoothSdk.sendWifiCredentials('Office WiFi', 'secret')
+const savedResult = await BluetoothSdk.getSavedWifiNetworks()
+if (savedResult.outcome === "confirmed") console.log(savedResult.networks)
+
+const wifiStatus = await BluetoothSdk.sendWifiCredentials("Office WiFi", "secret")
 console.log(wifiStatus.state)
 
-const forgetStatus = await BluetoothSdk.forgetWifiNetwork('Office WiFi')
-console.log(forgetStatus.state)
+const forgetResult = await BluetoothSdk.forgetWifiNetwork("Office WiFi")
+console.log(forgetResult.outcome)
 
 const hotspotStatus = await BluetoothSdk.setHotspotState(true)
 console.log(hotspotStatus.state)
@@ -389,19 +390,11 @@ const galleryAck = await BluetoothSdk.setGalleryModeEnabled(true)
 console.log(galleryAck.status)
 await BluetoothSdk.setGalleryModeEnabled(false)
 
-await BluetoothSdk.setPreferredMic('auto')
+await BluetoothSdk.setPreferredMic("auto")
 await BluetoothSdk.setMicState(true)
 await BluetoothSdk.setOwnAppAudioPlaying(false)
 
-const ledAck = await BluetoothSdk.rgbLedControl(
-  `led-${Date.now()}`,
-  'com.example.app',
-  'on',
-  'green',
-  500,
-  500,
-  3,
-)
+const ledAck = await BluetoothSdk.rgbLedControl(`led-${Date.now()}`, "com.example.app", "on", "green", 500, 500, 3)
 console.log(ledAck.state)
 ```
 
@@ -440,7 +433,15 @@ await sdk.setDashboardContent("")
 Settings commands that return `SettingsAckSuccessEvent` reject when the ASG reports an error ack. The SDK updates its local settings store only after that ASG ack resolves successfully, so observed SDK state reflects the acknowledged glasses state rather than a queued request. Raw `settings_ack` listener events still use `SettingsAckEvent` because they can include both success and failure statuses. `rgbLedControl(...)` resolves from a successful ASG `rgb_led_control_response` and rejects when the ASG reports `state: "error"`; raw `settings_ack` and `rgb_led_control_response` events remain available through listeners.
 
 WiFi, hotspot, and version-info commands resolve from the ASG response path, not local dispatch:
-`requestWifiScan()` resolves from the ASG `wifi_scan_result` completion response with the updated scan list, including `[]` when no networks are found. Intermediate `wifi_scan_result` events can arrive with `scanComplete: false` while the glasses stream discovered networks; the final event uses `scanComplete: true`. If older glasses stream non-empty scan results but never send the completion event, the request resolves with the accumulated scan list when the request times out. `sendWifiCredentials()` resolves when the requested SSID is connected, `forgetWifiNetwork()` resolves when that SSID is no longer connected, and `setHotspotState()` resolves when the requested hotspot state is reported. `requestVersionInfo()` waits for all chunks declared by the correlated response's `chunkCount`, `chunkIndex`, and `final` metadata. Legacy single-message responses complete immediately; legacy chunked responses complete on `version_info_3` after `version_info_1`. Missing final chunks time out rather than returning partial data after a quiet period.
+`requestWifiScan()` resolves from the ASG `wifi_scan_result` completion response with the updated scan list, including `[]` when no networks are found. Intermediate `wifi_scan_result` events can arrive with `scanComplete: false` while the glasses stream discovered networks; the final event uses `scanComplete: true`. If older glasses stream non-empty scan results but never send the completion event, the request resolves with the accumulated scan list when the request times out. `sendWifiCredentials()` resolves when the requested SSID is connected, `forgetWifiNetwork()` returns a semantic `WifiForgetResult`, `getSavedWifiNetworks()` returns a semantic `SavedWifiNetworksResult`, `setHotspotState()` resolves when the requested hotspot state is reported, and `requestVersionInfo()` waits for all chunks declared by the correlated response's `chunkCount`, `chunkIndex`, and `final` metadata. Legacy single-message responses complete immediately; legacy chunked responses complete on `version_info_3` after `version_info_1`. Missing final chunks time out rather than returning partial data after a quiet period.
+
+Current Mentra Live builds advertise `wifiForgetResultVersion` and `savedWifiNetworksVersion` in `version_info_1`. Native queues calls while those capabilities are unknown, sharing one 15-second deadline for negotiation and response. A discovery timeout rejects and never guesses that the glasses are legacy. Only version 1 is supported: modern commands carry `protocolVersion: 1`, a nonempty request ID, and the glasses process session ID; legacy forget commands omit all three fields. Unknown or malformed versions fail closed. Correlated results must match the complete tuple and (for forget) exact SSID; unrelated `wifi_status` events never settle a modern request. Session changes and disconnects reject pending WiFi work instead of allowing stale responses to cross sessions.
+
+`WifiForgetResult.outcome` is `confirmed`, `dispatched`, `not_found`, `unsupported`, `failed`, or `legacy_unverified`. K900 returns `dispatched`: ASG queued its asynchronous SystemUI broadcast, but the vendor API provides no completion callback and credential removal is not verified. `connected`, `currentSsid`, and `localIp` are best-effort diagnostic snapshot fields; `connected` is omitted when ASG cannot read the link state and must not be interpreted as `false`. Older firmware without the capability advertisement uses the isolated legacy path; accepted native dispatch immediately returns `legacy_unverified`, with no invented link-state snapshot. `getSavedWifiNetworks()` preserves exact SSID identity. It returns `confirmed` only for a backend with reliable enumeration, while K900 and legacy firmware return a typed `unsupported` result because the vendor credential store has no reliable list response.
+
+Promise results expose semantic outcomes and optional link snapshots, not `mode`, `capabilityVersion`, `requestId`, or `sid`. A legacy result returns `legacy_unverified` immediately after actual native transport acceptance; no active or compatible glasses transport rejects with `dispatch_failed`.
+
+Raw `wifi_forget_result` listeners receive a discriminated event union. `mode: "modern"` carries `requestId`, `sid`, `protocolVersion`, and semantic `outcome`; `mode: "legacy"` preserves the older uncorrelated wire frame's `dispatched` boolean. Partial tuples are rejected. Terminal Wi-Fi events use at-least-once BLE delivery, so raw listeners can observe retries; deduplicate modern events by `(requestId, sid)`. Promise coordinators accept only the first matching terminal frame.
 
 The SDK automatically sends the phone wall clock once shortly after a glasses connection becomes ready. It waits for the initial command burst to drain before timestamping the command so startup queue delay does not become clock skew. The once-per-connection guard resets after disconnect, so every successful reconnect synchronizes again. The SDK does not periodically verify or correct clock skew during a long-lived connection; apps that require periodic reconciliation can compare `requestVersionInfo().systemTimeMs` with the phone clock.
 
@@ -525,15 +526,15 @@ Mentra Live also rejects `ota_start` before acknowledgement when its known batte
 
 ```ts
 const photo = await BluetoothSdk.requestPhoto({
-  size: 'medium',
-  webhookUrl: 'https://api.example.com/mentra/photo',
-  authToken: 'optional-token',
-  compress: 'medium',
+  size: "medium",
+  webhookUrl: "https://api.example.com/mentra/photo",
+  authToken: "optional-token",
+  compress: "medium",
   sound: true,
   exposureTimeNs: null, // auto exposure; pass a positive nanosecond value for manual exposure
   iso: null, // auto ISO; pass a positive ISO only with manual exposureTimeNs
 })
-console.log('photo delivered', photo.photoUrl ?? photo.uploadUrl, photo.fileSizeBytes)
+console.log("photo delivered", photo.photoUrl ?? photo.uploadUrl, photo.fileSizeBytes)
 ```
 
 `requestPhoto(...)` resolves only after the full photo action reaches terminal success: capture completed and the photo was delivered to the webhook, either directly from the glasses over Wi-Fi or through the phone's Bluetooth fallback relay. If you omit `requestId`, the SDK generates one and the terminal response includes it. It rejects if the ASG reports `state: "error"`, if phone-side fallback upload fails, if the SDK cannot send the command, or if no terminal `photo_response` arrives within 30 seconds. Photo requests use this longer operation-specific deadline because max-quality BLE fallback can legitimately exceed the 15-second deadline used by ordinary commands. Use `photo_status` for intermediate stages such as `accepted`, `configuring`, `capturing`, `captured`, `uploading`, `ble_fallback_compression`, `ready_for_transfer`, and `transferring`; `photo_status` is progress, while `photo_response` is terminal success/error. The raw `photo_response` event stream still includes both success and error events for subscribers. The webhook should accept multipart form data with a `photo` file and `requestId`. If `authToken` is provided, the uploader adds `Authorization: Bearer <token>`. The camera light is always enabled for photo capture.
@@ -554,8 +555,8 @@ The missing/factory persistent FOV base is 102 degrees with centered ROI; existi
 const streamId = `stream-${Date.now()}`
 
 await BluetoothSdk.startStream({
-  type: 'start_stream',
-  streamUrl: 'http://192.168.1.42:8889/mentra-live/whip',
+  type: "start_stream",
+  streamUrl: "http://192.168.1.42:8889/mentra-live/whip",
   streamId,
   video: {fps: 15},
 })
@@ -571,19 +572,19 @@ Use `rtmp://` or `rtmps://` for RTMP, `srt://` for SRT, and `http://` or `https:
 React Native components should use `useBluetoothEvent()` for hardware events:
 
 ```tsx
-import {useBluetoothEvent} from '@mentra/bluetooth-sdk/react'
+import {useBluetoothEvent} from "@mentra/bluetooth-sdk/react"
 
 export function HardwareEventLogger() {
-  useBluetoothEvent('button_press', (event) => console.log(event))
-  useBluetoothEvent('touch_event', (event) => console.log(event))
-  useBluetoothEvent('photo_status', (event) => console.log(event.status, event.resolvedConfig, event.captureMetadata))
-  useBluetoothEvent('stream_status', (event) => console.log(event))
-  useBluetoothEvent('speaking_status', (event) => console.log(event.speaking))
-  useBluetoothEvent('mic_pcm', (event) => {
+  useBluetoothEvent("button_press", (event) => console.log(event))
+  useBluetoothEvent("touch_event", (event) => console.log(event))
+  useBluetoothEvent("photo_status", (event) => console.log(event.status, event.resolvedConfig, event.captureMetadata))
+  useBluetoothEvent("stream_status", (event) => console.log(event))
+  useBluetoothEvent("speaking_status", (event) => console.log(event.speaking))
+  useBluetoothEvent("mic_pcm", (event) => {
     console.log(event.sampleRate, event.bitsPerSample, event.channels, event.encoding)
     console.log(event.pcm)
   })
-  useBluetoothEvent('mic_health', (event) => {
+  useBluetoothEvent("mic_health", (event) => {
     console.log(event.reason, event.sequenceGapEvents, event.decodeFailures)
   })
 

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

@@ -339,6 +339,8 @@ class BluetoothSdkModule : Module() {
             "local_transcription",
             "wifi_status_change",
             "wifi_scan_result",
+            "wifi_forget_result",
+            "saved_wifi_networks",
             "hotspot_status_change",
             "hotspot_error",
             "photo_response",
@@ -592,12 +594,14 @@ class BluetoothSdkModule : Module() {
 
         SdkCoroutineFunction("requestWifiScan") { -> requireSdk().requestWifiScan().map { it.toMap() } }
 
+        SdkCoroutineFunction("getSavedWifiNetworks") { -> requireSdk().getSavedWifiNetworks().toMap() }
+
         SdkCoroutineFunction("sendWifiCredentials") { ssid: String, password: String ->
             requireSdk().sendWifiCredentials(ssid, password).values
         }
 
         SdkCoroutineFunction("forgetWifiNetwork") { ssid: String ->
-            requireSdk().forgetWifiNetwork(ssid).values
+            requireSdk().forgetWifiNetwork(ssid).toMap()
         }
 
         SdkCoroutineFunction("setHotspotState") { enabled: Boolean ->

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

@@ -494,6 +494,8 @@ public class Bridge private constructor() {
                     ?.let {
                         body[VersionInfoResponseAccumulator.RESPONSE_REQUEST_ID_KEY] = it
                     }
+            body["versionInfoType"] = stringField("versionInfoType", "version_info_type")
+            body["sid"] = stringField("sid")
             body["androidVersion"] = stringField("androidVersion", "android_version")
             body["firmwareVersion"] = stringField("firmwareVersion", "firmware_version")
             body["besFirmwareVersion"] = stringField("besFirmwareVersion", "bes_fw_version")
@@ -512,6 +514,15 @@ public class Bridge private constructor() {
             (values["hotspotOtaVersion"] as? Number
                             ?: values["hotspot_ota_version"] as? Number)
                     ?.let { body["hotspotOtaVersion"] = it.toInt() }
+            for ((key, wireKey) in listOf(
+                "wifiForgetResultVersion" to "wifi_forget_result_version",
+                "savedWifiNetworksVersion" to "saved_wifi_networks_version",
+            )) {
+                if (values.containsKey(key) || values.containsKey(wireKey)) {
+                    // Preserve malformed presence: it must not become legacy or be rounded to v1.
+                    body[key] = values[key] ?: values[wireKey] ?: -1
+                }
+            }
             sendTypedMessage("version_info", body)
         }
 
@@ -592,6 +603,58 @@ public class Bridge private constructor() {
             sendTypedMessage("wifi_status_change", payload)
         }
 
+        @JvmStatic
+        fun sendWifiForgetResult(
+                requestId: String,
+                sid: String,
+                ssid: String,
+                protocolVersion: Int,
+                outcome: String,
+                legacyDispatched: Boolean?,
+                connected: Boolean?,
+                currentSsid: String,
+                localIp: String,
+                error: String?,
+        ) {
+            val body =
+                    normalizeWifiForgetResultEvent(
+                            requestId,
+                            sid,
+                            ssid,
+                            protocolVersion,
+                            outcome,
+                            legacyDispatched,
+                            connected,
+                            currentSsid,
+                            localIp,
+                            error,
+                    )
+            if (body == null) {
+                log("Dropping malformed wifi_forget_result without modern or legacy fields")
+                return
+            }
+            sendTypedMessage("wifi_forget_result", body)
+        }
+
+        @JvmStatic
+        fun sendSavedWifiNetworks(
+                requestId: String,
+                sid: String,
+                protocolVersion: Int,
+                outcome: String,
+                networks: List<String>,
+                error: String?,
+        ) {
+            val body = HashMap<String, Any>()
+            body["requestId"] = requestId
+            body["sid"] = sid
+            body["protocolVersion"] = protocolVersion
+            body["outcome"] = outcome
+            body["networks"] = networks
+            if (error != null) body["error"] = error
+            sendTypedMessage("saved_wifi_networks", body)
+        }
+
         /**
          * Claim the WiFi scan-results store for a newly requested scan. Called by the
          * SDK when it generates the scanId, BEFORE the scan command goes out: store

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

@@ -1784,6 +1784,9 @@ class DeviceManager {
         sgc?.requestWifiScan(scanId)
     }
 
+    fun requestSavedWifiNetworks(requestId: String, sid: String): Boolean =
+        sgc?.requestSavedWifiNetworks(requestId, sid) ?: false
+
     fun sendIncidentId(incidentId: String, apiBaseUrl: String? = null) {
         Bridge.log("MAN: Sending incidentId to glasses for log upload: $incidentId")
         sgc?.sendIncidentId(incidentId, apiBaseUrl)
@@ -1802,10 +1805,8 @@ class DeviceManager {
         sgc?.sendWifiCredentials(ssid, password)
     }
 
-    fun forgetWifiNetwork(ssid: String) {
-        Bridge.log("MAN: Forgetting wifi network: $ssid")
-        sgc?.forgetWifiNetwork(ssid)
-    }
+    fun forgetWifiNetwork(ssid: String, requestId: String? = null, sid: String? = null): Boolean =
+        sgc?.forgetWifiNetwork(ssid, requestId, sid) ?: false
 
     fun setHotspotState(enabled: Boolean) {
         Bridge.log("MAN: Setting glasses hotspot state: $enabled")

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

@@ -3,6 +3,6 @@ package com.mentra.bluetoothsdk
 /** Generated from /changelogs. Do not edit directly. */
 internal val GENERATED_RELEASE_CHANGELOGS: List<ReleaseChangelog> =
     listOf(
-        ReleaseChangelog(version = "3.2.0", markdown = "This release is under active development. User-facing changes will be documented as they land."),
+        ReleaseChangelog(version = "3.2.0", markdown = "This release is under active development. User-facing changes will be documented as they land.\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`."),
         ReleaseChangelog(version = "3.1.0", markdown = "Software updates are more reliable, with clearer progress and recovery when the glasses restart.\n\n- MentraOS, Mentra Engine, the Bluetooth SDK, and the glasses client now share one coordinated release version.\n- Mentra Live updates can continue across APK, system, and firmware restarts without asking the user to start the same update again.\n- Bluetooth photo capture and transfer diagnostics are more precise and less disruptive to normal glasses traffic."),
     )

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

@@ -3,9 +3,9 @@ package com.mentra.bluetoothsdk
 /** Generated by release CI. Do not edit in a release checkout. */
 internal object GeneratedReleaseMetadata {
     const val FAMILY_BASE_VERSION: String = "3.2.0"
-    const val RELEASE_IDENTITY: String = "3.2.0-dev.200"
-    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.200"
-    const val SOURCE_COMMIT: String = "1cdd911f596eba7b2b2f0e9ba5655c7ff16b5362"
-    const val OTA_MANIFEST_URL: String = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.200.json"
-    const val OTA_MANIFEST_SHA256: String = "f0b5cca2fa4d1d43acf5933fb4de629819d36a145a162c763f4faa27a7c8ff79"
+    const val RELEASE_IDENTITY: String = "3.2.0-dev.203"
+    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.203"
+    const val SOURCE_COMMIT: String = "7eb4deefff27d498c2b4562d628607f399aa1f40"
+    const val OTA_MANIFEST_URL: String = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.203.json"
+    const val OTA_MANIFEST_SHA256: String = "0ae026238c8e70970be4e181cc1ae73dd905418292edebddb610012f4f0a9b6f"
 }