@mentra/bluetooth-sdk 3.2.0-dev.216 → 3.2.0-dev.221

package/README.md

@@ -29,6 +29,15 @@ to its existing retention limits. Native diagnostics are also kept in the native
 console. Forwarding covers SDK-owned diagnostics while the JS runtime is active,
 not arbitrary OS or third-party native logs or logs from before subscription.
 
+On Android, forwarding to JavaScript is capped at 100 messages per second. Each
+forwarded message holds a JNI global reference until the JavaScript thread drains
+it, so an unbounded log source can exhaust the process-wide reference table and
+abort the app rather than merely slow it down. Messages above the cap are withheld
+from the JavaScript stream only — they are still written to the native console —
+and the next forwarded message is preceded by a notice saying how many were
+withheld. Per-frame microphone payload events are not traced at all; audio faults
+are still reported through the `mic_health` event.
+
 Rebuild the native app after updating the SDK to pick up both platforms' logging
 changes. Adding this JS package alone cannot reroute logs in an older binary.
 

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

@@ -133,6 +133,7 @@ private inline fun <
 class BluetoothSdkModule : Module() {
     private var sdk: MentraBluetoothSdk? = null
     private var deviceManager: DeviceManager? = null
+    private val logForwarding = LogForwardingBudget()
     private val sdkListener =
             object : MentraBluetoothSdkListener {
                 override fun onGlassesChanged(glasses: GlassesRuntimeState) {
@@ -295,6 +296,16 @@ class BluetoothSdkModule : Module() {
                 }
 
                 override fun onLog(message: String) {
+                    // Each event pins a JNI global reference until JavaScript drains it. The
+                    // log stream is the one source whose rate is unbounded, so it is budgeted.
+                    val withheld = logForwarding.admit() ?: return
+                    if (withheld > 0) {
+                        val notice =
+                                "[W/BluetoothSdkModule] withheld $withheld native log line(s) from " +
+                                        "JavaScript to stay under ${logForwarding.maxPerWindow}/s; " +
+                                        "logcat has them all"
+                        sendEvent("log", mapOf("message" to notice))
+                    }
                     sendEvent("log", mapOf("message" to message))
                 }
 

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

@@ -30,18 +30,6 @@ public class Bridge private constructor() {
         private const val MIC_CHANNELS = 1
         private const val LC3_FRAME_DURATION_MS = 10
         private const val DEFAULT_LC3_FRAME_SIZE_BYTES = 60
-        private val AUDIO_TRACE_METADATA_KEYS =
-                listOf(
-                        "sampleRate",
-                        "bitsPerSample",
-                        "channels",
-                        "encoding",
-                        "frameDurationMs",
-                        "frameSizeBytes",
-                        "bitrate",
-                        "packetizedFromGlasses",
-                        "voiceActivityDetectionEnabled",
-                )
 
         @Volatile private var instance: Bridge? = null
 
@@ -943,43 +931,29 @@ public class Bridge private constructor() {
             }
         }
 
+        /**
+         * Returns null for events that must not be traced.
+         *
+         * "log" is excluded so tracing never recurses back through NativeLog. Audio payload
+         * events are excluded because they arrive at frame rate: tracing them turned every
+         * microphone frame into a second bridge event, and each of those pins a JNI global
+         * reference until JavaScript drains it. A JavaScript thread busy with call audio
+         * cannot keep up, so the references accumulated until the process-wide table
+         * overflowed and the runtime aborted. Audio faults (sequence gaps, decode failures)
+         * are still reported through "mic_health", and healthy frames need no trace.
+         */
         private fun tracePayloadForTypedMessage(
                 type: String,
                 body: Map<String, Any>
         ): Map<String, Any>? =
                 when {
                     type == "log" -> null
-                    isAudioPayloadEvent(type) -> audioTracePayload(type, body)
+                    isAudioPayloadEvent(type) -> null
                     else -> body
                 }
 
         private fun isAudioPayloadEvent(type: String): Boolean =
                 type == "mic_pcm" || type == "mic_lc3"
-
-        private fun audioTracePayload(type: String, body: Map<String, Any>): Map<String, Any> {
-            val payload = HashMap<String, Any>()
-            payload["type"] = type
-            payload["timestamp"] = System.currentTimeMillis()
-            payload["payloadOmitted"] = true
-            payload["payloadOmittedReason"] = "audio"
-
-            val audioBytes =
-                    when (type) {
-                        "mic_pcm" -> (body["pcm"] as? ByteArray)?.size
-                        "mic_lc3" -> (body["lc3"] as? ByteArray)?.size
-                        else -> null
-                    }
-            audioBytes?.let { payload["audioBytes"] = it }
-
-            AUDIO_TRACE_METADATA_KEYS.forEach { key ->
-                val value = body[key]
-                if (value != null) {
-                    payload[key] = value
-                }
-            }
-
-            return payload
-        }
     }
 
     init {

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.216"
-    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.216"
-    const val SOURCE_COMMIT: String = "4dc8e8b75c7a782abb2a9dead146d023d2fe45d6"
-    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.216.json"
-    const val OTA_MANIFEST_SHA256: String = "e0b87036ab2c104b97dcf1a6910d3b0da114c59047ee29dbecf747647cbdcd9a"
+    const val RELEASE_IDENTITY: String = "3.2.0-dev.221"
+    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.221"
+    const val SOURCE_COMMIT: String = "3837a3055e7a69e18553ce51c3a97579d2ad3b83"
+    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.221.json"
+    const val OTA_MANIFEST_SHA256: String = "657e9616ad0c464ee57d827c05b53393e45559992c13b15adbb06e0c903eb870"
 }

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

@@ -0,0 +1,50 @@
+package com.mentra.bluetoothsdk
+
+import android.os.SystemClock
+
+/**
+ * Bounds how many native log lines per second the module hands to the JavaScript runtime.
+ *
+ * Every event the module emits pins a JNI global reference until the JavaScript thread
+ * drains it, and the process-wide table holds about 51,200 references. Native code can log
+ * faster than a busy JavaScript thread drains, so an unbounded log stream aborts the process
+ * instead of merely lagging. Lines over the budget are withheld from JavaScript only; the
+ * native console still has every one of them. The first line forwarded after a shortfall
+ * reports how many were withheld, so the gap is visible in the JavaScript stream.
+ */
+internal class LogForwardingBudget(
+    val maxPerWindow: Int = DEFAULT_MAX_PER_SECOND,
+    private val windowMs: Long = 1_000L,
+    private val clock: () -> Long = SystemClock::elapsedRealtime,
+) {
+    private var windowEndsAtMs = Long.MIN_VALUE
+    private var forwardedInWindow = 0
+    private var withheld = 0
+
+    /**
+     * Returns null when the current line must be withheld, otherwise the number of lines
+     * withheld since the previous forwarded one (zero in steady state).
+     */
+    @Synchronized
+    fun admit(): Int? {
+        val now = clock()
+        if (now >= windowEndsAtMs) {
+            windowEndsAtMs = now + windowMs
+            forwardedInWindow = 0
+        }
+        if (forwardedInWindow >= maxPerWindow) {
+            withheld++
+            return null
+        }
+        forwardedInWindow++
+        return withheld.also { withheld = 0 }
+    }
+
+    companion object {
+        /**
+         * Far above the SDK's steady-state diagnostic rate, and low enough that a
+         * JavaScript thread has to stay stalled for minutes before the table could fill.
+         */
+        const val DEFAULT_MAX_PER_SECOND = 100
+    }
+}

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

@@ -0,0 +1,49 @@
+package com.mentra.bluetoothsdk
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+class LogForwardingBudgetTest {
+    private var nowMs = 0L
+    private val budget = LogForwardingBudget(maxPerWindow = 3, windowMs = 1_000L, clock = { nowMs })
+
+    @Test
+    fun `forwards up to the budget within a window and withholds the rest`() {
+        assertEquals(0, budget.admit())
+        assertEquals(0, budget.admit())
+        assertEquals(0, budget.admit())
+        assertNull(budget.admit())
+        assertNull(budget.admit())
+    }
+
+    @Test
+    fun `the first line forwarded after a shortfall reports how many were withheld`() {
+        repeat(5) { budget.admit() }
+
+        nowMs = 1_000L
+        assertEquals(2, budget.admit())
+        assertEquals(0, budget.admit())
+    }
+
+    @Test
+    fun `the budget renews every window`() {
+        repeat(5) { budget.admit() }
+        nowMs = 999L
+        assertNull(budget.admit())
+
+        nowMs = 1_000L
+        assertEquals(3, budget.admit())
+        assertEquals(0, budget.admit())
+        assertEquals(0, budget.admit())
+        assertNull(budget.admit())
+    }
+
+    @Test
+    fun `withheld lines are reported even after a long silence`() {
+        repeat(4) { budget.admit() }
+
+        nowMs = 60_000L
+        assertEquals(1, budget.admit())
+    }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/utils/NativeLogTest.kt

@@ -58,4 +58,19 @@ class NativeLogTest {
             Bridge.removeEventSink(healthy)
         }
     }
+
+    @Test
+    fun audioPayloadEventsAreNotTracedIntoTheLogStream() {
+        val events = mutableListOf<String>()
+        val sink = Bridge.addEventSink { type, _ -> events.add(type) }
+        try {
+            Bridge.sendTypedMessage("mic_pcm", mapOf("pcm" to ByteArray(320)))
+            Bridge.sendTypedMessage("mic_lc3", mapOf("lc3" to ByteArray(60)))
+            // Tracing these would emit a second bridge event per audio frame, and each one
+            // pins a JNI global reference until JavaScript drains it.
+            assertEquals(listOf("mic_pcm", "mic_lc3"), events)
+        } finally {
+            Bridge.removeEventSink(sink)
+        }
+    }
 }

package/build/generated/releaseMetadata.js

@@ -1,10 +1,10 @@
 export const BLUETOOTH_SDK_RELEASE_METADATA = Object.freeze({
     "schemaVersion": 1,
     "familyBaseVersion": "3.2.0",
-    "releaseIdentity": "3.2.0-dev.216",
-    "releaseSetId": "mentra-3.2.0-dev.216",
-    "sourceCommit": "4dc8e8b75c7a782abb2a9dead146d023d2fe45d6",
-    "otaManifestUrl": "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.216.json",
-    "otaManifestSha256": "e0b87036ab2c104b97dcf1a6910d3b0da114c59047ee29dbecf747647cbdcd9a"
+    "releaseIdentity": "3.2.0-dev.221",
+    "releaseSetId": "mentra-3.2.0-dev.221",
+    "sourceCommit": "3837a3055e7a69e18553ce51c3a97579d2ad3b83",
+    "otaManifestUrl": "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.221.json",
+    "otaManifestSha256": "657e9616ad0c464ee57d827c05b53393e45559992c13b15adbb06e0c903eb870"
 });
 //# sourceMappingURL=releaseMetadata.js.map

package/build/generated/releaseMetadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"releaseMetadata.js","sourceRoot":"","sources":["../../src/generated/releaseMetadata.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,8BAA8B,GAA0C,MAAM,CAAC,MAAM,CAAC;IACjG,eAAe,EAAE,CAAC;IAClB,mBAAmB,EAAE,OAAO;IAC5B,iBAAiB,EAAE,eAAe;IAClC,cAAc,EAAE,sBAAsB;IACtC,cAAc,EAAE,0CAA0C;IAC1D,gBAAgB,EAAE,wHAAwH;IAC1I,mBAAmB,EAAE,kEAAkE;CACxF,CAAC,CAAA","sourcesContent":["/** Generated by release CI. Do not edit in a release checkout. */\nexport interface BluetoothSdkReleaseMetadata {\n  schemaVersion: 1\n  familyBaseVersion: string | null\n  releaseIdentity: string | null\n  releaseSetId: string | null\n  sourceCommit: string | null\n  otaManifestUrl: string | null\n  otaManifestSha256: string | null\n}\n\nexport const BLUETOOTH_SDK_RELEASE_METADATA: Readonly<BluetoothSdkReleaseMetadata> = Object.freeze({\n  \"schemaVersion\": 1,\n  \"familyBaseVersion\": \"3.2.0\",\n  \"releaseIdentity\": \"3.2.0-dev.216\",\n  \"releaseSetId\": \"mentra-3.2.0-dev.216\",\n  \"sourceCommit\": \"4dc8e8b75c7a782abb2a9dead146d023d2fe45d6\",\n  \"otaManifestUrl\": \"https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.216.json\",\n  \"otaManifestSha256\": \"e0b87036ab2c104b97dcf1a6910d3b0da114c59047ee29dbecf747647cbdcd9a\"\n})\n"]}
+{"version":3,"file":"releaseMetadata.js","sourceRoot":"","sources":["../../src/generated/releaseMetadata.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,8BAA8B,GAA0C,MAAM,CAAC,MAAM,CAAC;IACjG,eAAe,EAAE,CAAC;IAClB,mBAAmB,EAAE,OAAO;IAC5B,iBAAiB,EAAE,eAAe;IAClC,cAAc,EAAE,sBAAsB;IACtC,cAAc,EAAE,0CAA0C;IAC1D,gBAAgB,EAAE,wHAAwH;IAC1I,mBAAmB,EAAE,kEAAkE;CACxF,CAAC,CAAA","sourcesContent":["/** Generated by release CI. Do not edit in a release checkout. */\nexport interface BluetoothSdkReleaseMetadata {\n  schemaVersion: 1\n  familyBaseVersion: string | null\n  releaseIdentity: string | null\n  releaseSetId: string | null\n  sourceCommit: string | null\n  otaManifestUrl: string | null\n  otaManifestSha256: string | null\n}\n\nexport const BLUETOOTH_SDK_RELEASE_METADATA: Readonly<BluetoothSdkReleaseMetadata> = Object.freeze({\n  \"schemaVersion\": 1,\n  \"familyBaseVersion\": \"3.2.0\",\n  \"releaseIdentity\": \"3.2.0-dev.221\",\n  \"releaseSetId\": \"mentra-3.2.0-dev.221\",\n  \"sourceCommit\": \"3837a3055e7a69e18553ce51c3a97579d2ad3b83\",\n  \"otaManifestUrl\": \"https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.221.json\",\n  \"otaManifestSha256\": \"657e9616ad0c464ee57d827c05b53393e45559992c13b15adbb06e0c903eb870\"\n})\n"]}

package/ios/Source/BluetoothSdkDefaults.swift

@@ -11,7 +11,7 @@ enum BluetoothSdkDefaults {
     static let voiceActivityDetectionEnabled = false
     static let loudnessGateEnabled = false
     private static let infoSdkVersionKey = "MentraBluetoothSdkVersion"
-    private static let swiftPackageSdkVersion = "3.2.0-dev.216"
+    private static let swiftPackageSdkVersion = "3.2.0-dev.221"
     private static let swiftPackageSdkVersionPlaceholder = "__MENTRA" + "_BLUETOOTH_SDK_VERSION__"
 
     private static func normalizedSdkVersion(_ value: String?) -> String? {

package/ios/Source/Bridge.swift

@@ -15,17 +15,6 @@ class Bridge {
     private static let micChannels = 1
     private static let lc3FrameDurationMs = 10
     private static let defaultLc3FrameSizeBytes = 60
-    private static let audioTraceMetadataKeys = [
-        "sampleRate",
-        "bitsPerSample",
-        "channels",
-        "encoding",
-        "frameDurationMs",
-        "frameSizeBytes",
-        "bitrate",
-        "packetizedFromGlasses",
-        "voiceActivityDetectionEnabled",
-    ]
     private static let eventSinkLock = NSLock()
     private static let defaultEventSinkId = "default"
     private static var eventSinks: [String: (String, [String: Any]) -> Void] = [:]
@@ -700,47 +689,22 @@ class Bridge {
         dispatchEvent(type, body)
     }
 
+    /// Returns nil for events that must not be traced.
+    ///
+    /// "log" is excluded so tracing never recurses back through the log event. Audio payload
+    /// events are excluded because they arrive at frame rate, which made every microphone
+    /// frame emit a second bridge event. On Android that overflowed the JNI global reference
+    /// table and aborted the process; here it is wasted work on the audio path. Audio faults
+    /// (sequence gaps, decode failures) are still reported through "mic_health", and healthy
+    /// frames need no trace.
     private static func tracePayloadForTypedMessage(_ type: String, body: [String: Any]) -> [String: Any]? {
-        if type == "log" {
+        if type == "log" || isAudioPayloadEvent(type) {
             return nil
         }
-        if isAudioPayloadEvent(type) {
-            return audioTracePayload(type, body: body)
-        }
         return body
     }
 
     private static func isAudioPayloadEvent(_ type: String) -> Bool {
         type == "mic_pcm" || type == "mic_lc3"
     }
-
-    private static func audioTracePayload(_ type: String, body: [String: Any]) -> [String: Any] {
-        var payload: [String: Any] = [
-            "type": type,
-            "timestamp": Int(Date().timeIntervalSince1970 * 1000),
-            "payloadOmitted": true,
-            "payloadOmittedReason": "audio",
-        ]
-
-        switch type {
-        case "mic_pcm":
-            if let data = body["pcm"] as? Data {
-                payload["audioBytes"] = data.count
-            }
-        case "mic_lc3":
-            if let data = body["lc3"] as? Data {
-                payload["audioBytes"] = data.count
-            }
-        default:
-            break
-        }
-
-        for key in audioTraceMetadataKeys {
-            if let value = body[key] {
-                payload[key] = value
-            }
-        }
-
-        return payload
-    }
 }

package/ios/Source/GeneratedReleaseMetadata.swift

@@ -3,9 +3,9 @@ import Foundation
 /// Generated by release CI. Do not edit in a release checkout.
 enum GeneratedReleaseMetadata {
     static let familyBaseVersion = "3.2.0"
-    static let releaseIdentity = "3.2.0-dev.216"
-    static let releaseSetId = "mentra-3.2.0-dev.216"
-    static let sourceCommit = "4dc8e8b75c7a782abb2a9dead146d023d2fe45d6"
-    static let otaManifestUrl = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.216.json"
-    static let otaManifestSha256 = "e0b87036ab2c104b97dcf1a6910d3b0da114c59047ee29dbecf747647cbdcd9a"
+    static let releaseIdentity = "3.2.0-dev.221"
+    static let releaseSetId = "mentra-3.2.0-dev.221"
+    static let sourceCommit = "3837a3055e7a69e18553ce51c3a97579d2ad3b83"
+    static let otaManifestUrl = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.221.json"
+    static let otaManifestSha256 = "657e9616ad0c464ee57d827c05b53393e45559992c13b15adbb06e0c903eb870"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/bluetooth-sdk",
-  "version": "3.2.0-dev.216",
+  "version": "3.2.0-dev.221",
   "description": "SDK for communicating with smart glasses",
   "main": "build/index.js",
   "react-native": "src/index.ts",

package/src/generated/releaseMetadata.ts

@@ -12,9 +12,9 @@ export interface BluetoothSdkReleaseMetadata {
 export const BLUETOOTH_SDK_RELEASE_METADATA: Readonly<BluetoothSdkReleaseMetadata> = Object.freeze({
   "schemaVersion": 1,
   "familyBaseVersion": "3.2.0",
-  "releaseIdentity": "3.2.0-dev.216",
-  "releaseSetId": "mentra-3.2.0-dev.216",
-  "sourceCommit": "4dc8e8b75c7a782abb2a9dead146d023d2fe45d6",
-  "otaManifestUrl": "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.216.json",
-  "otaManifestSha256": "e0b87036ab2c104b97dcf1a6910d3b0da114c59047ee29dbecf747647cbdcd9a"
+  "releaseIdentity": "3.2.0-dev.221",
+  "releaseSetId": "mentra-3.2.0-dev.221",
+  "sourceCommit": "3837a3055e7a69e18553ce51c3a97579d2ad3b83",
+  "otaManifestUrl": "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.221.json",
+  "otaManifestSha256": "657e9616ad0c464ee57d827c05b53393e45559992c13b15adbb06e0c903eb870"
 })