Architecture

The order nothing may climb

Twenty-two modules in one order, the consumer first. A module includes its own headers and those of the modules below it; an include pointing upward fails the check, in the commit hook and again in continuous integration.

The remedy for an upward include is never an exception. It is to move the header down, or to invert the call through an interface the lower module declares, which is how the admin panel reaches the running application without the application knowing that a panel exists. There is a mechanism for pinning an exception, site by site. It is empty, and the point of it is that it is empty: no two modules in the firmware depend on each other.

Includes are spelled from the root of the source tree, so a relative path that climbs out of its own directory fails the same check. Inside a module the check goes further and fences groups of files off from each other, and it refuses a cycle between headers. The picture in the next section is generated from those same include lines, and the check fails while the copy of it kept in the repository is out of date.

The graph

The module graph is generated from the includes themselves rather than drawn by hand, which is what stops a diagram and the code it describes from disagreeing: the tool that draws it is the tool that enforces the order.

Two cores, and what is not allowed on each

The chip has two cores, and the division between them is a rule rather than a tendency.

• Core 1: what you look at

  The main loop, the state machine, the screen and the buttons. It never blocks on a radio or on storage, because every millisecond it spends waiting is a millisecond the device feels slow in your hand.

• Core 0: what you wait for

  The Bluetooth host, Wi-Fi and the web server, the filesystem, and the cryptography. Deriving the key takes about a second and a half: it runs here, with a progress indicator drawn on the other core, and at the fastest clock the chip has, whereas every screen runs at the slowest.

A queue or a lock that either of two tasks could reach first is built before the task that consumes it exists, or inside a call that happens once. Checking whether it is null and creating it if so is the bug that looks correct: both cores pass that check, both build one, and one of them is waited on by nobody.

One tree, nine boards

A board is a configuration, not a copy of the firmware.

Each board has a directory holding its pin map, its panel, its power controller, its partition layout and its own figures, the sleep estimate the measurements page prints among them. The firmware builds on ESP-IDF 6.0.3 with no Arduino core in it, as C++26, with every compiler warning treated as an error. A guard reads all nine boards and fails on an inconsistency between them: thirty-odd invariants, including that every build carries exactly one key-derivation work factor, and that the serial console cannot be compiled into a production image.

Every board has up to four builds: an open development one, a debug one that never ships, an open production one, and a hardened one that irreversibly burns one-time fuses on its first boot. Three boards have no hardened build, because 4 MB of flash does not hold two update slots and a signed bootloader.