@mentra/bluetooth-sdk 0.1.2 → 0.1.4

package/README.md

@@ -5,6 +5,8 @@ React Native and Expo SDK for connecting mobile apps directly to supported Mentr
 The package includes:
 
 - A React Native / Expo module API exposed as `BluetoothSdk`.
+- React hooks under `@mentra/bluetooth-sdk/react` for common scan,
+  connection, status, and event lifecycles.
 - Native Android code published as `com.mentra:bluetooth-sdk`.
 - Native iOS code published as the `MentraBluetoothSDK` CocoaPod.
 - An Expo config plugin that wires the native dependencies into generated Android and iOS projects.
@@ -23,8 +25,8 @@ Use a development build or production native build. Expo Go cannot load this pac
 ## Install
 
 ```sh
-npm install @mentra/bluetooth-sdk
-npx expo install expo-build-properties
+bun add @mentra/bluetooth-sdk
+bunx expo install expo-build-properties
 ```
 
 For Expo apps, add the plugin to `app.json` or `app.config.ts`:
@@ -62,10 +64,10 @@ For Expo apps, add the plugin to `app.json` or `app.config.ts`:
 Then regenerate native projects and run a development build:
 
 ```sh
-npx expo prebuild
-npx expo run:ios
+bunx expo prebuild
+bunx expo run:ios
 # or
-npx expo run:android
+bunx expo run:android
 ```
 
 ## Permissions
@@ -107,7 +109,7 @@ iOS apps should include usage descriptions:
 
 ## Minimal Usage
 
-`connectFirst()` scans for the first matching glasses and connects to them. It times out after 15 seconds by default. Use `startScan()` plus `onBluetoothStatus()` only when your app needs to present a custom device picker.
+Use `scan()` when your app needs to show a picker. It calls `onResults` every time the discovered list changes, then resolves with the final list after the timeout.
 
 ```ts
 import BluetoothSdk, {
@@ -119,7 +121,19 @@ const removeGlassesListener = BluetoothSdk.onGlassesStatus((status) => {
   console.log('Glasses status changed', status)
 })
 
-await BluetoothSdk.connectFirst(DeviceModels.MentraLive)
+const devices = await BluetoothSdk.scan(DeviceModels.MentraLive, {
+  timeoutMs: 10_000,
+  onResults: (nextDevices) => {
+    console.log('Nearby glasses:', nextDevices)
+  },
+})
+
+const device = devices[0]
+if (!device) {
+  throw new Error('No Mentra Live glasses found')
+}
+
+await BluetoothSdk.connect(device)
 
 const glasses = await BluetoothSdk.getGlassesStatus()
 if (isReadyGlassesConnectionStatus(glasses.connection)) {
@@ -129,6 +143,46 @@ if (isReadyGlassesConnectionStatus(glasses.connection)) {
 removeGlassesListener()
 ```
 
+## React Hooks
+
+React Native apps can import optional lifecycle helpers from the `react`
+subpath. The hooks use the same SDK types and still leave commands such as
+`requestPhoto()`, `startStream()`, and `setMicState()` on the root
+`BluetoothSdk` object.
+
+```tsx
+import {Button, Text, View} from 'react-native'
+import {DeviceModels} from '@mentra/bluetooth-sdk'
+import {useBluetoothEvent, useGlassesConnection} from '@mentra/bluetooth-sdk/react'
+
+export function DeviceScreen() {
+  const glasses = useGlassesConnection({
+    scanModel: DeviceModels.MentraLive,
+    scanTimeoutMs: 10_000,
+  })
+
+  useBluetoothEvent('button_press', (event) => {
+    console.log('Glasses button:', event.buttonId, event.pressType)
+  })
+
+  return (
+    <View>
+      <Text>{glasses.connected ? 'Connected' : 'Disconnected'}</Text>
+      <Button disabled={glasses.busy} title="Scan" onPress={() => glasses.scan.startScan()} />
+      {glasses.scan.devices.map((device) => (
+        <Button key={device.id} title={device.name} onPress={() => glasses.connect(device)} />
+      ))}
+      <Button disabled={!glasses.connected} title="Disconnect" onPress={glasses.disconnect} />
+    </View>
+  )
+}
+```
+
+The hooks do not request Android permissions or choose a persistence package for
+you. Ask for permissions in your app before calling scan/connect actions, and
+pass a `defaultDeviceStorage` adapter to `useGlassesConnection` if you want a
+default device to survive app restarts.
+
 React Native status exposes `GlassesStatus.connection` as a discriminated union:
 
 ```ts
@@ -166,7 +220,6 @@ await saveDeviceToYourAppStorage(null)
 ```ts
 await BluetoothSdk.clearDisplay()
 await BluetoothSdk.showDashboard()
-await BluetoothSdk.setBrightness(60, false)
 await BluetoothSdk.setDashboardPosition(4, 2)
 
 await BluetoothSdk.requestWifiScan()
@@ -195,19 +248,18 @@ await BluetoothSdk.rgbLedControl(
 ## Photo Upload
 
 ```ts
-await BluetoothSdk.photoRequest(
+await BluetoothSdk.requestPhoto(
   `photo-${Date.now()}`,
   'com.example.app',
   'medium',
   'https://api.example.com/mentra/photo',
   'optional-token',
   'medium',
-  false,
   true,
 )
 ```
 
-The webhook should accept multipart form data with a `photo` file and `requestId`. If `authToken` is provided, the uploader adds `Authorization: Bearer <token>`.
+The webhook should accept multipart form data with a `photo` file and `requestId`. If `authToken` is provided, the uploader adds `Authorization: Bearer <token>`. The camera light is always enabled for photo capture.
 
 ## Streaming
 
@@ -229,7 +281,7 @@ await BluetoothSdk.keepStreamAlive({
 await BluetoothSdk.stopStream()
 ```
 
-Use `rtmp://` or `rtmps://` for RTMP, `srt://` for SRT, and `http://` or `https://` for WHIP/WebRTC ingest. Send keep-alives about every 15 seconds while streaming.
+Use `rtmp://` or `rtmps://` for RTMP, `srt://` for SRT, and `http://` or `https://` for WHIP/WebRTC ingest. Send keep-alives about every 15 seconds while streaming. The camera light is always enabled while streaming.
 
 ## Events
 
@@ -245,19 +297,23 @@ const subscriptions = [
 subscriptions.forEach((subscription) => subscription.remove())
 ```
 
-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`, `log`, `send_command_to_ble`, and `receive_command_from_ble`.
+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`.
+
+Only the documented root import is supported for partner apps. Package subpaths or symbols with a leading underscore are private implementation details and can change without notice.
 
 ## Local SDK Development
 
-For normal app development, install the published npm package. For SDK development before a package release, install a local checkout and point Metro/native resolution at the same path:
+For normal app development, install the published JavaScript package. For SDK development before a package release, install a local checkout and point Metro/native resolution at the same path:
 
 ```sh
-npm install --no-save /path/to/MentraOS/mobile/modules/bluetooth-sdk
-MENTRA_BLUETOOTH_SDK_PACKAGE_PATH=/path/to/MentraOS/mobile/modules/bluetooth-sdk npx expo run:ios
+bun add --no-save /path/to/MentraOS/mobile/modules/bluetooth-sdk
+MENTRA_BLUETOOTH_SDK_PACKAGE_PATH=/path/to/MentraOS/mobile/modules/bluetooth-sdk bunx expo run:ios
 ```
 
-Use `npx expo run:android` for Android. Keep local paths in your shell or CI environment, not in committed app config.
+Use `bunx expo run:android` for Android. Keep local paths in your shell or CI environment, not in committed app config.
 
-## Example App
+## Starter Example App
 
-The partner example app lives in `Mentra-Bluetooth-SDK-Partner-Kit/examples/react-native`. It demonstrates scan/connect, display, camera photo upload, RTMP/SRT/WebRTC streaming, Wi-Fi/hotspot, microphone PCM, RGB LED, gallery-button mode, and console event inspection.
+The [Mentra Bluetooth SDK Starter Kit](https://github.com/Mentra-Community/Mentra-Bluetooth-SDK-Starter-Kit) includes starter example apps for Android, iOS, and React Native / Expo. The React Native starter demonstrates scan/connect, display, camera photo upload, RTMP/SRT/WebRTC streaming, Wi-Fi/hotspot, microphone PCM, RGB LED, gallery-button mode, and console event inspection.

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

@@ -40,7 +40,7 @@ class BluetoothSdkModule : Module() {
                                 "compatible_glasses_search_stop",
                                 mapOf(
                                         "type" to "compatible_glasses_search_stop",
-                                        "device_model" to deviceModel,
+                                        "deviceModel" to deviceModel,
                                 )
                         )
                     }
@@ -294,6 +294,8 @@ class BluetoothSdkModule : Module() {
             sdk?.startScan(DeviceModel.fromDeviceType(model))
         }
 
+        AsyncFunction("stopScan") { sdk?.stopScan() }
+
         AsyncFunction("cancelConnectionAttempt") { sdk?.cancelConnectionAttempt() }
 
         AsyncFunction("showDashboard") { sdk?.showDashboard() }
@@ -346,14 +348,13 @@ class BluetoothSdkModule : Module() {
 
         AsyncFunction("queryGalleryStatus") { sdk?.queryGalleryStatus() }
 
-        AsyncFunction("photoRequest") {
+        AsyncFunction("requestPhoto") {
                 requestId: String,
                 appId: String,
                 size: String,
                 webhookUrl: String,
                 authToken: String?,
                 compress: String,
-                flash: Boolean,
                 sound: Boolean ->
             sdk?.requestPhoto(
                     PhotoRequest(
@@ -363,7 +364,6 @@ class BluetoothSdkModule : Module() {
                             webhookUrl = webhookUrl,
                             authToken = authToken,
                             compress = PhotoCompression.fromValue(compress),
-                            flash = flash,
                             sound = sound,
                     )
             )
@@ -387,8 +387,8 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - Video Recording Commands
 
-        AsyncFunction("startVideoRecording") { requestId: String, save: Boolean, flash: Boolean, sound: Boolean ->
-            sdk?.startVideoRecording(VideoRecordingRequest(requestId, save, flash, sound))
+        AsyncFunction("startVideoRecording") { requestId: String, save: Boolean, sound: Boolean ->
+            sdk?.startVideoRecording(VideoRecordingRequest(requestId, save, sound))
         }
 
         AsyncFunction("stopVideoRecording") { requestId: String ->
@@ -449,8 +449,8 @@ class BluetoothSdkModule : Module() {
                 packageName: String?,
                 action: String,
                 color: String?,
-                ontime: Int,
-                offtime: Int,
+                onDurationMs: Int,
+                offDurationMs: Int,
                 count: Int ->
             sdk?.rgbLedControl(
                     RgbLedRequest(
@@ -458,8 +458,8 @@ class BluetoothSdkModule : Module() {
                             packageName = packageName,
                             action = RgbLedAction.fromValue(action),
                             color = RgbLedColor.fromValue(color),
-                            ontime = ontime,
-                            offtime = offtime,
+                            onDurationMs = onDurationMs,
+                            offDurationMs = offDurationMs,
                             count = count,
                     )
             )
@@ -504,9 +504,9 @@ class BluetoothSdkModule : Module() {
 
 private fun Map<String, Any>?.toMentraDevice(): Device? {
     val values = this ?: return null
-    val model = values["model"] as? String ?: values["deviceModel"] as? String ?: return null
-    val name = values["name"] as? String ?: values["deviceName"] as? String ?: return null
-    val address = values["address"] as? String ?: values["deviceAddress"] as? String
+    val model = values["model"] as? String ?: return null
+    val name = values["name"] as? String ?: return null
+    val address = values["address"] as? String
     val rssi = (values["rssi"] as? Number)?.toInt()
     val id = values["id"] as? String
     return Device(

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

@@ -121,7 +121,7 @@ public class Bridge private constructor() {
         @JvmStatic
         fun sendAudioConnected(deviceName: String) {
             val data = HashMap<String, Any>()
-            data["device_name"] = deviceName
+            data["deviceName"] = deviceName
             sendTypedMessage("audio_connected", data as Map<String, Any>)
         }
 
@@ -211,19 +211,41 @@ public class Bridge private constructor() {
                         }
                         rssi?.let { put("rssi", it) }
                     }
-            val allResults = searchResults + newResult
-            val uniqueResults =
-                    allResults
-                            .asReversed()
-                            .distinctBy {
-                                val model = it["model"] ?: it["deviceModel"] ?: deviceModel
-                                val name = it["name"] ?: it["deviceName"] ?: return@distinctBy null
-                                "$model:$name"
-                            }
-                            .asReversed()
+            // Keep the public searchResults array stable as glasses are added or removed.
+            // Duplicate discoveries refresh their existing row; only new glasses append.
+            val uniqueResults = mergeStableSearchResults(searchResults, newResult, deviceModel)
             DeviceStore.set("bluetooth", "searchResults", uniqueResults)
         }
 
+        private fun mergeStableSearchResults(
+                currentResults: List<Map<String, Any>>,
+                newResult: Map<String, Any>,
+                fallbackModel: String
+        ): List<Map<String, Any>> {
+            val newKey = searchResultKey(newResult, fallbackModel) ?: return currentResults
+            val nextResults = currentResults.toMutableList()
+            val existingIndex =
+                    nextResults.indexOfFirst { result ->
+                        searchResultKey(result, fallbackModel) == newKey
+                    }
+            if (existingIndex >= 0) {
+                nextResults[existingIndex] = newResult
+            } else {
+                nextResults += newResult
+            }
+            return nextResults
+        }
+
+        private fun searchResultKey(result: Map<String, Any>, fallbackModel: String): String? {
+            val id = result["id"] as? String
+            if (!id.isNullOrBlank()) {
+                return id
+            }
+            val model = result["model"] as? String ?: fallbackModel
+            val name = result["name"] as? String ?: return null
+            return "$model:$name"
+        }
+
         // MARK: - Hardware Events
 
         /** Send button press event to React Native - matches iOS implementation */
@@ -255,8 +277,9 @@ public class Bridge private constructor() {
                 source: Int? = null
         ) {
             val body = HashMap<String, Any>()
-            body["device_model"] = deviceModel
-            body["gesture_name"] = gestureName
+            body["type"] = "touch_event"
+            body["deviceModel"] = deviceModel
+            body["gestureName"] = gestureName
             body["timestamp"] = timestamp
             if (source != null) {
                 body["source"] = source
@@ -277,8 +300,8 @@ public class Bridge private constructor() {
         @JvmStatic
         fun sendSwitchStatus(switchType: Int, value: Int, timestamp: Long) {
             val body = HashMap<String, Any>()
-            body["switch_type"] = switchType
-            body["switch_value"] = value
+            body["switchType"] = switchType
+            body["switchValue"] = value
             body["timestamp"] = timestamp
             sendTypedMessage("switch_status", body)
         }
@@ -301,6 +324,7 @@ public class Bridge private constructor() {
             if (requestId.isEmpty()) return
             try {
                 val body = HashMap<String, Any>()
+                body["type"] = "rgb_led_control_response"
                 body["requestId"] = requestId
                 body["state"] = if (success) "success" else "error"
                 if (!success) {
@@ -405,8 +429,8 @@ public class Bridge private constructor() {
             galleryData["photos"] = photoCount
             galleryData["videos"] = videoCount
             galleryData["total"] = totalCount
-            galleryData["total_size"] = totalSize
-            galleryData["has_content"] = hasContent
+            galleryData["totalSize"] = totalSize
+            galleryData["hasContent"] = hasContent
 
             sendTypedMessage("gallery_status", galleryData as Map<String, Any>)
         }
@@ -427,7 +451,7 @@ public class Bridge private constructor() {
         @JvmStatic
         fun sendHotspotError(errorMessage: String, timestamp: Long) {
             val eventBody = HashMap<String, Any>()
-            eventBody["error_message"] = errorMessage
+            eventBody["errorMessage"] = errorMessage
             eventBody["timestamp"] = timestamp
 
             sendTypedMessage("hotspot_error", eventBody as Map<String, Any>)

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

@@ -169,17 +169,17 @@ class DeviceManager {
         set(value) = DeviceStore.apply("bluetooth", "dashboard_depth", value)
 
     private var galleryMode: Boolean
-        get() = DeviceStore.store.get("bluetooth", "gallery_mode") as? Boolean ?: true
-        set(value) = DeviceStore.apply("bluetooth", "gallery_mode", value)
+        get() = DeviceStore.store.get("bluetooth", "galleryModeAuto") as? Boolean ?: true
+        set(value) = DeviceStore.apply("bluetooth", "galleryModeAuto", value)
 
     // state:
     private var searching: Boolean
         get() = DeviceStore.store.get("bluetooth", "searching") as? Boolean ?: false
         set(value) = DeviceStore.apply("bluetooth", "searching", value)
 
-    private var glassesBtcConnected: Boolean
-        get() = DeviceStore.store.get("glasses", "btcConnected") as? Boolean ?: false
-        set(value) = DeviceStore.apply("glasses", "btcConnected", value)
+    private var glassesBluetoothClassicConnected: Boolean
+        get() = DeviceStore.store.get("glasses", "bluetoothClassicConnected") as? Boolean ?: false
+        set(value) = DeviceStore.apply("glasses", "bluetoothClassicConnected", value)
 
     public var micRanking: MutableList<String>
         get() =
@@ -727,8 +727,8 @@ class DeviceManager {
 
             for (micMode in micRanking) {
                 if (micMode == MicTypes.PHONE_INTERNAL ||
-                                micMode == MicTypes.BT_CLASSIC ||
-                                micMode == MicTypes.BT
+                                micMode == MicTypes.BLUETOOTH_CLASSIC ||
+                                micMode == MicTypes.BLUETOOTH
                 ) {
 
                     if (phoneMic?.isRecordingWithMode(micMode) == true) {
@@ -790,8 +790,8 @@ class DeviceManager {
             }
 
             if (micMode == MicTypes.PHONE_INTERNAL ||
-                            micMode == MicTypes.BT_CLASSIC ||
-                            micMode == MicTypes.BT
+                            micMode == MicTypes.BLUETOOTH_CLASSIC ||
+                            micMode == MicTypes.BLUETOOTH
             ) {
                 phoneMic?.stopMode(micMode)
             }
@@ -1221,6 +1221,7 @@ class DeviceManager {
 
     fun startStream(message: MutableMap<String, Any>) {
         Bridge.log("MAN: startStream")
+        message["flash"] = true
         sgc?.startStream(message)
     }
 
@@ -1352,11 +1353,11 @@ class DeviceManager {
         sgc?.sendReboot()
     }
 
-    fun startVideoRecording(requestId: String, save: Boolean, flash: Boolean, sound: Boolean) {
+    fun startVideoRecording(requestId: String, save: Boolean, sound: Boolean) {
         Bridge.log(
-                "MAN: onStartVideoRecording: requestId=$requestId, save=$save, flash=$flash, sound=$sound"
+                "MAN: onStartVideoRecording: requestId=$requestId, save=$save, flash=true, sound=$sound"
         )
-        sgc?.startVideoRecording(requestId, save, flash, sound)
+        sgc?.startVideoRecording(requestId, save, true, sound)
     }
 
     fun stopVideoRecording(requestId: String) {
@@ -1372,20 +1373,17 @@ class DeviceManager {
         updateMicState()
     }
 
-    fun photoRequest(
+    fun requestPhoto(
             requestId: String,
             appId: String,
             size: String,
             webhookUrl: String,
             authToken: String?,
             compress: String,
-            flash: Boolean,
             sound: Boolean
     ) {
-        Bridge.log(
-                "MAN: onPhotoRequest: $requestId, $appId, $size, compress=$compress, flash=$flash, sound=$sound"
-        )
-        sgc?.requestPhoto(requestId, appId, size, webhookUrl, authToken, compress, flash, sound)
+        Bridge.log("MAN: requestPhoto: $requestId, $appId, $size, compress=$compress, flash=true, sound=$sound")
+        sgc?.requestPhoto(requestId, appId, size, webhookUrl, authToken, compress, true, sound)
     }
 
     fun rgbLedControl(
@@ -1393,12 +1391,12 @@ class DeviceManager {
             packageName: String?,
             action: String,
             color: String?,
-            ontime: Int,
-            offtime: Int,
+            onDurationMs: Int,
+            offDurationMs: Int,
             count: Int
     ) {
         Bridge.log("MAN: RGB LED control: action=$action, color=$color, requestId=$requestId")
-        sgc?.sendRgbLedControl(requestId, packageName, action, color, ontime, offtime, count)
+        sgc?.sendRgbLedControl(requestId, packageName, action, color, onDurationMs, offDurationMs, count)
     }
 
     fun connectDefault() {

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

@@ -66,7 +66,7 @@ object DeviceStore {
         store.set("glasses", "deviceModel", "")
         store.set("glasses", "firmwareVersion", "")
         store.set("glasses", "micEnabled", false)
-        store.set("glasses", "btcConnected", false)
+        store.set("glasses", "bluetoothClassicConnected", false)
         store.set("glasses", "caseRemoved", true)
         store.set("glasses", "caseOpen", true)
         store.set("glasses", "caseCharging", false)
@@ -121,12 +121,12 @@ object DeviceStore {
         store.set("bluetooth", "dashboard_depth", 2)
         store.set("bluetooth", "head_up_angle", 30)
         store.set("bluetooth", "contextual_dashboard", true)
-        store.set("bluetooth", "gallery_mode", true)
+        store.set("bluetooth", "galleryModeAuto", true)
         store.set("bluetooth", "screen_disabled", false)
         store.set("bluetooth", "button_photo_size", "medium")
         store.set("bluetooth", "button_camera_led", true)
         store.set("bluetooth", "button_max_recording_time", 10)
-        store.set("bluetooth", "camera_fov", mapOf("fov" to 118, "roi_position" to 0))
+        store.set("bluetooth", "camera_fov", mapOf("fov" to 118, "roiPosition" to 0))
         store.set("bluetooth", "button_video_width", 1280)
         store.set("bluetooth", "button_video_height", 720)
         store.set("bluetooth", "button_video_fps", 30)
@@ -239,7 +239,7 @@ object DeviceStore {
                     DeviceManager.getInstance().sgc?.setDashboardMenu(items)
                 }
             }
-            "bluetooth" to "gallery_mode" -> {
+            "bluetooth" to "galleryModeAuto" -> {
                 DeviceManager.getInstance().sgc?.sendGalleryMode()
             }
             "bluetooth" to "screen_disabled" -> {