@mentra/bluetooth-sdk 3.4.0-dev.993 → 3.4.0-dev.998

package/MIGRATION.md

@@ -0,0 +1,61 @@
+# Bluetooth SDK migration: Mentra Live pairing state
+
+This note covers the public pairing API in `@mentra/bluetooth-sdk` `3.3.0` relative to the published `3.2.1` package. `3.3.0` is the current release family in `package.json` and is not on npm yet.
+
+## Version
+
+The SDK version is `package.json` `"version"`. The iOS podspec (`ios/MentraBluetoothSDK.podspec`) and the Android Gradle module (`android/build.gradle`) read that same value. Swift package metadata is injected from it at pack time.
+
+This repository keeps the Bluetooth SDK version aligned with the matching Mentra Live software release. It does not cut an independent major for a breaking SDK change. The break below ships in the unpublished `3.3.0` family. No further version bump was applied in this change. Integrators on `3.2.1` pick it up by moving to `3.3.0` when that release is published.
+
+## Removed
+
+- `confirmReplaceOwner()` is removed.
+- The `confirm_replace_owner_result` event and its types are removed.
+- `owner_replaced` is deprecated and is never emitted. Remove listeners. Use `pairing_state_changed` or `GlassesStatus.pairingState`.
+- `pairing_info` no longer includes `awaiting_confirm` or `retained_owner_link`.
+
+## Added
+
+`GlassesStatus.pairingState` (absent on models other than Mentra Live):
+
+```ts
+type MentraLivePairingState =
+  | {state: "normal"}
+  | {state: "pairing_mode"; windowId: number; endsAtMs: number}
+  | {state: "pairing_rejected"}
+```
+
+| State | What to do |
+| --- | --- |
+| `normal` | Automatic reconnect is allowed. |
+| `pairing_mode` | A pairing window is open. Leave reconnect paused until `endsAtMs`. That timestamp is the window plus a 30-second margin. `windowId` identifies the window and survives a cold start. |
+| `pairing_rejected` | The glasses no longer accept this phone (another phone paired, or repeated authentication rejections on secure-pairing firmware). Reconnect has stopped. Show **Pair Again**. This clears only after a successful explicit `connect()` / `connectDefault()`, or after `forget()`. |
+
+`useMentraBluetooth().glasses` does not include `pairingState`. Read `getGlassesStatus()`, `subscribeGlassesStatus()`, or the `pairing_state_changed` event (`{state: MentraLivePairingState}`).
+
+`GlassesStatus.audioSetup` (every model) says whether the user has to do anything for glasses audio:
+
+```ts
+type GlassesAudioSetupState =
+  | {state: "idle"}
+  | {state: "not_applicable"}
+  | {state: "connecting"}
+  | {state: "connected"}
+  | {state: "needs_user"; action: "connect_in_settings"}
+```
+
+Render `needs_user` as a step that sends the user to Settings > Bluetooth, and treat `connected` and `not_applicable` as done. The SDK owns the waits (on iPhone: up to 8 seconds after a pair on firmware with `auto_audio`, none on older firmware, 10 seconds after a reconnect). Remove any app-side audio timers or `pairing_info.auto_audio` checks. Changes also arrive as `audio_setup_changed` (`{state: GlassesAudioSetupState}`).
+
+Other additions:
+
+- `entering_pairing_mode` includes `window_id` (same window as `pairingState.windowId`).
+- `pairing_mode_ended` fires when the glasses close the window and this phone is still accepted. `reason` is `"paired"`, `"cancelled"`, or `"timeout"`. Optional `window_id`. The previous phone does not get this event when another phone pairs; it moves to `pairing_rejected`.
+- `pairing_info.auto_audio` is true when the glasses derive Classic audio from the LE pair (CTKD). The SDK already uses it for `audioSetup`.
+- `pair_failure.code` may be `"ios_forget_pairing"`: iOS holds a stale Bluetooth pairing for these glasses during an explicit attempt. The user must open Settings > Bluetooth, choose Forget This Device, then pair again. On Android and iOS native apps this arrives as the pairing-failure error's `failureCode`.
+
+## Behavior
+
+On supported Mentra Live firmware, three presses of the power button open one 120-second pairing window. The glasses speak a 4-character code. Three presses again cancel the window. After a timeout or a cancel, the phone that was already paired reconnects automatically. If another phone pairs, that previous phone gets `pairing_rejected`. Pairing readiness needs no app-side `pairing_info` wait: the SDK reports the glasses ready only after secure firmware commits the bond, and treats glasses that send no `pairing_info` within 5 seconds as older firmware.
+
+User-facing sample copy should say "Pair Again". Do not say "owner" in that copy. API fields such as `owner_retained`, `owner_committed`, and `ownership_transfer` are unchanged identifiers on `entering_pairing_mode` and `pairing_info`.

package/README.md

@@ -448,6 +448,51 @@ await BluetoothSdk.clearDefaultDevice()
 await saveDeviceToYourAppStorage(null)
 ```
 
+## Mentra Live pairing
+
+`confirmReplaceOwner()` and `confirm_replace_owner_result` are removed. `owner_replaced` is deprecated and is never emitted. The replacement is `GlassesStatus.pairingState`, also delivered as `pairing_state_changed`. Full steps are in [MIGRATION.md](./MIGRATION.md). The version stays `3.3.0` in `package.json` (podspec and Gradle read it). npm still publishes `3.2.1`.
+
+On supported Mentra Live firmware, three power-button presses open one 120-second window and the glasses speak a 4-character code. Three presses again cancel it. The phone that was already paired pauses automatic reconnect for that window plus a 30-second margin (`pairingState.endsAtMs`), then reconnects after `pairing_mode_ended` with `reason` `"timeout"` or `"cancelled"`. If the glasses stop accepting this phone (another phone paired, or repeated authentication rejections on secure-pairing firmware), this phone's state becomes `pairing_rejected`: reconnect stops, and the UI should show Pair Again. That state clears only after a successful explicit pair or `forget()`.
+
+`useMentraBluetooth().glasses` does not include `pairingState`. Read `getGlassesStatus()`, `subscribeGlassesStatus()`, or:
+
+```ts
+BluetoothSdk.addListener("pairing_state_changed", (event) => {
+  if (event.state.state === "pairing_rejected") showPairAgain()
+})
+
+BluetoothSdk.addListener("pair_failure", (event) => {
+  if (event.code === "ios_forget_pairing") {
+    // iOS still has a Bluetooth pairing for these glasses.
+    // Settings > Bluetooth > Forget This Device, then pair again.
+  }
+})
+```
+
+`entering_pairing_mode` includes `window_id`. `pairing_info` includes `auto_audio` and no longer includes `awaiting_confirm` or `retained_owner_link`. Do not use the word "owner" in user-facing sample copy.
+
+## Glasses audio setup
+
+`GlassesStatus.audioSetup`, also delivered as `audio_setup_changed` (`{state}`), says whether the user has to do anything to get glasses audio working. The SDK decides it for every glasses model. Render it; do not add your own audio timers or platform checks.
+
+| `audioSetup.state` | Meaning | What to show |
+| --- | --- | --- |
+| `idle` | No glasses session | Nothing |
+| `not_applicable` | No audio step (Android attaches audio from the BLE bond; glasses without Classic audio) | Nothing |
+| `connecting` | Glasses connected, audio expected to come up on its own | A "connecting" state |
+| `connected` | Classic audio (A2DP or HFP) is up | Nothing |
+| `needs_user` | Audio did not come up on its own (`action: "connect_in_settings"`) | Ask the user to connect the glasses in Settings > Bluetooth |
+
+On iPhone, after a pair the SDK waits up to 8 seconds on firmware that brings audio up from the BLE pair and reports `needs_user` at once on older firmware. After a reconnect it waits 10 seconds. The state moves to `connected` as soon as audio comes up. Mentra Live firmware that reports its own audio link (`classic_link`) is preferred over the phone's audio route, which is wrong while another Bluetooth audio device holds it.
+
+```ts
+BluetoothSdk.addListener("audio_setup_changed", (event) => {
+  if (event.state.state === "needs_user") showConnectAudioInSettings()
+})
+```
+
+`useMentraBluetooth().glasses` does not include `audioSetup`. Read `getGlassesStatus()`, `subscribeGlassesStatus()`, or the event.
+
 ## Native notification controls
 
 G2 exposes firmware-owned notification history and popups. `getNativeNotificationStatus()` reports support, source (`phone` on Android or `ancs` on iOS), authorization, the desired controls, and submission/failure state. `submitted` means the controls were queued for the glasses, not that firmware acknowledged them. Unsupported drivers reject configuration instead of silently succeeding.
@@ -751,6 +796,8 @@ 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`, `mic_health`, `local_transcription`, `rgb_led_control_response`, `pair_failure`, `pairing_info`, `entering_pairing_mode`, `pairing_mode_ended`, `pairing_state_changed`, `audio_connected`, `audio_disconnected`, and `log`. `owner_replaced` remains in the type map and is never emitted.
+
 ### Claiming touchpad gestures
 
 On Mentra Live, disable a gesture's stock action before using it in your app:

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

@@ -310,7 +310,9 @@ class BluetoothSdkModule : Module() {
                 }
 
                 override fun onError(error: BluetoothError) {
-                    sendEvent("pair_failure", mapOf("error" to error.message))
+                    val body = mutableMapOf<String, Any>("error" to error.message)
+                    error.failureCode?.let { body["code"] = it }
+                    sendEvent("pair_failure", body)
                 }
 
                 override fun onRawEvent(eventName: String, values: Map<String, Any>) {
@@ -379,6 +381,9 @@ class BluetoothSdkModule : Module() {
             "pair_failure",
             "pairing_info",
             "entering_pairing_mode",
+            "pairing_mode_ended",
+            "pairing_state_changed",
+            "audio_setup_changed",
             "owner_replaced",
             "audio_pairing_needed",
             "audio_connected",

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

@@ -125,9 +125,10 @@ public class Bridge private constructor() {
 
         /** Send pair failure event */
         @JvmStatic
-        fun sendPairFailureEvent(error: String) {
+        fun sendPairFailureEvent(error: String, code: String? = null) {
             val data = HashMap<String, Any>()
             data["error"] = error
+            if (code != null) data["code"] = code
             sendTypedMessage("pair_failure", data as Map<String, Any>)
         }
 
@@ -138,6 +139,9 @@ public class Bridge private constructor() {
             classicBondReady: Boolean = false,
             securePairingCapable: Boolean = true,
             protocolVersion: Int = 1,
+            ownershipTransfer: Boolean = false,
+            ownerCommitted: Boolean = false,
+            autoAudio: Boolean = false,
         ) {
             val data = HashMap<String, Any>()
             data["had_previous_bond"] = hadPreviousBond
@@ -145,6 +149,9 @@ public class Bridge private constructor() {
             data["classic_bond_ready"] = classicBondReady
             data["secure_pairing_capable"] = securePairingCapable
             data["protocol_version"] = protocolVersion
+            data["ownership_transfer"] = ownershipTransfer
+            data["owner_committed"] = ownerCommitted
+            data["auto_audio"] = autoAudio
             sendTypedMessage("pairing_info", data as Map<String, Any>)
         }
 

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

@@ -23,6 +23,7 @@ import com.mentra.bluetoothsdk.sgcs.SceneElement
 import com.mentra.bluetoothsdk.sgcs.SceneFrame
 import com.mentra.bluetoothsdk.sgcs.Mach1
 import com.mentra.bluetoothsdk.sgcs.MentraLive
+import com.mentra.bluetoothsdk.sgcs.MentraLivePairingStateStore
 import com.mentra.bluetoothsdk.sgcs.MentraNex
 import com.mentra.bluetoothsdk.sgcs.Nimo
 import com.mentra.bluetoothsdk.sgcs.NimoResourceDiagnostics
@@ -571,8 +572,10 @@ class DeviceManager internal constructor(initializeHardware: Boolean) {
 
                         BluetoothAdapter.STATE_ON -> {
                             Bridge.log("MAN: Bluetooth turned ON")
-                            // Auto-reconnect to last known device if we have one
-                            if (defaultWearable.isNotEmpty() && deviceName.isNotEmpty()) {
+                            // Auto-reconnect to last known device if we have one.
+                            // After owner loss, connectById watches for the next pairing
+                            // mode instead of opening GATT.
+                            if (shouldReconnectAfterBluetoothOn()) {
                                 Bridge.log(
                                     "MAN: Bluetooth restored, attempting reconnect to: $deviceName"
                                 )
@@ -1509,6 +1512,8 @@ class DeviceManager internal constructor(initializeHardware: Boolean) {
             Bridge.log("MAN: SGC is null, returning")
             return
         }
+        // Before clearPendingConnection(): the pending target is what marks an explicit pair.
+        notePairingSessionReady()
 
         // A new identity must never inherit the previous glasses' address when
         // pairing supplied only a name. Same-device reconnects retain their cache.
@@ -2350,6 +2355,37 @@ class DeviceManager internal constructor(initializeHardware: Boolean) {
         sgc?.sendRgbLedControl(requestId, packageName, action, color, onDurationMs, offDurationMs, count)
     }
 
+    internal fun shouldReconnectAfterBluetoothOn(): Boolean =
+        defaultWearable.isNotEmpty() && deviceName.isNotEmpty()
+
+    /**
+     * A ready Mentra Live session. Only an explicit pair (a pending target) clears
+     * `pairing_rejected`; an automatic session only ends a pause and resets the streak.
+     */
+    internal fun notePairingSessionReady() {
+        if (sgc !is MentraLive) return
+        val explicitAttempt = pendingDeviceName.isNotEmpty() || pendingDeviceAddress.isNotEmpty()
+        MentraLivePairingStateStore.update("device_ready") { it.onSessionReady(explicitAttempt) }
+    }
+
+    /** Forget ends the pairing record. Also drops the pre-v4 owner-lost setting. */
+    internal fun clearPairingStateOnForget() {
+        MentraLivePairingStateStore.update("forget") { it.onForget() }
+        if (DeviceStore.store.get("bluetooth", "mentra_live_owner_lost") as? Boolean != true) return
+        DeviceStore.apply("bluetooth", "mentra_live_owner_lost", false)
+        Bridge.saveSetting("mentra_live_owner_lost", false)
+    }
+
+    /**
+     * The saved glasses' firmware is no longer known once they are forgotten. The next glasses
+     * report it again with their first `pairing_info`.
+     */
+    internal fun clearSecureFirmware() {
+        if (DeviceStore.store.get("bluetooth", "mentra_live_secure_firmware") as? Boolean != true) return
+        DeviceStore.apply("bluetooth", "mentra_live_secure_firmware", false)
+        Bridge.saveSetting("mentra_live_secure_firmware", false)
+    }
+
     fun connectDefault() {
         if (NimoResourceDiagnostics.dispatchCapturedEntry { connectDefault() }) return
         if (defaultWearable.isEmpty()) {
@@ -2376,8 +2412,14 @@ class DeviceManager internal constructor(initializeHardware: Boolean) {
         if (!NimoResourceDiagnostics.allowManagerConnect(defaultWearable, reconnectTarget)) return
         initSGC(defaultWearable)
         val live = sgc as? MentraLive
-        if (live?.isPairingYieldActive() == true) {
-            Bridge.log("MAN: connectDefault skipped — Mentra Live pairing yield active")
+        if (live != null && MentraLivePairingStateStore.isRejected) {
+            Bridge.log("MAN: connectDefault skipped — Mentra Live pairing_rejected (Pair Again or forget)")
+            return
+        }
+        if (live != null && MentraLivePairingStateStore.isPaused) {
+            // connectById only records the target and watches for the window to end.
+            Bridge.log("MAN: connectDefault deferred — Mentra Live pairing_mode")
+            live.connectById(reconnectTarget)
             return
         }
         searching = true
@@ -2570,6 +2612,8 @@ class DeviceManager internal constructor(initializeHardware: Boolean) {
             connectionRecovery.clear()
         }
         Bridge.log("MAN: Forgetting smart glasses")
+        clearPairingStateOnForget()
+        clearSecureFirmware()
 
         val live = sgc as? MentraLive
         if (live != null) {

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

@@ -2,6 +2,7 @@ package com.mentra.bluetoothsdk
 
 import android.os.Handler
 import android.os.Looper
+import com.mentra.bluetoothsdk.sgcs.GlassesAudioSetupPolicy
 import com.mentra.bluetoothsdk.utils.DeviceTypes
 import com.mentra.bluetoothsdk.utils.ConnTypes
 import com.mentra.bluetoothsdk.utils.MicMap
@@ -79,6 +80,8 @@ object DeviceStore {
         store.set("glasses", "micEnabled", false)
         store.set("glasses", "voiceActivityDetectionEnabled", BluetoothSdkDefaults.VOICE_ACTIVITY_DETECTION_ENABLED)
         store.set("glasses", "bluetoothClassicConnected", false)
+        store.set("glasses", "bluetoothClassicProfilesConnected", false)
+        store.set("glasses", "bluetoothAudioRouted", false)
         store.set("glasses", "caseRemoved", true)
         store.set("glasses", "caseOpen", true)
         store.set("glasses", "caseCharging", false)
@@ -167,6 +170,16 @@ object DeviceStore {
         return store.get(category, key)
     }
 
+    /**
+     * `GlassesStatus.audioSetup` follows readiness on every model ([GlassesAudioSetupPolicy]), so
+     * the snapshot that changed `fullyBooted` already carries the new state. Announce it like
+     * `pairing_state_changed`, only when it changed.
+     */
+    private fun publishAudioSetupChange(wasReady: Boolean, ready: Boolean) {
+        val state = GlassesAudioSetupPolicy.change(wasReady, ready) ?: return
+        Bridge.sendTypedMessage("audio_setup_changed", mapOf("state" to state.toMap()))
+    }
+
     fun set(category: String, key: String, value: Any) {
         store.set(category, key, value)
     }
@@ -175,12 +188,20 @@ object DeviceStore {
     fun apply(category: String, key: String, value: Any) {
         val oldValue = store.get(category, key)
         store.set(category, key, value)
+        if (category == "glasses" && key == "bluetoothClassicConnected") {
+            // Android has no separate profile/route signal; keep both equal to the Classic audio state.
+            store.set(category, "bluetoothClassicProfilesConnected", value)
+            store.set(category, "bluetoothAudioRouted", value)
+        }
         val skipped = observableStoreWouldHaveSkipped(oldValue, value)
         val forceMicReset =
                 category == ObservableStore.BLUETOOTH_CATEGORY && key == "mic_tuning" && isMicTuningReset(value)
         if (skipped && !forceMicReset) {
             return
         }
+        if (category == "glasses" && key == "fullyBooted" && value is Boolean) {
+            publishAudioSetupChange(oldValue as? Boolean ?: false, value)
+        }
 
         // Trigger hardware updates based on setting changes
         when (category to key) {

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.4.0"
-    const val RELEASE_IDENTITY: String = "3.4.0-dev.993"
-    const val RELEASE_SET_ID: String = "mentra-3.4.0-dev.993"
-    const val SOURCE_COMMIT: String = "7fd0a5cfd9fb3db878f18f3975121c613a4b8fcc"
-    const val OTA_MANIFEST_URL: String = "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.4.0/mentra-live-ota-3.4.0-dev.993.json"
-    const val OTA_MANIFEST_SHA256: String = "fb9e951467dcb09ceca5e7b3c244f6e7c21f0fd61efadbf3c06d59134e272345"
+    const val RELEASE_IDENTITY: String = "3.4.0-dev.998"
+    const val RELEASE_SET_ID: String = "mentra-3.4.0-dev.998"
+    const val SOURCE_COMMIT: String = "c77108af50fcaabe3f2c1464b2a5d649a30e337b"
+    const val OTA_MANIFEST_URL: String = "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.4.0/mentra-live-ota-3.4.0-dev.998.json"
+    const val OTA_MANIFEST_SHA256: String = "8c797478019499beb9a637bf418ff6586fd974115f712dfb51c7a96f6e08151c"
 }

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

@@ -9,6 +9,7 @@ import android.os.Bundle
 import android.os.Handler
 import android.os.Looper
 import android.util.Log
+import com.mentra.bluetoothsdk.sgcs.MentraLive
 import com.mentra.bluetoothsdk.sgcs.NimoResourceDiagnostics
 import com.mentra.bluetoothsdk.streaming.StreamSessionState
 import com.mentra.bluetoothsdk.utils.ControllerTypes
@@ -2110,6 +2111,7 @@ class MentraBluetoothSdk private constructor(
                         BluetoothError(
                             code = "pair_failure",
                             message = data["error"] as? String ?: data.toString(),
+                            failureCode = data["code"] as? String,
                         )
                     )
                 }

package/android/src/main/java/com/mentra/bluetoothsdk/connection/ConnectionModels.kt

@@ -45,6 +45,11 @@ data class BluetoothError(
     val code: String,
     val message: String,
     val cause: Throwable? = null,
+    /**
+     * Stable machine-readable cause within [code], when the SDK can classify it. For
+     * `pair_failure`: `ios_forget_pairing` (iOS only).
+     */
+    val failureCode: String? = null,
 )
 
 enum class ScanStopReason {

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

@@ -0,0 +1,64 @@
+package com.mentra.bluetoothsdk.sgcs
+
+/**
+ * `GlassesStatus.audioSetup`: whether the user has to do anything to get glasses audio working.
+ * Native code encodes it as a map, `{"state": "idle"}` through
+ * `{"state": "needs_user", "action": "connect_in_settings"}`, the same shape as the TypeScript
+ * `GlassesAudioSetupState` and iOS.
+ */
+internal enum class GlassesAudioSetupState(val state: String, val action: String? = null) {
+    /** No glasses session. */
+    IDLE("idle"),
+    /** No user step for audio on this platform and glasses. */
+    NOT_APPLICABLE("not_applicable"),
+    /** The link is up, audio is not, and the SDK still expects audio to come up on its own. */
+    CONNECTING("connecting"),
+    /** Classic audio to these glasses is up. */
+    CONNECTED("connected"),
+    /** Audio did not come up on its own. The user connects it in system Bluetooth settings. */
+    NEEDS_USER("needs_user", "connect_in_settings");
+
+    fun toMap(): Map<String, Any> =
+            if (action == null) mapOf("state" to state) else mapOf("state" to state, "action" to action)
+
+    companion object {
+        fun fromMap(raw: Any?): GlassesAudioSetupState? {
+            val state = (raw as? Map<*, *>)?.get("state") as? String ?: return null
+            return values().firstOrNull { it.state == state }
+        }
+    }
+}
+
+/**
+ * The Android audio setup rule, for every glasses model including Mentra Live. Android attaches
+ * Classic audio from the BLE bond (CTKD on secure Mentra Live firmware, `createBond` on older
+ * firmware), and glasses without Classic audio have nothing to set up, so there is never a user
+ * step to offer: `not_applicable` while the glasses are ready, `idle` without a session. The
+ * shared status layer applies it, so the update that marks the glasses ready carries
+ * `not_applicable` with it. iOS keeps its timed Mentra Live rules in `GlassesAudioSetupPolicy.swift`.
+ */
+internal object GlassesAudioSetupPolicy {
+    fun state(ready: Boolean): GlassesAudioSetupState =
+            if (ready) GlassesAudioSetupState.NOT_APPLICABLE else GlassesAudioSetupState.IDLE
+
+    /** The state `audio_setup_changed` announces when readiness moves, or null when it is unchanged. */
+    fun change(wasReady: Boolean, ready: Boolean): GlassesAudioSetupState? {
+        val after = state(ready)
+        return if (state(wasReady) == after) null else after
+    }
+}
+
+/**
+ * Mentra Live firmware `{"type":"classic_link","a2dp":<bool>,"hfp":<bool>}`: whether the phone's
+ * A2DP and HFP (service-level) links to the glasses are up. iOS feeds it into its audio setup
+ * rules; Android's `audioSetup` does not depend on it. A missing or malformed field reads false.
+ */
+internal data class MentraLiveClassicLink(val a2dp: Boolean, val hfp: Boolean) {
+    companion object {
+        fun parse(json: org.json.JSONObject): MentraLiveClassicLink =
+                MentraLiveClassicLink(
+                        a2dp = json.optBoolean("a2dp", false),
+                        hfp = json.optBoolean("hfp", false),
+                )
+    }
+}