The First-Run Wizard¶
On first power-on the owner is walked, on the touch panel alone, from a cold Pi with no Wi-Fi to a board that is online, has minted its identity, and is ready to play — optionally linked to their account. No keyboard, no phone-home configuration, no instruction card beyond “tap here”.
The wizard is almost entirely reuse. It sequences screens that already exist and drives bridges that already work; it reimplements neither Wi-Fi, nor provisioning, nor linking.
The gate¶
SetupBridge (kirin-gui/src/setup_bridge.h) owns exactly one persisted bit: whether this board has completed first-run setup. The shell’s initial screen is conditional on it, and the navigation rail is hidden while the wizard is up, so setup cannot be side-stepped before it completes. A Settings row re-enters the wizard, which is also the factory-reset path.
The bridge is deliberately tiny — it restores the flag at construction, so it is correct the instant the UI binds and no configured board ever flashes the wizard while a check runs.
The steps¶
Welcome — “let’s set up your board”.
Wi-Fi — the load-bearing step, since everything downstream needs the network. Reuses the existing Wi-Fi screen and the on-screen keyboard; the cold-Pi rfkill and regulatory-domain problem is already solved by host provisioning (Chapter The Touch Interface).
Board readiness — provisions the device identity. A bench board with no provisioning key simply skips this and plays anonymously, which is already a supported state (D-73).
Link account (skippable) — the QR and typeable-code flow of Chapter Accounts, Devices and Ratings. “Scan with the app — or skip and do it later.”
Check for updates — fires one check on entry, which downloads and stages any available release but never installs it (D-88). Purely informational, and Continue is always available. There is deliberately no inline install: it would restart the GUI mid-wizard, and since the completion flag is not set yet, that is a setup loop.
Board calibration — the sensor and gantry confirmation. This is the genuinely product-specific step and the one most worth polishing; it is the last to be added because it needs the hardware backend.
Done — mark complete, drop to Home.
Warning
Step 6 is the one part of the wizard that is not built. It waits on physical bring-up, not on software.
No stored cursor¶
D-91 — The wizard stores no step cursor and derives no resume point — it always opens at Welcome
Context An interrupted first run — power lost after Wi-Fi — should not start from nothing.
Decision The wizard holds no step index, persisted or derived. It always opens at Welcome, and each step renders its own satisfaction from live state: the Wi-Fi step shows “connected”, readiness shows “ready” the instant provisioning is confirmed, the link step shows the existing account. An interrupted run therefore walks forward through steps that already show themselves done — a couple of taps.
Rejected Deriving a resume point and jumping to it, which is what the first cut did. On any already-configured board — that is, every existing bench unit — it made the wizard invisible: it opened on a lone “Start playing” screen, which read as the wizard having skipped itself.
Consequences setup/complete remains the only persisted wizard state. This matches the codebase’s habit of re-deriving display from reality (the Wi-Fi screen re-scans on open) without the teleport.