@mentra/bluetooth-sdk 0.1.21-beta.5 → 3.1.0-beta.100

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

@@ -5,7 +5,8 @@ import android.net.Network
 import android.net.NetworkCapabilities
 import android.net.NetworkRequest
 import android.net.wifi.WifiNetworkSpecifier
-import android.os.Build
+import android.os.Handler
+import android.os.Looper
 import android.util.Base64
 import android.util.Log
 import expo.modules.kotlin.Promise
@@ -14,6 +15,7 @@ import expo.modules.kotlin.modules.ModuleDefinition
 import java.io.File
 import java.io.FileOutputStream
 import java.net.HttpURLConnection
+import java.net.Inet4Address
 import java.net.URL
 import java.util.concurrent.ConcurrentHashMap
 import java.util.concurrent.Executors
@@ -22,14 +24,18 @@ import java.util.concurrent.Executors
 class MentraLocalNetworkModule : Module() {
     private companion object {
         const val TAG = "MentraLocalNetwork"
+        const val NETWORK_READINESS_TIMEOUT_MS = 5_000L
     }
 
     private val lock = Any()
     private val executor = Executors.newCachedThreadPool()
+    private val handler = Handler(Looper.getMainLooper())
     private val activeConnections = ConcurrentHashMap<String, HttpURLConnection>()
+    private val networkReadiness = ScopedNetworkReadiness<Network>()
     private var localNetwork: Network? = null
     private var networkCallback: ConnectivityManager.NetworkCallback? = null
     private var pendingConnectPromise: Promise? = null
+    private var pendingReadinessTimeout: Runnable? = null
 
     override fun definition() = ModuleDefinition {
         Name("MentraLocalNetwork")
@@ -74,7 +80,9 @@ class MentraLocalNetworkModule : Module() {
         AsyncFunction("cancel") { requestId: String -> cancel(requestId) }
         AsyncFunction("disconnect") { disconnect() }
 
-        OnDestroy { disconnect() }
+        OnDestroy {
+            disconnect()
+        }
     }
 
     private fun connectivityManager(): ConnectivityManager =
@@ -83,11 +91,6 @@ class MentraLocalNetworkModule : Module() {
         }
 
     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 =
@@ -105,21 +108,55 @@ class MentraLocalNetworkModule : Module() {
         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
                         }
+                        networkReadiness.onAvailable(network)
+                    }
+                    Log.i(
+                        TAG,
+                        "Captured glasses WiFi network=$network; waiting for foreground capability " +
+                            "processBoundNetwork=${manager.boundNetworkForProcess}",
+                    )
+                    scheduleReadinessTimeout(this, ssid)
+                }
+
+                override fun onCapabilitiesChanged(network: Network, capabilities: NetworkCapabilities) {
+                    val connectPromise: Promise?
+                    synchronized(lock) {
+                        if (networkCallback !== this || localNetwork != null || pendingConnectPromise == null) return
+                        if (!networkReadiness.isReady(
+                                network,
+                                capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_FOREGROUND),
+                            )
+                        ) {
+                            return
+                        }
                         localNetwork = network
                         connectPromise = pendingConnectPromise
                         pendingConnectPromise = null
+                        cancelReadinessTimeoutLocked()
                     }
                     Log.i(
                         TAG,
-                        "Captured glasses WiFi network=$network processBoundNetwork=${manager.boundNetworkForProcess}",
+                        "Glasses WiFi network=$network is foreground and ready " +
+                            "processBoundNetwork=${manager.boundNetworkForProcess}",
+                    )
+                    val localAddress =
+                        manager.getLinkProperties(network)
+                            ?.linkAddresses
+                            ?.firstOrNull { it.address is Inet4Address }
+                            ?.address
+                            ?.hostAddress
+                    connectPromise?.resolve(
+                        buildMap<String, Any> {
+                            put("connected", true)
+                            put("ssid", ssid)
+                            if (!localAddress.isNullOrBlank()) put("localAddress", localAddress)
+                        },
                     )
-                    connectPromise?.resolve(mapOf("connected" to true, "ssid" to ssid))
                 }
 
                 override fun onUnavailable() {
@@ -135,13 +172,17 @@ class MentraLocalNetworkModule : Module() {
 
                 override fun onLost(network: Network) {
                     synchronized(lock) {
-                        if (networkCallback !== this || localNetwork != network) {
+                        if (networkCallback !== this ||
+                            (localNetwork != network && !networkReadiness.contains(network))
+                        ) {
                             Log.d(TAG, "Ignoring onLost from a stale network request")
                             return
                         }
                         localNetwork = null
+                        networkReadiness.clear()
                     }
                     cancelAll()
+                    rejectPendingConnect("ERR_LOCAL_WIFI_LOST", "Lost connection to $ssid")
                     clearNetworkCallback(this)
                     sendEvent("networkLost", mapOf("ssid" to ssid))
                 }
@@ -289,6 +330,39 @@ class MentraLocalNetworkModule : Module() {
         activeConnections.keys.toList().forEach(::cancel)
     }
 
+    private fun scheduleReadinessTimeout(
+        callback: ConnectivityManager.NetworkCallback,
+        ssid: String,
+    ) {
+        val timeout =
+            Runnable {
+                val connectPromise = synchronized(lock) {
+                    if (networkCallback !== callback || pendingConnectPromise == null) return@Runnable
+                    pendingReadinessTimeout = null
+                    val promise = pendingConnectPromise
+                    pendingConnectPromise = null
+                    promise
+                }
+                connectPromise?.reject(
+                    "ERR_LOCAL_WIFI_NOT_READY",
+                    "Connected to $ssid but the network did not become ready",
+                    null,
+                )
+                clearNetworkCallback(callback)
+            }
+        synchronized(lock) {
+            if (networkCallback !== callback || pendingConnectPromise == null) return
+            cancelReadinessTimeoutLocked()
+            pendingReadinessTimeout = timeout
+        }
+        handler.postDelayed(timeout, NETWORK_READINESS_TIMEOUT_MS)
+    }
+
+    private fun cancelReadinessTimeoutLocked() {
+        pendingReadinessTimeout?.let(handler::removeCallbacks)
+        pendingReadinessTimeout = null
+    }
+
     private fun disconnect() {
         cancelAll()
         val manager = appContext.reactContext?.getSystemService(ConnectivityManager::class.java)
@@ -297,6 +371,8 @@ class MentraLocalNetworkModule : Module() {
             callback = networkCallback
             networkCallback = null
             localNetwork = null
+            networkReadiness.clear()
+            cancelReadinessTimeoutLocked()
         }
         if (callback != null && manager != null) {
             try {
@@ -311,7 +387,12 @@ class MentraLocalNetworkModule : Module() {
     private fun clearNetworkCallback(callback: ConnectivityManager.NetworkCallback) {
         val manager = appContext.reactContext?.getSystemService(ConnectivityManager::class.java)
         synchronized(lock) {
-            if (networkCallback == callback) networkCallback = null
+            if (networkCallback == callback) {
+                networkCallback = null
+                localNetwork = null
+                networkReadiness.clear()
+                cancelReadinessTimeoutLocked()
+            }
         }
         if (manager != null) {
             try {

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

@@ -7,21 +7,19 @@ import org.json.JSONArray
 import org.json.JSONObject
 
 internal object OtaManifestDefaults {
-    private const val SDK_OTA_RELEASE_BASE_URL =
-        "https://github.com/Mentra-Community/MentraOS/releases/download/bluetooth-sdk-ota"
     // ASG builds before 39 ignore ota_start.ota_version_url, so SDK checks must
     // use the same legacy production manifest those glasses will install from.
     const val LEGACY_PROD_OTA_VERSION_URL = "https://ota.mentraglass.com/prod_live_version.json"
 
     fun defaultOtaVersionUrl(): String {
-        val sdkVersion = BuildConfig.SDK_VERSION.trim()
-        if (sdkVersion.isBlank() || sdkVersion == "unspecified") {
+        val manifestUrl = GeneratedReleaseMetadata.OTA_MANIFEST_URL.trim()
+        if (manifestUrl.isBlank()) {
             throw BluetoothSdkException(
-                "missing_sdk_version",
-                "Cannot determine Bluetooth SDK version for the default OTA manifest URL.",
+                "ota_manifest_unconfigured",
+                "This source-built Bluetooth SDK has no embedded OTA manifest. Configure one with the debug API.",
             )
         }
-        return "$SDK_OTA_RELEASE_BASE_URL/bluetooth-sdk-$sdkVersion-version.json"
+        return manifestUrl
     }
 }
 

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

@@ -0,0 +1,61 @@
+package com.mentra.bluetoothsdk
+
+/** One coordinated Mentra release note authored in /changelogs/<version>.md. */
+data class ReleaseChangelog(
+    val version: String,
+    val markdown: String,
+)
+
+internal object ReleaseChangelogCatalog {
+    private val baseVersionPattern = Regex("^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:[-+].*)?$")
+
+    fun select(
+        fromVersion: String?,
+        toVersion: String?,
+    ): List<ReleaseChangelog> {
+        val fallbackTarget =
+            GeneratedReleaseMetadata.FAMILY_BASE_VERSION.ifBlank {
+                GENERATED_RELEASE_CHANGELOGS.firstOrNull()?.version.orEmpty()
+            }
+        if (fallbackTarget.isBlank() && toVersion == null) return emptyList()
+        val target = baseVersion(toVersion ?: fallbackTarget, "toVersion")
+        if (GENERATED_RELEASE_CHANGELOGS.none { it.version == target }) {
+            throw BluetoothSdkException("missing_changelog", "No changelog is bundled for target version $target.")
+        }
+        if (fromVersion == null) return GENERATED_RELEASE_CHANGELOGS.filter { it.version == target }
+
+        val source = baseVersion(fromVersion, "fromVersion")
+        val direction = compareVersions(target, source)
+        return GENERATED_RELEASE_CHANGELOGS.filter { entry ->
+            when {
+                direction == 0 -> entry.version == target
+                direction > 0 -> compareVersions(entry.version, source) > 0 && compareVersions(entry.version, target) <= 0
+                else -> compareVersions(entry.version, source) < 0 && compareVersions(entry.version, target) >= 0
+            }
+        }
+    }
+
+    private fun baseVersion(
+        version: String,
+        label: String,
+    ): String {
+        val match = baseVersionPattern.matchEntire(version.trim())
+            ?: throw BluetoothSdkException(
+                "invalid_changelog_version",
+                "$label must be a semantic version such as 3.1.0, 3.1.0-dev.4, or 3.1.0-beta.2.",
+            )
+        return "${match.groupValues[1]}.${match.groupValues[2]}.${match.groupValues[3]}"
+    }
+
+    private fun compareVersions(
+        left: String,
+        right: String,
+    ): Int {
+        val a = left.split(".").map(String::toInt)
+        val b = right.split(".").map(String::toInt)
+        for (index in 0..2) {
+            if (a[index] != b[index]) return a[index] - b[index]
+        }
+        return 0
+    }
+}

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

@@ -0,0 +1,17 @@
+package com.mentra.bluetoothsdk
+
+internal class ScopedNetworkReadiness<T> {
+    private var candidate: T? = null
+
+    fun onAvailable(network: T) {
+        candidate = network
+    }
+
+    fun isReady(network: T, isForeground: Boolean): Boolean = candidate == network && isForeground
+
+    fun contains(network: T): Boolean = candidate == network
+
+    fun clear() {
+        candidate = null
+    }
+}

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

@@ -94,6 +94,21 @@ data class MicLc3Event(
     }
 }
 
+internal data class MicHealth(
+    val sequenceGapEvents: Long,
+    val decodeFailures: Long,
+    val lastLc3ReceivedAt: Long?,
+    val lastPcmProducedAt: Long?,
+) {
+    fun toMap(): Map<String, Any> =
+        buildMap {
+            put("sequenceGapEvents", sequenceGapEvents)
+            put("decodeFailures", decodeFailures)
+            lastLc3ReceivedAt?.let { put("lastLc3ReceivedAt", it) }
+            lastPcmProducedAt?.let { put("lastPcmProducedAt", it) }
+        }
+}
+
 data class LocalTranscriptionEvent(
     val text: String,
     val isFinal: Boolean,

package/android/src/main/java/com/mentra/bluetoothsdk/events/BluetoothEvents.kt

@@ -39,6 +39,29 @@ data class SpeakingStatusEvent(
     val values: Map<String, Any>,
 )
 
+data class MicHealthEvent(
+    val reason: String,
+    val sequenceGapEvents: Long,
+    val decodeFailures: Long,
+    val lastLc3ReceivedAt: Long?,
+    val lastPcmProducedAt: Long?,
+    val timestamp: Long,
+    val values: Map<String, Any>,
+) {
+    companion object {
+        internal fun fromMap(values: Map<String, Any>): MicHealthEvent =
+            MicHealthEvent(
+                reason = stringValue(values, "reason") ?: "",
+                sequenceGapEvents = longValue(values, "sequenceGapEvents") ?: 0,
+                decodeFailures = longValue(values, "decodeFailures") ?: 0,
+                lastLc3ReceivedAt = longValue(values, "lastLc3ReceivedAt"),
+                lastPcmProducedAt = longValue(values, "lastPcmProducedAt"),
+                timestamp = longValue(values, "timestamp") ?: System.currentTimeMillis(),
+                values = values,
+            )
+    }
+}
+
 data class OtaStartAckEvent(
     val timestamp: Long?,
     val values: Map<String, Any>,
@@ -144,6 +167,7 @@ interface MentraBluetoothSdkListener {
     fun onVersionInfo(event: VersionInfoResult) {}
     fun onMicPcm(event: MicPcmEvent) {}
     fun onMicLc3(event: MicLc3Event) {}
+    fun onMicHealth(event: MicHealthEvent) {}
     fun onLocalTranscription(event: LocalTranscriptionEvent) {}
     fun onDefaultDeviceChanged(device: Device?) {}
     fun onLog(message: String) {}

package/android/src/main/java/com/mentra/bluetoothsdk/net/LocalIpv4.kt

@@ -0,0 +1,57 @@
+package com.mentra.bluetoothsdk.net
+
+import java.net.Inet4Address
+import java.net.NetworkInterface
+
+/**
+ * Best-effort local IPv4 discovery for phone-hosted servers the glasses reach over WiFi
+ * (photo upload receiver, hotspot-served OTA). Prefers WiFi-ish interfaces carrying RFC1918
+ * addresses — under a glasses-hotspot session wlan0 holds the 192.168.43.x client address.
+ */
+object LocalIpv4 {
+  fun bestLocalIpv4Address(): String? {
+    val wifiPrivateCandidates = mutableListOf<Inet4Address>()
+    val wifiCandidates = mutableListOf<Inet4Address>()
+    val privateCandidates = mutableListOf<Inet4Address>()
+    val otherCandidates = mutableListOf<Inet4Address>()
+    val interfaces = NetworkInterface.getNetworkInterfaces()?.toList().orEmpty()
+    for (networkInterface in interfaces) {
+      if (!networkInterface.isUp || networkInterface.isLoopback) {
+        continue
+      }
+      val addresses = networkInterface.inetAddresses.toList()
+        .filterIsInstance<Inet4Address>()
+        .filter { address ->
+          !address.isLoopbackAddress &&
+            !address.isLinkLocalAddress
+        }
+      if (isWifiInterface(networkInterface.name)) {
+        wifiPrivateCandidates += addresses.filter { isPrivateIpv4(it.hostAddress.orEmpty()) }
+        wifiCandidates += addresses
+      } else {
+        privateCandidates += addresses.filter { isPrivateIpv4(it.hostAddress.orEmpty()) }
+        otherCandidates += addresses
+      }
+    }
+
+    return (
+      wifiPrivateCandidates.firstOrNull() ?:
+        wifiCandidates.firstOrNull() ?:
+        privateCandidates.firstOrNull() ?:
+        otherCandidates.firstOrNull()
+      )?.hostAddress
+  }
+
+  private fun isWifiInterface(name: String): Boolean {
+    return name.startsWith("wlan") ||
+      name.startsWith("p2p") ||
+      name.startsWith("ap") ||
+      name.startsWith("swlan")
+  }
+
+  private fun isPrivateIpv4(host: String): Boolean {
+    return host.startsWith("192.168.") ||
+      host.startsWith("10.") ||
+      host.matches(Regex("^172\\.(1[6-9]|2[0-9]|3[0-1])\\..*"))
+  }
+}