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

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

@@ -0,0 +1,86 @@
+package com.mentra.bluetoothsdk
+
+import org.json.JSONObject
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Assert.fail
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [33])
+class OtaManifestDowngradeTest {
+
+    private fun manifest(versionCode: Long): JSONObject =
+        JSONObject()
+            .put("apps", JSONObject().put("com.mentra.asg_client", JSONObject().put("versionCode", versionCode)))
+
+    private fun hasUpdate(
+        currentBuildNumber: String,
+        manifest: JSONObject,
+        floor: Long = 0L,
+    ): Boolean =
+        OtaManifestChecker.hasUpdate(
+            currentBuildNumber = currentBuildNumber,
+            currentMtkVersion = "",
+            currentBesVersion = "",
+            manifest = manifest,
+            downgradeFloorVersionCode = floor,
+        )
+
+    @Test
+    fun upgradeIsAlwaysAnUpdate() {
+        assertTrue(hasUpdate("49000000", manifest(49076573L)))
+    }
+
+    @Test
+    fun exactPinIsNotAnUpdateEvenWithAnEnabledFloor() {
+        assertFalse(hasUpdate("49000000", manifest(49000000L), floor = 49000000L))
+    }
+
+    @Test
+    fun downgradeNeedsAnEnabledFloor() {
+        // Default floor 0 (fail closed) disables downgrades for native/OEM callers.
+        assertFalse(hasUpdate("49076573", manifest(49000000L)))
+        // A positive floor at/below the pin enables it.
+        assertTrue(hasUpdate("49076573", manifest(49000000L), floor = 49000000L))
+        // A pin below the floor is refused.
+        assertFalse(hasUpdate("49076573", manifest(48999999L), floor = 49000000L))
+    }
+
+    @Test
+    fun exactPinIsNotAnUpdate() {
+        assertFalse(hasUpdate("49076573", manifest(49076573L)))
+    }
+
+    private fun legacyTopLevelManifest(versionCode: Long): JSONObject =
+        JSONObject().put("versionCode", versionCode)
+
+    @Test
+    fun legacyTopLevelManifestStaysUpgradeOnly() {
+        // No apps entry -> not an exact pin -> upgrade-only, never a false downgrade.
+        assertFalse(hasUpdate("49076573", legacyTopLevelManifest(49000000L)))
+        assertTrue(hasUpdate("49000000", legacyTopLevelManifest(49076573L)))
+    }
+
+    @Test
+    fun zeroedPinOnModernGlassesIsAnError() {
+        // An unverifiable pin must never present as "no update" on modern glasses.
+        try {
+            hasUpdate("49076573", manifest(0L))
+            fail("expected invalid_ota_manifest")
+        } catch (e: BluetoothSdkException) {
+            assertEquals("invalid_ota_manifest", e.code)
+        }
+    }
+
+    @Test
+    fun zeroedRescuePinIsInertForLegacyGlasses() {
+        // Pre-39 glasses are legitimately checked against the frozen rescue manifests, whose
+        // zeroed ASG pin must read as no APK update (the MTK patch chain is what matters there).
+        assertFalse(hasUpdate("38", manifest(0L)))
+    }
+}

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

@@ -0,0 +1,29 @@
+package com.mentra.bluetoothsdk
+
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.Test
+
+class StreamStatusEventTest {
+    @Test
+    fun `stream telemetry survives native status normalization`() {
+        val event =
+            StreamStatusEvent(
+                mapOf(
+                    "status" to "streaming",
+                    "streamId" to "stream-1",
+                    "stats" to
+                        mapOf(
+                            "bitrate" to 912_345L,
+                            "fps" to 19.8,
+                            "droppedFrames" to 2L,
+                            "duration" to 31L,
+                            "temperatureC" to 54.6,
+                        ),
+                )
+            )
+
+        assertThat(event.stats?.bitrate).isEqualTo(912_345L)
+        assertThat(event.stats?.temperatureC).isEqualTo(54.6)
+        assertThat((event.values["stats"] as Map<*, *>)["duration"]).isEqualTo(31L)
+    }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/camera/PhotoRequestTest.kt

@@ -5,6 +5,7 @@ import com.mentra.bluetoothsdk.PhotoMode
 import com.mentra.bluetoothsdk.PhotoRequest
 import com.mentra.bluetoothsdk.PhotoSize
 import org.assertj.core.api.Assertions.assertThat
+import org.assertj.core.api.Assertions.assertThatThrownBy
 import org.junit.Test
 
 class PhotoRequestTest {
@@ -108,4 +109,33 @@ class PhotoRequestTest {
 
         assertThat(request.transferMethod).isEqualTo("ble")
     }
+
+    @Test
+    fun `fromMap preserves direct transfer without BLE fallback`() {
+        val request =
+            PhotoRequest.fromMap(
+                mapOf(
+                    "size" to "medium",
+                    "transferMethod" to "direct",
+                    "webhookUrl" to "https://example.com/upload",
+                )
+            )
+
+        assertThat(request.transferMethod).isEqualTo("direct")
+    }
+
+    @Test
+    fun `fromMap rejects an unknown transfer method`() {
+        assertThatThrownBy {
+            PhotoRequest.fromMap(
+                mapOf(
+                    "size" to "medium",
+                    "transferMethod" to "wifi",
+                    "webhookUrl" to "https://example.com/upload",
+                )
+            )
+        }
+            .isInstanceOf(IllegalArgumentException::class.java)
+            .hasMessage("Invalid transferMethod \"wifi\". Expected auto, direct, or ble.")
+    }
 }

package/android/src/test/java/com/mentra/bluetoothsdk/sgcs/Ar99AdvertisementMatcherTest.java

@@ -0,0 +1,22 @@
+package com.mentra.bluetoothsdk.sgcs;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.junit.Test;
+
+public class Ar99AdvertisementMatcherTest {
+
+  @Test
+  public void supportsOnlyDocumentedProjectIdentifiers() {
+    assertThat(Ar99.isSupportedProjectName("AR99")).isTrue();
+    assertThat(Ar99.isSupportedProjectName("ar99")).isTrue();
+
+    assertThat(Ar99.isSupportedProjectName("AF98")).isFalse();
+    assertThat(Ar99.isSupportedProjectName("AF99")).isFalse();
+    assertThat(Ar99.isSupportedProjectName("HVXM")).isFalse();
+    assertThat(Ar99.isSupportedProjectName("HVXF")).isFalse();
+    assertThat(Ar99.isSupportedProjectName("AR99X")).isFalse();
+    assertThat(Ar99.isSupportedProjectName("")).isFalse();
+    assertThat(Ar99.isSupportedProjectName(null)).isFalse();
+  }
+}

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

@@ -135,6 +135,26 @@ public class BleJsonCompactTest {
         assertEquals("wifi_scan_result", BleJsonCompact.encode(wifiScan).getString("t"));
     }
 
+    @Test
+    public void streamTelemetryRoundTripsWithCompactKeys() throws Exception {
+        JSONObject status =
+                new JSONObject(
+                        "{\"type\":\"stream_status\",\"status\":\"streaming\","
+                                + "\"stats\":{\"bitrate\":912345,\"fps\":19.8,"
+                                + "\"droppedFrames\":2,\"duration\":31,"
+                                + "\"temperatureC\":54.6}}\n");
+
+        JSONObject wire = BleJsonCompact.encode(status);
+        assertEquals(912345L, wire.getJSONObject("st").getLong("br"));
+        assertEquals(54.6d, wire.getJSONObject("st").getDouble("tc"), 0.001d);
+
+        JSONObject restored = BleJsonCompact.decode(wire);
+        JSONObject stats = restored.getJSONObject("stats");
+        assertEquals(19.8d, stats.getDouble("fps"), 0.001d);
+        assertEquals(2L, stats.getLong("droppedFrames"));
+        assertEquals(31L, stats.getLong("duration"));
+    }
+
     @Test
     public void decodeIfSupported_rejectsCompactLowRoi() throws Exception {
         JSONObject compactPing = new JSONObject("{\"t\":\"ping\"}");

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

@@ -0,0 +1,45 @@
+package com.mentra.bluetoothsdk.utils
+
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.Test
+
+class PhoneAudioMonitorTest {
+    @Test
+    fun `keeps explicit playback hint while Android reports active media`() {
+        assertThat(
+                PhoneAudioMonitor.shouldKeepOwnAppAudioSignal(
+                        signalledPlaying = true,
+                        systemAudioPlaying = true,
+                        nowMs = 10_000,
+                        holdoffUntilMs = 1_000,
+                )
+            )
+            .isTrue()
+    }
+
+    @Test
+    fun `keeps explicit playback hint during codec transition holdoff`() {
+        assertThat(
+                PhoneAudioMonitor.shouldKeepOwnAppAudioSignal(
+                        signalledPlaying = true,
+                        systemAudioPlaying = false,
+                        nowMs = 500,
+                        holdoffUntilMs = 1_000,
+                )
+            )
+            .isTrue()
+    }
+
+    @Test
+    fun `expires stale playback hint when Android media is inactive`() {
+        assertThat(
+                PhoneAudioMonitor.shouldKeepOwnAppAudioSignal(
+                        signalledPlaying = true,
+                        systemAudioPlaying = false,
+                        nowMs = 1_000,
+                        holdoffUntilMs = 1_000,
+                )
+            )
+            .isFalse()
+    }
+}

package/build/BluetoothSdk.types.d.ts

@@ -58,7 +58,7 @@ export declare function isConnectedGlassesConnectionStatus(status: GlassesConnec
 export declare function isReadyGlassesConnectionStatus(status: GlassesConnectionStatus): boolean;
 export declare function isBusyGlassesConnectionStatus(status: GlassesConnectionStatus): boolean;
 export declare function createDisconnectedGlassesStatus(): Partial<GlassesStatus>;
-/** K900 `sr_getvol` response (Mentra Live glasses media step volume 0–15). */
+/** K900 `sr_getvol` response (Mentra Live glasses media step volume 0闂?5). */
 export type GlassesMediaVolumeGetResult = {
     level: number;
     statusCode: number;
@@ -91,11 +91,11 @@ export type WifiStatusChangeEvent = WifiStatus & {
     /**
      * Glasses-reported provisioning failure reason when THIS event is the verdict of a
      * failed connect attempt; absent on routine link-state updates. An attempt property,
-     * not a link property — which is why it lives on the event, not on WifiStatus:
+     * not a link property 闂?which is why it lives on the event, not on WifiStatus:
      * "connect_timeout" arrives on a disconnected status (never associated), while
      * "connected_to_other_network" arrives on a *connected* status (the attempt failed
      * and the glasses ended up on / fell back to a different SSID than requested).
-     * Requires ASG client v40+ — older glasses never send it.
+     * Requires ASG client v40+ 闂?older glasses never send it.
      */
     error?: string;
 };
@@ -360,16 +360,20 @@ export type RgbLedAction = "on" | "off";
 export type RgbLedColor = "red" | "green" | "blue" | "orange" | "white";
 export type PhotoSize = "low" | "medium" | "high" | "max";
 export type PhotoMode = "photo" | "text";
+export type PhotoTransferMethod = "auto" | "direct" | "ble";
 export type ButtonPhotoSize = "low" | "medium" | "high" | "max";
 /**
  * @deprecated Sticky action-button photo presets via {@link BluetoothSdkPublicModule.setPhotoCaptureDefaults}
  * are deprecated. Prefer per-request {@link BluetoothSdkPublicModule.requestPhoto} options
- * (e.g. `mode: "text"` for AE ÷3) instead of persisting button-photo tuning on the glasses.
+ * (e.g. `mode: "text"` for text sensor size/crop, or explicit `aeExposureDivisor`) instead of
+ * persisting button-photo tuning on the glasses.
  */
 export type PhotoCaptureDefaults = {
     size?: PhotoSize;
-    mfnr?: boolean;
+    /** ZSL preview buffering for physical camera-button photos. */
     zsl?: boolean;
+    /** MFNR still capture for physical camera-button photos. */
+    mfnr?: boolean;
     noiseReduction?: boolean;
     edgeEnhancement?: boolean;
     ispDigitalGain?: number;
@@ -413,6 +417,7 @@ export declare const DeviceModels: {
     readonly Z100: "Vuzix Z100";
     readonly Frame: "Brilliant Frame";
     readonly Nimo: "NIMO";
+    readonly Ar99: "AR99";
     readonly R1: "Even Realities R1";
 };
 export type DeviceModel = (typeof DeviceModels)[keyof typeof DeviceModels];
@@ -424,7 +429,7 @@ export type DashboardMenuItem = {
 };
 export declare const CAMERA_FOV_MIN = 62;
 export declare const CAMERA_FOV_MAX = 118;
-export declare const CAMERA_FOV_DEFAULT = 102;
+export declare const CAMERA_FOV_DEFAULT = 118;
 export type CameraRoiPosition = "center" | "bottom" | "top";
 export type CameraRoiPositionValue = 0 | 1 | 2;
 export type CameraFovPreset = "narrow" | "standard" | "wide";
@@ -461,8 +466,8 @@ export type PhotoRequestParams = {
     appId?: string;
     size: PhotoSize;
     mode?: PhotoMode;
-    /** `ble` skips direct upload and forces phone-relayed BLE image transfer. */
-    transferMethod?: "auto" | "ble";
+    /** `direct` disables BLE fallback; `ble` skips direct upload and forces phone-relayed transfer. */
+    transferMethod?: PhotoTransferMethod;
     webhookUrl: string | null;
     authToken: string | null;
     compress: PhotoCompression;
@@ -478,8 +483,10 @@ export type PhotoRequestParams = {
     /** Requested on wire; glasses may log not_implemented. */
     noiseReduction?: boolean;
     edgeEnhancement?: boolean;
-    mfnr?: boolean;
+    /** ZSL buffering. Forced off for manual/scan stills because fixed sensor controls take priority. */
     zsl?: boolean;
+    /** MFNR still capture. Forced off for manual/scan stills because fixed sensor controls take priority. */
+    mfnr?: boolean;
     ispDigitalGain?: number;
     ispAnalogGain?: string;
 };
@@ -491,6 +498,10 @@ export type WarmUpCameraParams = {
     exposureTimeNs?: number | null;
     /** Ready-state hold; defaults to 15 seconds and is capped at 60 seconds by ASG. */
     durationMs?: number;
+    /** ZSL preview buffering for the warm-up session. */
+    zsl?: boolean;
+    /** MFNR still capture for the warm-up session. */
+    mfnr?: boolean;
 };
 export type StreamVideoConfig = {
     width?: number;
@@ -595,7 +606,7 @@ export type StreamResolvedConfig = {
         noiseSuppression?: boolean;
     };
 };
-/** Live encoder telemetry, when the glasses emit it (no firmware does yet). */
+/** Live encoder and device telemetry emitted periodically by supported glasses firmware. */
 export type StreamLiveStats = {
     /** Current encoded video bitrate in bits per second. */
     bitrate?: number;
@@ -604,7 +615,7 @@ export type StreamLiveStats = {
     droppedFrames?: number;
     /** Seconds since the stream started. */
     duration?: number;
-    /** Device temperature in °C, if the hardware reports it. */
+    /** Device temperature in 闂佺娅ｉ悡? if the hardware reports it. */
     temperatureC?: number;
 };
 type StreamStatusCommon = {
@@ -653,6 +664,16 @@ export type MtkUpdateCompleteEvent = {
     message: string;
     timestamp: number;
 };
+/**
+ * The glasses process restarted while the BES kept the BLE link alive (its `sid`
+ * changed, or first appeared after an update from a pre-sid build). There is no
+ * physical disconnect for this — treat it as the logical reconnect edge.
+ */
+export type GlassesSessionChangedEvent = {
+    type: "glasses_session_changed";
+    previous_sid: string;
+    sid: string;
+};
 /** @deprecated Glasses no longer emit ota_progress; use {@link OtaStatusEvent} and status-store mapping. */
 export type OtaProgressEvent = {
     type: "ota_progress";
@@ -668,14 +689,6 @@ export type OtaStartAckEvent = {
     type: "ota_start_ack";
     timestamp: number;
 };
-export type OtaUpdateAvailableEvent = {
-    type: "ota_update_available";
-    version_code?: number;
-    version_name?: string;
-    updates?: string[];
-    total_size?: number;
-    cache_ready?: boolean;
-};
 export type OtaStatusEvent = {
     type: "ota_status";
     session_id: string;
@@ -749,9 +762,10 @@ export type BluetoothSdkModuleEvents = {
     stream_status: (event: StreamStatusEvent) => void;
     keep_alive_ack: (event: KeepAliveAckEvent) => void;
     mtk_update_complete: (event: MtkUpdateCompleteEvent) => void;
-    ota_update_available: (event: OtaUpdateAvailableEvent) => void;
+    glasses_session_changed: (event: GlassesSessionChangedEvent) => void;
     ota_start_ack: (event: OtaStartAckEvent) => void;
     ota_status: (event: OtaStatusEvent) => void;
+    ar99_ota_status: (event: Ar99OtaStatusEvent) => void;
     version_info: (event: VersionInfoEvent) => void;
     send_command_to_ble: (event: BleCommandTraceEvent) => void;
     receive_command_from_ble: (event: BleCommandTraceEvent) => void;
@@ -763,6 +777,15 @@ export interface ExtractionProgressEvent {
     bytesRead: number;
     totalBytes: number;
 }
+export interface Ar99OtaStatusEvent {
+    type: "ar99_ota_status";
+    phase: string;
+    progress: number;
+    offset: number;
+    total: number;
+    errorMessage?: string;
+    error_message?: string;
+}
 export interface PhoneNotificationEvent {
     notificationId: string;
     app: string;
@@ -818,9 +841,9 @@ export type BluetoothSdkEventMap = {
     mic_pcm: MicPcmEvent;
     mic_lc3: MicLc3Event;
     stream_status: StreamStatusEvent;
-    ota_update_available: OtaUpdateAvailableEvent;
     ota_start_ack: OtaStartAckEvent;
     ota_status: OtaStatusEvent;
+    ar99_ota_status: Ar99OtaStatusEvent;
     version_info: VersionInfoEvent;
     extraction_progress: ExtractionProgressEvent;
 };
@@ -857,9 +880,10 @@ export interface BluetoothSdkPublicModule {
     setHotspotState(enabled: boolean): Promise<HotspotStatusChangeEvent>;
     setGalleryModeEnabled(enabled: boolean): Promise<SettingsAckSuccessEvent>;
     setVoiceActivityDetectionEnabled(enabled: boolean): Promise<void>;
+    setLoudnessGateEnabled(enabled: boolean): Promise<void>;
     /**
      * @deprecated Sticky action-button photo presets are deprecated. Prefer per-request
-     * `requestPhoto(...)` options (e.g. `mode: "text"` for AE ÷3, or explicit per-shot
+     * `requestPhoto(...)` options (e.g. `mode: "text"` for text sensor size/crop, or explicit per-shot
      * fields). Still functional until removed in a future release.
      */
     setPhotoCaptureDefaults(settings: PhotoCaptureDefaults): Promise<SettingsAckSuccessEvent>;
@@ -894,7 +918,7 @@ export interface BluetoothSdkPublicModule {
      * Stop the active recording. When {@link webhookUrl} is provided, the glasses
      * upload the recorded video to it (multipart) using {@link authToken}. These
      * are supplied at stop time (not start) so the token is fresh when the upload
-     * runs — a recording can last arbitrarily long. An empty/omitted webhook keeps
+     * runs 闂?a recording can last arbitrarily long. An empty/omitted webhook keeps
      * the video on device (no upload).
      */
     stopVideoRecording(requestId: string, webhookUrl?: string, authToken?: string): Promise<VideoRecordingStoppedStatusEvent>;
@@ -911,6 +935,10 @@ export interface BluetoothSdkPublicModule {
     checkForOtaUpdate(): Promise<boolean>;
     /** Start the OTA flow with the same configured manifest URL used by checkForOtaUpdate(). */
     startOtaUpdate(): Promise<OtaStartAckEvent>;
+    startAr99OtaFromFile(path: string): Promise<boolean>;
+    cancelAr99Ota(): Promise<void>;
+    sendAr99FactoryReset(): Promise<void>;
+    buildAr99OtaSignature(secret: string, appName: string, currentVersion: string, serialNumber: string, nonce: string): string;
     setSttModelDetails(path: string, languageCode: string): Promise<void>;
     getSttModelPath(): Promise<string>;
     checkSttModelAvailable(): Promise<boolean>;
@@ -944,6 +972,8 @@ export interface OtaUpdateInfo {
     updates: string[];
     totalSize: number;
     cacheReady?: boolean;
+    /** True when the APK step installs an older build than the glasses currently run (exact-pin manifests only). */
+    isDowngrade?: boolean;
 }
 export interface OtaProgress {
     stage: OtaStage;
@@ -1015,13 +1045,15 @@ export interface Device {
     /**
      * Stable app-facing key for this scan result, within the limits of the
      * platform identifier available to the SDK. Do not parse this value; use the
-     * typed model, name, address, and rssi fields instead.
+     * typed model, name, address, projectName, and rssi fields instead.
      */
     id: string;
     model: DeviceModel;
     name: string;
     /** Platform address/identifier when available: Android Bluetooth address, iOS CoreBluetooth identifier. */
     address?: string;
+    /** Optional AR99 project discriminator. Supported value: AR99. */
+    projectName?: string;
     /**
      * Optional scan signal strength. It may be undefined at first discovery and
      * appear in a later scan update when the platform reports RSSI metadata.
@@ -1047,7 +1079,7 @@ export interface WifiSearchResult {
     ssid: string;
     requiresPassword: boolean;
     signalStrength: number;
-    /** Frequency in MHz (from glasses scan). 5 GHz band is typically 5170–5825. Omitted if unknown. */
+    /** Frequency in MHz (from glasses scan). 5 GHz band is typically 5170闂?825. Omitted if unknown. */
     frequency?: number;
 }
 export interface BluetoothStatus {
@@ -1096,6 +1128,7 @@ export type BluetoothSettingsUpdate = Partial<{
     twelve_hour_time: boolean;
     gallery_mode: boolean;
     voice_activity_detection_enabled: boolean;
+    loudness_gate_enabled: boolean;
     button_photo_size: ButtonPhotoSize;
     button_video_settings: {
         width: number;