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

package/android/src/test/java/com/mentra/bluetoothsdk/services/ForegroundServiceTypeTest.kt

@@ -0,0 +1,69 @@
+package com.mentra.bluetoothsdk.services
+
+import android.content.pm.ServiceInfo
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class ForegroundServiceTypeTest {
+    @Test
+    fun `bootstrap starts as dataSync`() {
+        assertEquals(
+            ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC,
+            ForegroundService.bootstrapServiceType(),
+        )
+    }
+
+    @Test
+    fun `preferred types remove dataSync once connectedDevice is available`() {
+        val serviceType =
+            ForegroundService.preferredServiceType(
+                hasConnectedDeviceAccess = true,
+                hasMicrophoneAccess = false,
+                hasLocationAccess = false,
+                includeMediaPlayback = false,
+            )
+
+        assertTrue(
+            serviceType and ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE != 0,
+        )
+        assertEquals(
+            0,
+            serviceType and ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC,
+        )
+    }
+
+    @Test
+    fun `preferred types retain dataSync only when no better type is available`() {
+        val serviceType =
+            ForegroundService.preferredServiceType(
+                hasConnectedDeviceAccess = false,
+                hasMicrophoneAccess = false,
+                hasLocationAccess = false,
+                includeMediaPlayback = false,
+            )
+
+        assertEquals(
+            ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC,
+            serviceType,
+        )
+    }
+
+    @Test
+    fun `production mask never carries dataSync with media playback`() {
+        val serviceType =
+            ForegroundService.preferredServiceType(
+                hasConnectedDeviceAccess = true,
+                hasMicrophoneAccess = true,
+                hasLocationAccess = true,
+            )
+
+        assertEquals(
+            0,
+            serviceType and ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC,
+        )
+        assertTrue(
+            serviceType and ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK != 0,
+        )
+    }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/sgcs/MentraLiveGattCharacteristicsTest.kt

@@ -0,0 +1,39 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class MentraLiveGattCharacteristicsTest {
+    @Test
+    fun `accepts the core characteristic pair without requiring optional characteristics`() {
+        assertTrue(
+            hasRequiredMentraLiveCoreCharacteristics(
+                hasRxCharacteristic = true,
+                hasTxCharacteristic = true,
+            )
+        )
+    }
+
+    @Test
+    fun `rejects an incomplete core characteristic pair`() {
+        assertFalse(
+            hasRequiredMentraLiveCoreCharacteristics(
+                hasRxCharacteristic = false,
+                hasTxCharacteristic = true,
+            )
+        )
+        assertFalse(
+            hasRequiredMentraLiveCoreCharacteristics(
+                hasRxCharacteristic = true,
+                hasTxCharacteristic = false,
+            )
+        )
+        assertFalse(
+            hasRequiredMentraLiveCoreCharacteristics(
+                hasRxCharacteristic = false,
+                hasTxCharacteristic = false,
+            )
+        )
+    }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/sgcs/MentraLivePairingAdvertisementParserTest.kt

@@ -0,0 +1,75 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class MentraLivePairingAdvertisementParserTest {
+    @Test
+    fun parsesMarkedSecurePairingAdvertisement() {
+        val result = MentraLivePairingAdvertisementParser.parse(securePayload(pairingFlag = 1))
+
+        assertEquals("1234", result?.pairingCode)
+        assertTrue(result?.pairingMode == true)
+    }
+
+    @Test
+    fun parsesMarkedOwnedAdvertisement() {
+        val result = MentraLivePairingAdvertisementParser.parse(securePayload(pairingFlag = 0))
+
+        assertEquals("1234", result?.pairingCode)
+        assertFalse(result?.pairingMode == true)
+    }
+
+    @Test
+    fun rejectsLegacyPayloadThatMatchesOldVersionCapabilityHeuristic() {
+        val legacyPayload = ByteArray(27)
+        legacyPayload[5] = 0
+        legacyPayload[6] = 1
+        legacyPayload[7] = 1
+        legacyPayload[8] = 0x34
+        legacyPayload[9] = 0x12
+
+        assertNull(MentraLivePairingAdvertisementParser.parse(legacyPayload))
+    }
+
+    @Test
+    fun rejectsUnmarkedFirstGenerationSecureTrailer() {
+        val unmarkedPayload = securePayload(pairingFlag = 1)
+        unmarkedPayload[10] = 0x11
+        unmarkedPayload[11] = 0x22
+
+        assertNull(MentraLivePairingAdvertisementParser.parse(unmarkedPayload))
+    }
+
+    @Test
+    fun rejectsEveryLegacyVersionAndCapabilityCombination() {
+        for (version in 0..255) {
+            for (capability in 0..255) {
+                val legacyPayload = ByteArray(27)
+                legacyPayload[5] = 1
+                legacyPayload[6] = version.toByte()
+                legacyPayload[7] = capability.toByte()
+                legacyPayload[10] = 0x4D
+                // Offset 11 is padding in the legacy format, so it cannot contain the second
+                // non-zero marker byte.
+                legacyPayload[11] = 0
+                assertNull(MentraLivePairingAdvertisementParser.parse(legacyPayload))
+            }
+        }
+    }
+
+    private fun securePayload(pairingFlag: Int): ByteArray {
+        return ByteArray(27).also {
+            it[5] = pairingFlag.toByte()
+            it[6] = 2
+            it[7] = 1
+            it[8] = 0x34
+            it[9] = 0x12
+            it[10] = 0x4D
+            it[11] = 0x50
+        }
+    }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/utils/BleJsonCompactTest.java

@@ -43,10 +43,13 @@ public class BleJsonCompactTest {
         assertEquals("photo_status", compact.getString("t"));
         assertEquals("p1", compact.getString("r"));
         assertEquals(3, compact.getInt("s"));
-        assertEquals(100L, compact.getLong("ts"));
-        assertFalse(compact.has("rc"));
+        assertEquals(1_700_000_000_100L, compact.getLong("timestamp"));
+        assertFalse(compact.has("ts"));
+        assertTrue(compact.has("rc"));
+        assertFalse(compact.getBoolean("rc"));
         assertEquals(1, compact.getJSONObject("cm").getInt("aes"));
         assertEquals(1, compact.getJSONObject("cm").getInt("src"));
+        assertTrue(compact.toString().length() < input.toString().length());
     }
 
     @Test
@@ -73,7 +76,7 @@ public class BleJsonCompactTest {
     }
 
     @Test
-    public void resolvedConfigDiffOmitsRepeatPayload() throws Exception {
+    public void resolvedConfigIsAlwaysSent() throws Exception {
         BleJsonCompact.markSessionConnected(1_000L);
         JSONObject config = new JSONObject("{\"source\":\"sdk\",\"transferMethod\":\"auto\"}");
         JSONObject first =
@@ -99,13 +102,97 @@ public class BleJsonCompactTest {
         JSONObject secondWire = BleJsonCompact.encode(second);
 
         assertTrue(firstWire.has("resolvedConfig"));
-        assertFalse(secondWire.has("resolvedConfig"));
-        assertEquals(
-                BleJsonCompact.hashConfig(config),
-                secondWire.getString(BleJsonCompact.KEY_RESOLVED_CONFIG_HASH));
+        assertTrue(secondWire.has("resolvedConfig"));
+        assertFalse(secondWire.has(BleJsonCompact.KEY_RESOLVED_CONFIG_HASH));
 
+        BleJsonCompact.markSessionConnected(9_000L);
         JSONObject restoredSecond = BleJsonCompact.decode(secondWire);
         assertEquals("sdk", restoredSecond.getJSONObject("resolvedConfig").getString("source"));
+        assertEquals(1_200L, restoredSecond.getLong("timestamp"));
+    }
+
+    @Test
+    public void legacyResolvedConfigHashStillDecodesWhenCached() throws Exception {
+        JSONObject config = new JSONObject("{\"source\":\"sdk\",\"transferMethod\":\"auto\"}");
+        JSONObject full =
+                new JSONObject(
+                        "{\"t\":\"stream_status\",\"s\":\"streaming\",\"resolvedConfig\":"
+                                + config
+                                + "}");
+        BleJsonCompact.decode(full);
+        JSONObject hashOnly =
+                new JSONObject(
+                        "{\"t\":\"stream_status\",\"s\":\"streaming\",\"rch\":\""
+                                + BleJsonCompact.hashConfig(config)
+                                + "\"}");
+
+        JSONObject restored = BleJsonCompact.decode(hashOnly);
+
+        assertEquals("sdk", restored.getJSONObject("resolvedConfig").getString("source"));
+        assertFalse(restored.has(BleJsonCompact.KEY_RESOLVED_CONFIG_HASH));
+    }
+
+    @Test
+    public void legacyResolvedConfigCacheMissKeepsHashForDiagnostics() throws Exception {
+        JSONObject hashOnly =
+                new JSONObject(
+                        "{\"t\":\"stream_status\",\"s\":\"streaming\",\"rch\":\"deadbeef\"}");
+
+        JSONObject restored = BleJsonCompact.decode(hashOnly);
+
+        assertEquals("deadbeef", restored.getString(BleJsonCompact.KEY_RESOLVED_CONFIG_HASH));
+        assertFalse(restored.has("resolvedConfig"));
+    }
+
+    @Test
+    public void ambiguousNestedWireKeysFallBackToVerboseJson() throws Exception {
+        JSONObject input =
+                new JSONObject(
+                        "{\"type\":\"stream_status\",\"payload\":{"
+                                + "\"s\":\"literal\",\"kind\":0,\"source\":1}}");
+
+        JSONObject wire = BleJsonCompact.encode(input);
+
+        assertTrue(wire.has("type"));
+        assertFalse(wire.has("t"));
+        assertEquals("literal", wire.getJSONObject("payload").getString("s"));
+        assertEquals(0, wire.getJSONObject("payload").getInt("kind"));
+        assertEquals(1, wire.getJSONObject("payload").getInt("source"));
+        JSONObject restored = BleJsonCompact.decodeIfSupported(wire);
+        assertEquals("literal", restored.getJSONObject("payload").getString("s"));
+        assertEquals(0, restored.getJSONObject("payload").getInt("kind"));
+        assertEquals(1, restored.getJSONObject("payload").getInt("source"));
+    }
+
+    @Test
+    public void numericEnumFieldsFallBackToVerboseJson() throws Exception {
+        JSONObject input =
+                new JSONObject(
+                        "{\"type\":\"stream_status\",\"payload\":{\"kind\":0,\"source\":1}}");
+
+        JSONObject wire = BleJsonCompact.encode(input);
+
+        assertTrue(wire.has("type"));
+        assertFalse(wire.has("t"));
+        assertEquals(0, wire.getJSONObject("payload").getInt("kind"));
+        assertEquals(1, wire.getJSONObject("payload").getInt("source"));
+    }
+
+    @Test
+    public void absoluteTimestampSurvivesDifferentSessionEpochs() throws Exception {
+        BleJsonCompact.markSessionConnected(1_000L);
+        JSONObject input =
+                new JSONObject(
+                        "{\"type\":\"stream_status\",\"status\":\"streaming\","
+                                + "\"timestamp\":1700000000123}");
+
+        JSONObject wire = BleJsonCompact.encode(input);
+        BleJsonCompact.markSessionConnected(9_000L);
+        JSONObject restored = BleJsonCompact.decode(wire);
+
+        assertEquals(1_700_000_000_123L, wire.getLong("timestamp"));
+        assertFalse(wire.has("ts"));
+        assertEquals(1_700_000_000_123L, restored.getLong("timestamp"));
     }
 
     @Test
@@ -135,6 +222,60 @@ public class BleJsonCompactTest {
         assertEquals("wifi_scan_result", BleJsonCompact.encode(wifiScan).getString("t"));
     }
 
+    @Test
+    public void startStreamPreservesDisabledSound() throws Exception {
+        JSONObject start =
+                new JSONObject(
+                        "{\"type\":\"start_stream\",\"streamUrl\":\"https://example.test/whip\","
+                                + "\"sound\":false}");
+
+        JSONObject wire = BleJsonCompact.encode(start);
+
+        assertEquals("start_stream", wire.getString("t"));
+        assertTrue(wire.has("sound"));
+        assertFalse(wire.getBoolean("sound"));
+        assertFalse(BleJsonCompact.decode(wire).getBoolean("sound"));
+    }
+
+    @Test
+    public void jsonValuesRoundTripAtEveryDepth() throws Exception {
+        JSONObject status =
+                new JSONObject(
+                        "{\"type\":\"stream_status\",\"status\":\"stopped\","
+                                + "\"streaming\":false,\"reconnecting\":false,"
+                                + "\"resolvedConfig\":{\"audio\":{\"echoCancellation\":false,"
+                                + "\"noiseSuppression\":false}},"
+                                + "\"nullValue\":null,\"emptyObject\":{},\"emptyArray\":[]}");
+
+        JSONObject wire = BleJsonCompact.encode(status);
+
+        assertTrue(wire.has("streaming"));
+        assertFalse(wire.getBoolean("streaming"));
+        assertTrue(wire.has("rc"));
+        assertFalse(wire.getBoolean("rc"));
+        JSONObject wireAudio = wire.getJSONObject("resolvedConfig").getJSONObject("audio");
+        assertTrue(wireAudio.has("echoCancellation"));
+        assertFalse(wireAudio.getBoolean("echoCancellation"));
+        assertTrue(wireAudio.has("noiseSuppression"));
+        assertFalse(wireAudio.getBoolean("noiseSuppression"));
+        assertTrue(wire.has("nullValue"));
+        assertTrue(wire.isNull("nullValue"));
+        assertEquals(0, wire.getJSONObject("emptyObject").length());
+        assertEquals(0, wire.getJSONArray("emptyArray").length());
+
+        JSONObject restored = BleJsonCompact.decode(wire);
+        assertFalse(restored.getBoolean("streaming"));
+        assertFalse(restored.getBoolean("reconnecting"));
+        JSONObject restoredAudio =
+                restored.getJSONObject("resolvedConfig").getJSONObject("audio");
+        assertFalse(restoredAudio.getBoolean("echoCancellation"));
+        assertFalse(restoredAudio.getBoolean("noiseSuppression"));
+        assertTrue(restored.has("nullValue"));
+        assertTrue(restored.isNull("nullValue"));
+        assertEquals(0, restored.getJSONObject("emptyObject").length());
+        assertEquals(0, restored.getJSONArray("emptyArray").length());
+    }
+
     @Test
     public void streamTelemetryRoundTripsWithCompactKeys() throws Exception {
         JSONObject status =

package/build/BluetoothSdk.types.d.ts

@@ -128,6 +128,8 @@ export type VersionInfoResult = {
     systemTimeMs?: number;
     otaVersionUrl: string;
     appVersion: string;
+    /** Phone-served hotspot OTA protocol version; 0 means unsupported/legacy glasses. */
+    hotspotOtaVersion: number;
 };
 export type VersionInfoEvent = VersionInfoResult & {
     type: "version_info";
@@ -532,6 +534,20 @@ export type PairFailureEvent = {
     type: "pair_failure";
     error: string;
 };
+export type PairingInfoEvent = {
+    had_previous_bond: boolean;
+    pairing_code?: string;
+    classic_bond_ready?: boolean;
+    secure_pairing_capable?: boolean;
+    protocol_version?: number;
+};
+export type EnteringPairingModeEvent = {
+    window_ms: number;
+    reason?: string;
+};
+export type OwnerReplacedEvent = {
+    reason: string;
+};
 export type AudioPairingNeededEvent = {
     type: "audio_pairing_needed";
     deviceName: string;
@@ -577,6 +593,16 @@ export type MicLc3Event = {
     packetizedFromGlasses: boolean;
     voiceActivityDetectionEnabled: boolean;
 };
+/** Native glasses-microphone diagnostics emitted when the SDK detects a transport or decode issue. */
+export type MicHealthEvent = {
+    type: "mic_health";
+    reason: "sequence_gap" | "decode_failure";
+    sequenceGapEvents: number;
+    decodeFailures: number;
+    lastLc3ReceivedAt?: number;
+    lastPcmProducedAt?: number;
+    timestamp: number;
+};
 export type StreamStatusLifecycleState = "initializing" | "streaming" | "stopping" | "stopped";
 export type StreamStatusReconnectState = "reconnecting" | "reconnected" | "reconnect_failed";
 export type StreamStatusState = StreamStatusLifecycleState | StreamStatusReconnectState | "error";
@@ -751,6 +777,9 @@ export type BluetoothSdkModuleEvents = {
     rgb_led_control_response: (event: RgbLedControlResponseEvent) => void;
     settings_ack: (event: SettingsAckEvent) => void;
     pair_failure: (event: PairFailureEvent) => void;
+    pairing_info: (event: PairingInfoEvent) => void;
+    entering_pairing_mode: (event: EnteringPairingModeEvent) => void;
+    owner_replaced: (event: OwnerReplacedEvent) => void;
     audio_pairing_needed: (event: AudioPairingNeededEvent) => void;
     audio_connected: (event: AudioConnectedEvent) => void;
     audio_disconnected: (event: AudioDisconnectedEvent) => void;
@@ -759,6 +788,7 @@ export type BluetoothSdkModuleEvents = {
     ws_bin: (event: WsBinEvent) => void;
     mic_pcm: (event: MicPcmEvent) => void;
     mic_lc3: (event: MicLc3Event) => void;
+    mic_health: (event: MicHealthEvent) => void;
     stream_status: (event: StreamStatusEvent) => void;
     keep_alive_ack: (event: KeepAliveAckEvent) => void;
     mtk_update_complete: (event: MtkUpdateCompleteEvent) => void;
@@ -835,11 +865,15 @@ export type BluetoothSdkEventMap = {
     rgb_led_control_response: RgbLedControlResponseEvent;
     settings_ack: SettingsAckEvent;
     pair_failure: PairFailureEvent;
+    pairing_info: PairingInfoEvent;
+    entering_pairing_mode: EnteringPairingModeEvent;
+    owner_replaced: OwnerReplacedEvent;
     audio_pairing_needed: AudioPairingNeededEvent;
     audio_connected: AudioConnectedEvent;
     audio_disconnected: AudioDisconnectedEvent;
     mic_pcm: MicPcmEvent;
     mic_lc3: MicLc3Event;
+    mic_health: MicHealthEvent;
     stream_status: StreamStatusEvent;
     ota_start_ack: OtaStartAckEvent;
     ota_status: OtaStatusEvent;
@@ -878,6 +912,8 @@ export interface BluetoothSdkPublicModule {
     sendWifiCredentials(ssid: string, password: string): Promise<WifiStatusChangeEvent>;
     forgetWifiNetwork(ssid: string): Promise<WifiStatusChangeEvent>;
     setHotspotState(enabled: boolean): Promise<HotspotStatusChangeEvent>;
+    /** Enable or disable Wi-Fi ADB on Mentra Live (no-op on other devices). */
+    setWifiAdbState(enabled: boolean): Promise<void>;
     setGalleryModeEnabled(enabled: boolean): Promise<SettingsAckSuccessEvent>;
     setVoiceActivityDetectionEnabled(enabled: boolean): Promise<void>;
     setLoudnessGateEnabled(enabled: boolean): Promise<void>;
@@ -922,6 +958,8 @@ export interface BluetoothSdkPublicModule {
      * the video on device (no upload).
      */
     stopVideoRecording(requestId: string, webhookUrl?: string, authToken?: string): Promise<VideoRecordingStoppedStatusEvent>;
+    /** Query the glasses for the current recording state and elapsed duration. */
+    queryVideoRecordingStatus(requestId: string): Promise<VideoRecordingStatusEvent>;
     startStream(params: StreamStartRequest): Promise<StreamStatusEvent>;
     stopStream(): Promise<StreamStatusEvent>;
     setMicState(enabled: boolean, useGlassesMic?: boolean, sendTranscript?: boolean, sendLc3Data?: boolean): Promise<void>;
@@ -931,10 +969,17 @@ export interface BluetoothSdkPublicModule {
     setGlassesMediaVolume(level: number): Promise<GlassesMediaVolumeSetResult>;
     rgbLedControl(requestId: string, packageName: string | null, action: RgbLedAction, color: RgbLedColor | null, onDurationMs: number, offDurationMs: number, count: number): Promise<RgbLedControlSuccessResponseEvent>;
     requestVersionInfo(): Promise<VersionInfoResult>;
+    /**
+     * Select the OTA manifest used by subsequent update checks and installs.
+     * The URL may point at Mentra's hosted manifest or any customer-controlled HTTP(S) server.
+     */
+    setOtaVersionUrl(otaVersionUrl: string): void;
+    /** Return the configured or release-embedded OTA manifest URL. Rejects when a source build is unconfigured. */
+    getOtaVersionUrl(): string;
     /** Fetch the configured OTA manifest and return whether any ASG/BES/MTK update is available. */
     checkForOtaUpdate(): Promise<boolean>;
-    /** Start the OTA flow with the same configured manifest URL used by checkForOtaUpdate(). */
-    startOtaUpdate(): Promise<OtaStartAckEvent>;
+    /** Start OTA from the configured or explicitly supplied manifest URL. */
+    startOtaUpdate(otaVersionUrl?: string | null): Promise<OtaStartAckEvent>;
     startAr99OtaFromFile(path: string): Promise<boolean>;
     cancelAr99Ota(): Promise<void>;
     sendAr99FactoryReset(): Promise<void>;
@@ -1000,6 +1045,7 @@ export interface GlassesStatus {
     besFirmwareVersion: string;
     mtkFirmwareVersion: string;
     bluetoothMacAddress: string;
+    wifiMacAddress: string;
     leftMacAddress: string;
     rightMacAddress: string;
     buildNumber: string;
@@ -1007,6 +1053,8 @@ export interface GlassesStatus {
     systemTimeMs?: number;
     otaVersionUrl: string;
     appVersion: string;
+    /** Phone-served hotspot OTA protocol version; 0 means unsupported/legacy glasses. */
+    hotspotOtaVersion: number;
     bluetoothName: string;
     serialNumber: string;
     style: string;
@@ -1061,6 +1109,12 @@ export interface Device {
      * appear in a later scan update when the platform reports RSSI metadata.
      */
     rssi?: number;
+    /** Mentra Live: unit is currently in pairing mode (adv flag). */
+    pairingMode?: boolean;
+    /** Mentra Live: four-character hex spoken pairing code when available. */
+    pairingCode?: string;
+    /** Mentra Live: advertisement carries the secure-pairing capability trailer. */
+    securePairingCapable?: boolean;
 }
 export interface ConnectOptions {
     saveAsDefault?: boolean;