@mentra/bluetooth-sdk 3.1.0-dev.10 → 3.1.0-dev.101

package/ios/Tests/ReleaseChangelogTests.swift

@@ -0,0 +1,13 @@
+@testable import MentraBluetoothSDK
+import XCTest
+
+final class ReleaseChangelogTests: XCTestCase {
+    func testIncludesTargetNotesForTransitionWithinOneReleaseTrain() throws {
+        let changelogs = try ReleaseChangelogCatalog.select(
+            fromVersion: "3.1.0-dev.2",
+            toVersion: "3.1.0-beta.8"
+        )
+
+        XCTAssertEqual(changelogs.map(\.version), ["3.1.0"])
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/bluetooth-sdk",
-  "version": "3.1.0-dev.10",
+  "version": "3.1.0-dev.101",
   "description": "SDK for communicating with smart glasses",
   "main": "build/index.js",
   "react-native": "src/index.ts",
@@ -32,6 +32,11 @@
       "types": "./build/photo-receiver/index.d.ts",
       "default": "./build/photo-receiver/index.js"
     },
+    "./ota-transport": {
+      "react-native": "./src/ota-transport/index.ts",
+      "types": "./build/ota-transport/index.d.ts",
+      "default": "./build/ota-transport/index.js"
+    },
     "./debug": {
       "react-native": "./src/debug.ts",
       "types": "./build/debug.d.ts",

package/scripts/public-ota-api.test.mjs

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict"
+import {readFileSync} from "node:fs"
+import path from "node:path"
+import test from "node:test"
+import {fileURLToPath} from "node:url"
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+
+test("publishes the supported OTA transport entrypoint", () => {
+  const manifest = JSON.parse(readFileSync(path.join(packageRoot, "package.json"), "utf8"))
+  assert.deepEqual(manifest.exports["./ota-transport"], {
+    "react-native": "./src/ota-transport/index.ts",
+    "types": "./build/ota-transport/index.d.ts",
+    "default": "./build/ota-transport/index.js",
+  })
+
+  const source = readFileSync(path.join(packageRoot, "src/ota-transport/index.ts"), "utf8")
+  assert.match(source, /export const otaLocalNetwork/)
+  assert.match(source, /export const otaServer/)
+  assert.doesNotMatch(source, /export \{default as Mentra(LocalNetwork|OtaServer)/)
+})
+
+test("keeps restart signals and correlated OTA status on the public root", () => {
+  const source = readFileSync(path.join(packageRoot, "src/index.ts"), "utf8")
+  for (const required of [
+    '"glasses_session_changed"',
+    '"mtk_update_complete"',
+    "queryOtaStatus",
+    "subscribeGlassesStatus",
+    "subscribeBluetoothStatus",
+    "setSystemTime",
+    "ping",
+  ]) {
+    assert.ok(source.includes(required), `missing public OTA primitive: ${required}`)
+  }
+  assert.match(source, /Unsupported BluetoothSdk event/)
+})

package/src/BluetoothSdk.types.ts

@@ -1043,6 +1043,10 @@ export type BluetoothSdkEventMap = {
   mic_lc3: MicLc3Event
   mic_health: MicHealthEvent
   stream_status: StreamStatusEvent
+  /** Mentra Live MTK updater completed and the glasses are about to restart. */
+  mtk_update_complete: MtkUpdateCompleteEvent
+  /** The ASG process restarted while the BES kept the BLE connection alive. */
+  glasses_session_changed: GlassesSessionChangedEvent
   ota_start_ack: OtaStartAckEvent
   ota_status: OtaStatusEvent
   ar99_ota_status: Ar99OtaStatusEvent
@@ -1068,6 +1072,15 @@ export interface BluetoothSdkPublicModule {
     listener: BluetoothSdkEventListener<EventName>,
   ): BluetoothSdkSubscription
 
+  /** Read an immutable snapshot of the current glasses state. */
+  getGlassesStatus(): Promise<PublicGlassesStatus>
+  /** Read an immutable snapshot of the phone Bluetooth adapter state. */
+  getBluetoothStatus(): Promise<PublicBluetoothStatus>
+  /** Observe immutable glasses-state patches. Returns an unsubscribe function. */
+  subscribeGlassesStatus(listener: (changed: Partial<PublicGlassesStatus>) => void): () => void
+  /** Observe immutable Bluetooth-state patches. Returns an unsubscribe function. */
+  subscribeBluetoothStatus(listener: (changed: Partial<PublicBluetoothStatus>) => void): () => void
+
   getDefaultDevice(): Promise<Device | null>
   setDefaultDevice(device: Device | null): Promise<void>
   clearDefaultDevice(): Promise<void>
@@ -1089,11 +1102,15 @@ export interface BluetoothSdkPublicModule {
   setHeadUpAngle(angleDegrees: number): Promise<void>
   setImuEnabled(enabled: boolean): Promise<void>
   setScreenDisabled(disabled: boolean): Promise<void>
+  /** Keep legacy Mentra Live OTA sessions awake. Modern sessions normally do not require this. */
+  ping(): Promise<void>
 
   requestWifiScan(): Promise<WifiSearchResult[]>
   sendWifiCredentials(ssid: string, password: string): Promise<WifiStatusChangeEvent>
   forgetWifiNetwork(ssid: string): Promise<WifiStatusChangeEvent>
   setHotspotState(enabled: boolean): Promise<HotspotStatusChangeEvent>
+  /** Set the glasses clock from the phone after an OTA clock-skew failure. */
+  setSystemTime(timestampMs: number): Promise<void>
   /** Enable or disable Wi-Fi ADB on Mentra Live (no-op on other devices). */
   setWifiAdbState(enabled: boolean): Promise<void>
 
@@ -1182,8 +1199,12 @@ export interface BluetoothSdkPublicModule {
   getOtaVersionUrl(): string
   /** Fetch the configured OTA manifest and return whether any ASG/BES/MTK update is available. */
   checkForOtaUpdate(): Promise<boolean>
+  /** Return bundled release changelogs crossed between two coordinated product versions, newest first. */
+  getReleaseChangelogs(fromVersion?: string | null, toVersion?: string | null): ReleaseChangelog[]
   /** Start OTA from the configured or explicitly supplied manifest URL. */
   startOtaUpdate(otaVersionUrl?: string | null): Promise<OtaStartAckEvent>
+  /** Query the active OTA session and return the correlated status response. */
+  queryOtaStatus(): Promise<OtaQueryResult>
   startAr99OtaFromFile(path: string): Promise<boolean>
   cancelAr99Ota(): Promise<void>
   sendAr99FactoryReset(): Promise<void>
@@ -1262,6 +1283,13 @@ export interface OtaUpdateInfo {
   isDowngrade?: boolean
 }
 
+export interface ReleaseChangelog {
+  /** Base production version, for example `3.1.0`. */
+  version: string
+  /** Markdown body authored in `/changelogs/<version>.md`. */
+  markdown: string
+}
+
 export interface OtaProgress {
   stage: OtaStage
   status: OtaProgressStatus

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

@@ -12,9 +12,9 @@ export interface BluetoothSdkReleaseMetadata {
 export const BLUETOOTH_SDK_RELEASE_METADATA: Readonly<BluetoothSdkReleaseMetadata> = Object.freeze({
   "schemaVersion": 1,
   "familyBaseVersion": "3.1.0",
-  "releaseIdentity": "3.1.0-dev.10",
-  "releaseSetId": "mentra-3.1.0-dev.10",
-  "sourceCommit": "64cf83b23a71e70261571a5f4401d1a7538f1852",
-  "otaManifestUrl": "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-v3.1.0-dev.10/mentra-live-ota-3.1.0-dev.10.json",
-  "otaManifestSha256": "214d92c8894033eaab276e668cb553c79990005d3330d23aaf499a514dc08cff"
+  "releaseIdentity": "3.1.0-dev.101",
+  "releaseSetId": "mentra-3.1.0-dev.101",
+  "sourceCommit": "7cbd0579aa228fcfd4d36adda6de1150c3a43647",
+  "otaManifestUrl": "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.1.0/mentra-live-ota-3.1.0-dev.101.json",
+  "otaManifestSha256": "37c1d4399b7d7a9bf973138bca4035e930df80cf67da828a3e54049ed0034802"
 })

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",
@@ -46,6 +49,8 @@ const PUBLIC_EVENT_NAMES = new Set<BluetoothSdkEventName>([
   "mic_lc3",
   "mic_health",
   "stream_status",
+  "mtk_update_complete",
+  "glasses_session_changed",
   "ota_start_ack",
   "ota_status",
   "ar99_ota_status",
@@ -64,6 +69,10 @@ const startOtaUpdate: BluetoothSdkPublicModule["startOtaUpdate"] = (otaVersionUr
   return PrivateBluetoothSdkModule.startOtaUpdate(otaVersionUrl)
 }
 
+const queryOtaStatus: BluetoothSdkPublicModule["queryOtaStatus"] = () => {
+  return PrivateBluetoothSdkModule.sendOtaQueryStatus()
+}
+
 const bindPublicMethod = <K extends keyof BluetoothSdkPublicModule>(name: K): BluetoothSdkPublicModule[K] => {
   const method = (PrivateBluetoothSdkModule as unknown as Record<string, unknown>)[name]
   if (typeof method === "function") {
@@ -77,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"),
@@ -95,10 +110,12 @@ 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"),
@@ -143,7 +160,9 @@ export const BluetoothSdk: BluetoothSdkPublicModule = Object.freeze({
   setOtaVersionUrl: bindPublicMethod("setOtaVersionUrl"),
   getOtaVersionUrl: bindPublicMethod("getOtaVersionUrl"),
   checkForOtaUpdate: bindPublicMethod("checkForOtaUpdate"),
+  getReleaseChangelogs,
   startOtaUpdate,
+  queryOtaStatus,
   startAr99OtaFromFile: bindPublicMethod("startAr99OtaFromFile"),
   cancelAr99Ota: bindPublicMethod("cancelAr99Ota"),
   sendAr99FactoryReset: bindPublicMethod("sendAr99FactoryReset"),
@@ -212,6 +231,7 @@ export type {
   HotspotErrorEvent,
   HotspotStatus,
   HotspotStatusChangeEvent,
+  GlassesSessionChangedEvent,
   KeepAliveAckEvent,
   LocalTranscriptionEvent,
   LogEvent,
@@ -228,6 +248,8 @@ export type {
   OtaStatusEvent,
   OtaQueryResult,
   OtaUpdateInfo,
+  ReleaseChangelog,
+  MtkUpdateCompleteEvent,
   PairFailureEvent,
   PairingInfoEvent,
   EnteringPairingModeEvent,
@@ -238,6 +260,8 @@ export type {
   PhotoFpsRange,
   PhotoMeteredPreview,
   PhotoMode,
+  PublicBluetoothStatus,
+  PublicGlassesStatus,
   PhotoTransferMethod,
   PhotoResponseEvent,
   PhotoRequestedCaptureConfig,

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),
+})