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

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

@@ -1,7 +1,10 @@
 package com.mentra.bluetoothsdk
 
+import android.app.Activity
+import android.app.Application
 import android.bluetooth.BluetoothManager
 import android.content.Context
+import android.os.Bundle
 import android.os.Handler
 import android.os.Looper
 import com.mentra.bluetoothsdk.utils.ControllerTypes
@@ -30,6 +33,23 @@ class MentraBluetoothSdk private constructor(
     private val discoveredDeviceNames = mutableSetOf<String>()
     private val bridgeEventSinkId: String
     private val storeListenerId: String
+    private val activityLifecycleCallbacks =
+        object : Application.ActivityLifecycleCallbacks {
+            override fun onActivityResumed(activity: Activity) {
+                // Match the Mentra App's OnActivityEntersForeground hook. This runs after
+                // runtime permission dialogs in native host apps, allowing the service to
+                // replace its temporary dataSync type with connectedDevice/microphone/location.
+                deviceManager.refreshForegroundServiceTypes()
+            }
+
+            override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) = Unit
+            override fun onActivityStarted(activity: Activity) = Unit
+            override fun onActivityPaused(activity: Activity) = Unit
+            override fun onActivityStopped(activity: Activity) = Unit
+            override fun onActivitySaveInstanceState(activity: Activity, outState: Bundle) = Unit
+            override fun onActivityDestroyed(activity: Activity) = Unit
+        }
+    private var activityLifecycleCallbacksRegistered = false
     private var suppressDefaultDeviceEvents = false
     private val streamKeepAliveLock = Any()
     private var activeStreamKeepAlive: ActiveStreamKeepAlive? = null
@@ -57,6 +77,10 @@ class MentraBluetoothSdk private constructor(
         listeners.add(listener)
         Bridge.initialize(appContext)
         deviceManager = DeviceManager.getInstance()
+        (appContext as? Application)?.let { application ->
+            application.registerActivityLifecycleCallbacks(activityLifecycleCallbacks)
+            activityLifecycleCallbacksRegistered = true
+        }
         bridgeEventSinkId = Bridge.addEventSink { eventName, data -> dispatchBridgeEvent(eventName, data) }
         // Baseline the analytics connection state before subscribing to the store:
         // store updates invoke listeners synchronously on the updating thread, so a
@@ -258,6 +282,9 @@ class MentraBluetoothSdk private constructor(
             DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "device_name", device.name)
             DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "device_address", device.address ?: "")
             DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "project_name", device.projectName ?: "")
+            DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_name", "")
+            DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_address", "")
+            DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_secure_pairing_capable", "")
         } finally {
             suppressDefaultDeviceEvents = false
         }
@@ -271,6 +298,9 @@ class MentraBluetoothSdk private constructor(
             DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "device_name", "")
             DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "device_address", "")
             DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "project_name", "")
+            DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_name", "")
+            DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_address", "")
+            DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_secure_pairing_capable", "")
         } finally {
             suppressDefaultDeviceEvents = false
         }
@@ -383,8 +413,29 @@ class MentraBluetoothSdk private constructor(
                 cancelConnectionAttempt()
             }
         }
-        if (options.saveAsDefault && !isController) {
-            setDefaultDevice(device)
+        if (!isController) {
+            if (options.saveAsDefault) {
+                setDefaultDevice(device)
+            } else {
+                // Pairing uses saveAsDefault=false so default identity stays on the
+                // previous owner until handleDeviceReady. Stash the GATT target separately
+                // so MentraLive can connect by MAC without promoting getDefaultDevice().
+                DeviceStore.apply(
+                        ObservableStore.BLUETOOTH_CATEGORY,
+                        "pending_device_name",
+                        device.name,
+                )
+                DeviceStore.apply(
+                        ObservableStore.BLUETOOTH_CATEGORY,
+                        "pending_device_address",
+                        device.address ?: "",
+                )
+                DeviceStore.apply(
+                        ObservableStore.BLUETOOTH_CATEGORY,
+                        "pending_device_secure_pairing_capable",
+                        device.securePairingCapable ?: "",
+                )
+            }
         }
         DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_wearable", device.model.deviceType)
         deviceManager.connectByName(device.name)
@@ -408,6 +459,9 @@ class MentraBluetoothSdk private constructor(
     }
 
     fun cancelConnectionAttempt() {
+        DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_name", "")
+        DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_address", "")
+        DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_secure_pairing_capable", "")
         deviceManager.disconnect()
     }
 
@@ -416,6 +470,9 @@ class MentraBluetoothSdk private constructor(
     }
 
     fun disconnect() {
+        DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_name", "")
+        DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_address", "")
+        DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "pending_device_secure_pairing_capable", "")
         deviceManager.disconnect()
     }
 
@@ -856,6 +913,10 @@ class MentraBluetoothSdk private constructor(
         }
     }
 
+    fun setWifiAdbState(enabled: Boolean) {
+        deviceManager.setWifiAdbState(enabled)
+    }
+
     fun setSystemTime(timestampMs: Long) {
         deviceManager.setSystemTime(timestampMs)
     }
@@ -1087,6 +1148,25 @@ class MentraBluetoothSdk private constructor(
         }
     }
 
+    suspend fun queryVideoRecordingStatus(requestId: String): VideoRecordingStatusEvent {
+        require(requestId.isNotBlank()) { "requestId is required to query video recording status." }
+        requireGlassesConnected("query video recording status")
+        val pending = PendingResponse<VideoRecordingStatusEvent>("query video recording status")
+        val pendingRequest = PendingVideoRecordingRequest("recording_status", pending)
+        if (pendingVideoRecordingRequests.putIfAbsent(requestId, pendingRequest) != null) {
+            throw BluetoothSdkException(
+                "request_in_flight",
+                "A video recording command is already waiting for requestId $requestId.",
+            )
+        }
+        try {
+            deviceManager.queryVideoRecordingStatus(requestId)
+            return pending.await()
+        } finally {
+            pendingVideoRecordingRequests.remove(requestId, pendingRequest)
+        }
+    }
+
     suspend fun requestVersionInfo(): VersionInfoResult {
         val pending = PendingResponse<VersionInfoResult>("version info request")
         synchronized(oneShotLock) {
@@ -1110,11 +1190,13 @@ class MentraBluetoothSdk private constructor(
         }
     }
 
-    internal fun setOtaVersionUrl(otaVersionUrl: String) {
+    /** Select the HTTP(S) manifest used by subsequent OTA checks and installs. */
+    fun setOtaVersionUrl(otaVersionUrl: String) {
         configuredOtaVersionUrl = OtaManifestChecker.normalizeHttpUrl(otaVersionUrl)
     }
 
-    internal fun getOtaVersionUrl(): String = configuredOtaVersionUrl ?: OtaManifestDefaults.defaultOtaVersionUrl()
+    /** Return the configured OTA manifest, or this SDK release's default manifest. */
+    fun getOtaVersionUrl(): String = configuredOtaVersionUrl ?: OtaManifestDefaults.defaultOtaVersionUrl()
 
     /** Fetch the configured OTA manifest and return whether any ASG/BES/MTK update is available. */
     suspend fun checkForOtaUpdate(): Boolean {
@@ -1143,6 +1225,12 @@ class MentraBluetoothSdk private constructor(
         )
     }
 
+    /** Return bundled release changelogs crossed between two coordinated product versions, newest first. */
+    fun getReleaseChangelogs(
+        fromVersion: String? = null,
+        toVersion: String? = null,
+    ): List<ReleaseChangelog> = ReleaseChangelogCatalog.select(fromVersion, toVersion)
+
     /** Ask connected Mentra Live glasses to report the current OTA install/session status. */
     private suspend fun queryOtaStatus(): OtaQueryResult =
         performOtaQuery("OTA status query") {
@@ -1240,6 +1328,12 @@ class MentraBluetoothSdk private constructor(
                 systemTimeMs = versionInfo.systemTimeMs ?: status.systemTimeMs,
                 otaVersionUrl = versionInfo.otaVersionUrl.ifBlank { status.otaVersionUrl },
                 appVersion = versionInfo.appVersion.ifBlank { status.appVersion },
+                hotspotOtaVersion =
+                    if (versionInfo.hotspotOtaVersion > 0) {
+                        versionInfo.hotspotOtaVersion
+                    } else {
+                        status.hotspotOtaVersion
+                    },
             )
         } catch (cancellation: CancellationException) {
             // Never swallow cancellation into the stale-status fallback: callers
@@ -1323,6 +1417,12 @@ class MentraBluetoothSdk private constructor(
 
     override fun close() {
         stopStreamKeepAliveMonitor()
+        if (activityLifecycleCallbacksRegistered) {
+            (appContext as? Application)?.unregisterActivityLifecycleCallbacks(
+                activityLifecycleCallbacks,
+            )
+            activityLifecycleCallbacksRegistered = false
+        }
         Bridge.removeEventSink(bridgeEventSinkId)
         DeviceStore.store.removeListener(storeListenerId)
         analytics.shutdown()
@@ -1520,6 +1620,9 @@ class MentraBluetoothSdk private constructor(
                 }
                 dispatchToListeners { it.onGalleryStatus(event) }
             }
+            "pairing_info" -> {
+                dispatchToListeners { it.onRawEvent(eventName, data) }
+            }
             "photo_response" -> {
                 val event = PhotoResponseEvent(data)
                 handlePhotoResponseForRequests(event)
@@ -1567,10 +1670,19 @@ class MentraBluetoothSdk private constructor(
             }
             "ota_status" -> {
                 val resultValues = data + mapOf("type" to "ota_status")
+                val event = OtaStatusEvent.fromMap(resultValues)
                 synchronized(oneShotLock) {
                     pendingOtaQuery?.resolve(OtaQueryResult(resultValues))
+                    otaStartRejectionErrorCode(event)?.let { errorCode ->
+                        pendingOtaStart?.reject(
+                            BluetoothSdkException(errorCode, "Glasses rejected OTA start: $errorCode")
+                        )
+                    }
                 }
-                dispatchToListeners { it.onOtaStatus(OtaStatusEvent.fromMap(resultValues)) }
+                dispatchToListeners { it.onOtaStatus(event) }
+            }
+            "mic_health" -> {
+                dispatchToListeners { it.onMicHealth(MicHealthEvent.fromMap(data)) }
             }
             "settings_ack" -> {
                 val event = SettingsAckEvent(data)
@@ -2161,6 +2273,13 @@ class MentraBluetoothSdk private constructor(
     }
 }
 
-
-
-
+/** OTA status messages are not request-correlated, so only known pre-ack failures settle a start. */
+internal fun otaStartRejectionErrorCode(event: OtaStatusEvent): String? =
+    if (
+        event.status.equals("failed", ignoreCase = true) &&
+            event.errorMessage.equals("battery_low", ignoreCase = true)
+    ) {
+        "battery_low"
+    } else {
+        null
+    }

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])\\..*"))
+  }
+}