@mentra/bluetooth-sdk 0.1.21-beta.5 → 3.1.0-beta.100

package/README.md

@@ -303,6 +303,8 @@ console.log(forgetStatus.state)
 const hotspotStatus = await BluetoothSdk.setHotspotState(true)
 console.log(hotspotStatus.state)
 
+await BluetoothSdk.setWifiAdbState(true) // Mentra Live Wi-Fi ADB (wireless debugging)
+
 const galleryAck = await BluetoothSdk.setGalleryModeEnabled(true)
 console.log(galleryAck.status)
 await BluetoothSdk.setGalleryModeEnabled(false)
@@ -328,6 +330,8 @@ Settings commands that return `SettingsAckSuccessEvent` reject when the ASG repo
 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, `setHotspotState()` resolves when the requested hotspot state is reported, and `requestVersionInfo()` resolves from the ASG `version_info` response instead of local store changes.
 
+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.
+
 React Native narrows returned values to success shapes where the raw listener event can also report errors:
 
 | API | Returned Value After `await` | Error Path |
@@ -335,6 +339,7 @@ React Native narrows returned values to success shapes where the raw listener ev
 | `requestPhoto(...)` | Terminal `PhotoSuccessResponseEvent` with `state: "success"` after capture and delivery finish. `uploadUrl` is always present; webhook JSON metadata such as `photoUrl`, `statusUrl`, `contentType`, or `fileSizeBytes` is included when the receiver returns it. | Rejects when raw `photo_response.state === "error"`, the SDK cannot send the command, or the terminal photo response times out. |
 | `startVideoRecording(...)` | `VideoRecordingStartedStatusEvent` with `success: true` and `status: "recording_started"`. | Rejects on `success: false` statuses such as `already_recording`, send failure, or timeout. |
 | `stopVideoRecording(...)` | `VideoRecordingStoppedStatusEvent` with `success: true` and `status: "recording_stopped"`. When a webhook URL is supplied, resolves after the video upload succeeds. | Rejects on `success: false` statuses such as `not_recording`, webhook upload failure, send failure, or timeout. |
+| `queryVideoRecordingStatus(requestId)` | `VideoRecordingStatusEvent` with the current `recording` state and elapsed `duration_ms` when available. | Rejects when disconnected, another video command uses the same request ID, or the response times out. |
 | `rgbLedControl(...)` | `RgbLedControlSuccessResponseEvent` with `state: "success"`. | Rejects when raw `rgb_led_control_response.state === "error"` or the response times out. |
 | `checkForOtaUpdate()` | `boolean`, true when the configured OTA manifest has an ASG APK, MTK, or BES update for the connected glasses; false only when the manifest was checked successfully and no update is available. | Rejects when the glasses are disconnected, version info is unavailable, the manifest cannot be fetched, or the manifest response is invalid/missing required ASG app version fields. |
 
@@ -344,38 +349,70 @@ Android and iOS async APIs use `BluetoothSdkException` / `BluetoothSdkError` for
 
 ## OTA Updates
 
-Mentra Live firmware owns the OTA flow. The SDK mirrors the MentraOS app commands and events:
+React Native apps should use `MentraLiveOtaFlow` or `useMentraLiveOta` from
+`@mentra/engine/ota`. They provide the same tested Wi-Fi/hotspot,
+APK/MTK/BES, restart, retry, and verification flow as the Mentra App. See
+[Update Mentra Live](https://docs.mentraglass.com/bluetooth-sdk/software-update).
 
+The Bluetooth SDK exposes the lower-level commands and transport capabilities
+that Mentra Engine and native apps build on. They are not a replacement for the
+Engine coordinator:
+
+- `setOtaVersionUrl(url)` selects the manifest used by subsequent checks and installs. Use this
+  for a customer-controlled internal update server.
+- `getOtaVersionUrl()` returns the selected manifest, or the SDK-version-pinned Mentra manifest
+  when no override was supplied.
 - `checkForOtaUpdate()` fetches the configured manifest and resolves with `true` when an ASG APK, MTK, or BES update is available.
 - `startOtaUpdate()` sends `ota_start` with the same configured manifest URL and resolves with the ASG start ack after your app presents the update and the user accepts it.
+- `queryOtaStatus()` returns the correlated status for the active session.
+- `@mentra/bluetooth-sdk/ota-transport` exposes scoped hotspot networking and
+  the local OTA artifact server without exposing native module internals.
+
+Release CI embeds an immutable manifest URL and checksum into every published
+SDK distribution. The completed coordinated release record correlates the SDK
+package with its exact manifest and OTA bundle. A completed release is available at
+`https://github.com/Mentra-Community/MentraOS/releases/tag/mentra-v<releaseIdentity>`
+and contains `mentra-release-<releaseIdentity>.json`, which records the exact
+package coordinates, asset URLs, sizes, checksums, and build provenance.
+
+Pre-wall-clock ASG builds that ignore `ota_start.ota_version_url` are checked
+against the URL they advertise, or the production default if they do not
+advertise one, so the app does not prompt for an update the glasses cannot
+install.
+
+Use these primitives directly only when implementing the documented native
+Android/iOS OTA contract or infrastructure beneath a coordinator. React Native
+application pages should render Mentra Engine's semantic controller state
+instead of sequencing raw events.
+
+Each coordinated prerelease publishes a portable OTA bundle. Stable releases
+promote the exact beta-tested OTA bytes, so always resolve the bundle coordinate
+and URL from `mentra-release-<releaseIdentity>.json` rather than constructing a
+filename. The selected archive contains
+`version.template.json`, every referenced ASG/MTK/BES artifact, `SHA256SUMS`,
+and a dependency-free configuration script. After unpacking it, generate the
+final manifest for its exact hosting URL:
 
-The default manifest is derived from the SDK version:
-`https://github.com/Mentra-Community/MentraOS/releases/download/bluetooth-sdk-ota/bluetooth-sdk-<sdkVersion>-version.json`.
-Each published SDK version points at a durable ASG client APK and firmware
-manifest that were built for that SDK release. Pre-wall-clock ASG builds that
-ignore `ota_start.ota_version_url` are checked against the URL they advertise,
-or the production default if they do not advertise one, so the app does not
-prompt for an update the glasses cannot install.
+```sh
+node configure.mjs https://updates.example.internal/mentra-live/version.json
+```
 
-```ts
-import BluetoothSdk from '@mentra/bluetooth-sdk'
+Host the entire directory at that location, then pass the same URL to `setOtaVersionUrl(...)`.
+The generated `version.json` contains absolute internal artifact URLs, so it works with Mentra Live
+ASG build 39 and newer as well as future firmware. Re-run the command if the hosted directory moves.
 
-BluetoothSdk.addListener('ota_status', (event) => {
-  console.log(`OTA ${event.status}: ${event.overall_percent}%`)
-})
-
-const hasUpdate = await BluetoothSdk.checkForOtaUpdate()
-if (hasUpdate) {
-  const userAccepted = await promptUserToInstallUpdate() // your app's UI
-  if (userAccepted) {
-    const startAck = await BluetoothSdk.startOtaUpdate()
-    console.log('OTA start acknowledged', startAck.timestamp)
-  }
-}
-```
+Firmware before ASG build 39 ignores `ota_start.ota_version_url` and must first be updated through
+its legacy or factory-supported path. OTA remains host-driven: the SDK does not check or install
+automatically.
 
 OTA requires Mentra Live glasses firmware that supports the ASG OTA protocol and network access from the glasses. During install, normal BLE traffic can be interrupted and the glasses may restart; keep the app connected and avoid sending unrelated commands until `ota_status.status` is `complete` or `failed`.
 
+For release selection, bundle verification, analytics opt-out, internal server
+requirements, and disconnected validation, see the
+[air-gapped deployment guide](https://docs.mentraglass.com/bluetooth-sdk/air-gapped-deployment).
+
+Mentra Live also rejects `ota_start` before acknowledgement when its known battery level is below 5%, emitting a failed `ota_status` with `error_message: "battery_low"`. Unknown battery state remains fail-open, so apps should keep their own (typically stricter) user-facing battery policy.
+
 ## Photo Upload
 
 ```ts
@@ -401,7 +438,7 @@ Use `setCameraFov({fov, roiPosition})` to configure Mentra Live camera field of
 
 The missing/factory persistent FOV base is 102 degrees with centered ROI; existing saved values are not migrated. Use `setCameraFovOverride({leaseId, fov, roiPosition, ttlMs})` for a memory-only crop and `releaseCameraFovOverride(leaseId)` to restore the persistent base. A stale release is a safe no-op, and refreshing the same lease/config extends its TTL without another HAL restart.
 
-`startVideoRecording(...)` resolves from the ASG `video_recording_status` event whose status is `recording_started`. `stopVideoRecording(...)` without a webhook resolves from `recording_stopped`; with a webhook it waits for `recording_stopped` plus a video `media_success`, and rejects on `media_error`. Raw `video_recording_status`, `media_success`, and `media_error` events remain available through listeners.
+`startVideoRecording(...)` resolves from the ASG `video_recording_status` event whose status is `recording_started`. `stopVideoRecording(...)` without a webhook resolves from `recording_stopped`; with a webhook it waits for `recording_stopped` plus a video `media_success`, and rejects on `media_error`. Use `queryVideoRecordingStatus(requestId)` after a timeout, reconnect, or app resume to fetch the glasses' current `recording` state and elapsed `duration_ms`. Raw `video_recording_status`, `media_success`, and `media_error` events remain available through listeners.
 
 ## Streaming
 
@@ -438,6 +475,9 @@ export function HardwareEventLogger() {
     console.log(event.sampleRate, event.bitsPerSample, event.channels, event.encoding)
     console.log(event.pcm)
   })
+  useBluetoothEvent('mic_health', (event) => {
+    console.log(event.reason, event.sequenceGapEvents, event.decodeFailures)
+  })
 
   return null
 }
@@ -445,10 +485,12 @@ export function HardwareEventLogger() {
 
 For non-React modules, `BluetoothSdk.addListener(...)` is the low-level subscription API. Keep the returned subscription and call `remove()` when the listener is no longer needed.
 
-Common event names include `button_press`, `touch_event`, `head_up`, `battery_status`, `wifi_status_change`, `wifi_scan_result`, `hotspot_status_change`, `photo_status`, `photo_response`, `gallery_status`, `settings_ack`, `version_info`, `stream_status`, `ota_start_ack`, `ota_status`, `mic_pcm`, `mic_lc3`, `local_transcription`, `rgb_led_control_response`, `audio_connected`, `audio_disconnected`, and `log`.
+Common event names include `button_press`, `touch_event`, `head_up`, `battery_status`, `wifi_status_change`, `wifi_scan_result`, `hotspot_status_change`, `photo_status`, `photo_response`, `gallery_status`, `settings_ack`, `version_info`, `stream_status`, `ota_start_ack`, `ota_status`, `mic_pcm`, `mic_lc3`, `mic_health`, `local_transcription`, `rgb_led_control_response`, `audio_connected`, `audio_disconnected`, and `log`.
 
 React Native event payload fields usually use camelCase. OTA events intentionally mirror the glasses firmware field names, such as `overall_percent` and `version_name`. For example, `touch_event` includes `gestureName`, `wifi_scan_result` includes `networks` and `scanComplete`, `version_info` matches the `requestVersionInfo()` result shape, `photo_response` success includes `uploadUrl` and may include webhook-returned `photoUrl`, `statusUrl`, `contentType`, and `fileSizeBytes`, and `gallery_status` includes `hasContent`, `cameraBusy`, and optional `cameraBusyReason`. `photo_status` reports intermediate photo states such as `accepted`, `queued`, `configuring`, `capturing`, `captured`, `compressing`, `ble_fallback_compression`, `uploading`, `ready_for_transfer`, `transferring`, and `failed`; the `configuring` event includes `resolvedConfig` with the effective JPEG dimensions, quality, requested size, transfer method, compression, and manual exposure fields when present. The `capturing` event may include `requestedCaptureConfig` and `meteredPreview`; the `captured` event may include `captureMetadata` with the HAL-applied exposure, ISO, frame duration, and AE state. `mic_pcm` includes `sampleRate`, `bitsPerSample`, `channels`, and `encoding`; `mic_lc3` includes `sampleRate`, `channels`, `encoding`, `frameDurationMs`, `frameSizeBytes`, `bitrate`, and `packetizedFromGlasses`.
 
+`mic_health` emits a snapshot when native code detects a glasses LC3 `sequence_gap` or `decode_failure`. Each event includes cumulative `sequenceGapEvents` and `decodeFailures` counters for the current connection plus `lastLc3ReceivedAt`, `lastPcmProducedAt`, and `timestamp` in Unix milliseconds when available. These failures occur before React Native receives PCM and cannot be reconstructed from `mic_pcm` alone. The existing `mic_pcm` and `mic_lc3` streams remain unchanged.
+
 Photo status metadata is tied to the capture stage where the glasses know it:
 
 | Status | Optional metadata | Meaning |

package/android/build.gradle

@@ -379,10 +379,13 @@ afterEvaluate {
     repositories {
       maven {
         name = 'sonatypeCentral'
-        url = uri('https://ossrh-staging-api.central.sonatype.com/service/local/staging/deploy/maven2/')
-        credentials {
-          username = centralUsername()
-          password = centralPassword()
+        def repositoryUrl = System.getenv('MENTRA_MAVEN_STAGING_REPOSITORY_URL') ?: 'https://ossrh-staging-api.central.sonatype.com/service/local/staging/deploy/maven2/'
+        url = uri(repositoryUrl)
+        if (repositoryUrl.startsWith('http')) {
+          credentials {
+            username = centralUsername()
+            password = centralPassword()
+          }
         }
       }
     }

package/android/lc3Lib/build.gradle

@@ -111,6 +111,17 @@ android {
 
         testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
 
+        ndk {
+            // Honor reactNativeArchitectures so CI/staging ABI filters apply.
+            // Without this, CMake still builds every ABI on an arm64-only job.
+            def abiList = (findProperty("reactNativeArchitectures") ?: "armeabi-v7a,arm64-v8a,x86,x86_64")
+                .toString()
+                .split(",")
+                .collect { it.trim() }
+                .findAll { !it.isEmpty() }
+            abiFilters(*abiList)
+        }
+
         externalNativeBuild {
             cmake {
                 arguments '-DCMAKE_OBJECT_PATH_MAX=600', '-DANDROID_STL=c++_static'
@@ -170,10 +181,13 @@ afterEvaluate {
         repositories {
             maven {
                 name = 'sonatypeCentral'
-                url = uri('https://ossrh-staging-api.central.sonatype.com/service/local/staging/deploy/maven2/')
-                credentials {
-                    username = centralUsername()
-                    password = centralPassword()
+                def repositoryUrl = System.getenv('MENTRA_MAVEN_STAGING_REPOSITORY_URL') ?: 'https://ossrh-staging-api.central.sonatype.com/service/local/staging/deploy/maven2/'
+                url = uri(repositoryUrl)
+                if (repositoryUrl.startsWith('http')) {
+                    credentials {
+                        username = centralUsername()
+                        password = centralPassword()
+                    }
                 }
             }
         }

package/android/silero/build.gradle

@@ -16,7 +16,15 @@ android {
         targetSdkVersion 36
 
         ndk {
-            abiFilters "armeabi-v7a", "x86", "x86_64", "arm64-v8a"
+            // Honor reactNativeArchitectures (dev CI is arm64-only; staging
+            // production sets all four ABIs) so this module does not keep
+            // compiling every ABI on a filtered build.
+            def abiList = (findProperty("reactNativeArchitectures") ?: "armeabi-v7a,arm64-v8a,x86,x86_64")
+                .toString()
+                .split(",")
+                .collect { it.trim() }
+                .findAll { !it.isEmpty() }
+            abiFilters(*abiList)
         }
     }
 

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

@@ -286,6 +286,10 @@ class BluetoothSdkModule : Module() {
                     sendEvent("mic_lc3", event.toMap())
                 }
 
+                override fun onMicHealth(event: MicHealthEvent) {
+                    sendEvent("mic_health", event.values)
+                }
+
                 override fun onLocalTranscription(event: LocalTranscriptionEvent) {
                     sendEvent("local_transcription", event.values)
                 }
@@ -355,6 +359,9 @@ class BluetoothSdkModule : Module() {
             "settings_ack",
             "version_info",
             "pair_failure",
+            "pairing_info",
+            "entering_pairing_mode",
+            "owner_replaced",
             "audio_pairing_needed",
             "audio_connected",
             "audio_disconnected",
@@ -365,6 +372,7 @@ class BluetoothSdkModule : Module() {
             "ws_bin",
             "mic_pcm",
             "mic_lc3",
+            "mic_health",
             "stream_status",
             "keep_alive_ack",
             "mtk_update_complete",
@@ -571,6 +579,10 @@ class BluetoothSdkModule : Module() {
             requireSdk().setHotspotState(enabled).values
         }
 
+        SdkAsyncFunction("setWifiAdbState") { enabled: Boolean ->
+            sdk?.setWifiAdbState(enabled)
+        }
+
         SdkAsyncFunction("setSystemTime") { timestampMs: Double ->
             sdk?.setSystemTime(timestampMs.toLong())
         }
@@ -756,6 +768,10 @@ class BluetoothSdkModule : Module() {
             requireSdk().stopVideoRecording(requestId, webhookUrl, authToken).values
         }
 
+        SdkCoroutineFunction("queryVideoRecordingStatus") { requestId: String ->
+            requireSdk().queryVideoRecordingStatus(requestId).values
+        }
+
         // MARK: - Stream Commands
 
         SdkCoroutineFunction("startStream") { params: Map<String, Any> ->

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

@@ -145,6 +145,23 @@ public class Bridge private constructor() {
             sendTypedMessage("pair_failure", data as Map<String, Any>)
         }
 
+        @JvmStatic
+        fun sendPairingInfo(
+            hadPreviousBond: Boolean,
+            pairingCode: String? = null,
+            classicBondReady: Boolean = false,
+            securePairingCapable: Boolean = true,
+            protocolVersion: Int = 1,
+        ) {
+            val data = HashMap<String, Any>()
+            data["had_previous_bond"] = hadPreviousBond
+            if (pairingCode != null) data["pairing_code"] = pairingCode
+            data["classic_bond_ready"] = classicBondReady
+            data["secure_pairing_capable"] = securePairingCapable
+            data["protocol_version"] = protocolVersion
+            sendTypedMessage("pairing_info", data as Map<String, Any>)
+        }
+
         /** Send audio connected event - matches iOS implementation for platform parity */
         @JvmStatic
         fun sendAudioConnected(deviceName: String) {
@@ -172,6 +189,14 @@ public class Bridge private constructor() {
             sendTypedMessage("mic_lc3", body as Map<String, Any>)
         }
 
+        @JvmStatic
+        internal fun sendMicHealth(health: MicHealth, reason: String) {
+            val body = HashMap(health.toMap())
+            body["reason"] = reason
+            body["timestamp"] = System.currentTimeMillis()
+            sendTypedMessage("mic_health", body)
+        }
+
         private fun micPcmEventBody(data: ByteArray): HashMap<String, Any> {
             val voiceActivityDetectionEnabled =
                     DeviceStore.get("glasses", "voiceActivityDetectionEnabled") as? Boolean
@@ -251,7 +276,10 @@ public class Bridge private constructor() {
                 deviceName: String,
                 deviceAddress: String = "",
                 rssi: Int? = null,
-                projectName: String? = null
+                projectName: String? = null,
+                pairingMode: Boolean? = null,
+                pairingCode: String? = null,
+                securePairingCapable: Boolean? = null,
         ) {
             val searchResults =
                     (DeviceStore.store.getCategory("bluetooth")["searchResults"] as? List<*>)
@@ -274,6 +302,9 @@ public class Bridge private constructor() {
                         }
                         projectName?.takeIf { it.isNotBlank() }?.let { put("projectName", it) }
                         rssi?.let { put("rssi", it) }
+                        pairingMode?.let { put("pairingMode", it) }
+                        pairingCode?.takeIf { it.isNotBlank() }?.let { put("pairingCode", it) }
+                        securePairingCapable?.let { put("securePairingCapable", it) }
                     }
             // Keep the public searchResults array stable as glasses are added or removed.
             // Duplicate discoveries refresh their existing row; only new glasses append.
@@ -462,6 +493,9 @@ public class Bridge private constructor() {
             }
             body["otaVersionUrl"] = stringField("otaVersionUrl", "ota_version_url")
             body["appVersion"] = stringField("appVersion", "app_version")
+            (values["hotspotOtaVersion"] as? Number
+                            ?: values["hotspot_ota_version"] as? Number)
+                    ?.let { body["hotspotOtaVersion"] = it.toInt() }
             sendTypedMessage("version_info", body)
         }
 
@@ -874,6 +908,3 @@ public class Bridge private constructor() {
         }
     }
 }
-
-
-