ShieldSigner / build & use0.0.19-dev

TASK 03

Build & iterate on firmware

Test the LVGL renderer, stage one named runtime, then build an OS image only when needed.

You need
  • Repository checkout and mise
  • Desktop toolchain for host tests; x86_64 Linux + Docker for the OS build
  • A camera bundle matching the intended Mini display/button profile
You’ll have

A tested host renderer, named immutable runtime inputs, or a separately tracked OS image candidate.

Current bench firmware: LVGL + Rust camera, tested on the standard 240×240 display/button board. Read the exact image, memory measurements and acceptance limits →

The current tested LVGL image uses the base-fork 240×240 bench profile. Selecting dev mode alone does not adapt it to the 2.8-inch pill carrier or its UR2 reader.

Start from the tested profile and source pins

  • Read the firmware status first: current bench image lvgl-dev.cb6170a37a5a, Python wallet logic, native LVGL UI, Rust camera and ZXing-C++ decoder.
  • The repository pins OS e7589465aff172f4f510ad46d18776ccc8d2c203 and app efdd1cfd14e80a076a7e1ae91e9f2270ecbcd44f. Keep those pins when reproducing the baseline.
  • Use the canonical artifact directories. Hardware and website version strings do not identify the flashed firmware.
  • A fresh clone contains source, not the local baseline image or camera bundles. Image discovery/verification requires those artifacts to have been built or provided separately.
Open the repository toolchain
git clone https://github.com/lightningspore/shieldsigner-dev.git
cd shieldsigner-dev
mise install
Current firmware and acceptance scope ↗

Try the host renderer before rebuilding Linux

  • These commands compile for your desktop and exercise the native screen protocol; they do not use the camera, flash a card or change a device.
  • The host binary goes to dist/firmware/work/lvgl/build-host; generated protocol evidence goes to dist/firmware/checks/lvgl/host.
  • A host pass is useful regression evidence, but physical display, GPIO and camera checks still need the target hardware.
Build and test locally
mise run lvgl:app:build:host
mise run lvgl:app:test:host
mise run firmware:test

Stage a new application iteration

  • Choose a new build name. The stager builds the ARM application renderer and freezes runtime, overlay and combined camera inputs together.
  • By default it uses the selected local image record's camera base. On a fresh checkout you must provide an existing reviewed camera bundle using --camera; local image artifacts are not in Git.
  • Staging is not an OS build, deployment or flash. Existing attempt directories are refused.
Stage using the verified local camera base
mise run firmware:stage -- --name my-lvgl-iteration
Or supply a reviewed camera bundle
mise run firmware:stage -- --name my-other-iteration --camera /path/to/reviewed/camera-bundle
Artifact layout and preservation rules ↗

Build an OS image only at the image boundary

  • Use an x86_64 Linux Docker builder. Pass the staged bundle explicitly so the image contains the intended LVGL inputs rather than a newly generated default camera-only bundle.
  • The example below uses a development bundle. Its variant must match --variant dev. SHIELDSIGNER_BUILD_HOST must already identify your authorized SSH builder.
  • Remote outputs use dist/firmware/work/os/<job>; the local job record goes to dist/firmware/jobs/<job>.json. Keep SDK, Rust, download and compiler caches.
Launch and inspect one named remote development build
mise run os:remote:build -- --variant dev --name my-lvgl-image --bundle dist/firmware/staging/my-lvgl-iteration/camera-bundle
mise run os:remote:status -- my-lvgl-image
Local builds, platform details and cached iteration ↗

Verify the candidate before calling it a flash image

  • A successful job needs an actual terminal exit-code; recent log lines alone do not prove liveness or completion. Inspect the matching launcher and Docker state.
  • Keep OS job output separate from the verified image store. Check the packed image, hashes, runtime identity and profile before deliberately selecting an image.
  • The selected current image is found by firmware:where and checked by firmware:verify. An arbitrary new build is not automatically promoted or hardware-qualified.
Check the deliberately selected image
mise run firmware:where
mise run firmware:verify
Image identity and acceptance limits ↗
Continue the buildFlash & boot the software →
Sources & deeper reference

Checked 12 October 2026. Menu names can vary with firmware.

Current LVGL firmware guide ↗Buildroot details and historical benchmarks ↗Firmware artifact lifecycle ↗Edit this workflow on GitHub ↗