Developer docs

Decisions

The architecture decision records: why the firmware is built the way it is, and what each choice costs. Generated from docs/adr/ in the repository.

One page for each architecture decision: the choice, what it was chosen over, and its consequences. They are written when the decision is made and kept; a later decision that changes an earlier one says so. Generated from docs/adr/ in the repository: edit those files, not these pages.

ADR 000202

Own small widget kit on M5GFX, not LVGL

The UI is drawn with M5GFX into an off-screen buffer, using a small widget kit we own: list, text view, line editor, dialog, Status Bar and Toast. We chose this over LVGL.

ADR 000404

A Debug Console over Wi-Fi, in Debug Builds only

Superseded in part by ADR 0010 (2026-10-06): there is no Debug Build any more. The console is in every firmware, off until switched on, and its token belongs to the device, not to the build. What this record says about how the…

ADR 000707

Our own copy of the SD driver, for one missing byte

Arduino-ESP32's SD library talks to the card over SPI through sd_diskio.cpp. That driver gives up on a write without saying why, and about once in 1,500 multi-block writes it gave up on one that had worked (issue #21). A 1.7 MB…

ADR 000808

CI signs releases with the project's key

A tag v is built, signed and published by Gitea Actions with nobody at a keyboard. The signing key of ADR 0003 is therefore held twice: in ~/.config/roro9stack/ota-key.pem on the development machine, as before, and as the…