Files
faceclaw/app/phone-ui/onboarding-flash-view-model.ts
T
JMO a7916a5479 Make the firmware upgrade reachable from older custom firmware
Glasses running an older Faceclaw firmware revision cannot be upgraded at all.
The flash asks for confirmation on the lens first, and that firmware never
shows the prompt, so the one path off it is closed. Measured on revision 13
(base 2.2.9.22).

showPrompt writes the EvenHub create-prompt page to the right arm and waits for
an ack. The lens accepts the write at the GATT layer and then answers nothing
and displays nothing: four attempts, four onWriteCharacteristic status=0
length=165, no reply. buildCreatePromptPage documents its geometry as
stock-firmware-safe "so this works before flashing", and that does not hold
there.

Three faults, each only visible once the previous one is fixed.

An unacked prompt page was fatal. Flashing is the only way off that firmware,
so failing here leaves the glasses permanently unupgradable. An unacked page
now falls back to the phone-side confirmation that the low-battery retry
already uses, on a screen that says what is being given up: the on-lens step is
what proves the glasses are the wearer's.

connectArm made a single attempt. The lens is routinely unavailable for a
moment just after a previous link to it closed, which is exactly the state a
retry is in, so the fallback failed instantly with "could not connect to the
right arm". FaceclawFirmwareFlasher.connectLensResilient already retries within
a window for this reason; connectArmResilient mirrors it and reports each
attempt.

That retry then tripped the lost-connection latch. Disconnecting between
attempts fires onConnectionStateChange, which set rightLost AND finished and
counted down the selection latch, so a successful second attempt still aborted
with "Lost connection to the glasses". The callback now ignores drops while the
arms are still being established.

Logging, because a failed flash used to leave almost nothing to read. emitLog
reached logcat, but emitState, emitProgress and emitComplete on the flasher,
and emitState and emitResult on the prompt communicator, went only to the
in-app listener, so the line carrying the reason existed only on the phone
screen. Seven `catch (Exception ignored)` blocks across the two classes now log
with the Throwable, matching the call sites elsewhere that already do.

tests/flash-prompt-fallback.test.cjs covers the decision at its seam through
the existing load-typescript loader. The first test fails against the current
view model and passes with this change; the second is a regression guard and
passes either way, so an unrelated failure cannot quietly skip the on-lens
confirmation.

Verified on hardware: both lenses flashed through this path after it had been a
dead end.
2026-09-22 22:09:11 -07:00

670 lines
23 KiB
TypeScript

import { finishOnboardingNavigation } from "./onboarding-navigation";
import { Frame, Observable } from "@nativescript/core";
import { ensureBlePermissions } from "../native/ble-permissions";
import {
isValidMacAddress,
loadDeviceAddresses,
saveDeviceAddresses,
} from "../g2/device-addresses";
import {
buildCustomFirmware,
buildStockFirmware,
FirmwareBuildError,
FirmwareProgress,
} from "../g2/firmware-builder";
import { buildAddressSet, DeviceDiscoveryBridge } from "../native/device-discovery";
import { FirmwareFlasher, FlashProgress, FlashState } from "../native/firmware-flasher";
import {
FlashPromptBattery,
FlashPromptCommunicator,
FlashPromptState,
} from "../native/flash-prompt-communicator";
import { resumeAutoReconnect, suppressAutoReconnect } from "../g2/reconnect-policy";
import { setOnboardingCompleted, setPreviewOnlyMode } from "./onboarding-state";
import { formatErrorMessage } from "../util/format-error";
type FlashPhase = "intro" | "prompt" | "building" | "flashing" | "flashed" | "error";
export type FlashMode = "install" | "uninstall";
// Flashing a lens takes minutes and the glasses reboot afterwards; refuse to
// start when either arm is below this so a flat battery can't interrupt it.
const MIN_FLASH_BATTERY_PERCENT = 30;
export class OnboardingFlashViewModel extends Observable {
private readonly mode: FlashMode;
private readonly fromOnboarding: boolean;
private _phase: FlashPhase = "intro";
private _headline = "Flash Custom Firmware";
private _status = "";
private _log = "";
private _busy = false;
private _progress = 0;
private readonly discovery = new DeviceDiscoveryBridge();
private addresses: { right: string; left: string } | null = null;
private firmwarePath = "";
private disposed = false;
private promptGeneration = 0;
private prompt: FlashPromptCommunicator | null = null;
private promptUnsubscribers: Array<() => void> = [];
private promptBattery: FlashPromptBattery | null = null;
private flasher: FirmwareFlasher | null = null;
private flasherUnsubscribers: Array<() => void> = [];
private retryAction: () => void = () => this.beginPrompt();
/** Overrides the error screen's "Retry" when the action is not a retry. */
private primaryLabelOverride: string | null = null;
constructor(options?: { mode?: FlashMode; fromOnboarding?: boolean; autoStart?: boolean }) {
super();
// The flash flow needs the glasses to itself: from here on the main
// page must not auto-reconnect, until an install succeeds (below) or
// the user connects explicitly.
suppressAutoReconnect();
this.mode = options?.mode ?? "install";
this.fromOnboarding = options?.fromOnboarding ?? true;
this._headline = this.mode === "uninstall" ? "Uninstall Custom Firmware" : "Flash Custom Firmware";
this._status =
this.mode === "uninstall"
? "This connects to your glasses, asks for confirmation on the lens, checks the battery, then downloads " +
"and reflashes the official firmware — removing Faceclaw's custom features."
: "This connects to your glasses, asks for confirmation on the lens, checks the battery, then downloads, " +
"verifies, and flashes Faceclaw's custom firmware.";
if (options?.autoStart) {
// Entered from a page that already explained what's about to happen
// (the onboarding firmware check), so the intro/"Connect & Confirm"
// step would be redundant: go straight to connecting.
void this.beginPrompt();
}
}
// Kept short to fit the glasses' ~50-column text grid.
private get glassesWarning(): string {
return this.mode === "uninstall"
? "Reinstalling the official firmware removes Faceclaw's custom features. Continue?"
: "Flashing custom firmware will void your warranty. Continue?";
}
private get noun(): string {
return this.mode === "uninstall" ? "official firmware" : "custom firmware";
}
// --- observable properties -------------------------------------------------
get phase(): FlashPhase {
return this._phase;
}
get headline(): string {
return this._headline;
}
set headline(value: string) {
if (this._headline !== value) {
this._headline = value;
this.notifyPropertyChange("headline", value);
}
}
get status(): string {
return this._status;
}
set status(value: string) {
if (this._status !== value) {
this._status = value;
this.notifyPropertyChange("status", value);
}
}
get log(): string {
return this._log;
}
set log(value: string) {
if (this._log !== value) {
this._log = value;
this.notifyPropertyChange("log", value);
this.notifyPropertyChange("logVisibility", this.logVisibility);
}
}
get logVisibility(): "visible" | "collapse" {
return this._log ? "visible" : "collapse";
}
get busy(): boolean {
return this._busy;
}
set busy(value: boolean) {
if (this._busy !== value) {
this._busy = value;
this.notifyPropertyChange("busy", value);
this.notifyPropertyChange("busyVisibility", this.busyVisibility);
}
}
get busyVisibility(): "visible" | "collapse" {
return this._busy ? "visible" : "collapse";
}
get progress(): number {
return this._progress;
}
set progress(value: number) {
const clamped = Math.max(0, Math.min(100, Math.round(value)));
if (this._progress !== clamped) {
this._progress = clamped;
this.notifyPropertyChange("progress", clamped);
}
}
get progressVisibility(): "visible" | "collapse" {
return this._phase === "flashing" ? "visible" : "collapse";
}
get primaryLabel(): string {
switch (this._phase) {
case "intro":
return "Connect & Confirm";
case "flashed":
return "Finish";
case "error":
return this.primaryLabelOverride ?? "Retry";
default:
return "";
}
}
get secondaryLabel(): string {
switch (this._phase) {
case "prompt":
return "Cancel";
default:
return "Back";
}
}
get primaryVisibility(): "visible" | "collapse" {
return this.primaryLabel ? "visible" : "collapse";
}
get secondaryVisibility(): "visible" | "collapse" {
// No escape hatch mid-write (building/flashing) or after success (flashed).
return this._phase === "building" || this._phase === "flashing" || this._phase === "flashed"
? "collapse"
: "visible";
}
// --- button handlers -------------------------------------------------------
onPrimaryTap(): void {
switch (this._phase) {
case "intro":
void this.beginPrompt();
return;
case "flashed":
this.finish();
return;
case "error":
this.retryAction();
return;
default:
return;
}
}
onSecondaryTap(): void {
if (this._phase === "prompt") {
this.cancelPrompt();
return;
}
if (this._phase === "building" || this._phase === "flashing" || this._phase === "flashed") {
return;
}
this.leave();
}
// --- prompt flow -----------------------------------------------------------
/**
* Connect to both arms, authenticate (this is where any system pairing
* prompts appear), show the Yes/No confirmation on the lens, then read the
* battery. With `skipPrompt` (retrying after a low-battery refusal, when
* the user has already confirmed) the on-glasses confirmation is skipped
* and only the battery is re-checked.
*/
private async beginPrompt(options?: { skipPrompt?: boolean }): Promise<void> {
if (this.disposed) return;
const generation = ++this.promptGeneration;
const skipPrompt = Boolean(options?.skipPrompt);
if (!global.isAndroid && !global.isIOS) {
this.toError("Flashing is only available on Android.", () => this.beginPrompt(options));
return;
}
this.setPhase("prompt");
this.headline = skipPrompt ? "Checking Battery" : "Confirm On Your Glasses";
this.log = "";
this.busy = true;
this.promptBattery = null;
this.status = "Preparing to connect. Make sure your glasses are on and the Even app is disconnected.";
try {
await ensureBlePermissions();
if (this.disposed || generation !== this.promptGeneration) return;
const addresses = await this.resolveAddresses();
if (this.disposed || generation !== this.promptGeneration) return;
if (!addresses) {
this.busy = false;
this.toError(
"Couldn't find both glasses arms. Make sure the glasses are powered on and the Even app is disconnected, then retry.",
() => this.beginPrompt(options),
);
return;
}
this.addresses = addresses;
this.status = skipPrompt
? "Connecting to your glasses to re-check the battery..."
: "Connecting to your glasses. Watch the lens for a Yes/No prompt.";
this.startCommunicator(addresses, skipPrompt);
} catch (error) {
if (this.disposed || generation !== this.promptGeneration) return;
this.busy = false;
this.toError(this.formatError(error), () => this.beginPrompt(options));
}
}
private startCommunicator(addresses: { right: string; left: string }, skipPrompt: boolean): void {
this.disposePrompt();
const prompt = new FlashPromptCommunicator(addresses, this.glassesWarning, { skipPrompt });
this.prompt = prompt;
this.promptUnsubscribers.push(
prompt.onLog((line) => this.appendLog(line)),
prompt.onStateChange((state, detail) => this.handlePromptState(state, detail, skipPrompt)),
prompt.onBattery((battery) => {
this.promptBattery = battery;
}),
prompt.onResult((approved) => this.handlePromptResult(approved, skipPrompt)),
);
prompt.start();
}
private handlePromptState(state: FlashPromptState, detail: string, skipPrompt: boolean): void {
switch (state) {
case "connecting":
this.status = "Connecting to your glasses...";
break;
case "connected":
this.status =
"Connected. Pairing with both lenses — if your phone asks to pair, accept it (once per lens)." +
(skipPrompt ? "" : " Then watch the lens for the confirmation.");
break;
case "battery":
this.status = "Checking the glasses' battery level...";
break;
case "prompting":
this.status =
"Look at the lens and choose Yes to flash or No to cancel. (Use the ring or a temple tap to select.)";
break;
case "result":
// Handled by onResult.
break;
case "cancelled":
this.busy = false;
this.toError("Cancelled.", () => this.beginPrompt());
break;
case "timeout":
this.busy = false;
this.toError(detail || "No response from the glasses.", () => this.beginPrompt());
break;
case "disconnected":
this.busy = false;
this.toError(detail || "Lost connection to the glasses.", () => this.beginPrompt({ skipPrompt }));
break;
case "error":
this.busy = false;
// An unacked prompt page is not a connection failure. The lens accepts the
// write at the GATT layer and then never answers, which is what firmware
// older than the revision this build needs does -- measured on revision 13,
// four writes accepted with status 0 and no reply, nothing shown on the lens.
// Flashing is the only way OFF that firmware, so failing here leaves the
// glasses permanently unupgradable. Fall back to the phone-side confirmation
// that the low-battery retry already uses, and say plainly what is being
// given up: the on-lens step is what proves these are the wearer's glasses.
if (/prompt page not acked/i.test(detail)) {
this.toError(
"Your glasses are on older firmware that can't show the confirmation prompt, so it can't be " +
"confirmed on the lens. You can confirm here instead. Only continue if these are your glasses " +
"and you want to install Faceclaw's custom firmware.",
() => this.beginPrompt({ skipPrompt: true }),
"Confirm On Your Phone",
"Confirm & Install",
);
break;
}
this.toError(detail || "Connection failed.", () => this.beginPrompt({ skipPrompt }));
break;
}
}
private handlePromptResult(approved: boolean, skipPrompt: boolean): void {
this.disposePrompt();
if (!approved) {
this.busy = false;
this.toError("You declined on the glasses. Firmware was not installed.", () => this.beginPrompt());
return;
}
const lowBattery = this.describeLowBattery(this.promptBattery);
if (lowBattery) {
this.busy = false;
// The user already confirmed on the lens; a retry only re-checks the battery.
this.toError(lowBattery, () => this.beginPrompt({ skipPrompt: true }), "Charge Your Glasses");
return;
}
if (!this.promptBattery || (this.promptBattery.right === null && this.promptBattery.left === null)) {
this.appendLog("battery level unknown; proceeding");
}
this.appendLog(skipPrompt ? "battery ok; confirmed earlier on the lens" : "confirmed on the lens; battery ok");
void this.buildFirmware();
}
/** A "charge first" message when either arm is below the flashing threshold, else null. */
private describeLowBattery(battery: FlashPromptBattery | null): string | null {
if (!battery) {
return null;
}
const readings = [
{ arm: "right", percent: battery.right },
{ arm: "left", percent: battery.left },
].filter((r): r is { arm: string; percent: number } => r.percent !== null);
const low = readings.filter((r) => r.percent < MIN_FLASH_BATTERY_PERCENT);
if (low.length === 0) {
return null;
}
const levels = readings.map((r) => `${r.arm} ${r.percent}%`).join(", ");
return (
`The glasses' battery is too low to flash safely (${levels}). ` +
`Charge both lenses to at least ${MIN_FLASH_BATTERY_PERCENT}%, then tap Retry to check again. ` +
"You won't need to confirm on the lens a second time."
);
}
private cancelPrompt(): void {
++this.promptGeneration;
this.status = "Cancelling...";
try {
this.prompt?.cancel();
} catch {
// ignore
}
this.disposePrompt();
this.busy = false;
this.toError("Cancelled.", () => this.beginPrompt());
}
// --- firmware build flow ---------------------------------------------------
private async buildFirmware(): Promise<void> {
this.setPhase("building");
this.headline = "Preparing Firmware";
this.busy = true;
this.status = "Confirmed. Downloading the stock firmware...";
try {
const build = this.mode === "uninstall" ? buildStockFirmware : buildCustomFirmware;
const result = await build((progress) => this.reportBuildProgress(progress));
if (this.disposed) return;
this.firmwarePath = result.path;
this.appendLog(`${this.noun} prepared and verified (${result.bytes.toLocaleString()} bytes), saved to ${result.path}`);
// The user already said Yes on the lens; no second confirmation here.
this.startFlashing();
} catch (error) {
if (this.disposed) return;
this.busy = false;
const message =
error instanceof FirmwareBuildError ? error.message : this.formatError(error);
this.toError(message, () => this.buildFirmware());
}
}
private reportBuildProgress(progress: FirmwareProgress): void {
if (this.disposed) return;
switch (progress.phase) {
case "downloading":
this.status = "Downloading the stock firmware from Even's CDN...";
break;
case "verifying-base":
this.status = "Verifying the downloaded firmware...";
break;
case "extracting-fonts":
this.status = "Extracting the glasses' fonts for EvenHub apps...";
break;
case "patching":
this.status = `Applying patches (${progress.applied}/${progress.total})...`;
break;
case "verifying-output":
this.status = "Verifying the patched firmware...";
break;
case "writing":
this.status = "Saving the prepared firmware...";
break;
case "done":
break;
}
}
// --- flashing flow ---------------------------------------------------------
private startFlashing(): void {
if (this.disposed) return;
if (!this.addresses || !this.firmwarePath) {
this.toError("Missing glasses addresses or firmware; start over.", () => this.beginPrompt());
return;
}
this.setPhase("flashing");
this.headline = "Flashing Firmware";
this.busy = true;
this.progress = 0;
this.status =
"Starting. Keep both lenses powered on and nearby — each lens takes a few minutes, " +
"and the glasses will reboot when each lens finishes. Do not close the app during flashing.";
this.disposeFlasher();
const flasher = new FirmwareFlasher(this.addresses, this.firmwarePath);
this.flasher = flasher;
this.flasherUnsubscribers.push(
flasher.onLog((line) => this.appendLog(line)),
flasher.onProgress((progress) => this.handleFlashProgress(progress)),
flasher.onStateChange((state, detail) => this.handleFlashState(state, detail)),
flasher.onComplete((success, detail) => this.handleFlashComplete(success, detail)),
);
flasher.start();
}
private handleFlashState(state: FlashState, detail: string): void {
switch (state) {
case "validating":
this.status = "Validating the firmware image...";
break;
case "connecting":
this.status = `Connecting to the ${detail || ""} lens...`.replace(" ", " ");
break;
case "flashing":
this.status = `Flashing the ${detail || ""} lens. Keep the glasses on and nearby.`.replace(" ", " ");
break;
case "rebooting":
this.status = detail || "Lenses rebooting; reconnecting...";
break;
case "done":
case "error":
// Handled by onComplete.
break;
}
}
private handleFlashProgress(progress: FlashProgress): void {
const lensIndex = progress.lens === "right" ? 1 : 0;
// Weight by bytes, not by component index: the image is one large segment
// plus several small ones, so per-component steps move wildly unevenly.
const withinLens = progress.bytesTotal > 0 ? Math.min(1, progress.bytesSent / progress.bytesTotal) : 0;
this.progress = ((lensIndex + withinLens) / 2) * 100;
this.status =
`Flashing ${progress.lens} lens — part ${progress.componentIndex}/${progress.componentCount}, ` +
`block ${progress.blockIndex}/${progress.blockCount}. Keep the glasses on and nearby.`;
}
private handleFlashComplete(success: boolean, detail: string): void {
this.disposeFlasher();
this.busy = false;
if (success) {
if (this.mode === "install") {
// A successful install ends the manual-disconnected state: the main
// page may auto-connect to the freshly flashed glasses. (After an
// uninstall the glasses run stock firmware, which Faceclaw would
// immediately flag as incompatible, so stay manually disconnected.)
resumeAutoReconnect();
}
this.progress = 100;
this.setPhase("flashed");
this.headline = "All Done";
this.status =
detail ||
(this.mode === "uninstall"
? "Official firmware reinstalled. Your glasses are rebooting into the stock firmware."
: "Firmware installed. Your glasses are rebooting into Faceclaw's custom firmware.");
return;
}
this.toError(detail || "Flashing failed.", () => this.startFlashing());
}
// --- helpers ---------------------------------------------------------------
private async resolveAddresses(): Promise<{ right: string; left: string } | null> {
const stored = loadDeviceAddresses();
if (isValidMacAddress(stored.right) && isValidMacAddress(stored.left)) {
return { right: stored.right, left: stored.left };
}
this.status = "Scanning for your glasses...";
const candidates = await this.discovery.scanCandidates(8000);
const found = buildAddressSet(candidates);
if (isValidMacAddress(found.right) && isValidMacAddress(found.left)) {
saveDeviceAddresses({ right: found.right, left: found.left, ring: found.ring || stored.ring });
return { right: found.right, left: found.left };
}
return null;
}
private finish(): void {
if (this.mode === "install") {
// Reaching the app via a successful install completes onboarding and
// clears preview-only. (Idempotent when already past onboarding.)
setPreviewOnlyMode(false);
setOnboardingCompleted(true);
}
this.disposePrompt();
this.disposeFlasher();
finishOnboardingNavigation();
}
private leave(): void {
this.disposePrompt();
this.disposeFlasher();
const frame = Frame.topmost();
if (this.fromOnboarding && frame?.canGoBack()) {
frame.goBack();
return;
}
if (!this.fromOnboarding) { finishOnboardingNavigation(); return; }
frame?.navigate({
moduleName: this.fromOnboarding ? "phone-ui/onboarding-page" : "phone-ui/main-page",
clearHistory: true,
});
}
private toError(
message: string,
retry: () => void,
headline = "Something Went Wrong",
primaryLabel: string | null = null,
): void {
this.primaryLabelOverride = primaryLabel;
this.retryAction = retry;
this.status = message;
this.setPhase("error");
this.headline = headline;
}
private setPhase(phase: FlashPhase): void {
if (this._phase !== phase) {
this._phase = phase;
this.notifyPropertyChange("phase", phase);
}
this.notifyPropertyChange("primaryLabel", this.primaryLabel);
this.notifyPropertyChange("secondaryLabel", this.secondaryLabel);
this.notifyPropertyChange("primaryVisibility", this.primaryVisibility);
this.notifyPropertyChange("secondaryVisibility", this.secondaryVisibility);
this.notifyPropertyChange("progressVisibility", this.progressVisibility);
}
private appendLog(line: string): void {
const stamp = new Date().toISOString().slice(11, 19);
this.log = this._log ? `${this._log}\n[${stamp}] ${line}` : `[${stamp}] ${line}`;
}
dispose(): void {
this.disposed = true; ++this.promptGeneration;
this.discovery.stopScan(); this.disposePrompt(); this.disposeFlasher();
}
private disposePrompt(): void {
for (const unsubscribe of this.promptUnsubscribers) {
try {
unsubscribe();
} catch {
// ignore
}
}
this.promptUnsubscribers = [];
if (this.prompt) {
try {
this.prompt.close();
} catch {
// ignore
}
this.prompt = null;
}
}
private disposeFlasher(): void {
for (const unsubscribe of this.flasherUnsubscribers) {
try {
unsubscribe();
} catch {
// ignore
}
}
this.flasherUnsubscribers = [];
if (this.flasher) {
try {
this.flasher.close();
} catch {
// ignore
}
this.flasher = null;
}
}
private formatError(error: unknown): string {
return formatErrorMessage(error);
}
}