@mentra/bluetooth-sdk 0.1.5 → 0.1.6

package/README.md

@@ -123,15 +123,21 @@ const devices = await BluetoothSdk.scan(DeviceModels.MentraLive, {
   },
 })
 
-const device = devices[0]
+const device = await chooseDevice(devices)
 if (!device) {
-  throw new Error('No Mentra Live glasses found')
+  throw new Error('No Mentra Live glasses selected')
 }
 
 await BluetoothSdk.connect(device)
-await BluetoothSdk.displayText('Hello from Mentra', 0, 0, 24)
+await BluetoothSdk.requestVersionInfo()
 ```
 
+In multi-device environments, present an explicit picker instead of
+auto-connecting to the first nearby device.
+
+Mentra Live does not have a display. Use display commands only after gating by
+model capability.
+
 Use `Device.id` as the stable app-facing key for scan rows, selected devices,
 and persisted default devices. Do not parse it for model, name, or address
 information; use the typed `model`, `name`, `address`, and `rssi` fields
@@ -139,6 +145,10 @@ instead. Android commonly uses a Bluetooth address when available, iOS commonly
 uses a CoreBluetooth identifier when available, and the SDK falls back to
 `model:name` when no platform identifier is available.
 
+`Device.rssi` is optional. A device can appear in scan results before the
+platform reports RSSI, so picker UI should handle `undefined` and avoid
+reordering rows just because RSSI metadata arrives later.
+
 ## React Hooks
 
 React Native apps can import optional lifecycle helpers from the `react`
@@ -285,21 +295,27 @@ Use `rtmp://` or `rtmps://` for RTMP, `srt://` for SRT, and `http://` or `https:
 
 ## Events
 
-```ts
-const subscriptions = [
-  BluetoothSdk.addListener('button_press', (event) => console.log(event)),
-  BluetoothSdk.addListener('touch_event', (event) => console.log(event)),
-  BluetoothSdk.addListener('photo_response', (event) => console.log(event)),
-  BluetoothSdk.addListener('stream_status', (event) => console.log(event)),
-  BluetoothSdk.addListener('mic_pcm', (event) => {
+React Native components should use `useBluetoothEvent()` for hardware events:
+
+```tsx
+import {useBluetoothEvent} from '@mentra/bluetooth-sdk/react'
+
+export function HardwareEventLogger() {
+  useBluetoothEvent('button_press', (event) => console.log(event))
+  useBluetoothEvent('touch_event', (event) => console.log(event))
+  useBluetoothEvent('photo_response', (event) => console.log(event))
+  useBluetoothEvent('stream_status', (event) => console.log(event))
+  useBluetoothEvent('mic_pcm', (event) => {
     console.log(event.sampleRate, event.bitsPerSample, event.channels, event.encoding)
     console.log(event.pcm)
-  }),
-]
+  })
 
-subscriptions.forEach((subscription) => subscription.remove())
+  return null
+}
 ```
 
+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`, `hotspot_status_change`, `photo_response`, `gallery_status`, `stream_status`, `keep_alive_ack`, `mic_pcm`, `mic_lc3`, `local_transcription`, `rgb_led_control_response`, `audio_connected`, `audio_disconnected`, and `log`.
 
 React Native event payload fields use camelCase. For example, `touch_event` includes `gestureName`, `photo_response` success includes `uploadUrl`, and `gallery_status` includes `hasContent` and `cameraBusy`. `mic_pcm` includes `sampleRate`, `bitsPerSample`, `channels`, `encoding`, and `vadGated`; `mic_lc3` includes `sampleRate`, `channels`, `encoding`, `frameDurationMs`, `frameSizeBytes`, `bitrate`, `packetizedFromGlasses`, and `vadGated`.

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

@@ -9,12 +9,20 @@ class BluetoothSdkModule : Module() {
     private var deviceManager: DeviceManager? = null
     private val sdkListener =
             object : MentraBluetoothSdkListener {
-                override fun onGlassesStatusChanged(status: GlassesStatusUpdate) {
-                    sendEvent("glasses_status", status.toMap())
+                override fun onGlassesChanged(glasses: GlassesRuntimeState) {
+                    sendEvent(
+                            "glasses_status",
+                            sdk?.getRawGlassesStatus()?.toMap()
+                                    ?: GlassesStatus.fromMap(DeviceStore.store.getCategory("glasses")).toMap()
+                    )
                 }
 
-                override fun onBluetoothStatusChanged(status: BluetoothStatusUpdate) {
-                    sendEvent("bluetooth_status", status.toMap())
+                override fun onSdkStateChanged(sdkState: PhoneSdkRuntimeState) {
+                    sendEvent(
+                            "bluetooth_status",
+                            sdk?.getRawBluetoothStatus()?.toMap()
+                                    ?: DeviceStore.store.getCategory(ObservableStore.BLUETOOTH_CATEGORY)
+                    )
                 }
 
                 override fun onDeviceDiscovered(device: Device) {
@@ -31,7 +39,7 @@ class BluetoothSdkModule : Module() {
 
                 override fun onScanStopped(reason: ScanStopReason) {
                     if (reason == ScanStopReason.COMPLETED) {
-                        val status = sdk?.getBluetoothStatus()
+                        val status = sdk?.getRawBluetoothStatus()
                         val deviceModel =
                                 status?.pendingWearable?.takeIf { it.isNotBlank() }
                                         ?: status?.defaultWearable
@@ -196,12 +204,12 @@ class BluetoothSdkModule : Module() {
         // MARK: - Observable Store Functions
 
         Function("getGlassesStatus") {
-            sdk?.getGlassesStatus()?.toMap()
+            sdk?.getRawGlassesStatus()?.toMap()
                     ?: GlassesStatus.fromMap(DeviceStore.store.getCategory("glasses")).toMap()
         }
 
         Function("getBluetoothStatus") {
-            sdk?.getBluetoothStatus()?.toMap() ?: DeviceStore.store.getCategory(ObservableStore.BLUETOOTH_CATEGORY)
+            sdk?.getRawBluetoothStatus()?.toMap() ?: DeviceStore.store.getCategory(ObservableStore.BLUETOOTH_CATEGORY)
         }
 
         Function("getDefaultDevice") { sdk?.getDefaultDevice()?.toMap() }

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

@@ -138,6 +138,7 @@ object DeviceStore {
         store.set("bluetooth", "should_send_lc3", false)
         store.set("bluetooth", "should_send_transcript", false)
         store.set("bluetooth", "bypass_vad", true)
+        store.set("bluetooth", "use_native_dashboard", false)
     }
 
     fun get(category: String, key: String): Any? {

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

@@ -4,10 +4,10 @@ import android.bluetooth.BluetoothManager
 import android.content.Context
 import android.os.Handler
 import android.os.Looper
-import com.mentra.bluetoothsdk.utils.ConnTypes
 import com.mentra.bluetoothsdk.utils.ControllerTypes
 import com.mentra.bluetoothsdk.utils.PhoneAudioMonitor
 import java.util.Collections
+import java.util.concurrent.atomic.AtomicBoolean
 
 class MentraBluetoothSdk private constructor(
     context: Context,
@@ -34,6 +34,7 @@ class MentraBluetoothSdk private constructor(
 
     companion object {
         private val DEFAULT_DEVICE_KEYS = setOf("default_wearable", "device_name", "device_address")
+        private val SCAN_STATE_KEYS = setOf("searching", "searchingController", "searchResults")
         private const val DEFAULT_SCAN_TIMEOUT_MS = 15_000L
 
         @JvmStatic
@@ -58,10 +59,22 @@ class MentraBluetoothSdk private constructor(
         listeners.remove(listener)
     }
 
-    fun getGlassesStatus(): GlassesStatus =
+    fun getState(): MentraBluetoothState =
+        MentraBluetoothState.from(getRawGlassesStatus(), getRawBluetoothStatus())
+
+    fun getGlasses(): GlassesRuntimeState =
+        getState().glasses
+
+    fun getSdkState(): PhoneSdkRuntimeState =
+        getState().sdk
+
+    fun getScanState(): BluetoothScanState =
+        getState().scan
+
+    internal fun getRawGlassesStatus(): GlassesStatus =
         GlassesStatus.fromMap(DeviceStore.store.getCategory("glasses"))
 
-    fun getBluetoothStatus(): BluetoothStatus =
+    internal fun getRawBluetoothStatus(): BluetoothStatus =
         BluetoothStatus.fromMap(DeviceStore.store.getCategory(ObservableStore.BLUETOOTH_CATEGORY))
 
     fun getDefaultDevice(): Device? = currentDefaultDevice()
@@ -144,7 +157,7 @@ class MentraBluetoothSdk private constructor(
         val latestResults = mutableListOf<Device>()
         lateinit var timeoutRunnable: Runnable
         lateinit var session: ScanSession
-        var finished = false
+        val finished = AtomicBoolean(false)
 
         fun emitResults(devices: List<Device>) {
             latestResults.clear()
@@ -154,16 +167,13 @@ class MentraBluetoothSdk private constructor(
 
         val scanListener =
             object : MentraBluetoothSdkCallback() {
-                override fun onBluetoothStatusChanged(status: BluetoothStatusUpdate) {
-                    status.searchResults?.let { results ->
-                        emitResults(results.filter { it.model == model })
-                    }
+                override fun onScanChanged(scan: BluetoothScanState) {
+                    emitResults(scan.devices.filter { it.model == model })
                 }
-        }
+            }
 
         fun finish(reason: ScanStopReason) {
-            if (finished) return
-            finished = true
+            if (!finished.compareAndSet(false, true)) return
             removeListener(scanListener)
             mainHandler.removeCallbacks(timeoutRunnable)
             session.markStopped()
@@ -178,7 +188,7 @@ class MentraBluetoothSdk private constructor(
         try {
             emitResults(emptyList())
             startScan(model)
-            emitResults(getBluetoothStatus().searchResults.filter { it.model == model })
+            emitResults(getRawBluetoothStatus().searchResults.filter { it.model == model })
             mainHandler.postDelayed(timeoutRunnable, normalizedTimeoutMs)
             return session
         } catch (error: Throwable) {
@@ -483,13 +493,22 @@ class MentraBluetoothSdk private constructor(
 
     private fun dispatchStoreUpdate(category: String, changes: Map<String, Any>) {
         when (ObservableStore.normalizeCategory(category)) {
-            "glasses" ->
+            "glasses" -> {
+                val state = getState()
                 dispatchToListeners {
-                    it.onGlassesStatusChanged(GlassesStatusUpdate.fromMap(glassesStatusChanges(changes)))
+                    it.onStateChanged(state)
+                    it.onGlassesChanged(state.glasses)
                 }
+            }
             ObservableStore.BLUETOOTH_CATEGORY -> {
+                val state = getState()
+                val scanChanged = changes.keys.any { it in SCAN_STATE_KEYS }
                 dispatchToListeners {
-                    it.onBluetoothStatusChanged(BluetoothStatusUpdate.fromMap(changes))
+                    it.onStateChanged(state)
+                    it.onSdkStateChanged(state.sdk)
+                    if (scanChanged) {
+                        it.onScanChanged(state.scan)
+                    }
                 }
                 if (!suppressDefaultDeviceEvents && changes.keys.any { it in DEFAULT_DEVICE_KEYS }) {
                     dispatchDefaultDeviceChanged()
@@ -499,37 +518,6 @@ class MentraBluetoothSdk private constructor(
         }
     }
 
-    private fun glassesStatusChanges(changes: Map<String, Any>): Map<String, Any> {
-        var merged = changes
-
-        if (changes.keys.any { it in setOf("wifiConnected", "wifiSsid", "wifiLocalIp") }) {
-            merged =
-                merged +
-                    mapOf(
-                        "wifiConnected" to ((DeviceStore.get("glasses", "wifiConnected") as? Boolean) ?: false),
-                        "wifiSsid" to ((DeviceStore.get("glasses", "wifiSsid") as? String) ?: ""),
-                        "wifiLocalIp" to ((DeviceStore.get("glasses", "wifiLocalIp") as? String) ?: ""),
-                    )
-        }
-
-        if (changes.keys.any { it in setOf("connected", "fullyBooted", "connectionState") }) {
-            merged =
-                merged +
-                    mapOf(
-                        "connected" to ((DeviceStore.get("glasses", "connected") as? Boolean) ?: false),
-                        "fullyBooted" to ((DeviceStore.get("glasses", "fullyBooted") as? Boolean) ?: false),
-                        "connectionState" to ((DeviceStore.get("glasses", "connectionState") as? String) ?: ConnTypes.DISCONNECTED),
-                    )
-        }
-
-        if (changes.containsKey("signalStrengthUpdatedAt") && !changes.containsKey("signalStrength")) {
-            val signalStrength = (DeviceStore.get("glasses", "signalStrength") as? Number)?.toInt() ?: -1
-            merged = merged + ("signalStrength" to signalStrength)
-        }
-
-        return merged
-    }
-
     private fun dispatchDefaultDeviceChanged() {
         val defaultDevice = currentDefaultDevice()
         dispatchToListeners { it.onDefaultDeviceChanged(defaultDevice) }

package/android/src/main/java/com/mentra/bluetoothsdk/audio/AudioModels.kt

@@ -0,0 +1,125 @@
+package com.mentra.bluetoothsdk
+
+enum class MicPreference(val value: String) {
+    AUTO("auto"),
+    PHONE("phone"),
+    GLASSES("glasses"),
+    BLUETOOTH("bluetooth"),
+}
+
+data class MicPcmEvent(
+    val pcm: ByteArray,
+    val sampleRate: Int,
+    val bitsPerSample: Int,
+    val channels: Int,
+    val encoding: String,
+    val vadGated: Boolean,
+) {
+    constructor(values: Map<String, Any>) : this(
+        pcm = values["pcm"] as? ByteArray ?: ByteArray(0),
+        sampleRate = numberValue(values, "sampleRate") ?: SAMPLE_RATE,
+        bitsPerSample = numberValue(values, "bitsPerSample") ?: BITS_PER_SAMPLE,
+        channels = numberValue(values, "channels") ?: CHANNELS,
+        encoding = stringValue(values, "encoding") ?: ENCODING,
+        vadGated = boolValue(values, "vadGated") ?: false,
+    )
+
+    fun toMap(): Map<String, Any> =
+        mapOf(
+            "type" to "mic_pcm",
+            "pcm" to pcm,
+            "sampleRate" to sampleRate,
+            "bitsPerSample" to bitsPerSample,
+            "channels" to channels,
+            "encoding" to encoding,
+            "vadGated" to vadGated,
+        )
+
+    companion object {
+        const val SAMPLE_RATE = 16_000
+        const val BITS_PER_SAMPLE = 16
+        const val CHANNELS = 1
+        const val ENCODING = "pcm_s16le"
+    }
+}
+
+data class MicLc3Event(
+    val lc3: ByteArray,
+    val sampleRate: Int,
+    val channels: Int,
+    val encoding: String,
+    val frameDurationMs: Int,
+    val frameSizeBytes: Int,
+    val bitrate: Int,
+    val packetizedFromGlasses: Boolean,
+    val vadGated: Boolean,
+) {
+    constructor(values: Map<String, Any>) : this(
+        lc3 = values["lc3"] as? ByteArray ?: ByteArray(0),
+        sampleRate = numberValue(values, "sampleRate") ?: SAMPLE_RATE,
+        channels = numberValue(values, "channels") ?: CHANNELS,
+        encoding = stringValue(values, "encoding") ?: ENCODING,
+        frameDurationMs = numberValue(values, "frameDurationMs") ?: FRAME_DURATION_MS,
+        frameSizeBytes = numberValue(values, "frameSizeBytes") ?: DEFAULT_FRAME_SIZE_BYTES,
+        bitrate = numberValue(values, "bitrate") ?: DEFAULT_BITRATE,
+        packetizedFromGlasses = boolValue(values, "packetizedFromGlasses") ?: false,
+        vadGated = boolValue(values, "vadGated") ?: false,
+    )
+
+    fun toMap(): Map<String, Any> =
+        mapOf(
+            "type" to "mic_lc3",
+            "lc3" to lc3,
+            "sampleRate" to sampleRate,
+            "channels" to channels,
+            "encoding" to encoding,
+            "frameDurationMs" to frameDurationMs,
+            "frameSizeBytes" to frameSizeBytes,
+            "bitrate" to bitrate,
+            "packetizedFromGlasses" to packetizedFromGlasses,
+            "vadGated" to vadGated,
+        )
+
+    companion object {
+        const val SAMPLE_RATE = 16_000
+        const val CHANNELS = 1
+        const val ENCODING = "lc3"
+        const val FRAME_DURATION_MS = 10
+        const val DEFAULT_FRAME_SIZE_BYTES = 60
+        const val DEFAULT_BITRATE = DEFAULT_FRAME_SIZE_BYTES * 8 * (1000 / FRAME_DURATION_MS)
+    }
+}
+
+data class LocalTranscriptionEvent(
+    val text: String,
+    val isFinal: Boolean,
+    val values: Map<String, Any>,
+)
+
+data class GlassesMediaVolumeGetResult(
+    val level: Int?,
+    val statusCode: Int?,
+    val values: Map<String, Any>,
+) {
+    companion object {
+        fun fromMap(values: Map<String, Any>): GlassesMediaVolumeGetResult =
+            GlassesMediaVolumeGetResult(
+                level = numberValue(values, "level"),
+                statusCode = (values["statusCode"] as? Number)?.toInt(),
+                values = values,
+            )
+    }
+}
+
+data class GlassesMediaVolumeSetResult(
+    val statusCode: Int?,
+    val values: Map<String, Any>,
+) {
+    companion object {
+        fun fromMap(values: Map<String, Any>): GlassesMediaVolumeSetResult =
+            GlassesMediaVolumeSetResult(
+                statusCode = (values["statusCode"] as? Number)?.toInt(),
+                values = values,
+            )
+    }
+}

package/android/src/main/java/com/mentra/bluetoothsdk/camera/CameraModels.kt

@@ -0,0 +1,187 @@
+package com.mentra.bluetoothsdk
+
+enum class GalleryMode {
+    AUTO,
+    MANUAL,
+}
+
+enum class PhotoSize(val value: String) {
+    SMALL("small"),
+    MEDIUM("medium"),
+    LARGE("large"),
+    FULL("full");
+
+    companion object {
+        @JvmStatic
+        fun fromValue(value: String?): PhotoSize =
+            values().firstOrNull { it.value == value } ?: MEDIUM
+    }
+}
+
+enum class ButtonPhotoSize(val value: String) {
+    SMALL("small"),
+    MEDIUM("medium"),
+    LARGE("large");
+
+    companion object {
+        @JvmStatic
+        fun fromValue(value: String?): ButtonPhotoSize =
+            values().firstOrNull { it.value == value } ?: MEDIUM
+    }
+}
+
+enum class PhotoCompression(val value: String) {
+    NONE("none"),
+    MEDIUM("medium"),
+    HEAVY("heavy");
+
+    companion object {
+        @JvmStatic
+        fun fromValue(value: String?): PhotoCompression =
+            values().firstOrNull { it.value == value } ?: NONE
+    }
+}
+
+data class ButtonPhotoSettings(
+    val size: ButtonPhotoSize,
+)
+
+data class ButtonVideoRecordingSettings(
+    val width: Int,
+    val height: Int,
+    val frameRate: Int,
+)
+
+enum class CameraFov(val fov: Int, val roiPosition: Int) {
+    STANDARD(118, 0),
+    WIDE(118, 0),
+}
+
+data class PhotoRequest @JvmOverloads constructor(
+    val requestId: String,
+    val appId: String,
+    val size: PhotoSize,
+    val webhookUrl: String,
+    val authToken: String? = null,
+    val compress: PhotoCompression = PhotoCompression.MEDIUM,
+    val sound: Boolean = true,
+)
+
+enum class RgbLedAction(val value: String) {
+    ON("on"),
+    OFF("off");
+
+    companion object {
+        @JvmStatic
+        fun fromValue(value: String?): RgbLedAction =
+            values().firstOrNull { it.value == value } ?: OFF
+    }
+}
+
+enum class RgbLedColor(val value: String) {
+    RED("red"),
+    GREEN("green"),
+    BLUE("blue"),
+    ORANGE("orange"),
+    WHITE("white");
+
+    companion object {
+        @JvmStatic
+        fun fromValue(value: String?): RgbLedColor? =
+            values().firstOrNull { it.value == value }
+    }
+}
+
+data class RgbLedRequest @JvmOverloads constructor(
+    val requestId: String,
+    val packageName: String?,
+    val action: RgbLedAction,
+    val color: RgbLedColor?,
+    val onDurationMs: Int,
+    val offDurationMs: Int,
+    val count: Int,
+)
+
+data class VideoRecordingRequest(
+    val requestId: String,
+    val save: Boolean,
+    val sound: Boolean,
+)
+
+data class GalleryStatusEvent(
+    val values: Map<String, Any>,
+)
+
+sealed interface PhotoResponse {
+    val state: String
+    val requestId: String
+    val timestamp: Long
+
+    fun toMap(): Map<String, Any> =
+        when (this) {
+            is Success -> mapOf(
+                "state" to state,
+                "requestId" to requestId,
+                "uploadUrl" to uploadUrl,
+                "timestamp" to timestamp,
+            )
+
+            is Error -> mutableMapOf<String, Any>(
+                "state" to state,
+                "requestId" to requestId,
+                "timestamp" to timestamp,
+                "errorMessage" to errorMessage,
+            ).apply {
+                if (!errorCode.isNullOrBlank()) {
+                    this["errorCode"] = errorCode
+                }
+            }
+        }
+
+    fun toEventMap(): Map<String, Any> = toMap() + mapOf("type" to "photo_response")
+
+    data class Success(
+        override val requestId: String,
+        val uploadUrl: String,
+        override val timestamp: Long,
+    ) : PhotoResponse {
+        override val state: String = "success"
+    }
+
+    data class Error(
+        override val requestId: String,
+        val errorCode: String?,
+        val errorMessage: String,
+        override val timestamp: Long,
+    ) : PhotoResponse {
+        override val state: String = "error"
+    }
+
+    companion object {
+        fun fromMap(values: Map<String, Any>): PhotoResponse {
+            val requestId = stringValue(values, "requestId").orEmpty()
+            val timestamp = longValue(values, "timestamp") ?: System.currentTimeMillis()
+            val state = stringValue(values, "state")?.lowercase()
+            return if (state == "success") {
+                val uploadUrl = stringValue(values, "uploadUrl").orEmpty()
+                Success(requestId = requestId, uploadUrl = uploadUrl, timestamp = timestamp)
+            } else {
+                Error(
+                    requestId = requestId,
+                    errorCode = stringValue(values, "errorCode"),
+                    errorMessage = stringValue(values, "errorMessage") ?: "Unknown photo error",
+                    timestamp = timestamp,
+                )
+            }
+        }
+    }
+}
+
+data class PhotoResponseEvent(
+    val response: PhotoResponse,
+) {
+    constructor(values: Map<String, Any>) : this(PhotoResponse.fromMap(values))
+
+    val requestId: String get() = response.requestId
+    val values: Map<String, Any> get() = response.toEventMap()
+}

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

@@ -0,0 +1,78 @@
+package com.mentra.bluetoothsdk
+
+import com.mentra.bluetoothsdk.utils.ConnTypes
+import java.util.concurrent.atomic.AtomicBoolean
+
+enum class GlassesConnectionState(val value: String) {
+    DISCONNECTED(ConnTypes.DISCONNECTED),
+    SCANNING(ConnTypes.SCANNING),
+    CONNECTING(ConnTypes.CONNECTING),
+    BONDING(ConnTypes.BONDING),
+    CONNECTED(ConnTypes.CONNECTED);
+
+    val isConnected: Boolean
+        get() = this == CONNECTED
+
+    val isBusy: Boolean
+        get() = this == SCANNING || this == CONNECTING || this == BONDING
+
+    internal fun toStatusMap(
+        connected: Boolean,
+        fullyBooted: Boolean,
+    ): Map<String, Any> =
+        when {
+            this == CONNECTED || connected || fullyBooted ->
+                mapOf("state" to "connected", "fullyBooted" to fullyBooted)
+            this == SCANNING -> mapOf("state" to "scanning")
+            this == CONNECTING -> mapOf("state" to "connecting")
+            this == BONDING -> mapOf("state" to "bonding")
+            else -> mapOf("state" to "disconnected")
+        }
+
+    companion object {
+        @JvmStatic
+        fun fromValue(value: String?): GlassesConnectionState =
+            optionalFromValue(value) ?: DISCONNECTED
+
+        internal fun optionalFromValue(value: String?): GlassesConnectionState? {
+            val normalized = value?.trim()?.takeIf { it.isNotEmpty() } ?: return null
+            return values().firstOrNull { it.value.equals(normalized, ignoreCase = true) }
+        }
+    }
+}
+
+data class BluetoothError(
+    val code: String,
+    val message: String,
+    val cause: Throwable? = null,
+)
+
+enum class ScanStopReason {
+    COMPLETED,
+    CANCELLED,
+    ERROR,
+}
+
+interface ScanCallback {
+    fun onResults(devices: List<Device>) {}
+    fun onComplete(devices: List<Device>) {}
+    fun onError(error: BluetoothError) {}
+}
+
+abstract class MentraBluetoothScanCallback : ScanCallback
+
+class ScanSession internal constructor(
+    private val stopAction: () -> Unit,
+) {
+    private val stopped = AtomicBoolean(false)
+
+    fun stop() {
+        if (stopped.compareAndSet(false, true)) {
+            stopAction()
+        }
+    }
+
+    internal fun markStopped() {
+        stopped.set(true)
+    }
+}