Repository navigation
Set up and upgrade firmware 3.0 displays (setup, upgrade, update), config clear and a raw command - #240
Merged
Conversation
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
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Piece 5b of the firmware 3.0 work, on top of #238.
What it adds
opendisplay.setup: classifies a device and plans its steps.SetupRunperforms 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.opendisplay setupconfigures a 3.0 display, checks the panel with a test pattern, then claims it or uses it without a key.upgrademoves a 2.x display to 3.0;--state-fileresumes it.updatesends a 3.x image.dev.config.clear(): CONFIG_CLEAR 0x0045. It raisesConfigClearErrorwhen 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.setup,upgrade,updateandrawtake--key-storefrom the shared device options.Testing
setupstarting from no config;update;rawwith a firmware-version read.upgradefrom 2.x on the nRF52840.https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3