@mentra/bluetooth-sdk 3.1.0-dev.7 → 3.1.0-dev.70

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/mentra-live/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,39 +364,34 @@ 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.
-
-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.
-
-```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)
-  }
-}
-```
-
-Bluetooth SDK releases also publish
-`bluetooth-sdk-<sdkVersion>-ota-bundle.zip` beside the default manifest. The 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:
+- `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:
 
 ```sh
 node configure.mjs https://updates.example.internal/mentra-live/version.json
@@ -405,6 +407,10 @@ 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/mentra-live/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

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

@@ -148,21 +148,17 @@ public class Bridge private constructor() {
         @JvmStatic
         fun sendPairingInfo(
             hadPreviousBond: Boolean,
-            transferId: String? = null,
             pairingCode: String? = null,
             classicBondReady: Boolean = false,
             securePairingCapable: Boolean = true,
             protocolVersion: Int = 1,
-            binding: String? = null,
         ) {
             val data = HashMap<String, Any>()
             data["had_previous_bond"] = hadPreviousBond
-            if (transferId != null) data["transfer_id"] = transferId
             if (pairingCode != null) data["pairing_code"] = pairingCode
             data["classic_bond_ready"] = classicBondReady
             data["secure_pairing_capable"] = securePairingCapable
             data["protocol_version"] = protocolVersion
-            if (binding != null) data["binding"] = binding
             sendTypedMessage("pairing_info", data as Map<String, Any>)
         }
 
@@ -912,4 +908,3 @@ public class Bridge private constructor() {
         }
     }
 }
-

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

@@ -1359,9 +1359,7 @@ class DeviceManager {
         if (pendingDeviceAddress.isNotEmpty()) {
             deviceAddress = pendingDeviceAddress
         }
-        pendingDeviceName = ""
-        pendingDeviceAddress = ""
-        pendingWearable = ""
+        clearPendingConnection()
 
         val readyKey = "${sgc?.type}:${deviceName}"
         val now = System.currentTimeMillis()
@@ -2137,7 +2135,7 @@ class DeviceManager {
             return
         }
 
-        disconnect()
+        disconnect(clearPendingIdentity = false)
         Thread.sleep(100)
         searching = true
         pendingDeviceName = name
@@ -2170,7 +2168,7 @@ class DeviceManager {
         handleDeviceReady()
     }
 
-    fun disconnect() {
+    fun disconnect(clearPendingIdentity: Boolean = true) {
         sgc?.clearDisplay()
         sgc?.disconnect()
         sgc = null // Clear the SGC reference after disconnect
@@ -2202,6 +2200,15 @@ class DeviceManager {
         DeviceStore.apply("glasses", "controllerConnected", false)
         controller?.disconnect()
         controller = null
+        if (clearPendingIdentity) {
+            clearPendingConnection()
+        }
+    }
+
+    private fun clearPendingConnection() {
+        pendingDeviceName = ""
+        pendingDeviceAddress = ""
+        pendingWearable = ""
     }
 
     fun disconnectController() {
@@ -2276,9 +2283,7 @@ class DeviceManager {
         defaultWearable = ""
         deviceName = ""
         deviceAddress = ""
-        pendingDeviceName = ""
-        pendingDeviceAddress = ""
-        pendingWearable = ""
+        clearPendingConnection()
         Bridge.saveSetting("default_wearable", "")
         Bridge.saveSetting("device_name", "")
         Bridge.saveSetting("device_address", "")

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.7"
-    const val RELEASE_SET_ID: String = "mentra-3.1.0-dev.7"
-    const val SOURCE_COMMIT: String = "872697a6395c31d30ec75d64f039eaa763dcbb51"
-    const val OTA_MANIFEST_URL: String = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-v3.1.0-dev.7/mentra-live-ota-3.1.0-dev.7.json"
-    const val OTA_MANIFEST_SHA256: String = "8fbea7589345658dc5dffcb394229ffc5c52fbe75352acb8f6827d83290ce750"
+    const val RELEASE_IDENTITY: String = "3.1.0-dev.70"
+    const val RELEASE_SET_ID: String = "mentra-3.1.0-dev.70"
+    const val SOURCE_COMMIT: String = "1554856d69f4cd5d14c1ea769171a444d3e0c4b4"
+    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.70.json"
+    const val OTA_MANIFEST_SHA256: String = "593990d9b25a7a47dd80c6a7e3486964b4349191a7abe885fcc24135e1604c69"
 }

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
@@ -159,59 +186,25 @@ class MentraLive : SGCManager() {
                 10_000L // 10s before first scan after shutdown
 
         private const val MENTRA_MANUFACTURER_ID = 0xB822
-        private const val ADV_MANUF_PAIRING_FLAG_OFFSET = 5
-        private const val ADV_PAIRING_DISCOVERABLE: Byte = 0x01
-        private const val ADV_PAIRING_PROTOCOL_VERSION_MIN = 1
-        private const val ADV_PAIRING_PROTOCOL_VERSION_MAX = 15
 
         private fun manufacturerData(result: ScanResult): ByteArray? {
             return result.scanRecord?.getManufacturerSpecificData(MENTRA_MANUFACTURER_ID)
         }
 
-        /**
-         * OS-1615 ads append `flag | version | capability | code_lo | code_hi` after the
-         * connected byte. Field firmware uses the same 0xB822 company id but then writes the
-         * XOR'd Classic MAC at those offsets. Length alone is not a pairing flag: treating MAC
-         * bytes as version/capability hides every old unit as "secure, not in pairing mode".
-         */
-        private fun hasSecurePairingTrailer(manufData: ByteArray?): Boolean {
-            if (manufData == null) {
-                return false
-            }
-            val trailerBase = ADV_MANUF_PAIRING_FLAG_OFFSET + 1
-            if (manufData.size < trailerBase + 4) {
-                return false
-            }
-            val version = manufData[trailerBase].toInt() and 0xFF
-            val capability = manufData[trailerBase + 1].toInt() and 0xFF
-            return version in ADV_PAIRING_PROTOCOL_VERSION_MIN..ADV_PAIRING_PROTOCOL_VERSION_MAX &&
-                    (capability and 0x01) != 0
-        }
-
         private fun isPairingDiscoverable(result: ScanResult): Boolean {
-            val manufData = manufacturerData(result) ?: return false
-            if (!hasSecurePairingTrailer(manufData)) {
-                return false
-            }
-            return manufData[ADV_MANUF_PAIRING_FLAG_OFFSET] == ADV_PAIRING_DISCOVERABLE
+            return MentraLivePairingAdvertisementParser.parse(manufacturerData(result))?.pairingMode ==
+                    true
         }
 
         private fun advertisesPairingFlag(result: ScanResult): Boolean {
-            return hasSecurePairingTrailer(manufacturerData(result))
+            return MentraLivePairingAdvertisementParser.parse(manufacturerData(result)) != null
         }
 
-        /** Trailer immediately after pairing flag: version | capability | code_lo | code_hi */
         private fun parseSecurePairingTrailer(result: ScanResult): Triple<Boolean, String?, Boolean> {
-            val manufData = manufacturerData(result) ?: return Triple(false, null, false)
-            if (!hasSecurePairingTrailer(manufData)) {
-                return Triple(false, null, false)
-            }
-            val pairingMode = manufData[ADV_MANUF_PAIRING_FLAG_OFFSET] == ADV_PAIRING_DISCOVERABLE
-            val trailerBase = ADV_MANUF_PAIRING_FLAG_OFFSET + 1
-            val codeLo = manufData[trailerBase + 2].toInt() and 0xFF
-            val codeHi = manufData[trailerBase + 3].toInt() and 0xFF
-            val code = String.format("%02X%02X", codeHi, codeLo)
-            return Triple(pairingMode, code, true)
+            val advertisement =
+                    MentraLivePairingAdvertisementParser.parse(manufacturerData(result))
+                            ?: return Triple(false, null, false)
+            return Triple(advertisement.pairingMode, advertisement.pairingCode, true)
         }
 
         fun isMentraLiveBluetoothName(name: String?): Boolean {
@@ -1299,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(
@@ -1386,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,
         )
     }
 
@@ -1475,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,
@@ -2109,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
@@ -3817,19 +3822,16 @@ class MentraLive : SGCManager() {
                 val body = HashMap<String, Any>()
                 body["window_ms"] = windowMs
                 body["reason"] = json.optString("reason", "user_gesture")
-                if (json.has("txn")) body["txn"] = json.optInt("txn")
                 Bridge.sendTypedMessage("entering_pairing_mode", body)
             }
             "pairing_info" ->
                     Bridge.sendPairingInfo(
                             json.optBoolean("had_previous_bond", false),
-                            jsonNullableString(json, "transfer_id"),
                             jsonNullableString(json, "pairing_code"),
                             json.optBoolean("classic_bond_ready", false),
                             // Legacy firmware that omits this field is not secure-capable.
                             json.optBoolean("secure_pairing_capable", false),
                             json.optInt("protocol_version", 1),
-                            jsonNullableString(json, "binding"),
                     )
             "imu_response",
             "imu_stream_response",
@@ -5956,6 +5958,7 @@ class MentraLive : SGCManager() {
 
         // Start scanning for BLE devices
         startScan()
+        handler.post { emitConnectedPendingDeviceForPairingScan() }
     }
 
     private fun releaseStaleClassicForDiscovery() {
@@ -6852,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/main/java/com/mentra/bluetoothsdk/sgcs/MentraLivePairingAdvertisement.kt

@@ -0,0 +1,54 @@
+package com.mentra.bluetoothsdk.sgcs
+
+internal data class MentraLivePairingAdvertisement(
+    val pairingMode: Boolean,
+    val pairingCode: String,
+)
+
+internal object MentraLivePairingAdvertisementParser {
+    private const val PAIRING_FLAG_OFFSET = 5
+    private const val PAIRING_DISCOVERABLE: Byte = 0x01
+    private const val PROTOCOL_VERSION_OFFSET = PAIRING_FLAG_OFFSET + 1
+    private const val CAPABILITY_OFFSET = PROTOCOL_VERSION_OFFSET + 1
+    private const val CODE_LOW_OFFSET = CAPABILITY_OFFSET + 1
+    private const val CODE_HIGH_OFFSET = CODE_LOW_OFFSET + 1
+    private const val MAGIC_FIRST_OFFSET = CODE_HIGH_OFFSET + 1
+    private const val MAGIC_SECOND_OFFSET = MAGIC_FIRST_OFFSET + 1
+    private const val PROTOCOL_VERSION_MIN = 2
+    private const val PROTOCOL_VERSION_MAX = 15
+    private const val SECURE_PAIRING_CAPABILITY = 0x01
+    private const val MAGIC_FIRST = 0x4D // M
+    private const val MAGIC_SECOND = 0x50 // P
+
+    /**
+     * Parses company-id-stripped 0xB822 manufacturer data.
+     *
+     * Legacy firmware stores an XOR'd Classic MAC where the original pairing implementation
+     * expected version and capability bytes. Requiring the `MP` marker makes the formats
+     * unambiguous instead of probabilistically classifying MAC bytes as a secure trailer.
+     */
+    fun parse(manufacturerData: ByteArray?): MentraLivePairingAdvertisement? {
+        if (manufacturerData == null || manufacturerData.size <= MAGIC_SECOND_OFFSET) {
+            return null
+        }
+
+        val version = manufacturerData[PROTOCOL_VERSION_OFFSET].toInt() and 0xFF
+        val capability = manufacturerData[CAPABILITY_OFFSET].toInt() and 0xFF
+        val magicFirst = manufacturerData[MAGIC_FIRST_OFFSET].toInt() and 0xFF
+        val magicSecond = manufacturerData[MAGIC_SECOND_OFFSET].toInt() and 0xFF
+        if (version !in PROTOCOL_VERSION_MIN..PROTOCOL_VERSION_MAX ||
+            (capability and SECURE_PAIRING_CAPABILITY) == 0 ||
+            magicFirst != MAGIC_FIRST ||
+            magicSecond != MAGIC_SECOND
+        ) {
+            return null
+        }
+
+        val codeLow = manufacturerData[CODE_LOW_OFFSET].toInt() and 0xFF
+        val codeHigh = manufacturerData[CODE_HIGH_OFFSET].toInt() and 0xFF
+        return MentraLivePairingAdvertisement(
+            pairingMode = manufacturerData[PAIRING_FLAG_OFFSET] == PAIRING_DISCOVERABLE,
+            pairingCode = String.format("%02X%02X", codeHigh, codeLow),
+        )
+    }
+}

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 })
+    }
+}