@mentra/bluetooth-sdk 3.2.0-dev.195 → 3.2.0-dev.200

package/README.md

@@ -115,6 +115,24 @@ Android apps should request the permissions required by the features they use:
 
 Some Android 12+ devices require Location permission and Location services before BLE scan callbacks are delivered.
 
+### Android Foreground Service Types
+
+The SDK service reads its allowed types from the merged Android manifest.
+The default manifest retains MentraOS's connected-device, microphone, location,
+media-playback and data-sync capabilities. A Bluetooth-only host can override
+`com.mentra.bluetoothsdk.services.ForegroundService` to use `connectedDevice`
+with `tools:replace="android:foregroundServiceType"`, and remove unused typed
+FGS permissions from its final manifest. Startup then uses `connectedDevice`
+instead of `dataSync`; the SDK's `CHANGE_WIFI_STATE` permission satisfies its
+startup prerequisite even before a Bluetooth runtime permission is granted.
+
+Only restrict types when the corresponding background features are unused.
+Receiving the glasses' BLE audio is distinct from selecting Android's phone or
+Bluetooth headset microphone. Hosts using Android microphone capture, location
+tracking or background media playback must retain the corresponding types and
+permissions, including those required by other native modules. At least
+`connectedDevice` or `dataSync` must remain for SDK service startup.
+
 iOS apps should include usage descriptions:
 
 ```json
@@ -422,7 +440,7 @@ await sdk.setDashboardContent("")
 Settings commands that return `SettingsAckSuccessEvent` reject when the ASG reports an error ack. The SDK updates its local settings store only after that ASG ack resolves successfully, so observed SDK state reflects the acknowledged glasses state rather than a queued request. Raw `settings_ack` listener events still use `SettingsAckEvent` because they can include both success and failure statuses. `rgbLedControl(...)` resolves from a successful ASG `rgb_led_control_response` and rejects when the ASG reports `state: "error"`; raw `settings_ack` and `rgb_led_control_response` events remain available through listeners.
 
 WiFi, hotspot, and version-info commands resolve from the ASG response path, not local dispatch:
-`requestWifiScan()` resolves from the ASG `wifi_scan_result` completion response with the updated scan list, including `[]` when no networks are found. Intermediate `wifi_scan_result` events can arrive with `scanComplete: false` while the glasses stream discovered networks; the final event uses `scanComplete: true`. If older glasses stream non-empty scan results but never send the completion event, the request resolves with the accumulated scan list when the request times out. `sendWifiCredentials()` resolves when the requested SSID is connected, `forgetWifiNetwork()` resolves when that SSID is no longer connected, `setHotspotState()` resolves when the requested hotspot state is reported, and `requestVersionInfo()` resolves from the ASG `version_info` response instead of local store changes.
+`requestWifiScan()` resolves from the ASG `wifi_scan_result` completion response with the updated scan list, including `[]` when no networks are found. Intermediate `wifi_scan_result` events can arrive with `scanComplete: false` while the glasses stream discovered networks; the final event uses `scanComplete: true`. If older glasses stream non-empty scan results but never send the completion event, the request resolves with the accumulated scan list when the request times out. `sendWifiCredentials()` resolves when the requested SSID is connected, `forgetWifiNetwork()` resolves when that SSID is no longer connected, and `setHotspotState()` resolves when the requested hotspot state is reported. `requestVersionInfo()` waits for all chunks declared by the correlated response's `chunkCount`, `chunkIndex`, and `final` metadata. Legacy single-message responses complete immediately; legacy chunked responses complete on `version_info_3` after `version_info_1`. Missing final chunks time out rather than returning partial data after a quiet period.
 
 The SDK automatically sends the phone wall clock once shortly after a glasses connection becomes ready. It waits for the initial command burst to drain before timestamping the command so startup queue delay does not become clock skew. The once-per-connection guard resets after disconnect, so every successful reconnect synchronizes again. The SDK does not periodically verify or correct clock skew during a long-lived connection; apps that require periodic reconciliation can compare `requestVersionInfo().systemTimeMs` with the phone clock.
 

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

@@ -476,11 +476,24 @@ public class Bridge private constructor() {
         }
 
         @JvmStatic
-        fun sendVersionInfo(values: Map<String, Any>) {
+        @JvmOverloads
+        fun sendVersionInfo(values: Map<String, Any>, responseChunk: String = "version_info") {
             fun stringField(vararg keys: String): String =
                     keys.firstNotNullOfOrNull { key -> values[key] as? String } ?: ""
             val body = HashMap<String, Any>()
             body["type"] = "version_info"
+            body[VersionInfoResponseAccumulator.RESPONSE_CHUNK_KEY] = responseChunk
+            mapOf(
+                "chunkIndex" to VersionInfoResponseAccumulator.RESPONSE_INDEX_KEY,
+                "chunkCount" to VersionInfoResponseAccumulator.RESPONSE_COUNT_KEY,
+                "final" to VersionInfoResponseAccumulator.RESPONSE_FINAL_KEY,
+                "sid" to VersionInfoResponseAccumulator.RESPONSE_SID_KEY,
+            ).forEach { (wireKey, internalKey) -> values[wireKey]?.let { body[internalKey] = it } }
+            (values["requestId"] as? String ?: values["request_id"] as? String)
+                    ?.takeIf { it.isNotEmpty() }
+                    ?.let {
+                        body[VersionInfoResponseAccumulator.RESPONSE_REQUEST_ID_KEY] = it
+                    }
             body["androidVersion"] = stringField("androidVersion", "android_version")
             body["firmwareVersion"] = stringField("firmwareVersion", "firmware_version")
             body["besFirmwareVersion"] = stringField("besFirmwareVersion", "bes_fw_version")

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

@@ -2016,9 +2016,14 @@ class DeviceManager {
      * Request version info from glasses. Glasses will respond with version_info message containing
      * build number, firmware version, etc.
      */
-    fun requestVersionInfo() {
+    fun requestVersionInfo(requestId: String? = null) {
         Bridge.log("MAN: 📱 Requesting version info from glasses")
-        sgc?.requestVersionInfo()
+        val controller = sgc
+        if (controller is MentraLive) {
+            controller.requestVersionInfo(requestId)
+        } else {
+            controller?.requestVersionInfo()
+        }
     }
 
     /** Send shutdown command to glasses. This will initiate a graceful shutdown of the device. */

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.195"
-    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.195"
-    const val SOURCE_COMMIT: String = "321202ca96ec1852be19a7230ebcc3593fe87e54"
-    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.195.json"
-    const val OTA_MANIFEST_SHA256: String = "70f26063b2c281b9b046965f6f6d7ca22f8b53242c6c5be02030c5a04c7115e4"
+    const val RELEASE_IDENTITY: String = "3.2.0-dev.200"
+    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.200"
+    const val SOURCE_COMMIT: String = "1cdd911f596eba7b2b2f0e9ba5655c7ff16b5362"
+    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.200.json"
+    const val OTA_MANIFEST_SHA256: String = "f0b5cca2fa4d1d43acf5933fb4de629819d36a145a162c763f4faa27a7c8ff79"
 }

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

@@ -71,7 +71,7 @@ class MentraBluetoothSdk private constructor(
     private var pendingWifiScan: PendingWifiScan? = null
     private var pendingWifiStatus: PendingWifiStatusRequest? = null
     private var pendingHotspotStatus: PendingHotspotStatusRequest? = null
-    private var pendingVersionInfo: PendingResponse<VersionInfoResult>? = null
+    private var pendingVersionInfo: PendingVersionInfoRequest? = null
     @Volatile private var configuredOtaVersionUrl: String? = null
 
     init {
@@ -178,6 +178,12 @@ class MentraBluetoothSdk private constructor(
         var uploadSucceeded: Boolean = false,
     )
 
+    private class PendingVersionInfoRequest(
+        val pending: PendingResponse<VersionInfoResult>,
+        val accumulator: VersionInfoResponseAccumulator,
+    ) {
+    }
+
     private data class PendingWifiScan(
         val pending: PendingResponse<List<WifiScanResult>>,
         val scanId: String,
@@ -1195,7 +1201,13 @@ class MentraBluetoothSdk private constructor(
     }
 
     suspend fun requestVersionInfo(): VersionInfoResult {
+        val requestId = UUID.randomUUID().toString()
         val pending = PendingResponse<VersionInfoResult>("version info request")
+        val request =
+            PendingVersionInfoRequest(
+                pending = pending,
+                accumulator = VersionInfoResponseAccumulator(requestId),
+            )
         synchronized(oneShotLock) {
             if (pendingVersionInfo != null) {
                 throw BluetoothSdkException(
@@ -1203,14 +1215,14 @@ class MentraBluetoothSdk private constructor(
                     "A version info request is already waiting for a glasses response.",
                 )
             }
-            pendingVersionInfo = pending
+            pendingVersionInfo = request
         }
         try {
-            deviceManager.requestVersionInfo()
+            deviceManager.requestVersionInfo(requestId)
             return pending.await()
         } finally {
             synchronized(oneShotLock) {
-                if (pendingVersionInfo === pending) {
+                if (pendingVersionInfo === request) {
                     pendingVersionInfo = null
                 }
             }
@@ -1607,6 +1619,22 @@ class MentraBluetoothSdk private constructor(
         }
     }
 
+    private fun handleVersionInfoForRequest(data: Map<String, Any>) {
+        synchronized(oneShotLock) {
+            val request = pendingVersionInfo ?: return
+            when (val outcome = request.accumulator.accept(data)) {
+                VersionInfoAccumulatorOutcome.Ignored -> Unit
+                VersionInfoAccumulatorOutcome.Waiting -> Unit
+                is VersionInfoAccumulatorOutcome.Complete -> {
+                    if (pendingVersionInfo === request) {
+                        pendingVersionInfo = null
+                        request.pending.resolve(outcome.result)
+                    }
+                }
+            }
+        }
+    }
+
     private fun dispatchBridgeEvent(eventName: String, data: Map<String, Any>) {
         when (eventName) {
             "log" -> dispatchToListeners { it.onLog(data["message"] as? String ?: data.toString()) }
@@ -1773,9 +1801,7 @@ class MentraBluetoothSdk private constructor(
             }
             "version_info" -> {
                 val event = VersionInfoResult.fromMap(data)
-                synchronized(oneShotLock) {
-                    pendingVersionInfo?.resolve(event)
-                }
+                handleVersionInfoForRequest(data)
                 dispatchToListeners { it.onVersionInfo(event) }
             }
             "mic_pcm" -> {

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

@@ -0,0 +1,88 @@
+package com.mentra.bluetoothsdk
+
+internal sealed interface VersionInfoAccumulatorOutcome {
+    data object Ignored : VersionInfoAccumulatorOutcome
+    data object Waiting : VersionInfoAccumulatorOutcome
+    data class Complete(val result: VersionInfoResult) : VersionInfoAccumulatorOutcome
+}
+
+/** One request, explicit modern completion, or the deployed legacy chunk-3 terminal boundary. */
+internal class VersionInfoResponseAccumulator(private val expectedRequestId: String) {
+    private val values = mutableMapOf<String, Any>()
+    private val chunks = mutableMapOf<Int, Map<String, Any>>()
+    private var count: Int? = null
+    private var sid: String? = null
+    private var legacyStarted = false
+    private var completed = false
+
+    fun accept(event: Map<String, Any>): VersionInfoAccumulatorOutcome {
+        if (completed) return VersionInfoAccumulatorOutcome.Ignored
+        val hasModernMetadata = event.keys.any { it in MODERN_KEYS }
+        if (hasModernMetadata) {
+            if (event[RESPONSE_REQUEST_ID_KEY] != expectedRequestId) return VersionInfoAccumulatorOutcome.Ignored
+            val index = integer(event[RESPONSE_INDEX_KEY]) ?: return VersionInfoAccumulatorOutcome.Ignored
+            val total = integer(event[RESPONSE_COUNT_KEY]) ?: return VersionInfoAccumulatorOutcome.Ignored
+            val final = event[RESPONSE_FINAL_KEY] as? Boolean ?: return VersionInfoAccumulatorOutcome.Ignored
+            val process = (event[RESPONSE_SID_KEY] as? String)?.takeIf { it.isNotBlank() }
+                ?: return VersionInfoAccumulatorOutcome.Ignored
+            if (total !in 1..16 || index !in 1..total || final != (index == total)) return VersionInfoAccumulatorOutcome.Ignored
+            if (count != null && (count != total || sid != process)) return VersionInfoAccumulatorOutcome.Ignored
+            if (count == null) {
+                values.clear()
+                count = total
+                sid = process
+            }
+            chunks[index] = event
+            if (chunks.size != total) return VersionInfoAccumulatorOutcome.Waiting
+            (1..total).forEach { merge(chunks.getValue(it)) }
+            return finish()
+        }
+        // Once a response is correlated, unsolicited legacy traffic cannot replace it.
+        if (count != null) return VersionInfoAccumulatorOutcome.Ignored
+        when (event[RESPONSE_CHUNK_KEY] as? String ?: "version_info") {
+            "version_info" -> { values.clear(); merge(event); return finish() }
+            "version_info_1" -> { values.clear(); legacyStarted = true; merge(event) }
+            "version_info_2" -> {
+                if (!legacyStarted) return VersionInfoAccumulatorOutcome.Ignored
+                merge(event)
+            }
+            "version_info_3" -> {
+                if (!legacyStarted) return VersionInfoAccumulatorOutcome.Ignored
+                merge(event)
+                return finish()
+            }
+            else -> return VersionInfoAccumulatorOutcome.Ignored
+        }
+        // Silence is never evidence of completion. The request's normal deadline handles loss.
+        return VersionInfoAccumulatorOutcome.Waiting
+    }
+
+    private fun finish(): VersionInfoAccumulatorOutcome.Complete {
+        completed = true
+        return VersionInfoAccumulatorOutcome.Complete(VersionInfoResult.fromMap(values))
+    }
+
+    private fun merge(event: Map<String, Any>) {
+        event.forEach { (key, value) ->
+            if (!key.startsWith("_response") && key != "type" && (value !is String || value.isNotEmpty())) {
+                values[key] = value
+            }
+        }
+    }
+
+    private fun integer(value: Any?): Int? {
+        val number = value as? Number ?: return null
+        val int = number.toInt()
+        return int.takeIf { number.toDouble() == it.toDouble() }
+    }
+
+    companion object {
+        internal const val RESPONSE_CHUNK_KEY = "_responseChunk"
+        internal const val RESPONSE_REQUEST_ID_KEY = "_responseRequestId"
+        internal const val RESPONSE_INDEX_KEY = "_responseChunkIndex"
+        internal const val RESPONSE_COUNT_KEY = "_responseChunkCount"
+        internal const val RESPONSE_FINAL_KEY = "_responseFinal"
+        internal const val RESPONSE_SID_KEY = "_responseSid"
+        private val MODERN_KEYS = setOf(RESPONSE_REQUEST_ID_KEY, RESPONSE_INDEX_KEY, RESPONSE_COUNT_KEY, RESPONSE_FINAL_KEY)
+    }
+}

package/android/src/main/java/com/mentra/bluetoothsdk/services/Foreground.kt

@@ -3,6 +3,7 @@ package com.mentra.bluetoothsdk.services
 import android.app.NotificationChannel
 import android.app.NotificationManager
 import android.app.Service
+import android.content.ComponentName
 import android.content.Intent
 import android.content.pm.PackageManager
 import android.content.pm.ServiceInfo
@@ -21,14 +22,31 @@ class ForegroundService : Service() {
         const val ACTION_REFRESH_TYPES =
                 "com.mentra.bluetoothsdk.services.action.REFRESH_FOREGROUND_SERVICE_TYPES"
 
-        internal fun bootstrapServiceType(): Int =
-                ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC
+        internal const val DEFAULT_SERVICE_TYPES =
+                ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC or
+                        ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE or
+                        ServiceInfo.FOREGROUND_SERVICE_TYPE_LOCATION or
+                        ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK or
+                        ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE
+
+        internal fun bootstrapServiceType(declaredTypes: Int = DEFAULT_SERVICE_TYPES): Int {
+            // Both types can start without a while-in-use permission. The SDK declares
+            // CHANGE_WIFI_STATE, which satisfies connectedDevice's prerequisite.
+            if (declaredTypes and ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC != 0) {
+                return ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC
+            }
+            require(declaredTypes and ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE != 0) {
+                "The SDK foreground service must declare connectedDevice or dataSync"
+            }
+            return ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
+        }
 
         internal fun preferredServiceType(
                 hasConnectedDeviceAccess: Boolean,
                 hasMicrophoneAccess: Boolean,
                 hasLocationAccess: Boolean,
                 includeMediaPlayback: Boolean = true,
+                declaredTypes: Int = DEFAULT_SERVICE_TYPES,
         ): Int {
             var serviceType = 0
 
@@ -47,21 +65,31 @@ class ForegroundService : Service() {
                 serviceType = serviceType or ServiceInfo.FOREGROUND_SERVICE_TYPE_LOCATION
             }
 
-            return if (serviceType == 0) bootstrapServiceType() else serviceType
+            serviceType = serviceType and declaredTypes
+            return if (serviceType == 0) bootstrapServiceType(declaredTypes) else serviceType
         }
     }
 
     private var locationTypeRequested = false
 
+    private val declaredServiceTypes: Int by lazy {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+            packageManager.getServiceInfo(ComponentName(this, ForegroundService::class.java), 0)
+                    .foregroundServiceType
+        } else {
+            DEFAULT_SERVICE_TYPES
+        }
+    }
+
     override fun onCreate() {
         super.onCreate()
         Bridge.log("ForegroundService: onCreate() called")
         BleTraceLogger.logLifecycle(this, "ForegroundService", "service_create")
-        // Enter the foreground immediately with a type that has no runtime
-        // prerequisites. onStartCommand() replaces this bootstrap type with the
+        // Enter the foreground immediately using a type allowed by the host manifest.
+        // onStartCommand() replaces this bootstrap type with the
         // eligible long-running types, deliberately omitting dataSync so Android 15's
         // six-hour dataSync timer no longer applies.
-        startForegroundWithType(bootstrapServiceType())
+        startForegroundWithType(bootstrapServiceType(declaredServiceTypes))
     }
 
     override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
@@ -114,12 +142,13 @@ class ForegroundService : Service() {
             return 0 // No service types before Android Q
         }
 
-        // Audio prompts can be initiated by glasses while the host Activity is
-        // backgrounded. mediaPlayback has no runtime prerequisite, so keep it
-        // active on the existing Mentra service for the entire connected
-        // session rather than trying to launch a second service after a wake
-        // phrase arrives.
-        Bridge.log("ForegroundService: Added mediaPlayback (supports background audio)")
+        // MentraOS uses background audio prompts; Bluetooth-only hosts can omit
+        // this type from their merged manifest.
+        val includeMediaPlayback =
+                declaredServiceTypes and ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK != 0
+        if (includeMediaPlayback) {
+            Bridge.log("ForegroundService: Added mediaPlayback (supports background audio)")
+        }
 
         // Check Bluetooth permissions
         val hasBluetoothPermission =
@@ -168,13 +197,14 @@ class ForegroundService : Service() {
 
         // Check microphone permission
         val hasMicPermission =
-                ContextCompat.checkSelfPermission(this, android.Manifest.permission.RECORD_AUDIO) ==
-                        PackageManager.PERMISSION_GRANTED
+                declaredServiceTypes and ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE != 0 &&
+                        ContextCompat.checkSelfPermission(this, android.Manifest.permission.RECORD_AUDIO) ==
+                                PackageManager.PERMISSION_GRANTED
 
         if (hasMicPermission) {
             Bridge.log("ForegroundService: Added microphone (has RECORD_AUDIO permission)")
         } else {
-            Bridge.log("ForegroundService: No microphone permission")
+            Bridge.log("ForegroundService: Microphone type disabled or permission not granted")
         }
 
         val hasLocationPermission =
@@ -189,7 +219,9 @@ class ForegroundService : Service() {
         val locationManager = getSystemService(LocationManager::class.java)
         val isLocationEnabled = locationManager?.isLocationEnabled == true
 
-        val hasLocationAccess = locationTypeRequested && hasLocationPermission && isLocationEnabled
+        val hasLocationAccess =
+                declaredServiceTypes and ServiceInfo.FOREGROUND_SERVICE_TYPE_LOCATION != 0 &&
+                        locationTypeRequested && hasLocationPermission && isLocationEnabled
         if (hasLocationAccess) {
             Bridge.log("ForegroundService: Added location (has foreground location permission)")
         } else {
@@ -203,6 +235,8 @@ class ForegroundService : Service() {
                 hasConnectedDeviceAccess = hasConnectedDeviceAccess,
                 hasMicrophoneAccess = hasMicPermission,
                 hasLocationAccess = hasLocationAccess,
+                includeMediaPlayback = includeMediaPlayback,
+                declaredTypes = declaredServiceTypes,
         )
     }