@mentra/bluetooth-sdk 3.1.0-dev.10 → 3.1.0-dev.102

package/README.md

@@ -349,7 +349,14 @@ 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.
@@ -357,6 +364,9 @@ Mentra Live firmware owns the OTA flow. The SDK mirrors the MentraOS app command
   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
@@ -370,25 +380,10 @@ 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.
 
-```ts
-import BluetoothSdk from '@mentra/bluetooth-sdk'
-
-// Optional: point both the phone-side check and glasses install at an internal server.
-BluetoothSdk.setOtaVersionUrl('https://updates.example.internal/mentra-live/version.json')
-
-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)
-  }
-}
-```
+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
@@ -414,7 +409,7 @@ OTA requires Mentra Live glasses firmware that supports the ASG OTA protocol and
 
 For release selection, bundle verification, analytics opt-out, internal server
 requirements, and disconnected validation, see the
-[air-gapped deployment guide](https://docs.mentraglass.com/mentra-live/air-gapped-deployment).
+[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.
 

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

@@ -0,0 +1,7 @@
+package com.mentra.bluetoothsdk
+
+/** Generated from /changelogs. Do not edit directly. */
+internal val GENERATED_RELEASE_CHANGELOGS: List<ReleaseChangelog> =
+    listOf(
+        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.1.0"
-    const val RELEASE_IDENTITY: String = "3.1.0-dev.10"
-    const val RELEASE_SET_ID: String = "mentra-3.1.0-dev.10"
-    const val SOURCE_COMMIT: String = "64cf83b23a71e70261571a5f4401d1a7538f1852"
-    const val OTA_MANIFEST_URL: String = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-v3.1.0-dev.10/mentra-live-ota-3.1.0-dev.10.json"
-    const val OTA_MANIFEST_SHA256: String = "214d92c8894033eaab276e668cb553c79990005d3330d23aaf499a514dc08cff"
+    const val RELEASE_IDENTITY: String = "3.1.0-dev.102"
+    const val RELEASE_SET_ID: String = "mentra-3.1.0-dev.102"
+    const val SOURCE_COMMIT: String = "1e5cd9f88a6a43db2f51f4ddd3c6a4b8f15d0fed"
+    const val OTA_MANIFEST_URL: String = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.1.0/mentra-live-ota-3.1.0-dev.102.json"
+    const val OTA_MANIFEST_SHA256: String = "5ff3b609846566abecea90ce5fed4a8d281db2dee82a728b7d80a97beedc4f13"
 }

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

@@ -284,6 +284,7 @@ class MentraBluetoothSdk private constructor(
             DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "project_name", device.projectName ?: "")
             DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_name", "")
             DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_address", "")
+            DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_secure_pairing_capable", "")
         } finally {
             suppressDefaultDeviceEvents = false
         }
@@ -299,6 +300,7 @@ class MentraBluetoothSdk private constructor(
             DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "project_name", "")
             DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_name", "")
             DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_address", "")
+            DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_secure_pairing_capable", "")
         } finally {
             suppressDefaultDeviceEvents = false
         }
@@ -428,6 +430,11 @@ class MentraBluetoothSdk private constructor(
                         "pending_device_address",
                         device.address ?: "",
                 )
+                DeviceStore.apply(
+                        ObservableStore.BLUETOOTH_CATEGORY,
+                        "pending_device_secure_pairing_capable",
+                        device.securePairingCapable ?: "",
+                )
             }
         }
         DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_wearable", device.model.deviceType)
@@ -454,6 +461,7 @@ class MentraBluetoothSdk private constructor(
     fun cancelConnectionAttempt() {
         DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_name", "")
         DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_address", "")
+        DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_secure_pairing_capable", "")
         deviceManager.disconnect()
     }
 
@@ -464,6 +472,7 @@ class MentraBluetoothSdk private constructor(
     fun disconnect() {
         DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_name", "")
         DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_address", "")
+        DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_secure_pairing_capable", "")
         deviceManager.disconnect()
     }
 
@@ -1216,6 +1225,12 @@ class MentraBluetoothSdk private constructor(
         )
     }
 
+    /** Return bundled release changelogs crossed between two coordinated product versions, newest first. */
+    fun getReleaseChangelogs(
+        fromVersion: String? = null,
+        toVersion: String? = null,
+    ): List<ReleaseChangelog> = ReleaseChangelogCatalog.select(fromVersion, toVersion)
+
     /** Ask connected Mentra Live glasses to report the current OTA install/session status. */
     private suspend fun queryOtaStatus(): OtaQueryResult =
         performOtaQuery("OTA status query") {

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

@@ -0,0 +1,61 @@
+package com.mentra.bluetoothsdk
+
+/** One coordinated Mentra release note authored in /changelogs/<version>.md. */
+data class ReleaseChangelog(
+    val version: String,
+    val markdown: String,
+)
+
+internal object ReleaseChangelogCatalog {
+    private val baseVersionPattern = Regex("^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:[-+].*)?$")
+
+    fun select(
+        fromVersion: String?,
+        toVersion: String?,
+    ): List<ReleaseChangelog> {
+        val fallbackTarget =
+            GeneratedReleaseMetadata.FAMILY_BASE_VERSION.ifBlank {
+                GENERATED_RELEASE_CHANGELOGS.firstOrNull()?.version.orEmpty()
+            }
+        if (fallbackTarget.isBlank() && toVersion == null) return emptyList()
+        val target = baseVersion(toVersion ?: fallbackTarget, "toVersion")
+        if (GENERATED_RELEASE_CHANGELOGS.none { it.version == target }) {
+            throw BluetoothSdkException("missing_changelog", "No changelog is bundled for target version $target.")
+        }
+        if (fromVersion == null) return GENERATED_RELEASE_CHANGELOGS.filter { it.version == target }
+
+        val source = baseVersion(fromVersion, "fromVersion")
+        val direction = compareVersions(target, source)
+        return GENERATED_RELEASE_CHANGELOGS.filter { entry ->
+            when {
+                direction == 0 -> entry.version == target
+                direction > 0 -> compareVersions(entry.version, source) > 0 && compareVersions(entry.version, target) <= 0
+                else -> compareVersions(entry.version, source) < 0 && compareVersions(entry.version, target) >= 0
+            }
+        }
+    }
+
+    private fun baseVersion(
+        version: String,
+        label: String,
+    ): String {
+        val match = baseVersionPattern.matchEntire(version.trim())
+            ?: throw BluetoothSdkException(
+                "invalid_changelog_version",
+                "$label must be a semantic version such as 3.1.0, 3.1.0-dev.4, or 3.1.0-beta.2.",
+            )
+        return "${match.groupValues[1]}.${match.groupValues[2]}.${match.groupValues[3]}"
+    }
+
+    private fun compareVersions(
+        left: String,
+        right: String,
+    ): Int {
+        val a = left.split(".").map(String::toInt)
+        val b = right.split(".").map(String::toInt)
+        for (index in 0..2) {
+            if (a[index] != b[index]) return a[index] - b[index]
+        }
+        return 0
+    }
+}

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

@@ -82,6 +82,33 @@ internal fun hasRequiredMentraLiveCoreCharacteristics(
         hasTxCharacteristic: Boolean,
 ): Boolean = hasRxCharacteristic && hasTxCharacteristic
 
+internal fun isPendingMentraLivePairingTarget(
+        connectedName: String,
+        connectedAddress: String,
+        pendingName: String,
+        pendingAddress: String,
+): Boolean {
+    if (pendingAddress.isNotEmpty()) {
+        return connectedAddress.equals(pendingAddress, ignoreCase = true)
+    }
+    return pendingName.isNotEmpty() && connectedName == pendingName
+}
+
+internal fun shouldRecoverConnectedMentraLivePairingTarget(
+        isConnected: Boolean,
+        connectedName: String,
+        connectedAddress: String,
+        pendingName: String,
+        pendingAddress: String,
+): Boolean =
+        isConnected &&
+                isPendingMentraLivePairingTarget(
+                        connectedName,
+                        connectedAddress,
+                        pendingName,
+                        pendingAddress,
+                )
+
 /**
  * Smart Glasses Communicator for Mentra Live (K900) glasses Uses BLE to communicate with the
  * glasses
@@ -1265,11 +1292,6 @@ class MentraLive : SGCManager() {
             val generation = ++scanGeneration
             isScanning = true
             bluetoothScanner!!.startScan(filters, settings, scanCallback)
-            // Connected glasses stop advertising (BLE_CONNECTION_MAX=1). Pairing scan
-            // would otherwise return empty even though GATT is already up.
-            if (!isReconnecting) {
-                handler.post { emitConnectedDeviceForPairingScan() }
-            }
 
             // Set a timeout to stop scanning
             handler.postDelayed(
@@ -1352,29 +1374,44 @@ class MentraLive : SGCManager() {
     }
 
     /**
-     * Pairing scan listens for advertisements. A unit that is already GATT-connected
-     * (typical after a CTKD retry / back-out on field firmware) has stopped ADV, so
-     * emit it as pairable or the scan list stays empty.
+     * A selected pairing target can stop advertising once its GATT link comes up, before
+     * readiness promotes it to the default device. Re-emit only that explicit pending target;
+     * an established owner's connected glasses have no pending name/address and stay hidden.
      */
-    private fun emitConnectedDeviceForPairingScan() {
-        if (!isConnected || isReconnecting || pairingYieldActive) {
-            return
-        }
+    private fun emitConnectedPendingDeviceForPairingScan() {
+        if (!manualDiscoveryActive || isReconnecting || pairingYieldActive) return
         val device = connectedDevice ?: bluetoothGatt?.device ?: return
         val name = safeBondedDeviceName(device)
-        if (!isMentraLiveBluetoothName(name)) {
+        if (!isMentraLiveBluetoothName(name)) return
+
+        val pendingName = DeviceStore.get("bluetooth", "pending_device_name") as? String ?: ""
+        val pendingAddress =
+                DeviceStore.get("bluetooth", "pending_device_address") as? String ?: ""
+        val pendingSecurePairingCapable =
+                DeviceStore.get("bluetooth", "pending_device_secure_pairing_capable") as? Boolean
+        val address = device.address ?: ""
+        if (
+                !shouldRecoverConnectedMentraLivePairingTarget(
+                        isConnected,
+                        name,
+                        address,
+                        pendingName,
+                        pendingAddress,
+                )
+        ) {
             return
         }
+
         Bridge.log(
-                "LIVE: Pairing scan: already GATT-connected to $name — emitting as pairable (ADV off while connected)"
+                "LIVE: Pairing scan: recovering connected pending target $name ($address)"
         )
         Bridge.sendDiscoveredDevice(
                 DeviceTypes.LIVE,
                 name,
-                device.address ?: "",
+                address,
                 pairingMode = true,
                 pairingCode = null,
-                securePairingCapable = false,
+                securePairingCapable = pendingSecurePairingCapable,
         )
     }
 
@@ -1441,10 +1478,11 @@ class MentraLive : SGCManager() {
                                         advertisesPairingFlag(result) &&
                                         !isPairingDiscoverable(result)
                         ) {
-                            // Tell RN a nearby unit is advertising but not pairable so the
-                            // empty-state hint can fire. The scan list never shows these.
+                            // Tell RN a nearby unit is advertising but not pairable. The scan
+                            // screen keeps it visible with pairing-mode guidance but blocks the
+                            // connection until a pairable advertisement arrives.
                             Bridge.log(
-                                    "LIVE: Nearby $deviceName is secure firmware not in pairing mode — hiding from scan list"
+                                    "LIVE: Nearby $deviceName is secure firmware not in pairing mode — exposing as non-pairable"
                             )
                             Bridge.sendDiscoveredDevice(
                                     DeviceTypes.LIVE,
@@ -2075,6 +2113,7 @@ class MentraLive : SGCManager() {
                             isConnecting = false
                             isConnected = true
                             connectedDevice = gatt.device
+                            emitConnectedPendingDeviceForPairingScan()
 
                             DeviceStore.apply("glasses", "bluetoothName", connectedDevice!!.name)
                             // Persist MAC so reconnection can use direct GATT instead of scanning
@@ -5919,6 +5958,7 @@ class MentraLive : SGCManager() {
 
         // Start scanning for BLE devices
         startScan()
+        handler.post { emitConnectedPendingDeviceForPairingScan() }
     }
 
     private fun releaseStaleClassicForDiscovery() {
@@ -6815,12 +6855,21 @@ class MentraLive : SGCManager() {
                         ")"
         )
         markPairingTiming("ctkd_initiate", "bondState=${device.bondState}")
-        if (device.bondState == BluetoothDevice.BOND_BONDED) {
-            Bridge.log("LIVE: CTKD: Device is already bonded - connecting A2DP audio profile")
-            markPairingTiming("ctkd_already_bonded")
-            connectA2dpProfile(device)
-        } else {
-            createBond(device)
+        when (device.bondState) {
+            BluetoothDevice.BOND_BONDED -> {
+                Bridge.log(
+                        "LIVE: CTKD: Device is already bonded - connecting A2DP audio profile"
+                )
+                markPairingTiming("ctkd_already_bonded")
+                connectA2dpProfile(device)
+            }
+            BluetoothDevice.BOND_BONDING -> {
+                // Secure pairing firmware may request SMP as soon as GATT connects.
+                // Let that in-flight procedure finish instead of calling createBond twice.
+                Bridge.log("LIVE: CTKD: Bonding already in progress - waiting for completion")
+                markPairingTiming("ctkd_bonding_already_in_progress")
+            }
+            else -> createBond(device)
         }
     }
 

package/android/src/test/java/com/mentra/bluetoothsdk/ReleaseChangelogTest.kt

@@ -0,0 +1,13 @@
+package com.mentra.bluetoothsdk
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+class ReleaseChangelogTest {
+    @Test
+    fun includesTargetNotesForTransitionWithinOneReleaseTrain() {
+        val changelogs = ReleaseChangelogCatalog.select("3.1.0-dev.2", "3.1.0-beta.8")
+
+        assertEquals(listOf("3.1.0"), changelogs.map { it.version })
+    }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/sgcs/MentraLivePairingAdvertisementParserTest.kt

@@ -7,6 +7,64 @@ import org.junit.Assert.assertTrue
 import org.junit.Test
 
 class MentraLivePairingAdvertisementParserTest {
+    @Test
+    fun connectedPairingRecoveryRequiresExplicitPendingTarget() {
+        assertFalse(
+                isPendingMentraLivePairingTarget(
+                        connectedName = "MENTRA_LIVE_BLE_OWNER",
+                        connectedAddress = "AA:BB:CC:DD:EE:FF",
+                        pendingName = "",
+                        pendingAddress = "",
+                )
+        )
+        assertTrue(
+                isPendingMentraLivePairingTarget(
+                        connectedName = "MENTRA_LIVE_BLE_TARGET",
+                        connectedAddress = "AA:BB:CC:DD:EE:FF",
+                        pendingName = "MENTRA_LIVE_BLE_TARGET",
+                        pendingAddress = "",
+                )
+        )
+        assertTrue(
+                isPendingMentraLivePairingTarget(
+                        connectedName = "MENTRA_LIVE_BLE_TARGET",
+                        connectedAddress = "AA:BB:CC:DD:EE:FF",
+                        pendingName = "OTHER",
+                        pendingAddress = "aa:bb:cc:dd:ee:ff",
+                )
+        )
+        assertFalse(
+                isPendingMentraLivePairingTarget(
+                        connectedName = "MENTRA_LIVE_BLE_TARGET",
+                        connectedAddress = "AA:BB:CC:DD:EE:FF",
+                        pendingName = "MENTRA_LIVE_BLE_TARGET",
+                        pendingAddress = "11:22:33:44:55:66",
+                )
+        )
+    }
+
+    @Test
+    fun connectedPairingRecoveryRequiresActiveGattConnection() {
+        assertFalse(
+                shouldRecoverConnectedMentraLivePairingTarget(
+                        isConnected = false,
+                        connectedName = "MENTRA_LIVE_BLE_TARGET",
+                        connectedAddress = "AA:BB:CC:DD:EE:FF",
+                        pendingName = "MENTRA_LIVE_BLE_TARGET",
+                        pendingAddress = "AA:BB:CC:DD:EE:FF",
+                )
+        )
+        assertTrue(
+                shouldRecoverConnectedMentraLivePairingTarget(
+                        isConnected = true,
+                        connectedName = "MENTRA_LIVE_BLE_TARGET",
+                        connectedAddress = "AA:BB:CC:DD:EE:FF",
+                        pendingName = "MENTRA_LIVE_BLE_TARGET",
+                        pendingAddress = "AA:BB:CC:DD:EE:FF",
+                )
+        )
+    }
+
     @Test
     fun parsesMarkedSecurePairingAdvertisement() {
         val result = MentraLivePairingAdvertisementParser.parse(securePayload(pairingFlag = 1))

package/build/BluetoothSdk.types.d.ts

@@ -875,6 +875,10 @@ export type BluetoothSdkEventMap = {
     mic_lc3: MicLc3Event;
     mic_health: MicHealthEvent;
     stream_status: StreamStatusEvent;
+    /** Mentra Live MTK updater completed and the glasses are about to restart. */
+    mtk_update_complete: MtkUpdateCompleteEvent;
+    /** The ASG process restarted while the BES kept the BLE connection alive. */
+    glasses_session_changed: GlassesSessionChangedEvent;
     ota_start_ack: OtaStartAckEvent;
     ota_status: OtaStatusEvent;
     ar99_ota_status: Ar99OtaStatusEvent;
@@ -889,6 +893,14 @@ export type BluetoothSdkSubscription = {
 export type BluetoothSdkEvent = BluetoothSdkEventMap[BluetoothSdkEventName];
 export interface BluetoothSdkPublicModule {
     addListener<EventName extends BluetoothSdkEventName>(eventName: EventName, listener: BluetoothSdkEventListener<EventName>): BluetoothSdkSubscription;
+    /** Read an immutable snapshot of the current glasses state. */
+    getGlassesStatus(): Promise<PublicGlassesStatus>;
+    /** Read an immutable snapshot of the phone Bluetooth adapter state. */
+    getBluetoothStatus(): Promise<PublicBluetoothStatus>;
+    /** Observe immutable glasses-state patches. Returns an unsubscribe function. */
+    subscribeGlassesStatus(listener: (changed: Partial<PublicGlassesStatus>) => void): () => void;
+    /** Observe immutable Bluetooth-state patches. Returns an unsubscribe function. */
+    subscribeBluetoothStatus(listener: (changed: Partial<PublicBluetoothStatus>) => void): () => void;
     getDefaultDevice(): Promise<Device | null>;
     setDefaultDevice(device: Device | null): Promise<void>;
     clearDefaultDevice(): Promise<void>;
@@ -908,10 +920,14 @@ export interface BluetoothSdkPublicModule {
     setHeadUpAngle(angleDegrees: number): Promise<void>;
     setImuEnabled(enabled: boolean): Promise<void>;
     setScreenDisabled(disabled: boolean): Promise<void>;
+    /** Keep legacy Mentra Live OTA sessions awake. Modern sessions normally do not require this. */
+    ping(): Promise<void>;
     requestWifiScan(): Promise<WifiSearchResult[]>;
     sendWifiCredentials(ssid: string, password: string): Promise<WifiStatusChangeEvent>;
     forgetWifiNetwork(ssid: string): Promise<WifiStatusChangeEvent>;
     setHotspotState(enabled: boolean): Promise<HotspotStatusChangeEvent>;
+    /** Set the glasses clock from the phone after an OTA clock-skew failure. */
+    setSystemTime(timestampMs: number): Promise<void>;
     /** Enable or disable Wi-Fi ADB on Mentra Live (no-op on other devices). */
     setWifiAdbState(enabled: boolean): Promise<void>;
     setGalleryModeEnabled(enabled: boolean): Promise<SettingsAckSuccessEvent>;
@@ -978,8 +994,12 @@ export interface BluetoothSdkPublicModule {
     getOtaVersionUrl(): string;
     /** Fetch the configured OTA manifest and return whether any ASG/BES/MTK update is available. */
     checkForOtaUpdate(): Promise<boolean>;
+    /** Return bundled release changelogs crossed between two coordinated product versions, newest first. */
+    getReleaseChangelogs(fromVersion?: string | null, toVersion?: string | null): ReleaseChangelog[];
     /** Start OTA from the configured or explicitly supplied manifest URL. */
     startOtaUpdate(otaVersionUrl?: string | null): Promise<OtaStartAckEvent>;
+    /** Query the active OTA session and return the correlated status response. */
+    queryOtaStatus(): Promise<OtaQueryResult>;
     startAr99OtaFromFile(path: string): Promise<boolean>;
     cancelAr99Ota(): Promise<void>;
     sendAr99FactoryReset(): Promise<void>;
@@ -1022,6 +1042,12 @@ export interface OtaUpdateInfo {
     /** True when the APK step installs an older build than the glasses currently run (exact-pin manifests only). */
     isDowngrade?: boolean;
 }
+export interface ReleaseChangelog {
+    /** Base production version, for example `3.1.0`. */
+    version: string;
+    /** Markdown body authored in `/changelogs/<version>.md`. */
+    markdown: string;
+}
 export interface OtaProgress {
     stage: OtaStage;
     status: OtaProgressStatus;