twislaandClaude Opus 5.5
c68741cc46
There is no Debug Build any more (ADR 0010, issue #68, Q188 to Q195). The console and the test commands are compiled into every firmware. It listens only while Settings > Debug Console is on, which isn't the default; off, neither its task nor its 4 KB ring exists. The token is made by the device and shown on that page; a client proves it knows it by answering a challenge with an HMAC, so it never crosses the network, and five wrong answers close the console for a minute. DBG in the Status Bar while it listens. Over USB serial only: debug on, debug token <value>, debug token new. scripts/flash.sh --debug uses them to set a device up with the developer's token. scripts/rdbg.py takes the token from -t, $RORO_DEBUG_TOKEN or the file, answers the challenge, and fetches a release's ELF to decode a crash. Gone: the cardputer-adv-debug environment, RORO_DEBUG, the +debug version, scripts/debug_flags.py, update install ... force, and the rule that a Debug Build doesn't install releases. Old clients and old firmwares don't talk to each other. Against the builds it replaces: 30 KB more flash and 88 bytes more static RAM than the release, 4 KB less RAM than the Debug Build. 468 host tests. Checked on the device: off by default, login, the pause after wrong tokens, Safe Mode with the console, the setting surviving an update, debug off. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT
2.2 KiB
+++ title = "Build, test and release" description = "Docker is the only tool you need. How the firmware is built, how the host tests run, and what CI does on a pull request and on a tag." weight = 1
[extra] docs = true source = "README.md" tag = "Build" +++
Requirements
Only Docker is needed. PlatformIO and the ESP32 toolchain run inside a container, and are cached in the roro9stack-pio Docker volume. The first build downloads about 1 GB and takes a few minutes.
Build and test (local CI)
scripts/ci.sh
This runs the host-side unit tests (test/, native environment), then builds the firmware. The output is .pio/build/cardputer-adv/firmware.factory.bin.
scripts/coverage.sh runs the same tests with coverage counters and writes a line-by-line report to .pio/coverage/index.html. The badge above is its figure for main: the share of the lines of lib/ that the host tests run. lib/ is the logic that compiles on a PC; lib/SD (the card's driver) and src/ (the Apps, the Services, everything that needs the device) have no host tests and aren't in that figure.
The framework is rebuilt with the TLS settings in platformio.ini (custom_sdkconfig, ADR 0006), so the first build after a fresh checkout takes about 4 minutes; later builds take under a minute.
CI and releases
Gitea Actions (.gitea/workflows/ci.yml, docs/milestones/R1.md) runs the host tests on every push to main, and on a pull request also builds the firmware: changes reach main through pull requests. Pushing a tag v* runs all of it and publishes a release on Gitea with:
roro9stack-<version>.ota, the signed Update File;roro9stack-<version>-factory.bin, the whole flash image for a first install over USB;roro9stack-<version>.elf.gz, to decode crash reports from that build;SHA256SUMS.
CI signs with the project's key, held as a repository secret (ADR 0008). There is one firmware: the Debug Console is in every build, switched off until its owner switches it on (ADR 0010).
scripts/ota_verify.py <file.ota> checks an Update File on a PC the way a device does. scripts/release_build.sh and scripts/release_publish.py are what the workflow runs; they work the same by hand.