@glassly/engine 0.1.0-dev.0

package/src/services/otaDisplayState.ts

@@ -0,0 +1,156 @@
+import type {OtaProgress, OtaStatus} from "@glassly/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 reboot recovery complete                             -> "complete"
+ *   3. BES reboot recovery awaiting reconnect                  -> "restarting"
+ *   4. BES terminal (any connection state)                     -> "restarting"
+ *      (legacy-shaped BES "complete" counts only in install phase)
+ *   6. apkCompletedViaBuildIncrease (legacy build-number port) -> "complete"
+ *   7. otaStatus.status === "failed"                           -> "failed"
+ *   8. otaStatus.status === "complete" (non-BES)               -> "complete"
+ *      (unless legacy-shaped download-complete or held apk settle -> in flight)
+ *   9. !connected + legacy in-flight complete (held apk)       -> "updating"
+ *   10. !connected + APK step_complete with totalSteps > 1     -> "starting"   (expected reboot)
+ *   11. !connected + BES in flight                             -> "restarting" (defensive)
+ *   12. !connected                                             -> "disconnected"
+ *   13. connected + in_progress | step_complete | legacy in-flight complete -> "updating"
+ *   14. fallback                                               -> "starting"
+ */
+export function deriveDisplayState(args: {
+  otaStatus: OtaStatus | null
+  otaProgress: OtaProgress | null
+  connected: boolean
+  errorMsg: string
+  /**
+   * Retained for host API compatibility. A session-wide reconnect edge is not
+   * sufficient for BES completion because it may belong to an earlier APK step.
+   */
+  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
+  /** Phone-observed BES disconnect/reconnect recovery, independent of stale OTA progress. */
+  besRestartRecovery?: "awaiting" | "complete" | null
+  /** Downgrade detour: the reconnected glasses reported exactly the pinned target version. */
+  versionChangeConverged?: boolean
+  /** True for the whole downgrade (version-change) session. */
+  versionChangeSession?: boolean
+}): DisplayState {
+  const {
+    otaStatus,
+    otaProgress,
+    connected,
+    errorMsg,
+    legacyApkSettleHold,
+    apkCompletedViaBuildIncrease,
+    besRestartRecovery,
+    versionChangeConverged,
+    versionChangeSession,
+  } = args
+
+  if (errorMsg) return "failed"
+
+  // Downgrade detour completion: exact-version convergence after reconnect is the
+  // only completion signal (the wipe destroys ASG's ota_session, and the target is
+  // a LOWER build so no build-number increase fires). Outranks the stale install
+  // status still sitting in the store from before the handoff.
+  if (versionChangeConverged) return "complete"
+
+  // A BES reboot destroys or strands the glasses-side OTA session on older
+  // clients. Once the phone observed that reboot, stale pre-reboot progress must
+  // not move the UI from restarting back to updating.
+  if (besRestartRecovery === "complete") return "complete"
+  if (besRestartRecovery === "awaiting") return "restarting"
+
+  // In a version-change session, convergence (above) is the ONLY completion for the ASG
+  // downgrade. A bare non-firmware "complete" before convergence — the glasses refusing
+  // the downgrade (floor/gate) with no install, or a stale pre-handoff status — must never
+  // present as success. Firmware-step completions (mtk/bes) DO pass through: a combined
+  // downgrade+firmware manifest applies firmware first on its own pass, which must finish
+  // so the phone re-checks and re-offers the now-firmware-free downgrade.
+  const isFirmwareComplete = otaStatus?.stepType === "mtk" || otaStatus?.stepType === "bes"
+  if (versionChangeSession && otaStatus?.status === "complete" && !isFirmwareComplete) {
+    return connected ? "updating" : "disconnected"
+  }
+
+  const besTerminal = isBesTerminal(otaStatus, otaProgress)
+  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,132 @@
+/** Shared OTA progress watchdog timings (see progress-legacy.tsx / progress.tsx). */
+import type {OtaProgress, OtaStatus} from "@glassly/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
+/** Wait between ended native ota_start requests; never overlaps a pending request. */
+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
+/** 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
+
+export type OtaProtocolProfile = "legacy" | "unified"
+
+/**
+ * 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
+}
+
+/**
+ * Select the compatibility profile once at install-screen attach. The old split
+ * routes made this decision from the pre-update build and kept it for the whole
+ * mounted flow, even when an APK step restarted into a newer ASG build. Returning
+ * null leaves the coordinator undecided until the first meaningful OTA event.
+ */
+export function selectOtaProtocolProfile(
+  otaStatus: OtaStatus | null,
+  otaProgress: OtaProgress | null,
+  buildNumber: string | null | undefined,
+): OtaProtocolProfile | null {
+  const build = Number.parseInt(buildNumber ?? "", 10)
+  if (Number.isFinite(build) && build > 0) {
+    return build < MINIMUM_OTA_STATUS_BUILD ? "legacy" : "unified"
+  }
+  if (otaStatus) return isLegacyShapedOtaStatus(otaStatus) ? "legacy" : "unified"
+  if (otaProgress) return "legacy"
+  return null
+}
+
+export const OtaProgressMessages = {
+  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.",
+  hotspotArtifactDownloadFailed: "Could not download the update to your phone. Check phone internet and try again.",
+  hotspotArtifactVerifyFailed: "The update package could not be verified. Please try again later.",
+  hotspotWifiPermissionDenied: "Allow nearby devices access so the phone can connect to the glasses hotspot.",
+  hotspotStartFailed: "Could not start the glasses hotspot. Please try again.",
+  hotspotJoinFailed: "Could not connect the phone to the glasses hotspot. Please try again.",
+  hotspotServerFailed: "Could not make the update available to the glasses. Please try again.",
+} as const

package/src/services/otaLegacyMapping.ts

@@ -0,0 +1,71 @@
+import type {OtaProgress, OtaProgressStatus, OtaStatus} from "@glassly/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/otaManifestUrl.ts

@@ -0,0 +1,53 @@
+import {sdkPinnedOtaManifestUrl} from "@glassly/bluetooth-sdk/internal"
+
+import {SETTINGS, useSettingsStore} from "../stores/settings"
+
+// Legacy production manifest — pre-39 glasses install from this (they ignore ota_start's URL).
+const OTA_VERSION_URL_LEGACY_PROD = "https://ota.glassly.ai/prod_live_version.json"
+// Modern production fleet manifest (v2). Only a last-resort fallback when the SDK-derived pin
+// URL is somehow unavailable; modern glasses honor ota_start's URL, so this must be the v2
+// artifact, not the legacy v1 rescue manifest.
+const OTA_VERSION_URL_PROD = "https://ota.glassly.ai/prod_live_version_v2.json"
+
+function isLegacyAsgOtaStartBuild(glassesBuildNumber?: string | null): boolean {
+  const buildNumber = Number.parseInt(glassesBuildNumber ?? "", 10)
+  // ASG builds before 39 ignore ota_start.ota_version_url, so compare against
+  // the URL they will actually use.
+  return Number.isFinite(buildNumber) && buildNumber < 39
+}
+
+function getOtaVersionUrlDevOverride(): string | null {
+  // Super mode only: a wrong OTA manifest can brick glasses, so a saved
+  // override is inert unless super mode is currently enabled.
+  if (!useSettingsStore.getState().getSetting(SETTINGS.super_mode.key)) {
+    return null
+  }
+  const value = useSettingsStore.getState().getSetting(SETTINGS.ota_version_url.key)
+  const trimmed = typeof value === "string" ? value.trim() : ""
+  return trimmed || null
+}
+
+export function resolveOtaManifestUrl(glassesUrl?: string | null, glassesBuildNumber?: string | null): string {
+  const deviceUrl = glassesUrl?.trim()
+  if (isLegacyAsgOtaStartBuild(glassesBuildNumber)) {
+    // Legacy glasses ignore ota_start.ota_version_url and install from their
+    // compiled default, so the developer override does not apply to them either.
+    return deviceUrl || OTA_VERSION_URL_LEGACY_PROD
+  }
+
+  const devOverrideUrl = getOtaVersionUrlDevOverride()
+  if (devOverrideUrl) {
+    return devOverrideUrl
+  }
+
+  const envUrl = process.env.EXPO_PUBLIC_ASG_OTA_VERSION_URL?.trim()
+  if (envUrl) {
+    return envUrl
+  }
+
+  // The phone owns manifest selection: modern glasses are driven with the manifest pinned to
+  // this app's Bluetooth SDK version. Modern ASG builds report no manifest URL of their own;
+  // a glasses-reported URL (older modern builds advertising their baked fleet default) is only
+  // a last resort when the SDK version is somehow unavailable.
+  return sdkPinnedOtaManifestUrl() || deviceUrl || OTA_VERSION_URL_PROD
+}

package/src/services/slimStreamStatus.ts

@@ -0,0 +1,39 @@
+import type {StreamStatusEvent} from "@glassly/bluetooth-sdk/internal"
+
+/**
+ * 1Hz encoder FPS/bitrate telemetry on `stream_status.stats`.
+ * Lifecycle status (started/stopped/error) is unaffected.
+ * Keep false in production; flip locally to debug the Glassly Call FPS ladder.
+ *
+ * Compatibility kill switch: old glasses can still emit stats. Copy onto a new object;
+ * never mutate the incoming event. Manual acceptance with every layer false: join
+ * waterfall yes; BLE stream_status.stats / STREAM_QUALITY / encoder-stats / watch-stats no.
+ */
+export const ENABLE_PIPELINE_FPS_TELEMETRY = false
+
+/** Fields forwarded to cloud / miniapps after the first resolvedConfig ack. */
+export function slimStreamStatusEvent(
+  event: StreamStatusEvent,
+  options: {includeResolvedConfig?: boolean; enableFpsTelemetry?: boolean} = {},
+): Record<string, unknown> {
+  const enableFpsTelemetry = options.enableFpsTelemetry ?? ENABLE_PIPELINE_FPS_TELEMETRY
+  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
+  }
+  // Compatibility kill switch: old glasses may still emit 1Hz stats. Copy onto a
+  // new object; never mutate `event` — other consumers may still need the original.
+  if (enableFpsTelemetry && event.stats) slim.stats = event.stats
+  return slim
+}
+
+export function streamStatusSignature(payload: Record<string, unknown>): string {
+  return JSON.stringify(payload)
+}