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

package/src/changelogs.ts

@@ -0,0 +1,44 @@
+import type {ReleaseChangelog} from "./BluetoothSdk.types"
+import {GENERATED_RELEASE_CHANGELOGS} from "./generated/changelogCatalog"
+import {BLUETOOTH_SDK_RELEASE_METADATA} from "./generated/releaseMetadata"
+
+const BASE_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:[-+].*)?$/
+
+function baseVersion(version: string, label: string): string {
+  const match = BASE_VERSION_PATTERN.exec(version.trim())
+  if (!match) throw new Error(`${label} must be a semantic version such as 3.1.0, 3.1.0-dev.4, or 3.1.0-beta.2`)
+  return `${match[1]}.${match[2]}.${match[3]}`
+}
+
+function compareVersions(left: string, right: string): number {
+  const a = left.split(".").map(Number)
+  const b = right.split(".").map(Number)
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] - b[index]
+  }
+  return 0
+}
+
+/**
+ * Return authored release notes crossed between two product versions, newest first.
+ * The target release is always included, including transitions within one base train.
+ */
+export function getReleaseChangelogs(fromVersion?: string | null, toVersion?: string | null): ReleaseChangelog[] {
+  const fallbackTarget = BLUETOOTH_SDK_RELEASE_METADATA.familyBaseVersion ?? GENERATED_RELEASE_CHANGELOGS[0]?.version
+  if (!fallbackTarget && !toVersion) return []
+  const target = baseVersion(toVersion ?? fallbackTarget, "toVersion")
+  if (!GENERATED_RELEASE_CHANGELOGS.some(({version}) => version === target)) {
+    throw new Error(`No changelog is bundled for target version ${target}`)
+  }
+  if (!fromVersion) {
+    return GENERATED_RELEASE_CHANGELOGS.filter(({version}) => version === target).map((entry) => ({...entry}))
+  }
+
+  const source = baseVersion(fromVersion, "fromVersion")
+  const direction = compareVersions(target, source)
+  return GENERATED_RELEASE_CHANGELOGS.filter(({version}) => {
+    if (direction === 0) return version === target
+    if (direction > 0) return compareVersions(version, source) > 0 && compareVersions(version, target) <= 0
+    return compareVersions(version, source) < 0 && compareVersions(version, target) >= 0
+  }).map((entry) => ({...entry}))
+}

package/src/generated/changelogCatalog.ts

@@ -0,0 +1,9 @@
+/** Generated from /changelogs. Do not edit directly. */
+export const GENERATED_RELEASE_CHANGELOGS = Object.freeze(
+[
+  {
+    "version": "3.1.0",
+    "markdown": "Software updates are more reliable, with clearer progress and recovery when the glasses restart.\n\n- MentraOS, Mentra Engine, the Bluetooth SDK, and the glasses client now share one coordinated release version.\n- Mentra Live updates can continue across APK, system, and firmware restarts without asking the user to start the same update again.\n- Bluetooth photo capture and transfer diagnostics are more precise and less disruptive to normal glasses traffic."
+  }
+] as const,
+)

package/src/generated/releaseMetadata.ts

@@ -0,0 +1,20 @@
+/** Generated by release CI. Do not edit in a release checkout. */
+export interface BluetoothSdkReleaseMetadata {
+  schemaVersion: 1
+  familyBaseVersion: string | null
+  releaseIdentity: string | null
+  releaseSetId: string | null
+  sourceCommit: string | null
+  otaManifestUrl: string | null
+  otaManifestSha256: string | null
+}
+
+export const BLUETOOTH_SDK_RELEASE_METADATA: Readonly<BluetoothSdkReleaseMetadata> = Object.freeze({
+  "schemaVersion": 1,
+  "familyBaseVersion": "3.1.0",
+  "releaseIdentity": "3.1.0-beta.100",
+  "releaseSetId": "mentra-3.1.0-beta.100",
+  "sourceCommit": "c7c90f50ce7fd83dadc9a005e152db1d88083e4f",
+  "otaManifestUrl": "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.1.0/mentra-live-ota-3.1.0-beta.100.json",
+  "otaManifestSha256": "7fdf5b1f75d5d07007e45c929495cd4b6800c810c94e3c60c62bda99d1c61552"
+})

package/src/index.ts

@@ -3,8 +3,11 @@ import type {
   BluetoothSdkEventListener,
   BluetoothSdkEventName,
   BluetoothSdkPublicModule,
+  PublicBluetoothStatus,
+  PublicGlassesStatus,
   VideoRecordingDefaults,
 } from "./BluetoothSdk.types"
+import {getReleaseChangelogs} from "./changelogs"
 
 const PUBLIC_EVENT_NAMES = new Set<BluetoothSdkEventName>([
   "log",
@@ -36,12 +39,18 @@ const PUBLIC_EVENT_NAMES = new Set<BluetoothSdkEventName>([
   "rgb_led_control_response",
   "settings_ack",
   "pair_failure",
+  "pairing_info",
+  "entering_pairing_mode",
+  "owner_replaced",
   "audio_pairing_needed",
   "audio_connected",
   "audio_disconnected",
   "mic_pcm",
   "mic_lc3",
+  "mic_health",
   "stream_status",
+  "mtk_update_complete",
+  "glasses_session_changed",
   "ota_start_ack",
   "ota_status",
   "ar99_ota_status",
@@ -56,8 +65,12 @@ const addListener: BluetoothSdkPublicModule["addListener"] = (eventName, listene
   return PrivateBluetoothSdkModule.addListener(eventName, listener as BluetoothSdkEventListener<BluetoothSdkEventName>)
 }
 
-const startOtaUpdate: BluetoothSdkPublicModule["startOtaUpdate"] = () => {
-  return PrivateBluetoothSdkModule.startOtaUpdate()
+const startOtaUpdate: BluetoothSdkPublicModule["startOtaUpdate"] = (otaVersionUrl) => {
+  return PrivateBluetoothSdkModule.startOtaUpdate(otaVersionUrl)
+}
+
+const queryOtaStatus: BluetoothSdkPublicModule["queryOtaStatus"] = () => {
+  return PrivateBluetoothSdkModule.sendOtaQueryStatus()
 }
 
 const bindPublicMethod = <K extends keyof BluetoothSdkPublicModule>(name: K): BluetoothSdkPublicModule[K] => {
@@ -73,6 +86,12 @@ const bindPublicMethod = <K extends keyof BluetoothSdkPublicModule>(name: K): Bl
 
 export const BluetoothSdk: BluetoothSdkPublicModule = Object.freeze({
   addListener,
+  getGlassesStatus: bindPublicMethod("getGlassesStatus"),
+  getBluetoothStatus: bindPublicMethod("getBluetoothStatus"),
+  subscribeGlassesStatus: (listener: (changed: Partial<PublicGlassesStatus>) => void) =>
+    PrivateBluetoothSdkModule.onGlassesStatus(listener),
+  subscribeBluetoothStatus: (listener: (changed: Partial<PublicBluetoothStatus>) => void) =>
+    PrivateBluetoothSdkModule.onBluetoothStatus(listener),
   getDefaultDevice: bindPublicMethod("getDefaultDevice"),
   setDefaultDevice: bindPublicMethod("setDefaultDevice"),
   clearDefaultDevice: bindPublicMethod("clearDefaultDevice"),
@@ -91,10 +110,13 @@ export const BluetoothSdk: BluetoothSdkPublicModule = Object.freeze({
   setHeadUpAngle: bindPublicMethod("setHeadUpAngle"),
   setImuEnabled: bindPublicMethod("setImuEnabled"),
   setScreenDisabled: bindPublicMethod("setScreenDisabled"),
+  ping: bindPublicMethod("ping"),
   requestWifiScan: bindPublicMethod("requestWifiScan"),
   sendWifiCredentials: bindPublicMethod("sendWifiCredentials"),
   forgetWifiNetwork: bindPublicMethod("forgetWifiNetwork"),
   setHotspotState: bindPublicMethod("setHotspotState"),
+  setSystemTime: bindPublicMethod("setSystemTime"),
+  setWifiAdbState: bindPublicMethod("setWifiAdbState"),
   setGalleryModeEnabled: bindPublicMethod("setGalleryModeEnabled"),
   setVoiceActivityDetectionEnabled: bindPublicMethod("setVoiceActivityDetectionEnabled"),
   setLoudnessGateEnabled: bindPublicMethod("setLoudnessGateEnabled"),
@@ -125,6 +147,7 @@ export const BluetoothSdk: BluetoothSdkPublicModule = Object.freeze({
   stopCameraWarmUp: bindPublicMethod("stopCameraWarmUp"),
   startVideoRecording: bindPublicMethod("startVideoRecording"),
   stopVideoRecording: bindPublicMethod("stopVideoRecording"),
+  queryVideoRecordingStatus: bindPublicMethod("queryVideoRecordingStatus"),
   startStream: bindPublicMethod("startStream"),
   stopStream: bindPublicMethod("stopStream"),
   setMicState: bindPublicMethod("setMicState"),
@@ -134,8 +157,12 @@ export const BluetoothSdk: BluetoothSdkPublicModule = Object.freeze({
   setGlassesMediaVolume: bindPublicMethod("setGlassesMediaVolume"),
   rgbLedControl: bindPublicMethod("rgbLedControl"),
   requestVersionInfo: bindPublicMethod("requestVersionInfo"),
+  setOtaVersionUrl: bindPublicMethod("setOtaVersionUrl"),
+  getOtaVersionUrl: bindPublicMethod("getOtaVersionUrl"),
   checkForOtaUpdate: bindPublicMethod("checkForOtaUpdate"),
+  getReleaseChangelogs,
   startOtaUpdate,
+  queryOtaStatus,
   startAr99OtaFromFile: bindPublicMethod("startAr99OtaFromFile"),
   cancelAr99Ota: bindPublicMethod("cancelAr99Ota"),
   sendAr99FactoryReset: bindPublicMethod("sendAr99FactoryReset"),
@@ -204,23 +231,37 @@ export type {
   HotspotErrorEvent,
   HotspotStatus,
   HotspotStatusChangeEvent,
+  GlassesSessionChangedEvent,
+  KeepAliveAckEvent,
   LocalTranscriptionEvent,
   LogEvent,
   MicLc3Event,
+  MicHealthEvent,
   MicMode,
   MicPcmEvent,
   MicPreference,
   OtaStartAckEvent,
+  OtaProgress,
+  OtaProgressStatus,
+  OtaStage,
   OtaStatus,
   OtaStatusEvent,
   OtaQueryResult,
+  OtaUpdateInfo,
+  ReleaseChangelog,
+  MtkUpdateCompleteEvent,
   PairFailureEvent,
+  PairingInfoEvent,
+  EnteringPairingModeEvent,
+  OwnerReplacedEvent,
   PhotoCaptureMetadata,
   PhotoResolvedConfig,
   PhotoCompression,
   PhotoFpsRange,
   PhotoMeteredPreview,
   PhotoMode,
+  PublicBluetoothStatus,
+  PublicGlassesStatus,
   PhotoTransferMethod,
   PhotoResponseEvent,
   PhotoRequestedCaptureConfig,

package/src/ota-server/MentraOtaServer.types.ts

@@ -0,0 +1,10 @@
+export type OtaServerResult = {
+  baseUrl: string
+  host: string
+  manifestUrl: string
+  port: number
+}
+
+export type MentraOtaServerModuleEvents = {
+  artifactDownloadProgress: (event: {destination: string; bytesWritten: number; contentLength: number}) => void
+}

package/src/ota-server/MentraOtaServerModule.ts

@@ -0,0 +1,23 @@
+import {NativeModule, requireNativeModule} from "expo"
+
+import type {MentraOtaServerModuleEvents, OtaServerResult} from "./MentraOtaServer.types"
+
+declare class MentraOtaServerModule extends NativeModule<MentraOtaServerModuleEvents> {
+  /**
+   * Serve `manifestJson` at /version.json and `artifactPaths` (sha256 -> local file path)
+   * at /artifacts/<sha256>. Pass `host` when the caller knows the authoritative local
+   * address (e.g. from the scoped hotspot network); omit to fall back to interface
+   * scanning. Returns the URLs to hand to the glasses via ota_start.
+   */
+  startOtaServer(
+    manifestJson: string,
+    artifactPaths: Record<string, string>,
+    host?: string | null,
+  ): Promise<OtaServerResult>
+  stopOtaServer(): Promise<void>
+  /** Wait for iPhone Wi-Fi (`en0`) to acquire an address on the glasses gateway subnet. */
+  waitForWifiAddress(gateway: string, timeoutMs: number): Promise<string>
+  downloadArtifact(source: string, destination: string): Promise<{statusCode: number; bytesWritten: number}>
+}
+
+export default requireNativeModule<MentraOtaServerModule>("MentraOtaServer")

package/src/ota-server/MentraOtaServerModule.web.ts

@@ -0,0 +1,17 @@
+import {NativeModule, registerWebModule} from "expo"
+
+import type {MentraOtaServerModuleEvents, OtaServerResult} from "./MentraOtaServer.types"
+
+class MentraOtaServerModule extends NativeModule<MentraOtaServerModuleEvents> {
+  async startOtaServer(): Promise<OtaServerResult> {
+    throw new Error("The OTA server is only available in native apps.")
+  }
+
+  async stopOtaServer(): Promise<void> {}
+
+  async waitForWifiAddress(): Promise<string> {
+    throw new Error("The OTA server is only available in native apps.")
+  }
+}
+
+export default registerWebModule(MentraOtaServerModule, "MentraOtaServer")

package/src/ota-server/index.ts

@@ -0,0 +1,2 @@
+export {default} from "./MentraOtaServerModule"
+export * from "./MentraOtaServer.types"

package/src/ota-transport/index.ts

@@ -0,0 +1,116 @@
+// This public adapter is the package-owned boundary over its native implementation.
+// eslint-disable-next-line no-restricted-imports
+import MentraLocalNetwork from "../_private/MentraLocalNetworkModule"
+// eslint-disable-next-line no-restricted-imports
+import MentraOtaServer from "../ota-server"
+
+export type OtaTransportSubscription = {remove(): void}
+
+export type OtaLocalNetworkConnection = {
+  connected: boolean
+  ssid: string
+  localAddress?: string
+}
+
+export type OtaLocalNetworkLostEvent = {ssid: string}
+
+export type OtaLocalNetworkResponse = {
+  status: number
+  headers: Record<string, string>
+  bodyBase64: string
+}
+
+export type OtaLocalNetworkDownloadResult = {
+  statusCode: number
+  bytesWritten: number
+  headers: Record<string, string>
+}
+
+export type OtaLocalNetworkDownloadProgress = {
+  requestId: string
+  bytesWritten: number
+  contentLength: number
+  statusCode?: number
+  headers?: Record<string, string>
+}
+
+export type OtaArtifactDownloadProgress = {
+  destination: string
+  bytesWritten: number
+  contentLength: number
+}
+
+export type OtaServerResult = {
+  baseUrl: string
+  host: string
+  manifestUrl: string
+  port: number
+}
+
+/**
+ * Scoped networking for traffic that must stay on a Mentra Live hotspot while
+ * the phone's default route remains on cellular or another Wi-Fi network.
+ *
+ * The module is optional because iOS uses its system Wi-Fi join flow instead.
+ */
+export const otaLocalNetwork = Object.freeze({
+  isAvailable: (): boolean => MentraLocalNetwork != null,
+  connect: async (ssid: string, password: string): Promise<OtaLocalNetworkConnection> => {
+    if (!MentraLocalNetwork) throw new Error("Scoped local networking is not available in this native build")
+    return MentraLocalNetwork.connect(ssid, password)
+  },
+  request: async (
+    requestId: string,
+    url: string,
+    method: string,
+    headers: Record<string, string>,
+    body: string | null,
+    timeoutMs: number,
+  ): Promise<OtaLocalNetworkResponse> => {
+    if (!MentraLocalNetwork) throw new Error("Scoped local networking is not available in this native build")
+    return MentraLocalNetwork.request(requestId, url, method, headers, body, timeoutMs)
+  },
+  download: async (
+    requestId: string,
+    url: string,
+    destination: string,
+    headers: Record<string, string>,
+    connectionTimeoutMs: number,
+    readTimeoutMs: number,
+  ): Promise<OtaLocalNetworkDownloadResult> => {
+    if (!MentraLocalNetwork) throw new Error("Scoped local networking is not available in this native build")
+    return MentraLocalNetwork.download(requestId, url, destination, headers, connectionTimeoutMs, readTimeoutMs)
+  },
+  cancel: async (requestId: string): Promise<void> => {
+    if (!MentraLocalNetwork) return
+    await MentraLocalNetwork.cancel(requestId)
+  },
+  disconnect: async (): Promise<void> => {
+    if (!MentraLocalNetwork) return
+    await MentraLocalNetwork.disconnect()
+  },
+  onDownloadProgress: (listener: (event: OtaLocalNetworkDownloadProgress) => void): OtaTransportSubscription => {
+    if (!MentraLocalNetwork) return {remove() {}}
+    return MentraLocalNetwork.addListener("downloadProgress", listener)
+  },
+  onNetworkLost: (listener: (event: OtaLocalNetworkLostEvent) => void): OtaTransportSubscription => {
+    if (!MentraLocalNetwork) return {remove() {}}
+    return MentraLocalNetwork.addListener("networkLost", listener)
+  },
+})
+
+/** Native HTTP server and artifact downloader used by the Engine OTA coordinator. */
+export const otaServer = Object.freeze({
+  start: (
+    manifestJson: string,
+    artifactPaths: Record<string, string>,
+    host?: string | null,
+  ): Promise<OtaServerResult> => MentraOtaServer.startOtaServer(manifestJson, artifactPaths, host),
+  stop: (): Promise<void> => MentraOtaServer.stopOtaServer(),
+  waitForWifiAddress: (gateway: string, timeoutMs: number): Promise<string> =>
+    MentraOtaServer.waitForWifiAddress(gateway, timeoutMs),
+  downloadArtifact: (source: string, destination: string): Promise<{statusCode: number; bytesWritten: number}> =>
+    MentraOtaServer.downloadArtifact(source, destination),
+  onArtifactDownloadProgress: (listener: (event: OtaArtifactDownloadProgress) => void): OtaTransportSubscription =>
+    MentraOtaServer.addListener("artifactDownloadProgress", listener),
+})