Skip to content

Set up and upgrade firmware 3.0 displays (setup, upgrade, update), config clear and a raw command - #240

Merged
g4bri3lDev merged 9 commits into
mainfrom
feat/setup-flow
Nov 21, 2026
Merged

g4bri3lDev merged 9 commits into
mainfrom
feat/setup-flow

Conversation

@g4bri3lDev

Copy link
Copy Markdown
Member

Piece 5b of the firmware 3.0 work, on top of #238.

What it adds

  • opendisplay.setup: classifies a device and plans its steps. SetupRun performs them one at a time and pauses on a request: a claim code, a panel choice, a confirmation, a power-cycle gesture or a wired install. It can be saved to JSON and resumed.
  • Release files: fetched from GitHub, checked against the release manifest and cached. This includes the manifest's first move from 2.x over Bluetooth.
  • CLI:
    • opendisplay setup configures a 3.0 display, checks the panel with a test pattern, then claims it or uses it without a key.
    • upgrade moves a 2.x display to 3.0; --state-file resumes it.
    • update sends a 3.x image.
    • Each step prints one line.
  • dev.config.clear(): CONFIG_CLEAR 0x0045. It raises ConfigClearError when the device refuses.
  • opendisplay raw --cmd HEX [--payload HEX]: sends one command frame and prints the reply. This is a debugging aid; dev.legacy.send_raw() does the same from Python.
  • Fixed during the hardware run: a run that wrote the config itself now always checks the panel, also without a key and after a restart.
  • Fixed after Let every CLI command open a SEC2 session on a claimed display #237 merged: setup, upgrade, update and raw take --key-store from the shared device options.

Testing

  • 2060 unit tests; prek clean.
  • On the E1002 (ESP32-S3, 3.0.2):
    • setup starting from no config;
    • update;
    • raw with a firmware-version read.
  • Not run on hardware yet: upgrade from 2.x on the nRF52840.

https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3

device_state() says where a device stands from SEC_STATUS, the READ_IDENT tail bits or the
advertisement: legacy, virgin, fresh, gesture, open, claimed, claimed in claim mode, locked,
unknown. plan_setup() lists the steps for it. Both are pure, ported case by case from the
website's wizard planner (Web od-wizard.js and its tests, v3/website b7df514).

Added to the port, from our hardware work:
- a display with no config, or one that needs migration, is configured and its panel checked
  before it is claimed, since it cannot show the claim code otherwise (unless claim mode has
  locked the config);
- a 2.x device is backed up, given 3.0 and confirmed first, and planned again once it runs 3.0;
- a device in claim mode whose owner wants no key leaves claim mode first (USE_WITHOUT_KEY).

DeviceIdent gains the SECURITY_V2 tail bits (sec2, claimed, claim_mode, legacy_secrets_open).

Claude-Session: https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3
…ifest

BoardRelease gains from_2x_files, from_2x_protocol and from_2x_erases_config (the ble-ota-from-2x
flow: the BG22 AppLoader and nRF54 SMP), and usb_install_protocol (adafruit-serial-dfu, swd, or
none for the website flasher). The setup flow picks the install path from these.

Claude-Session: https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3
…opendisplay.setup.configure

find_secrets, unclaimed_form, strip_secrets and the write-then-read-back check move out of the
CLI module so the setup runner can use them. cli_migrate imports them back; its output is
unchanged (its 35 tests pass as before). write_and_verify raises ConfigMismatchError instead of
exiting, and returns whether the device rewrote the 0x27.

Claude-Session: https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3
SetupRun performs plan_setup()'s steps on a device and pauses on a typed request when it needs
the user: the key choice, the claim-mode gesture, the claim code, a panel, a confirmation
(untested drive data, a BG22 install with no rollback, the panel check), a board, a wired
install, or a config to start from. It saves and restores as JSON for a Home Assistant restart.

Every run_until_input opens the device again and plans from what it reads, so a saved run never
repeats a step the device shows as done; only the backup, the panel check and the image confirm
are remembered. A claim code is confirmed on the link that asked for it. The 2.x backup goes to
the caller's sink with its secrets; the run keeps a copy without them. From 2.x it installs over
Bluetooth where the release has a ble-ota-from-2x flow (BG22 AppLoader, nRF54 SMP), checking the
image against the manifest SHA-256, and otherwise names the USB install files and the website
flasher.

Claude-Session: https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3
…nd cached

ReleaseDownloader reads a Firmware_Unified release manifest (a given tag, or the latest) and
fetches its files with the standard library, refusing and not caching a file whose SHA-256
differs from the manifest. Files are kept per tag under the user cache directory
($OPENDISPLAY_CACHE, ~/Library/Caches, $XDG_CACHE_HOME, %LOCALAPPDATA%).

SetupRun now also takes the manifest as an async callable, called once and only when a 2.x
device needs it, so a run on a 3.0 device contacts nothing.

Claude-Session: https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3
setup runs the setup flow and turns each request into a prompt: the key choice, the claim-mode
gesture, the claim code, the panel check, untested drive data, a board, a config file. upgrade is
the same flow for a 2.x display: it backs the config up (mode 0600, never over an earlier file),
installs 3.0 over Bluetooth where the release allows it or names the USB install files and the
website flasher, saves its state, and goes on from it when run again once the display runs 3.0.
update sends one 3.x image with dev.firmware.update() and asks first on a display that cannot
return to its old image. README: a CLI list entry and a section on setting up a display.

Claude-Session: https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3
ConfigView.clear() erases the stored config and refreshes the profile; a
NACK raises ConfigClearError. OpenDisplayDevice.send_raw() sends one frame
(encrypted with a session) and returns the reply unchecked, and
`opendisplay raw --cmd HEX [--payload HEX] [--no-reply]` prints it, as a
debugging aid. The README covers both, and the setup step lines.

Claude-Session: https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3
… each step

Once the run had written the config, the device no longer planned the panel
check itself, so a setup without a key (or any open-device path) finished
without ever drawing the test pattern. Seen on the E1002 on 2026-11-18. The run
now owes the check after its own write, and saves that across a restart.

SetupRun.on_step is called before each step; `setup` and `upgrade` print one
line per step.

Claude-Session: https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3
…ared device options

The device options gained --key-store in #237, so adding it again made argparse refuse to build the parser.

Claude-Session: https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3
@g4bri3lDev
g4bri3lDev merged commit f90e23f into main Nov 21, 2026
3 checks passed
@codecov

codecov Bot commented Nov 21, 2026

Copy link
Copy Markdown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant