@mentra/bluetooth-sdk 0.1.20 → 0.1.21-beta.1

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

@@ -0,0 +1,333 @@
+package com.mentra.bluetoothsdk
+
+import android.net.ConnectivityManager
+import android.net.Network
+import android.net.NetworkCapabilities
+import android.net.NetworkRequest
+import android.net.wifi.WifiNetworkSpecifier
+import android.os.Build
+import android.util.Base64
+import android.util.Log
+import expo.modules.kotlin.Promise
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import java.io.File
+import java.io.FileOutputStream
+import java.net.HttpURLConnection
+import java.net.URL
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.Executors
+
+/** MentraOS-internal transport for glasses-local traffic without process network binding. */
+class MentraLocalNetworkModule : Module() {
+    private companion object {
+        const val TAG = "MentraLocalNetwork"
+    }
+
+    private val lock = Any()
+    private val executor = Executors.newCachedThreadPool()
+    private val activeConnections = ConcurrentHashMap<String, HttpURLConnection>()
+    private var localNetwork: Network? = null
+    private var networkCallback: ConnectivityManager.NetworkCallback? = null
+    private var pendingConnectPromise: Promise? = null
+
+    override fun definition() = ModuleDefinition {
+        Name("MentraLocalNetwork")
+        Events("downloadProgress", "networkLost")
+
+        AsyncFunction("connect") { ssid: String, password: String, promise: Promise ->
+            connect(ssid, password, promise)
+        }
+
+        AsyncFunction("request") {
+            requestId: String,
+            url: String,
+            method: String,
+            headers: Map<String, String>,
+            body: String?,
+            timeoutMs: Int,
+            promise: Promise ->
+            executor.execute { performRequest(requestId, url, method, headers, body, timeoutMs, promise) }
+        }
+
+        AsyncFunction("download") {
+            requestId: String,
+            url: String,
+            destination: String,
+            headers: Map<String, String>,
+            connectionTimeoutMs: Int,
+            readTimeoutMs: Int,
+            promise: Promise ->
+            executor.execute {
+                performDownload(
+                    requestId,
+                    url,
+                    destination,
+                    headers,
+                    connectionTimeoutMs,
+                    readTimeoutMs,
+                    promise,
+                )
+            }
+        }
+
+        AsyncFunction("cancel") { requestId: String -> cancel(requestId) }
+        AsyncFunction("disconnect") { disconnect() }
+
+        OnDestroy { disconnect() }
+    }
+
+    private fun connectivityManager(): ConnectivityManager =
+        requireNotNull(appContext.reactContext?.getSystemService(ConnectivityManager::class.java)) {
+            "ConnectivityManager is unavailable"
+        }
+
+    private fun connect(ssid: String, password: String, promise: Promise) {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.Q) {
+            promise.reject("ERR_UNSUPPORTED_ANDROID", "Scoped local WiFi requires Android 10 or newer", null)
+            return
+        }
+
+        disconnect()
+        val manager = connectivityManager()
+        val specifier =
+            WifiNetworkSpecifier.Builder()
+                .setSsid(ssid)
+                .setWpa2Passphrase(password)
+                .build()
+        val request =
+            NetworkRequest.Builder()
+                .addTransportType(NetworkCapabilities.TRANSPORT_WIFI)
+                .removeCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
+                .setNetworkSpecifier(specifier)
+                .build()
+
+        val callback =
+            object : ConnectivityManager.NetworkCallback() {
+                override fun onAvailable(network: Network) {
+                    val connectPromise: Promise?
+                    synchronized(lock) {
+                        if (networkCallback !== this) {
+                            Log.d(TAG, "Ignoring onAvailable from a stale network request")
+                            return
+                        }
+                        localNetwork = network
+                        connectPromise = pendingConnectPromise
+                        pendingConnectPromise = null
+                    }
+                    Log.i(
+                        TAG,
+                        "Captured glasses WiFi network=$network processBoundNetwork=${manager.boundNetworkForProcess}",
+                    )
+                    connectPromise?.resolve(mapOf("connected" to true, "ssid" to ssid))
+                }
+
+                override fun onUnavailable() {
+                    synchronized(lock) {
+                        if (networkCallback !== this) {
+                            Log.d(TAG, "Ignoring onUnavailable from a stale network request")
+                            return
+                        }
+                    }
+                    rejectPendingConnect("ERR_LOCAL_WIFI_UNAVAILABLE", "Could not connect to $ssid")
+                    clearNetworkCallback(this)
+                }
+
+                override fun onLost(network: Network) {
+                    synchronized(lock) {
+                        if (networkCallback !== this || localNetwork != network) {
+                            Log.d(TAG, "Ignoring onLost from a stale network request")
+                            return
+                        }
+                        localNetwork = null
+                    }
+                    cancelAll()
+                    clearNetworkCallback(this)
+                    sendEvent("networkLost", mapOf("ssid" to ssid))
+                }
+            }
+
+        synchronized(lock) {
+            pendingConnectPromise = promise
+            networkCallback = callback
+        }
+        try {
+            manager.requestNetwork(request, callback, 30_000)
+        } catch (error: Exception) {
+            clearNetworkCallback(callback)
+            rejectPendingConnect("ERR_LOCAL_WIFI_REQUEST", error.message ?: "Local WiFi request failed", error)
+        }
+    }
+
+    private fun performRequest(
+        requestId: String,
+        url: String,
+        method: String,
+        headers: Map<String, String>,
+        body: String?,
+        timeoutMs: Int,
+        promise: Promise,
+    ) {
+        var connection: HttpURLConnection? = null
+        try {
+            connection = openConnection(requestId, url)
+            connection.requestMethod = method
+            connection.connectTimeout = timeoutMs
+            connection.readTimeout = timeoutMs
+            headers.forEach(connection::setRequestProperty)
+            if (body != null) {
+                connection.doOutput = true
+                connection.outputStream.use { it.write(body.toByteArray(Charsets.UTF_8)) }
+            }
+            val status = connection.responseCode
+            val stream = if (status >= 400) connection.errorStream else connection.inputStream
+            val bytes = stream?.use { it.readBytes() } ?: ByteArray(0)
+            promise.resolve(
+                mapOf(
+                    "status" to status,
+                    "headers" to responseHeaders(connection),
+                    "bodyBase64" to Base64.encodeToString(bytes, Base64.NO_WRAP),
+                ),
+            )
+        } catch (error: Exception) {
+            promise.reject("ERR_LOCAL_HTTP", error.message ?: "Local HTTP request failed", error)
+        } finally {
+            activeConnections.remove(requestId)
+            connection?.disconnect()
+        }
+    }
+
+    private fun performDownload(
+        requestId: String,
+        url: String,
+        destination: String,
+        headers: Map<String, String>,
+        connectionTimeoutMs: Int,
+        readTimeoutMs: Int,
+        promise: Promise,
+    ) {
+        var connection: HttpURLConnection? = null
+        try {
+            connection = openConnection(requestId, url)
+            connection.requestMethod = "GET"
+            connection.connectTimeout = connectionTimeoutMs
+            connection.readTimeout = readTimeoutMs
+            headers.forEach(connection::setRequestProperty)
+            val status = connection.responseCode
+            if (status !in 200..299) throw IllegalStateException("HTTP $status")
+            val contentLength = connection.contentLengthLong
+            val responseHeaders = responseHeaders(connection)
+
+            // Match RNFS's begin callback contract before the first response byte. Gallery
+            // resumable downloads need the real status and Content-Range to validate segments.
+            sendEvent(
+                "downloadProgress",
+                mapOf(
+                    "requestId" to requestId,
+                    "bytesWritten" to 0L,
+                    "contentLength" to contentLength,
+                    "statusCode" to status,
+                    "headers" to responseHeaders,
+                ),
+            )
+
+            val destinationFile = File(destination)
+            destinationFile.parentFile?.mkdirs()
+            var bytesWritten = 0L
+            connection.inputStream.use { input ->
+                FileOutputStream(destinationFile, false).use { output ->
+                    val buffer = ByteArray(64 * 1024)
+                    while (true) {
+                        val count = input.read(buffer)
+                        if (count < 0) break
+                        output.write(buffer, 0, count)
+                        bytesWritten += count
+                        sendEvent(
+                            "downloadProgress",
+                            mapOf(
+                                "requestId" to requestId,
+                                "bytesWritten" to bytesWritten,
+                                "contentLength" to contentLength,
+                            ),
+                        )
+                    }
+                }
+            }
+            promise.resolve(
+                mapOf(
+                    "statusCode" to status,
+                    "bytesWritten" to bytesWritten,
+                    "headers" to responseHeaders,
+                ),
+            )
+        } catch (error: Exception) {
+            promise.reject("ERR_LOCAL_DOWNLOAD", error.message ?: "Local download failed", error)
+        } finally {
+            activeConnections.remove(requestId)
+            connection?.disconnect()
+        }
+    }
+
+    private fun openConnection(requestId: String, url: String): HttpURLConnection {
+        val network = synchronized(lock) { localNetwork }
+            ?: throw IllegalStateException("Local WiFi is not connected")
+        val connection = network.openConnection(URL(url)) as HttpURLConnection
+        activeConnections[requestId] = connection
+        return connection
+    }
+
+    private fun responseHeaders(connection: HttpURLConnection): Map<String, String> =
+        connection.headerFields
+            .filterKeys { it != null }
+            .mapValues { (_, values) -> values.joinToString(", ") }
+
+    private fun cancel(requestId: String) {
+        activeConnections.remove(requestId)?.disconnect()
+    }
+
+    private fun cancelAll() {
+        activeConnections.keys.toList().forEach(::cancel)
+    }
+
+    private fun disconnect() {
+        cancelAll()
+        val manager = appContext.reactContext?.getSystemService(ConnectivityManager::class.java)
+        val callback: ConnectivityManager.NetworkCallback?
+        synchronized(lock) {
+            callback = networkCallback
+            networkCallback = null
+            localNetwork = null
+        }
+        if (callback != null && manager != null) {
+            try {
+                manager.unregisterNetworkCallback(callback)
+            } catch (_: IllegalArgumentException) {
+                // Already unregistered by the platform.
+            }
+        }
+        rejectPendingConnect("ERR_LOCAL_WIFI_CANCELLED", "Local WiFi connection cancelled")
+    }
+
+    private fun clearNetworkCallback(callback: ConnectivityManager.NetworkCallback) {
+        val manager = appContext.reactContext?.getSystemService(ConnectivityManager::class.java)
+        synchronized(lock) {
+            if (networkCallback == callback) networkCallback = null
+        }
+        if (manager != null) {
+            try {
+                manager.unregisterNetworkCallback(callback)
+            } catch (_: IllegalArgumentException) {
+                // Callback was not registered or has already been removed.
+            }
+        }
+    }
+
+    private fun rejectPendingConnect(code: String, message: String, cause: Throwable? = null) {
+        val promise: Promise?
+        synchronized(lock) {
+            promise = pendingConnectPromise
+            pendingConnectPromise = null
+        }
+        promise?.reject(code, message, cause)
+    }
+}

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

@@ -70,8 +70,13 @@ internal object OtaManifestChecker {
         currentMtkVersion: String,
         currentBesVersion: String,
         manifest: JSONObject,
+        // Downgrade floor: a non-positive value (the default) disables downgrades entirely,
+        // matching ASG's fail-closed DowngradeGate and the engine. OEM SDK consumers that do
+        // not set a floor therefore get upgrade-only behavior and are never told a downgrade is
+        // available that the glasses would refuse.
+        downgradeFloorVersionCode: Long = 0L,
     ): Boolean =
-        hasApkUpdate(currentBuildNumber, manifest) ||
+        hasApkUpdate(currentBuildNumber, manifest, downgradeFloorVersionCode) ||
             hasMtkUpdate(manifest.optJSONArray("mtk_patches"), currentMtkVersion) ||
             hasBesUpdate(manifest.optJSONObject("bes_firmware"), currentBesVersion)
 
@@ -95,15 +100,50 @@ internal object OtaManifestChecker {
         throw BluetoothSdkException("invalid_ota_manifest", "OTA manifest is missing ASG app versionCode.")
     }
 
-    private fun hasApkUpdate(currentBuildNumber: String, manifest: JSONObject): Boolean {
+    private fun hasApkUpdate(
+        currentBuildNumber: String,
+        manifest: JSONObject,
+        downgradeFloorVersionCode: Long,
+    ): Boolean {
         val currentVersion =
             currentBuildNumber.toLongOrNull()
                 ?: throw BluetoothSdkException(
                     "invalid_glasses_version",
                     "Cannot check OTA update because glasses build number is invalid.",
                 )
+        // Only apps-shaped manifests are exact pins. A legacy top-level manifest (versionCode at
+        // the root, no apps entry) is NOT a pin and stays strictly upgrade-only, matching the
+        // engine TS checker — otherwise a build newer than such a manifest would report a false
+        // downgrade the JS path ignores.
+        val isExactPin = manifest.optJSONObject("apps")?.optJSONObject(ASG_CLIENT_PACKAGE)?.hasNumber("versionCode") == true
         val serverVersion = latestAppInfo(manifest).requiredLong("versionCode")
-        return serverVersion > currentVersion
+        if (!isExactPin) {
+            return serverVersion > currentVersion
+        }
+        // Exact pin: any mismatch is an update in either direction (downgrades take the
+        // uninstall-then-reinstall detour on the glasses). A non-positive pin is only legitimate
+        // in the frozen legacy rescue manifests that pre-39 glasses are checked against; for
+        // modern glasses it means the manifest cannot verify anything, and that must surface as an
+        // error — never as "no update".
+        if (serverVersion <= 0) {
+            if (currentVersion >= 39) {
+                throw BluetoothSdkException(
+                    "invalid_ota_manifest",
+                    "OTA manifest ASG pin is missing or zero; cannot verify update state.",
+                )
+            }
+            return false
+        }
+        if (serverVersion > currentVersion) {
+            return true
+        }
+        // Exact match: already on the pin, no update.
+        if (serverVersion == currentVersion) {
+            return false
+        }
+        // Downgrade: only actionable at/above the enabled floor; a non-positive floor disables
+        // downgrades (fail closed, matching ASG and the engine).
+        return downgradeFloorVersionCode > 0 && serverVersion >= downgradeFloorVersionCode
     }
 
     private fun hasMtkUpdate(patches: JSONArray?, currentVersion: String): Boolean {

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

@@ -110,14 +110,15 @@ class CameraFov @JvmOverloads constructor(
     companion object {
         const val MIN_FOV = 62
         const val MAX_FOV = 118
-        const val DEFAULT_FOV = 102
+        const val DEFAULT_FOV = 118
         const val NARROW_FOV = 82
+        const val STANDARD_FOV = 102
         @JvmField
         val DEFAULT_ROI_POSITION = CameraRoiPosition.CENTER
         @JvmField
         val NARROW = CameraFov(NARROW_FOV, DEFAULT_ROI_POSITION)
         @JvmField
-        val STANDARD = CameraFov(DEFAULT_FOV, DEFAULT_ROI_POSITION)
+        val STANDARD = CameraFov(STANDARD_FOV, DEFAULT_ROI_POSITION)
         @JvmField
         val WIDE = CameraFov(MAX_FOV, DEFAULT_ROI_POSITION)
     }
@@ -200,8 +201,22 @@ data class PhotoRequest @JvmOverloads constructor(
     val ispAnalogGain: String? = null,
     val resetCaptureTuning: Boolean? = null,
     val mode: PhotoMode = PhotoMode.PHOTO,
+    /** `direct` disables BLE fallback; `ble` skips direct upload; `auto` tries both. */
+    val transferMethod: String = "auto",
 ) {
     companion object {
+        private fun transferMethodFromValue(value: Any?): String {
+            if (value == null) return "auto"
+            val raw = value as? String
+                ?: throw IllegalArgumentException(
+                    "Invalid transferMethod ${value::class.java.simpleName}. Expected auto, direct, or ble."
+                )
+            return raw.takeIf { it == "auto" || it == "direct" || it == "ble" }
+                ?: throw IllegalArgumentException(
+                    "Invalid transferMethod \"$raw\". Expected auto, direct, or ble."
+                )
+        }
+
         /** Mirrors iOS `BluetoothSdkModule` defaults for keys omitted from the JS bridge. */
         @JvmStatic
         fun fromMap(values: Map<String, Any>): PhotoRequest {
@@ -238,6 +253,7 @@ data class PhotoRequest @JvmOverloads constructor(
                 save = boolValue(values, "save", "saveToGallery") ?: false,
                 sound = boolValue(values, "sound") ?: true,
                 mode = PhotoMode.fromValue(stringValue(values, "mode")),
+                transferMethod = transferMethodFromValue(values["transferMethod"]),
                 exposureTimeNs = exposureTimeNs,
                 iso = iso,
                 aeExposureDivisor = aeDivisor,

package/android/src/main/java/com/mentra/bluetoothsdk/debug/BleTraceLogger.kt

@@ -12,7 +12,7 @@ object BleTraceLogger {
     private const val MAX_PAYLOAD_CHARS = 3000
     private const val K900_TYPE = "k900"
     private val sensitiveKeyParts =
-        listOf("password", "pass", "token", "secret", "authorization", "auth", "email")
+        listOf("password", "pass", "token", "secret", "authorization", "auth", "email", "serial")
 
     @JvmStatic
     fun logJson(direction: String, layer: String, payload: JSONObject?, bytes: Int? = null) {

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

@@ -6,6 +6,7 @@ import android.app.Service
 import android.content.Intent
 import android.content.pm.PackageManager
 import android.content.pm.ServiceInfo
+import android.location.LocationManager
 import android.os.Build
 import android.os.IBinder
 import androidx.core.app.NotificationCompat
@@ -17,8 +18,12 @@ class ForegroundService : Service() {
     companion object {
         const val CHANNEL_ID = "MentraServiceChannel"
         const val NOTIFICATION_ID = 1001
+        const val ACTION_REFRESH_TYPES =
+                "com.mentra.bluetoothsdk.services.action.REFRESH_FOREGROUND_SERVICE_TYPES"
     }
 
+    private var locationTypeRequested = false
+
     override fun onCreate() {
         super.onCreate()
         Bridge.log("ForegroundService: onCreate() called")
@@ -34,6 +39,11 @@ class ForegroundService : Service() {
                 "service_start_command",
                 mapOf("action" to intent?.action, "flags" to flags, "startId" to startId)
         )
+        if (intent?.action == ACTION_REFRESH_TYPES) {
+            // This action is only sent while the host Activity is foregrounded. Android 14+
+            // rejects adding a while-in-use location type from the background.
+            locationTypeRequested = true
+        }
         // Re-check permissions in case they changed
         startForegroundWithAutoDetectedType()
         return START_STICKY
@@ -71,6 +81,14 @@ class ForegroundService : Service() {
 
         var serviceType = 0
 
+        // 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.
+        serviceType = serviceType or ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
+        Bridge.log("ForegroundService: Added mediaPlayback (supports background audio)")
+
         // Check Bluetooth permissions
         val hasBluetoothPermission =
                 when {
@@ -124,6 +142,28 @@ class ForegroundService : Service() {
             Bridge.log("ForegroundService: No microphone permission")
         }
 
+        val hasLocationPermission =
+                ContextCompat.checkSelfPermission(
+                        this,
+                        android.Manifest.permission.ACCESS_FINE_LOCATION
+                ) == PackageManager.PERMISSION_GRANTED ||
+                        ContextCompat.checkSelfPermission(
+                                this,
+                                android.Manifest.permission.ACCESS_COARSE_LOCATION
+                        ) == PackageManager.PERMISSION_GRANTED
+        val locationManager = getSystemService(LocationManager::class.java)
+        val isLocationEnabled = locationManager?.isLocationEnabled == true
+
+        if (locationTypeRequested && hasLocationPermission && isLocationEnabled) {
+            serviceType = serviceType or ServiceInfo.FOREGROUND_SERVICE_TYPE_LOCATION
+            Bridge.log("ForegroundService: Added location (has foreground location permission)")
+        } else {
+            Bridge.log(
+                    "ForegroundService: No location type " +
+                            "(requested=$locationTypeRequested, permission=$hasLocationPermission, enabled=$isLocationEnabled)"
+            )
+        }
+
         // Only use dataSync as absolute last resort fallback if no other types were added.
         // WARNING: dataSync has a 6-hour timeout on Android 14+ which will crash the app.
         // This should rarely happen since CHANGE_NETWORK_STATE is a normal permission.
@@ -141,11 +181,20 @@ class ForegroundService : Service() {
         val hasConnectedDevice =
                 (serviceType and ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE) != 0
         val hasMicrophone = (serviceType and ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE) != 0
+        val hasLocation = (serviceType and ServiceInfo.FOREGROUND_SERVICE_TYPE_LOCATION) != 0
+        val hasMediaPlayback =
+                (serviceType and ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK) != 0
 
         return when {
+            hasConnectedDevice && hasMicrophone && hasLocation ->
+                    "Glasses, microphone & location active"
+            hasConnectedDevice && hasLocation -> "Smart glasses & location active"
+            hasMicrophone && hasLocation -> "Microphone & location active"
+            hasLocation -> "Location active"
             hasConnectedDevice && hasMicrophone -> "Glasses & microphone active"
             hasConnectedDevice -> "Smart glasses connected"
             hasMicrophone -> "Microphone active"
+            hasMediaPlayback -> "Audio playback active"
             else -> "Syncing data"
         }
     }
@@ -160,6 +209,10 @@ class ForegroundService : Service() {
                 types.add("connectedDevice")
         if (serviceType and ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE != 0)
                 types.add("microphone")
+        if (serviceType and ServiceInfo.FOREGROUND_SERVICE_TYPE_LOCATION != 0)
+                types.add("location")
+        if (serviceType and ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK != 0)
+                types.add("mediaPlayback")
 
         return types.joinToString("|")
     }