@mentra/engine 0.1.0-dev.0

package/src/services/navigation/routesApiCodec.ts

@@ -0,0 +1,69 @@
+/**
+ * Pure decoders used by `NavigationService.computeRoute` when talking to
+ * Mapbox's Directions API directly (no native dependency).
+ *
+ * Kept in their own module so unit tests don't have to bring up the
+ * `crust` native module to exercise them. The algorithms are unit
+ * testable; the surrounding service is not.
+ *
+ * Migrated from Google Routes API: Mapbox returns numeric `distance`
+ * (meters) / `duration` (seconds) rather than Google's `"123s"` protobuf
+ * strings, and `polyline6` (precision-6) geometry rather than Google's
+ * precision-5 encoded polyline. `parseDurationSeconds` is retained for
+ * back-compat but Mapbox callers pass the numeric value through directly.
+ */
+
+export type LatLng = {lat: number; lng: number}
+
+/**
+ * Back-compat: Google Routes API encoded durations as protobuf strings
+ * ("123s"). Mapbox returns a number, so new callers should not need this.
+ * Accepts a number (passed through) or a "123s" string.
+ */
+export function parseDurationSeconds(s: string | number): number {
+  if (typeof s === "number") return Number.isFinite(s) ? Math.round(s) : 0
+  const match = s.match(/^(\d+)/)
+  return match ? Number(match[1]) : 0
+}
+
+/**
+ * Decode an encoded polyline. The standard Google/Mapbox polyline
+ * algorithm, parameterized by coordinate precision:
+ *   - precision 5 (Google Routes, Mapbox `polyline`): factor 1e5
+ *   - precision 6 (Mapbox `polyline6`): factor 1e6
+ *
+ * We request `geometries=polyline6` from Mapbox Directions for the extra
+ * precision (tighter road-centerline tracing keeps the turn-pivot dots on
+ * the visible road), so the default precision here is 6.
+ *
+ * Reference: https://docs.mapbox.com/api/navigation/directions/#route-object
+ */
+export function decodePolyline(encoded: string, precision: number = 6): LatLng[] {
+  if (!encoded) return []
+  const factor = Math.pow(10, precision)
+  const points: LatLng[] = []
+  let index = 0
+  let lat = 0
+  let lng = 0
+  while (index < encoded.length) {
+    let result = 0
+    let shift = 0
+    let b: number
+    do {
+      b = encoded.charCodeAt(index++) - 63
+      result |= (b & 0x1f) << shift
+      shift += 5
+    } while (b >= 0x20)
+    lat += result & 1 ? ~(result >> 1) : result >> 1
+    result = 0
+    shift = 0
+    do {
+      b = encoded.charCodeAt(index++) - 63
+      result |= (b & 0x1f) << shift
+      shift += 5
+    } while (b >= 0x20)
+    lng += result & 1 ? ~(result >> 1) : result >> 1
+    points.push({lat: lat / factor, lng: lng / factor})
+  }
+  return points
+}

package/src/services/otaDisplayState.ts

@@ -0,0 +1,115 @@
+import type {OtaProgress, OtaStatus} from "@mentra/bluetooth-sdk/internal"
+
+import {isLegacyShapedOtaStatus} from "./otaInstallPolicy"
+
+export type DisplayState = "starting" | "updating" | "complete" | "failed" | "disconnected" | "restarting"
+
+/**
+ * Pure derivation of the OTA progress UI state from the glasses data in the
+ * Zustand store plus a couple of genuinely-local inputs. See
+ * OtaInstallCoordinator.ts for the state machine that consumes this (the host
+ * progress screen renders its snapshot).
+ *
+ * Legacy shape (WP 8C): old (< 37) ASG builds send `ota_progress`, which the SDK
+ * maps to ota_status with sessionId "" and FINISHED→"complete" at ANY phase. For
+ * those statuses a download-phase "complete" only means the download finished
+ * (the install is still ahead), and an apk install "complete" may be held by the
+ * coordinator's settle window — both stay "updating" instead of terminal.
+ *
+ * Priority-ordered rules (first match wins):
+ *   1. errorMsg !== ""                                          -> "failed"
+ *   2. BES terminal + connected + sawReconnectEdge             -> "complete"
+ *   3. BES terminal (any connection state)                     -> "restarting"
+ *      (legacy-shaped BES "complete" counts only in install phase)
+ *   4. apkCompletedViaBuildIncrease (legacy build-number port) -> "complete"
+ *   5. otaStatus.status === "failed"                           -> "failed"
+ *   6. otaStatus.status === "complete" (non-BES)               -> "complete"
+ *      (unless legacy-shaped download-complete or held apk settle -> in flight)
+ *   7. !connected + legacy in-flight complete (held apk)       -> "updating"
+ *   8. !connected + APK step_complete with totalSteps > 1      -> "starting"   (expected reboot)
+ *   9. !connected + BES in flight                              -> "restarting" (defensive)
+ *   10. !connected                                             -> "disconnected"
+ *   11. connected + in_progress | step_complete | legacy in-flight complete -> "updating"
+ *   12. fallback                                               -> "starting"
+ */
+export function deriveDisplayState(args: {
+  otaStatus: OtaStatus | null
+  otaProgress: OtaProgress | null
+  connected: boolean
+  errorMsg: string
+  sawReconnectEdge: boolean
+  /** Coordinator is holding a legacy apk install "complete" for the settle window (WP 8C). */
+  legacyApkSettleHold?: boolean
+  /** Legacy APK completion detected by build-number increase (WP 8C). */
+  apkCompletedViaBuildIncrease?: boolean
+}): DisplayState {
+  const {otaStatus, otaProgress, connected, errorMsg, sawReconnectEdge, legacyApkSettleHold, apkCompletedViaBuildIncrease} =
+    args
+
+  if (errorMsg) return "failed"
+
+  const besTerminal = isBesTerminal(otaStatus, otaProgress)
+  if (besTerminal && connected && sawReconnectEdge) return "complete"
+  if (besTerminal) return "restarting"
+
+  // Legacy build-number APK completion: the coordinator clears errorMsg when it fires,
+  // and the flag outranks whatever stale legacy status is still in the store (the old
+  // screen's last-write-wins completion from starting/failed/installing).
+  if (apkCompletedViaBuildIncrease) return "complete"
+
+  if (otaStatus?.status === "failed") return "failed"
+
+  // Legacy-shaped "complete" that is still in flight: a download-phase FINISHED (the
+  // install is still ahead), or an apk install FINISHED held by the settle window.
+  const legacyInFlightComplete =
+    isLegacyShapedOtaStatus(otaStatus) &&
+    otaStatus?.status === "complete" &&
+    (otaStatus.phase === "download" ||
+      (!!legacyApkSettleHold && otaStatus.stepType === "apk" && otaStatus.phase === "install"))
+
+  if (otaStatus?.status === "complete" && !legacyInFlightComplete) return "complete"
+
+  if (!connected) {
+    // The held apk install complete means the glasses are restarting into the new
+    // build — the legacy screen kept showing "installing" through that restart.
+    if (legacyInFlightComplete && otaStatus?.phase === "install") return "updating"
+
+    // By here, the failed/complete rules already returned for terminal statuses.
+    // For APK multi-step, "step_complete" means the current step ended and the
+    // glasses are rebooting to start the next one.
+    const apkRebootExpected =
+      otaStatus?.stepType === "apk" && (otaStatus?.totalSteps ?? 0) > 1 && otaStatus.status === "step_complete"
+    if (apkRebootExpected) return "starting"
+
+    // Legacy-shaped BES download events do not mean a reboot is coming (the flash
+    // has not started); the legacy screen treated that drop as a plain disconnect.
+    const besStatusInFlight =
+      otaStatus?.stepType === "bes" && !(isLegacyShapedOtaStatus(otaStatus) && otaStatus.phase === "download")
+    const besInFlight =
+      besStatusInFlight || (otaProgress?.currentUpdate === "bes" && otaProgress?.stage === "install")
+    if (besInFlight) return "restarting"
+
+    return "disconnected"
+  }
+
+  if (otaStatus?.status === "in_progress" || otaStatus?.status === "step_complete" || legacyInFlightComplete) {
+    return "updating"
+  }
+
+  return "starting"
+}
+
+function isBesTerminal(otaStatus: OtaStatus | null, otaProgress: OtaProgress | null): boolean {
+  if (otaStatus?.stepType === "bes" && (otaStatus.status === "step_complete" || otaStatus.status === "complete")) {
+    // Legacy-shaped statuses map download FINISHED to "complete" too; only an
+    // install-phase terminal means the BES flash actually ran (WP 8C).
+    if (isLegacyShapedOtaStatus(otaStatus) && otaStatus.phase !== "install") {
+      return false
+    }
+    return true
+  }
+  if (otaProgress?.currentUpdate === "bes" && otaProgress.stage === "install" && otaProgress.status === "FINISHED") {
+    return true
+  }
+  return false
+}

package/src/services/otaInstallPolicy.ts

@@ -0,0 +1,106 @@
+/** Shared OTA progress watchdog timings (see progress-legacy.tsx / progress.tsx). */
+import type {OtaProgress, OtaStatus} from "@mentra/bluetooth-sdk/internal"
+
+/**
+ * First glasses `build_number` (ASG `versionCode`) that uses `progress.tsx` with unified
+ * `ota_status` session UI. Strictly lower builds use `/ota/progress-legacy` (routed from
+ * `check-for-updates.tsx` before navigation), and get the LEGACY_* padded policy below
+ * in the unified OtaInstallCoordinator (WP 8C). Change only here.
+ */
+export const MINIMUM_OTA_STATUS_BUILD = 37
+
+export const MAX_RETRIES = 3
+export const RETRY_INTERVAL_MS = 5000
+/** APK/BES and general install when progress events are expected */
+export const PROGRESS_TIMEOUT_MS = 120_000
+/** Fail if still at 0% in starting/downloading */
+export const DOWNLOAD_STUCK_TIMEOUT_MS = 70_000
+/** MTK system install often goes quiet for long periods */
+export const MTK_INSTALL_TIMEOUT_MS = 300_000
+/** Whole multi-step session cap */
+export const GLOBAL_OTA_TIMEOUT_MS = 20 * 60 * 1000
+/** After APK reboot, ASG OTA service needs time before next ota_start */
+export const POST_APK_OTA_START_DELAY_MS = 6000
+/** BLE keepalive during OTA */
+export const PING_INTERVAL_MS = 10_000
+/**
+ * If we sent ota_query_status (e.g. on reconnect) and the glasses haven't
+ * replied with an ota_status by then, fall back to ota_start. This recovers
+ * from the case where the glasses process restarted between mount and
+ * reconnect — the session is gone, ota_query_status returns nothing, and
+ * the user would otherwise sit on the spinner forever.
+ */
+export const QUERY_REPLY_TIMEOUT_MS = 6000
+/** 15s lockout on the Continue button after a BES restart, to prevent an accidental tap. */
+export const BES_CONTINUE_LOCKOUT_MS = 15_000
+
+// --- Legacy old-build (< MINIMUM_OTA_STATUS_BUILD) OTA policy (WP 8C) ---
+//
+// Ported verbatim from mobile/src/app/ota/progress-legacy.tsx, which padded EVERY
+// watchdog/timer by +20s for old ASG builds ("Legacy OTA: +20s on every watchdog /
+// timer duration"). Old builds respond slower on every path, so where the legacy
+// screen used a longer duration the coordinator applies the longer value whenever
+// the session is legacy-shaped (see isLegacyShapedOtaStatus / the coordinator's
+// session-shape check). Builds >= 37 keep the unpadded values above.
+
+/** The uniform pad progress-legacy.tsx added to every duration for old builds. */
+export const LEGACY_EXTRA_TIMEOUT_MS = 20_000
+export const LEGACY_RETRY_INTERVAL_MS = RETRY_INTERVAL_MS + LEGACY_EXTRA_TIMEOUT_MS
+export const LEGACY_PROGRESS_TIMEOUT_MS = PROGRESS_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS
+export const LEGACY_DOWNLOAD_STUCK_TIMEOUT_MS = DOWNLOAD_STUCK_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS
+export const LEGACY_MTK_INSTALL_TIMEOUT_MS = MTK_INSTALL_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS
+export const LEGACY_GLOBAL_OTA_TIMEOUT_MS = GLOBAL_OTA_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS
+export const LEGACY_PING_INTERVAL_MS = PING_INTERVAL_MS + LEGACY_EXTRA_TIMEOUT_MS
+export const LEGACY_BES_CONTINUE_LOCKOUT_MS = BES_CONTINUE_LOCKOUT_MS + LEGACY_EXTRA_TIMEOUT_MS
+/**
+ * After a legacy apk `install FINISHED` observed in-flight, the legacy screen held the
+ * completed state for 12s (+20s pad) so the ASG process restart settles (and fresh
+ * version_info lands) before the user can continue.
+ */
+export const LEGACY_APK_COMPLETION_SETTLE_MS = 12_000 + LEGACY_EXTRA_TIMEOUT_MS
+/**
+ * Legacy MTK install stall simulation (display-only): the MTK system install typically
+ * stalls around 49-50%. After LEGACY_MTK_STALL_DETECT_MS without a new event in the
+ * [45, 55) zone, the legacy screen simulated +1% every LEGACY_MTK_SIM_TICK_MS starting
+ * at max(stall+1, 51) and capped at 60%, purely to keep the user informed.
+ */
+export const LEGACY_MTK_STALL_DETECT_MS = 20_000 + LEGACY_EXTRA_TIMEOUT_MS
+export const LEGACY_MTK_SIM_TICK_MS = 15_000 + LEGACY_EXTRA_TIMEOUT_MS
+export const LEGACY_MTK_STALL_ZONE_MIN_PERCENT = 45
+export const LEGACY_MTK_STALL_ZONE_MAX_PERCENT = 55
+export const LEGACY_MTK_SIM_FLOOR_PERCENT = 51
+export const LEGACY_MTK_SIM_CAP_PERCENT = 60
+
+/**
+ * Legacy-shaped ota_status: old (< 37) ASG builds send `ota_progress`, which the SDK
+ * (Android MentraLive.kt / iOS MentraLive.swift) maps to a unified ota_status with
+ * sessionId "" and totalSteps 1, and FINISHED→"complete" regardless of phase. A real
+ * (>= 37) session always carries a sessionId; an "idle" reply also has sessionId "" but
+ * proves the glasses speak the unified protocol, so it is NOT legacy-shaped.
+ */
+export function isLegacyShapedOtaStatus(otaStatus: OtaStatus | null): boolean {
+  return !!otaStatus && otaStatus.sessionId === "" && otaStatus.status !== "idle"
+}
+
+/**
+ * Is the current install session legacy-shaped? Event shape wins when events exist
+ * (per the WP 8C rule: key off legacy-shaped inputs, not a build flag, where possible);
+ * before any event arrives only the glasses build number can tell.
+ */
+export function isLegacyShapedOtaSession(
+  otaStatus: OtaStatus | null,
+  otaProgress: OtaProgress | null,
+  buildNumber: string | null | undefined,
+): boolean {
+  if (otaStatus) return isLegacyShapedOtaStatus(otaStatus)
+  if (otaProgress) return true
+  const build = Number.parseInt(buildNumber ?? "", 10)
+  return Number.isFinite(build) && build > 0 && build < MINIMUM_OTA_STATUS_BUILD
+}
+
+export const OtaProgressMessages = {
+  noAckResponse: "Unable to start update. Glasses did not respond.",
+  stalledOrStuck: "Update may have failed. Ensure glasses have internet access and try again.",
+  globalTimeout: "Update took too long. Please try again.",
+  sendOtaStartFailed: "Failed to communicate with glasses.",
+} as const

package/src/services/otaLegacyMapping.ts

@@ -0,0 +1,71 @@
+import type {OtaProgress, OtaProgressStatus, OtaStatus} from "@mentra/bluetooth-sdk/internal"
+
+/** Normalized ota_status fields (snake_case) after bridging Core/expo (snake or camel). */
+export type NormalizedOtaStatusEvent = {
+  session_id: string
+  total_steps: number
+  current_step: number
+  step_type: string
+  phase: "download" | "install"
+  step_percent: number
+  overall_percent: number
+  status: string
+  error_message?: string
+}
+
+/**
+ * Core may deliver ota_status with snake_case (Android) or camelCase (some bridge paths).
+ * Use this for Mantle and legacy otaProgress mapping.
+ */
+export function normalizeOtaStatusEvent(event: Record<string, unknown>): NormalizedOtaStatusEvent {
+  const e = event as Record<string, any>
+  const phase: "download" | "install" = e?.phase === "install" ? "install" : "download"
+  const err = e?.error_message ?? e?.errorMessage
+  return {
+    session_id: String(e?.session_id ?? e?.sessionId ?? ""),
+    total_steps: Number(e?.total_steps ?? e?.totalSteps ?? 0),
+    current_step: Number(e?.current_step ?? e?.currentStep ?? 0),
+    step_type: String(e?.step_type ?? e?.stepType ?? "apk"),
+    phase,
+    step_percent: Number(e?.step_percent ?? e?.stepPercent ?? 0),
+    overall_percent: Number(e?.overall_percent ?? e?.overallPercent ?? 0),
+    status: String(e?.status ?? "idle"),
+    error_message: err == null || err === "" ? undefined : String(err),
+  }
+}
+
+export function otaStatusFromNormalized(n: NormalizedOtaStatusEvent): OtaStatus {
+  return {
+    sessionId: n.session_id,
+    totalSteps: n.total_steps,
+    currentStep: n.current_step,
+    stepType: n.step_type as OtaStatus["stepType"],
+    phase: n.phase,
+    stepPercent: n.step_percent,
+    overallPercent: n.overall_percent,
+    status: n.status as OtaStatus["status"],
+    error: n.error_message,
+  }
+}
+
+/** Maps unified ota_status from Core into the legacy otaProgress store shape (progress-legacy, settings). */
+export function legacyOtaProgressFromOtaStatusEvent(
+  event: Record<string, unknown> | NormalizedOtaStatusEvent,
+): OtaProgress {
+  const n = normalizeOtaStatusEvent(event as Record<string, unknown>)
+  const raw = (n.overall_percent ?? n.step_percent ?? 0) as number
+  let st: OtaProgressStatus = "PROGRESS"
+  // Native K900 BES OTA (sr_adota) sends step_complete, not complete, on success — map for progress-legacy FINISHED.
+  if (n.status === "complete" || n.status === "step_complete") st = "FINISHED"
+  else if (n.status === "failed") st = "FAILED"
+  else if (n.status === "idle") st = "STARTED"
+  return {
+    stage: n.phase === "install" ? "install" : "download",
+    status: st,
+    progress: Math.round(raw),
+    bytesDownloaded: 0,
+    totalBytes: 0,
+    currentUpdate: n.step_type || "apk",
+    errorMessage: n.error_message,
+  }
+}

package/src/services/slimStreamStatus.ts

@@ -0,0 +1,28 @@
+import type {StreamStatusEvent} from "@mentra/bluetooth-sdk/internal"
+
+/** Fields forwarded to cloud / miniapps after the first resolvedConfig ack. */
+export function slimStreamStatusEvent(
+  event: StreamStatusEvent,
+  options: {includeResolvedConfig?: boolean} = {},
+): Record<string, unknown> {
+  const slim: Record<string, unknown> = {
+    type: "stream_status",
+    kind: event.kind,
+    status: event.status,
+  }
+  if (event.streamId) slim.streamId = event.streamId
+  const ts = event.timestamp
+  if (typeof ts === "number" && Number.isFinite(ts)) slim.timestamp = ts
+  if (options.includeResolvedConfig && event.resolvedConfig) {
+    slim.resolvedConfig = event.resolvedConfig
+  }
+  // Live telemetry passes straight through — unlike resolvedConfig it changes
+  // per event, and the signature dedupe upstream only suppresses identical
+  // payloads.
+  if (event.stats) slim.stats = event.stats
+  return slim
+}
+
+export function streamStatusSignature(payload: Record<string, unknown>): string {
+  return JSON.stringify(payload)
+}