@mentra/bluetooth-sdk 3.2.0-dev.180 → 3.2.0-dev.181

package/README.md

@@ -125,6 +125,7 @@ const devices = await BluetoothSdk.scan(DeviceModels.MentraLive, {
   onResults: (nextDevices) => {
     console.log('Nearby glasses:', nextDevices)
   },
+  onDiagnostic: (hint) => showScanHint(hint.message),
 })
 
 const device = await chooseDevice(devices)
@@ -137,6 +138,12 @@ const versionInfo = await BluetoothSdk.requestVersionInfo()
 console.log(versionInfo.buildNumber)
 ```
 
+`onDiagnostic` optionally reports a matching phone connection after an empty scan
+on Android and iOS. It is advisory, does not identify another app, and leaves
+normal empty completion unchanged. React hooks expose it as `scan.diagnostic`
+on `useMentraBluetooth()`, or `diagnostic` on `useBluetoothScan()`. Clear the hint
+when retrying or connecting.
+
 In multi-device environments, present an explicit picker instead of
 auto-connecting to the first nearby device.
 

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

@@ -541,6 +541,12 @@ class BluetoothSdkModule : Module() {
             sdk?.startScan(DeviceModel.fromDeviceType(model))
         }
 
+        SdkAsyncFunction("getScanDiagnostic") { model: String ->
+            sdk?.connectedDeviceScanDiagnostic(DeviceModel.fromDeviceType(model))?.let {
+                mapOf("code" to it.code, "message" to it.message)
+            }
+        }
+
         SdkAsyncFunction("stopScan") { -> sdk?.stopScan() }
 
         SdkAsyncFunction("cancelConnectionAttempt") { -> sdk?.cancelConnectionAttempt() }

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

@@ -0,0 +1,69 @@
+package com.mentra.bluetoothsdk
+
+/**
+ * Pure matcher deciding whether a GATT-connected peripheral (as enumerated by
+ * `BluetoothManager.getConnectedDevices`) is plausibly the glasses a scan for a
+ * given [DeviceModel] was looking for. This is a name/address heuristic, not
+ * proof of device identity or connection ownership.
+ *
+ * Kept free of Android framework types so the logic is unit-testable on the
+ * JVM (see `ConnectedDeviceMatcherTest`).
+ */
+internal object ConnectedDeviceMatcher {
+
+    /**
+     * True when the candidate peripheral either matches the saved default
+     * device for the scanned [model] (by address ignoring case when both
+     * addresses exist, otherwise by a nonblank exact name) or carries a
+     * known advertised-name prefix for that model.
+     *
+     * [defaultDevice] only counts when its model equals the scanned [model];
+     * a saved Mentra Live cannot explain an empty Nex scan. [DeviceModel.SIMULATED]
+     * never matches anything.
+     */
+    fun matches(
+        model: DeviceModel,
+        defaultDevice: Device?,
+        candidateName: String?,
+        candidateAddress: String?,
+    ): Boolean {
+        if (model == DeviceModel.SIMULATED) return false
+        val matchesDefault = if (defaultDevice?.model == model) {
+            val savedAddress = defaultDevice.address?.takeIf { it.isNotBlank() }
+            val address = candidateAddress?.takeIf { it.isNotBlank() }
+            if (savedAddress != null && address != null) {
+                address.equals(savedAddress, ignoreCase = true)
+            } else {
+                !candidateName.isNullOrBlank() && candidateName == defaultDevice.name
+            }
+        } else {
+            false
+        }
+        return matchesDefault || (candidateName != null && matchesModelNamePrefix(model, candidateName))
+    }
+
+    /**
+     * Per-model advertised/bonded-name filters, mirroring the scan filters the
+     * SGCs apply: MentraLive.kt (`Xy_A`, `XyBLE_`, `MENTRA_LIVE_BLE`,
+     * `MENTRA_LIVE_BT`, lowercase `mentra_live`) and MentraNex.kt (`Nex1-`,
+     * `MENTRA_DISPLAY_`). Models without a Mentra-branded advertised name
+     * (G1, G2, Nimo, Ar99, ...) have no prefix entry here and are detected
+     * only through the saved-default match above.
+     */
+    private fun matchesModelNamePrefix(
+        model: DeviceModel,
+        name: String,
+    ): Boolean =
+        when (model) {
+            DeviceModel.MENTRA_LIVE ->
+                name == "Xy_A" ||
+                    name.startsWith("XyBLE_") ||
+                    name.startsWith("MENTRA_LIVE_BLE") ||
+                    name.startsWith("MENTRA_LIVE_BT") ||
+                    name.lowercase().startsWith("mentra_live")
+            DeviceModel.MENTRA_NEX ->
+                name.startsWith("Nex1-") ||
+                    name.startsWith("MENTRA_DISPLAY_")
+            else -> false
+        }
+}

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.2.0"
-    const val RELEASE_IDENTITY: String = "3.2.0-dev.180"
-    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.180"
-    const val SOURCE_COMMIT: String = "1f24e462561fef37b7082204847a541db4a87c41"
-    const val OTA_MANIFEST_URL: String = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.180.json"
-    const val OTA_MANIFEST_SHA256: String = "cbf2a1b81430bd34942e2a1764138f6d79197767b4434a2d8c44311768f8b873"
+    const val RELEASE_IDENTITY: String = "3.2.0-dev.181"
+    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.181"
+    const val SOURCE_COMMIT: String = "89a4792321ce95bd16aadd721bc3dbc20e338861"
+    const val OTA_MANIFEST_URL: String = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.181.json"
+    const val OTA_MANIFEST_SHA256: String = "d9a100cc81733d02848a86c7617eff154f4cd9d714d1d36407789aeebbf71251"
 }

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

@@ -3,6 +3,7 @@ package com.mentra.bluetoothsdk
 import android.app.Activity
 import android.app.Application
 import android.bluetooth.BluetoothManager
+import android.bluetooth.BluetoothProfile
 import android.content.Context
 import android.os.Bundle
 import android.os.Handler
@@ -347,6 +348,16 @@ class MentraBluetoothSdk private constructor(
             timeoutMs = timeoutMs,
         )
 
+    /**
+     * Scans for glasses of [model], reporting through [callback].
+     *
+     * A completed or cancelled scan ends with [ScanCallback.onComplete].
+     * [ScanCallback.onError] remains reserved for failure to start scanning.
+     * Callbacks implementing [ScanDiagnosticCallback] may receive a best-effort
+     * hint before an empty completed scan. Android reports phone-wide connection
+     * state, so this hint cannot identify an owning app or prove why scanning
+     * found no devices. React Native's separate scan implementation is unaffected.
+     */
     @JvmOverloads
     fun scan(
         model: DeviceModel,
@@ -378,7 +389,9 @@ class MentraBluetoothSdk private constructor(
             mainHandler.removeCallbacks(timeoutRunnable)
             session.markStopped()
             stopScan(reason)
-            callback.onComplete(latestResults.toList())
+            callback.completeScan(reason, latestResults.toList()) {
+                connectedDeviceScanDiagnostic(model)
+            }
         }
 
         timeoutRunnable = Runnable { finish(ScanStopReason.COMPLETED) }
@@ -1494,6 +1507,49 @@ class MentraBluetoothSdk private constructor(
         )
     }
 
+    /**
+     * A model-compatible device already connected to this phone can explain an
+     * empty scan, but Android does not expose app ownership or exclusive use.
+     * Skip known SDK connections/attempts and unavailable Bluetooth permissions.
+     */
+    internal fun connectedDeviceScanDiagnostic(model: DeviceModel): ScanDiagnostic? {
+        if (model == DeviceModel.SIMULATED) return null
+        val glassesStatus = getRawGlassesStatus()
+        if (glassesStatus.connected ||
+            glassesStatus.connectionState == GlassesConnectionState.CONNECTED ||
+            glassesStatus.connectionState == GlassesConnectionState.CONNECTING ||
+            glassesStatus.connectionState == GlassesConnectionState.BONDING
+        ) {
+            return null
+        }
+        return try {
+            val bluetoothManager =
+                appContext.getSystemService(Context.BLUETOOTH_SERVICE) as? BluetoothManager ?: return null
+            val adapter = bluetoothManager.adapter ?: return null
+            if (!adapter.isEnabled) return null
+            val defaultDevice = currentDefaultDevice()
+            val device = bluetoothManager.getConnectedDevices(BluetoothProfile.GATT)
+                .firstOrNull { device ->
+                    ConnectedDeviceMatcher.matches(
+                        model = model,
+                        defaultDevice = defaultDevice,
+                        candidateName = device.name,
+                        candidateAddress = device.address,
+                    )
+                } ?: return null
+            val name = device.name?.takeIf { it.isNotBlank() } ?: device.address
+            ScanDiagnostic(
+                code = "device_connected_on_phone",
+                message =
+                    "Scan found no glasses, but a matching device \"$name\" is already connected to this phone. " +
+                        "If another app is using it, disconnect it there and scan again.",
+            )
+        } catch (error: SecurityException) {
+            // BLUETOOTH_CONNECT can be absent or revoked while scanning.
+            null
+        }
+    }
+
     private fun requireBluetoothReady(operation: String) {
         val bluetoothManager = appContext.getSystemService(Context.BLUETOOTH_SERVICE) as? BluetoothManager
         val adapter =

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

@@ -53,13 +53,50 @@ enum class ScanStopReason {
     ERROR,
 }
 
+/**
+ * Callbacks for `MentraBluetoothSdk.scan`.
+ *
+ * Completed and cancelled scans report [onComplete]. A failure to start reports
+ * [onError] and is thrown to the caller. Optional empty-scan hints are delivered
+ * separately through [ScanDiagnosticCallback], never as errors.
+ */
 interface ScanCallback {
     fun onResults(devices: List<Device>) {}
     fun onComplete(devices: List<Device>) {}
     fun onError(error: BluetoothError) {}
 }
 
-abstract class MentraBluetoothScanCallback : ScanCallback
+/** A non-fatal scan hint; it does not establish the cause of an empty result. */
+data class ScanDiagnostic(val code: String, val message: String)
+
+/**
+ * Optional scan diagnostics, delivered before [onComplete] for an empty completed
+ * scan. Kept separate so existing compiled [ScanCallback] implementations do not
+ * need a new method. Android's `device_connected_on_phone` hint identifies a
+ * model-compatible GATT connection on this phone, not which app owns it.
+ */
+interface ScanDiagnosticCallback : ScanCallback {
+    fun onDiagnostic(diagnostic: ScanDiagnostic)
+}
+
+abstract class MentraBluetoothScanCallback : ScanDiagnosticCallback {
+    override fun onDiagnostic(diagnostic: ScanDiagnostic) {}
+}
+
+/** Complete once, with an optional advisory that never replaces completion. */
+internal fun ScanCallback.completeScan(
+    reason: ScanStopReason,
+    devices: List<Device>,
+    diagnostic: () -> ScanDiagnostic?,
+) {
+    try {
+        if (this is ScanDiagnosticCallback && reason == ScanStopReason.COMPLETED && devices.isEmpty()) {
+            diagnostic()?.let { onDiagnostic(it) }
+        }
+    } finally {
+        onComplete(devices)
+    }
+}
 
 class ScanSession internal constructor(
     private val stopAction: () -> Unit,

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

@@ -0,0 +1,161 @@
+package com.mentra.bluetoothsdk
+
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.Test
+
+class ConnectedDeviceMatcherTest {
+    private val savedLive =
+        Device(
+            model = DeviceModel.MENTRA_LIVE,
+            name = "Mentra Live 4X2A",
+            address = "AA:BB:CC:DD:EE:FF",
+        )
+
+    @Test
+    fun `matches Mentra Live advertised name prefixes`() {
+        for (name in listOf("Xy_A", "XyBLE_1234", "MENTRA_LIVE_BLE_9", "MENTRA_LIVE_BT_9", "mentra_live_abc")) {
+            assertThat(
+                ConnectedDeviceMatcher.matches(
+                    model = DeviceModel.MENTRA_LIVE,
+                    defaultDevice = null,
+                    candidateName = name,
+                    candidateAddress = null,
+                ),
+            ).describedAs(name).isTrue()
+        }
+    }
+
+    @Test
+    fun `matches Mentra Nex advertised name prefixes`() {
+        for (name in listOf("Nex1-77", "MENTRA_DISPLAY_02")) {
+            assertThat(
+                ConnectedDeviceMatcher.matches(
+                    model = DeviceModel.MENTRA_NEX,
+                    defaultDevice = null,
+                    candidateName = name,
+                    candidateAddress = null,
+                ),
+            ).describedAs(name).isTrue()
+        }
+    }
+
+    @Test
+    fun `name prefixes are scoped to the scanned model`() {
+        // A held Mentra Live can never explain an empty Nex (or G1) scan.
+        assertThat(
+            ConnectedDeviceMatcher.matches(
+                model = DeviceModel.MENTRA_NEX,
+                defaultDevice = null,
+                candidateName = "XyBLE_1234",
+                candidateAddress = null,
+            ),
+        ).isFalse()
+        assertThat(
+            ConnectedDeviceMatcher.matches(
+                model = DeviceModel.G1,
+                defaultDevice = null,
+                candidateName = "MENTRA_LIVE_BT_9",
+                candidateAddress = null,
+            ),
+        ).isFalse()
+    }
+
+    @Test
+    fun `rejects non-Mentra peripherals`() {
+        for (name in listOf("Even G1_22_L_", "Pixel Watch", "MX Master 3S")) {
+            assertThat(
+                ConnectedDeviceMatcher.matches(
+                    model = DeviceModel.MENTRA_LIVE,
+                    defaultDevice = savedLive,
+                    candidateName = name,
+                    candidateAddress = "11:22:33:44:55:66",
+                ),
+            ).describedAs(name).isFalse()
+        }
+    }
+
+    @Test
+    fun `matches the saved default by exact name`() {
+        assertThat(
+            ConnectedDeviceMatcher.matches(
+                model = DeviceModel.MENTRA_LIVE,
+                defaultDevice = savedLive,
+                candidateName = "Mentra Live 4X2A",
+                candidateAddress = null,
+            ),
+        ).isTrue()
+    }
+
+    @Test
+    fun `matches the saved default by address ignoring case`() {
+        // Stored addresses can arrive lowercase from the JS side.
+        assertThat(
+            ConnectedDeviceMatcher.matches(
+                model = DeviceModel.MENTRA_LIVE,
+                defaultDevice = savedLive.copy(address = "aa:bb:cc:dd:ee:ff"),
+                candidateName = null,
+                candidateAddress = "AA:BB:CC:DD:EE:FF",
+            ),
+        ).isTrue()
+    }
+
+    @Test
+    fun `saved default only counts for its own model`() {
+        // Scanning for G1 while the saved default is a Mentra Live.
+        assertThat(
+            ConnectedDeviceMatcher.matches(
+                model = DeviceModel.G1,
+                defaultDevice = savedLive,
+                candidateName = "Mentra Live 4X2A",
+                candidateAddress = "AA:BB:CC:DD:EE:FF",
+            ),
+        ).isFalse()
+    }
+
+    @Test
+    fun `models without a branded name rely on the saved default`() {
+        val savedG1 = Device(model = DeviceModel.G1, name = "Even G1_22_L_", address = null)
+        assertThat(
+            ConnectedDeviceMatcher.matches(
+                model = DeviceModel.G1,
+                defaultDevice = savedG1,
+                candidateName = "Even G1_22_L_",
+                candidateAddress = null,
+            ),
+        ).isTrue()
+    }
+
+    @Test
+    fun `simulated model never matches`() {
+        assertThat(
+            ConnectedDeviceMatcher.matches(
+                model = DeviceModel.SIMULATED,
+                defaultDevice = savedLive,
+                candidateName = "Mentra Live 4X2A",
+                candidateAddress = "AA:BB:CC:DD:EE:FF",
+            ),
+        ).isFalse()
+    }
+    @Test
+    fun `blank saved identities never identify an unrelated connection`() {
+        val saved = Device(DeviceModel.G1, name = "", address = "")
+        assertThat(ConnectedDeviceMatcher.matches(DeviceModel.G1, saved, "", "")).isFalse()
+        assertThat(ConnectedDeviceMatcher.matches(DeviceModel.G1, saved, null, null)).isFalse()
+    }
+
+    @Test
+    fun `different known addresses override a matching saved name`() {
+        val saved = Device(DeviceModel.G1, name = "Even G1", address = "AA:BB:CC:DD:EE:FF")
+        assertThat(
+            ConnectedDeviceMatcher.matches(DeviceModel.G1, saved, "Even G1", "11:22:33:44:55:66"),
+        ).isFalse()
+    }
+
+    @Test
+    fun `a branded candidate can still match its model without being the saved device`() {
+        assertThat(
+            ConnectedDeviceMatcher.matches(DeviceModel.MENTRA_LIVE, savedLive, "XyBLE_5678", "11:22:33:44:55:66"),
+        ).isTrue()
+    }
+
+}

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

@@ -0,0 +1,87 @@
+package com.mentra.bluetoothsdk
+
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.Test
+
+class ScanCompletionTest {
+    private val hint = ScanDiagnostic("device_connected_on_phone", "A matching device is connected to this phone.")
+
+    @Test
+    fun `empty completed scan delivers diagnostic then completion without error`() {
+        val events = mutableListOf<String>()
+        val callback = object : MentraBluetoothScanCallback() {
+            override fun onDiagnostic(diagnostic: ScanDiagnostic) {
+                assertThat(diagnostic).isEqualTo(hint)
+                events.add("diagnostic")
+            }
+            override fun onComplete(devices: List<Device>) {
+                assertThat(devices).isEmpty()
+                events.add("complete")
+            }
+            override fun onError(error: BluetoothError) {
+                events.add("error")
+            }
+        }
+        callback.completeScan(ScanStopReason.COMPLETED, emptyList()) { hint }
+        assertThat(events).containsExactly("diagnostic", "complete")
+    }
+
+    @Test
+    fun `legacy callbacks complete without querying diagnostics`() {
+        var completed = false
+        // Implement only the pre-existing interface; it gains no abstract method.
+        val callback = object : ScanCallback {
+            override fun onComplete(devices: List<Device>) { completed = true }
+        }
+        callback.completeScan(ScanStopReason.COMPLETED, emptyList()) {
+            error("Legacy callbacks must not query diagnostics")
+        }
+        assertThat(completed).isTrue()
+        assertThat(ScanCallback::class.java.declaredMethods.map { it.name })
+            .containsExactlyInAnyOrder("onResults", "onComplete", "onError")
+    }
+
+    @Test
+    fun `cancelled scans and nonempty scans never query diagnostics`() {
+        val device = Device(DeviceModel.MENTRA_LIVE, "XyBLE_1234")
+        val completed = mutableListOf<List<Device>>()
+        val callback = object : MentraBluetoothScanCallback() {
+            override fun onComplete(devices: List<Device>) { completed.add(devices) }
+            override fun onDiagnostic(diagnostic: ScanDiagnostic) { error("Unexpected diagnostic") }
+        }
+        for ((reason, devices) in listOf(
+            ScanStopReason.CANCELLED to emptyList(),
+            ScanStopReason.COMPLETED to listOf(device),
+        )) {
+            callback.completeScan(reason, devices) { error("Unexpected diagnostic query") }
+        }
+        assertThat(completed).containsExactly(emptyList(), listOf(device))
+    }
+
+    @Test
+    fun `missing diagnostic leaves an ordinary empty completion`() {
+        val events = mutableListOf<String>()
+        val callback = object : MentraBluetoothScanCallback() {
+            override fun onComplete(devices: List<Device>) { events.add("complete") }
+            override fun onDiagnostic(diagnostic: ScanDiagnostic) { events.add("diagnostic") }
+            override fun onError(error: BluetoothError) { events.add("error") }
+        }
+        callback.completeScan(ScanStopReason.COMPLETED, emptyList()) { null }
+        assertThat(events).containsExactly("complete")
+    }
+
+    @Test
+    fun `completion still runs if the diagnostic handler throws`() {
+        var completed = false
+        val failure = IllegalStateException("consumer diagnostic handler failed")
+        val callback = object : MentraBluetoothScanCallback() {
+            override fun onComplete(devices: List<Device>) { completed = true }
+            override fun onDiagnostic(diagnostic: ScanDiagnostic) { throw failure }
+        }
+        val thrown = runCatching {
+            callback.completeScan(ScanStopReason.COMPLETED, emptyList()) { hint }
+        }.exceptionOrNull()
+        assertThat(thrown).isSameAs(failure)
+        assertThat(completed).isTrue()
+    }
+}

package/build/BluetoothSdk.types.d.ts

@@ -1178,6 +1178,11 @@ export interface ConnectOptions {
     cancelExistingConnectionAttempt?: boolean;
 }
 export type ScanResultsCallback = (devices: Device[]) => void;
+/** Advisory for an empty scan. System connection state does not identify an owning app. */
+export interface ScanDiagnostic {
+    code: string;
+    message: string;
+}
 export interface ScanOptions {
     model: DeviceModel;
     /** Defaults to 15000. */
@@ -1186,6 +1191,8 @@ export interface ScanOptions {
     timeout?: number;
     /** Called every time the discovered device list changes during the scan. */
     onResults?: ScanResultsCallback;
+    /** Optional non-fatal hint before an empty scan resolves, on Android and iOS. */
+    onDiagnostic?: (diagnostic: ScanDiagnostic) => void;
 }
 export type ScanModelOptions = Omit<ScanOptions, "model">;
 export interface WifiSearchResult {