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

package/src/_private/BluetoothSdkModule.ts

@@ -11,6 +11,7 @@ import {
   CAMERA_FOV_MIN,
   CameraFovPreset,
   CameraFovRequest,
+  CameraFovOverrideRequest,
   CameraFovResult,
   CameraFovSetting,
   CameraRoiPosition,
@@ -116,7 +117,7 @@ declare class BluetoothSdkNativeModule extends NativeModule<BluetoothSdkModuleEv
   sendWifiCredentials(ssid: string, password: string): Promise<WifiStatusChangeEvent>
   forgetWifiNetwork(ssid: string): Promise<WifiStatusChangeEvent>
   setHotspotState(enabled: boolean): Promise<HotspotStatusChangeEvent>
-  /** Set glasses system clock (Mentra Live only) when phone detects clock skew. */
+  /** Set the glasses system clock when phone detects clock skew (Mentra Live and G2). */
   setSystemTime(timestampMs: number): Promise<void>
   /** Logs current WiFi frequency (MHz) and 5 GHz band to Android logcat. */
   logCurrentWifiFrequency(): Promise<void>
@@ -124,14 +125,20 @@ declare class BluetoothSdkNativeModule extends NativeModule<BluetoothSdkModuleEv
   // Gallery Commands
   setGalleryModeEnabled(enabled: boolean): Promise<SettingsAckSuccessEvent>
   setVoiceActivityDetectionEnabled(enabled: boolean): Promise<void>
+  /** Mentra Live center-mic loudness / Barrier gate (cs_swit type 10). */
+  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).
+   * `requestPhoto(...)` options (e.g. `mode: "text"` for text sensor size/crop).
    */
   setPhotoCaptureDefaults(settings: PhotoCaptureDefaults): Promise<SettingsAckSuccessEvent>
   setVideoRecordingDefaults(width: number, height: number, fps: number): Promise<SettingsAckSuccessEvent>
   setMaxVideoRecordingDuration(minutes: number): Promise<SettingsAckSuccessEvent>
   setCameraFov(request: CameraFovRequest): Promise<CameraFovResult>
+  setLegacyCameraFov(request: CameraFovRequest): Promise<CameraFovResult>
+  restoreLegacyCameraFov(): Promise<void>
+  setCameraFovOverride(request: CameraFovOverrideRequest): Promise<CameraFovResult>
+  releaseCameraFovOverride(leaseId: string): Promise<SettingsAckSuccessEvent>
   /**
    * Configure camera HAL tuning (ANR / gain) on Mentra Live glasses.
    * Sends a {@code camera_tuning_config} BLE message; the ASG client relays it as a
@@ -144,6 +151,7 @@ declare class BluetoothSdkNativeModule extends NativeModule<BluetoothSdkModuleEv
   queryGalleryStatus(): Promise<GalleryStatusEvent>
   requestPhoto(params: PhotoRequestParams): Promise<PhotoSuccessResponseEvent>
   warmUpCamera(params: WarmUpCameraParams): Promise<CameraStatusEvent>
+  stopCameraWarmUp(requestId: string): Promise<void>
 
   // OTA Commands
   setOtaVersionUrl(otaVersionUrl: string): void
@@ -151,6 +159,10 @@ declare class BluetoothSdkNativeModule extends NativeModule<BluetoothSdkModuleEv
   checkForOtaUpdate(): Promise<boolean>
   startOtaUpdate(otaVersionUrl?: string | null): Promise<OtaStartAckEvent>
   sendOtaQueryStatus(): Promise<OtaQueryResult>
+  startAr99OtaFromFile(path: string): Promise<boolean>
+  cancelAr99Ota(): Promise<void>
+  sendAr99FactoryReset(): Promise<void>
+  buildAr99OtaSignature(secret: string, appName: string, currentVersion: string, serialNumber: string, nonce: string): string
 
   // Version Info Commands
   requestVersionInfo(): Promise<VersionInfoResult>
@@ -184,9 +196,26 @@ declare class BluetoothSdkNativeModule extends NativeModule<BluetoothSdkModuleEv
   // Used to suspend LC3 mic during audio playback to avoid MCU overload
   setOwnAppAudioPlaying(playing: boolean): Promise<void>
 
+  // Live PCM output stream (miniapp speaker.createStream). MentraOS-internal
+  // ? 16-bit LE PCM chunks into a streaming AudioTrack (USAGE_MEDIA, so it
+  // follows the phone's media route, e.g. A2DP to glasses). Implemented with
+  // AudioTrack on Android and AVAudioEngine on iOS.
+  /** Open a PCM stream session. One AudioTrack per id; caller manages ids. */
+  pcmStreamOpen(streamId: string, sampleRate: number, channels: number, volume: number): Promise<void>
+  /**
+   * Append base64 PCM. Resolves with the queued-but-unplayed backlog in ms;
+   * blocks (on a background dispatcher) while the backlog is above the
+   * backpressure ceiling, so awaited writes self-throttle to realtime.
+   */
+  pcmStreamWrite(streamId: string, base64: string): Promise<{bufferedMs: number}>
+  /** Drain the backlog, then stop. Resolves with the total played duration. */
+  pcmStreamClose(streamId: string): Promise<{durationMs: number}>
+  /** Stop immediately, dropping any backlog. Idempotent. */
+  pcmStreamAbort(streamId: string): Promise<void>
+
   /** Mentra Live only: K900 `cs_getvol` / `sr_getvol`. */
   getGlassesMediaVolume(): Promise<GlassesMediaVolumeGetResult>
-  /** Mentra Live only: K900 `cs_vol` / `sr_vol`; level clamped 0–15 on native. */
+  /** Mentra Live only: K900 `cs_vol` / `sr_vol`; level clamped 0??5 on native. */
   setGlassesMediaVolume(level: number): Promise<GlassesMediaVolumeSetResult>
 
   // RGB LED Control
@@ -244,13 +273,10 @@ const DEFAULT_CONNECT_OPTIONS: Required<ConnectOptions> = {
 
 const DEFAULT_SCAN_TIMEOUT_MS = 15_000
 
-function bindNativeMethod<T extends (...args: never[]) => unknown>(
-  module: Record<string, unknown>,
-  name: string,
-): T {
+function bindNativeMethod<T extends (...args: never[]) => unknown>(module: Record<string, unknown>, name: string): T {
   const method = module[name]
   if (typeof method !== "function") {
-    console.warn(`[BluetoothSdk] Native method "${name}" is unavailable — rebuild the app (bun android / bun ios)`)
+    console.warn(`[BluetoothSdk] Native method "${name}" is unavailable ??rebuild the app (bun android / bun ios)`)
     return (async () => {
       throw new Error(`BluetoothSdk.${name} is not available in this native build. Rebuild the app.`)
     }) as T
@@ -267,10 +293,10 @@ const CAMERA_ROI_POSITION_VALUES: Record<CameraRoiPosition, CameraFovSetting["ro
 }
 
 // Named presets are a convenience layer over the numeric {fov, roiPosition} API.
-// "narrow" uses 82, a device-tested FOV; "standard" matches CAMERA_FOV_DEFAULT.
+// The default is the full sensor; "standard" preserves the historical 102� crop.
 const CAMERA_FOV_PRESETS: Record<CameraFovPreset, CameraFovSetting> = {
   narrow: {fov: 82, roiPosition: 0},
-  standard: {fov: CAMERA_FOV_DEFAULT, roiPosition: 0},
+  standard: {fov: 102, roiPosition: 0},
   wide: {fov: CAMERA_FOV_MAX, roiPosition: 0},
 }
 
@@ -286,11 +312,7 @@ function normalizeCameraFov(request: CameraFovRequest): CameraFovSetting {
   const roiPosition = request.roiPosition ?? "center"
 
   return {
-    fov: clampInteger(
-      Number.isFinite(request.fov) ? request.fov : CAMERA_FOV_DEFAULT,
-      CAMERA_FOV_MIN,
-      CAMERA_FOV_MAX,
-    ),
+    fov: clampInteger(Number.isFinite(request.fov) ? request.fov : CAMERA_FOV_DEFAULT, CAMERA_FOV_MIN, CAMERA_FOV_MAX),
     roiPosition: clampInteger(CAMERA_ROI_POSITION_VALUES[roiPosition] ?? 0, CAMERA_ROI_MIN, CAMERA_ROI_MAX) as
       | 0
       | 1
@@ -470,14 +492,53 @@ NativeBluetoothSdkModule.setVoiceActivityDetectionEnabled = function (enabled: b
   return this.updateBluetoothSettings({voice_activity_detection_enabled: enabled})
 }
 
-const nativeSetCameraFov = bindNativeMethod<
-  (fov: CameraFovSetting) => MaybePromise<CameraFovResult>
->(NativeBluetoothSdkModule as unknown as Record<string, unknown>, "setCameraFov")
+NativeBluetoothSdkModule.setLoudnessGateEnabled = function (enabled: boolean) {
+  return this.updateBluetoothSettings({loudness_gate_enabled: enabled})
+}
+
+const nativeSetCameraFov = bindNativeMethod<(fov: CameraFovSetting) => MaybePromise<CameraFovResult>>(
+  NativeBluetoothSdkModule as unknown as Record<string, unknown>,
+  "setCameraFov",
+)
 NativeBluetoothSdkModule.setCameraFov = function (request: CameraFovRequest) {
   const setting = normalizeCameraFov(request)
   return Promise.resolve(nativeSetCameraFov(setting))
 }
 
+const nativeSetLegacyCameraFov = bindNativeMethod<(fov: CameraFovSetting) => MaybePromise<CameraFovResult>>(
+  NativeBluetoothSdkModule as unknown as Record<string, unknown>,
+  "setLegacyCameraFov",
+)
+NativeBluetoothSdkModule.setLegacyCameraFov = function (request: CameraFovRequest) {
+  return Promise.resolve(nativeSetLegacyCameraFov(normalizeCameraFov(request)))
+}
+
+const nativeRestoreLegacyCameraFov = bindNativeMethod<() => MaybePromise<void>>(
+  NativeBluetoothSdkModule as unknown as Record<string, unknown>,
+  "restoreLegacyCameraFov",
+)
+NativeBluetoothSdkModule.restoreLegacyCameraFov = function () {
+  return Promise.resolve(nativeRestoreLegacyCameraFov())
+}
+
+const nativeSetCameraFovOverride = bindNativeMethod<
+  (request: CameraFovSetting & {leaseId: string; ttlMs: number}) => MaybePromise<CameraFovResult>
+>(NativeBluetoothSdkModule as unknown as Record<string, unknown>, "setCameraFovOverride")
+NativeBluetoothSdkModule.setCameraFovOverride = function (request: CameraFovOverrideRequest) {
+  const setting = normalizeCameraFov(request)
+  const requestedTtl =
+    typeof request.ttlMs === "number" && Number.isFinite(request.ttlMs) && request.ttlMs > 0
+      ? Math.round(request.ttlMs)
+      : 300_000
+  return Promise.resolve(
+    nativeSetCameraFovOverride({
+      ...setting,
+      leaseId: request.leaseId,
+      ttlMs: Math.min(requestedTtl, 600_000),
+    }),
+  )
+}
+
 NativeBluetoothSdkModule.setMicState = function (
   enabled: boolean,
   useGlassesMic?: boolean,
@@ -588,3 +649,7 @@ NativeBluetoothSdkModule.warmUpCamera = function (params: WarmUpCameraParams) {
 
 export default NativeBluetoothSdkModule
 export const BluetoothSdk = NativeBluetoothSdkModule as BluetoothSdkInternalModule
+
+
+
+

package/src/_private/MentraLocalNetworkModule.ts

@@ -0,0 +1,50 @@
+import {NativeModule, requireOptionalNativeModule} from "expo"
+
+export type LocalNetworkResponse = {
+  status: number
+  headers: Record<string, string>
+  bodyBase64: string
+}
+
+export type LocalNetworkDownloadResult = {
+  statusCode: number
+  bytesWritten: number
+  headers: Record<string, string>
+}
+
+export type LocalNetworkDownloadProgress = {
+  requestId: string
+  bytesWritten: number
+  contentLength: number
+  statusCode?: number
+  headers?: Record<string, string>
+}
+
+type LocalNetworkEvents = {
+  downloadProgress: (event: LocalNetworkDownloadProgress) => void
+  networkLost: (event: {ssid: string}) => void
+}
+
+declare class MentraLocalNetworkNativeModule extends NativeModule<LocalNetworkEvents> {
+  connect(ssid: string, password: string): Promise<{connected: boolean; ssid: string}>
+  request(
+    requestId: string,
+    url: string,
+    method: string,
+    headers: Record<string, string>,
+    body: string | null,
+    timeoutMs: number,
+  ): Promise<LocalNetworkResponse>
+  download(
+    requestId: string,
+    url: string,
+    destination: string,
+    headers: Record<string, string>,
+    connectionTimeoutMs: number,
+    readTimeoutMs: number,
+  ): Promise<LocalNetworkDownloadResult>
+  cancel(requestId: string): Promise<void>
+  disconnect(): Promise<void>
+}
+
+export default requireOptionalNativeModule<MentraLocalNetworkNativeModule>("MentraLocalNetwork")

package/src/_private/cameraRequestPayload.ts

@@ -9,9 +9,10 @@ function nonBlankString(value?: string | null): string | undefined {
 /** Expo Android bridge rejects null values in Map<String, Any> — omit optional nullish fields. */
 export function warmUpCameraParamsForNative(
   params: WarmUpCameraParams,
-): Record<string, string | number> {
-  const payload: Record<string, string | number> = {
+): Record<string, string | number | boolean> {
+  const payload: Record<string, string | number | boolean> = {
     size: normalizePhotoSizeTier(params.size),
+    mode: params.mode ?? "photo",
   }
   const requestId = nonBlankString(params.requestId)
   if (requestId != null) {
@@ -25,5 +26,11 @@ export function warmUpCameraParamsForNative(
   if (durationMs != null && Number.isFinite(durationMs) && durationMs > 0) {
     payload.durationMs = Math.round(durationMs)
   }
+  if (params.mfnr != null) {
+    payload.mfnr = params.mfnr
+  }
+  if (params.zsl != null) {
+    payload.zsl = params.zsl
+  }
   return payload
 }

package/src/_private/photoRequestPayload.ts

@@ -1,4 +1,14 @@
-import type {PhotoRequestParams, PhotoSize} from "../BluetoothSdk.types"
+import type {PhotoRequestParams, PhotoSize, PhotoTransferMethod} from "../BluetoothSdk.types"
+
+const PHOTO_TRANSFER_METHODS = new Set<PhotoTransferMethod>(["auto", "direct", "ble"])
+
+function photoTransferMethodForNative(value: unknown): PhotoTransferMethod {
+  if (value === undefined) return "auto"
+  if (typeof value === "string" && PHOTO_TRANSFER_METHODS.has(value as PhotoTransferMethod)) {
+    return value as PhotoTransferMethod
+  }
+  throw new TypeError(`Invalid transferMethod ${JSON.stringify(value)}. Expected "auto", "direct", or "ble".`)
+}
 
 /** Maps unknown/legacy size strings to the current wire format. */
 export function normalizePhotoSizeTier(size: string | undefined): PhotoSize {
@@ -25,12 +35,11 @@ function nonBlankString(value?: string | null): string | undefined {
 }
 
 /** Expo Android bridge rejects null values in Map<String, Any> — omit optional nullish fields. */
-export function photoRequestParamsForNative(
-  params: PhotoRequestParams,
-): Record<string, string | number | boolean> {
+export function photoRequestParamsForNative(params: PhotoRequestParams): Record<string, string | number | boolean> {
   const payload: Record<string, string | number | boolean> = {
     size: normalizePhotoSizeTier(params.size),
     mode: params.mode ?? "photo",
+    transferMethod: photoTransferMethodForNative(params.transferMethod),
     webhookUrl: params.webhookUrl ?? "",
     compress: params.compress,
     sound: params.sound,

package/src/_private/sdkOtaManifest.ts

@@ -0,0 +1,31 @@
+/**
+ * SDK-pinned OTA manifest URL derivation.
+ *
+ * Each Bluetooth SDK release publishes an immutable manifest
+ * (`bluetooth-sdk-<version>-version.json`) pinning the exact ASG artifact paired with that SDK
+ * version. The URL is derived from this package's own version — the version is frozen into the
+ * published artifact, so this is equivalent to baking the URL at release time while keeping the
+ * manifest itself replaceable as an operational escape hatch (asset moves, CDN migration).
+ *
+ * Mirrors the native derivation in `OtaManifestDefaults.defaultOtaVersionUrl()` (Kotlin) /
+ * `BluetoothSdkDefaults` (Swift).
+ */
+
+const SDK_OTA_RELEASE_BASE_URL = "https://github.com/Mentra-Community/MentraOS/releases/download/bluetooth-sdk-ota"
+
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const packageJson = require("../../package.json") as {version?: string}
+
+/** This Bluetooth SDK package's own version, as published. */
+export const BLUETOOTH_SDK_VERSION: string = (packageJson.version ?? "").trim()
+
+/**
+ * The immutable manifest URL pinning the ASG artifact paired with this SDK version, or null when
+ * the package version is unavailable (malformed workspace state).
+ */
+export function sdkPinnedOtaManifestUrl(): string | null {
+  if (!BLUETOOTH_SDK_VERSION) {
+    return null
+  }
+  return `${SDK_OTA_RELEASE_BASE_URL}/bluetooth-sdk-${BLUETOOTH_SDK_VERSION}-version.json`
+}

package/src/index.ts

@@ -44,6 +44,7 @@ const PUBLIC_EVENT_NAMES = new Set<BluetoothSdkEventName>([
   "stream_status",
   "ota_start_ack",
   "ota_status",
+  "ar99_ota_status",
   "version_info",
   "extraction_progress",
 ])
@@ -96,9 +97,10 @@ export const BluetoothSdk: BluetoothSdkPublicModule = Object.freeze({
   setHotspotState: bindPublicMethod("setHotspotState"),
   setGalleryModeEnabled: bindPublicMethod("setGalleryModeEnabled"),
   setVoiceActivityDetectionEnabled: bindPublicMethod("setVoiceActivityDetectionEnabled"),
+  setLoudnessGateEnabled: bindPublicMethod("setLoudnessGateEnabled"),
   /**
    * @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: bindPublicMethod("setPhotoCaptureDefaults"),
@@ -113,10 +115,14 @@ export const BluetoothSdk: BluetoothSdkPublicModule = Object.freeze({
   },
   setMaxVideoRecordingDuration: bindPublicMethod("setMaxVideoRecordingDuration"),
   setCameraFov: bindPublicMethod("setCameraFov"),
+  setLegacyCameraFov: bindPublicMethod("setLegacyCameraFov"),
+  setCameraFovOverride: bindPublicMethod("setCameraFovOverride"),
+  releaseCameraFovOverride: bindPublicMethod("releaseCameraFovOverride"),
   setCameraTuningConfig: bindPublicMethod("setCameraTuningConfig"),
   queryGalleryStatus: bindPublicMethod("queryGalleryStatus"),
   requestPhoto: bindPublicMethod("requestPhoto"),
   warmUpCamera: bindPublicMethod("warmUpCamera"),
+  stopCameraWarmUp: bindPublicMethod("stopCameraWarmUp"),
   startVideoRecording: bindPublicMethod("startVideoRecording"),
   stopVideoRecording: bindPublicMethod("stopVideoRecording"),
   startStream: bindPublicMethod("startStream"),
@@ -130,6 +136,10 @@ export const BluetoothSdk: BluetoothSdkPublicModule = Object.freeze({
   requestVersionInfo: bindPublicMethod("requestVersionInfo"),
   checkForOtaUpdate: bindPublicMethod("checkForOtaUpdate"),
   startOtaUpdate,
+  startAr99OtaFromFile: bindPublicMethod("startAr99OtaFromFile"),
+  cancelAr99Ota: bindPublicMethod("cancelAr99Ota"),
+  sendAr99FactoryReset: bindPublicMethod("sendAr99FactoryReset"),
+  buildAr99OtaSignature: bindPublicMethod("buildAr99OtaSignature"),
   setSttModelDetails: bindPublicMethod("setSttModelDetails"),
   getSttModelPath: bindPublicMethod("getSttModelPath"),
   checkSttModelAvailable: bindPublicMethod("checkSttModelAvailable"),
@@ -160,6 +170,7 @@ export {
 
 export type {
   AccelEvent,
+  Ar99OtaStatusEvent,
   AudioConnectedEvent,
   AudioDisconnectedEvent,
   AudioPairingNeededEvent,
@@ -210,6 +221,7 @@ export type {
   PhotoFpsRange,
   PhotoMeteredPreview,
   PhotoMode,
+  PhotoTransferMethod,
   PhotoResponseEvent,
   PhotoRequestedCaptureConfig,
   PhotoRequestParams,