Merge pull request 'Devlog: "It was off" (the website, and one firmware with the Debug Console in it)' (#71) from devlog-console into main

Reviewed-on: #71

.gitea/workflows/ci.yml

@@ -1,7 +1,7 @@
 # CI and releases (docs/milestones/R1.md).
 #   A push to main:    the host tests, with their coverage of lib/, and the README's badges
 #                      published to the branch `badges`.
-#   A pull request:    the same tests and coverage, then the release firmware and the Debug Build.
+#   A pull request:    the same tests and coverage, then the firmware.
 #                      A branch's pushes run nothing by themselves: its pull request runs, once.
 #   A tag v*:          all of it, then a Gitea release with the signed Update File.
 #   Run by hand:       the release of a tag that exists already (the ones from before CI).
@@ -59,7 +59,7 @@ jobs:
         if: github.event_name != 'workflow_dispatch'
         run: scripts/coverage.sh
 
-      - name: The release firmware and the Debug Build
+      - name: The firmware
         if: github.event_name == 'pull_request' || github.ref_type == 'tag'
         run: scripts/ci.sh builds
 

.gitea/workflows/site.yml

@@ -3,14 +3,15 @@
 #
 # It runs when the site, or a document the site is built from, changes (a pull request, or a push to
 # main); the firmware workflow (ci.yml) skips a change that touches only these files. A change that
-# touches both runs both.
+# touches both runs both. src/main.cpp is here too: the site's command reference is generated from the
+# firmware's own `help` text, and this job checks that it is still current.
 name: Site
 on:
   push:
     branches: [main]
-    paths: ['site/**', 'docs/**', 'README.md', 'CONTEXT.md', '.gitea/workflows/site.yml']
+    paths: ['site/**', 'docs/**', 'README.md', 'CONTEXT.md', 'src/main.cpp', '.gitea/workflows/site.yml']
   pull_request:
-    paths: ['site/**', 'docs/**', 'README.md', 'CONTEXT.md', '.gitea/workflows/site.yml']
+    paths: ['site/**', 'docs/**', 'README.md', 'CONTEXT.md', 'src/main.cpp', '.gitea/workflows/site.yml']
 
 jobs:
   build:
@@ -39,6 +40,9 @@ jobs:
           git fetch -q origin '+refs/heads/*:refs/remotes/origin/*' '+refs/pull/*/head:refs/remotes/pull/*'
           git checkout -q --detach "${{ github.sha }}"
 
+      - name: The generated developer pages are current
+        run: python3 site/tools/gen_dev_docs.py --check
+
       - name: Build the site
         run: |
           cd site

CONTEXT.md

@@ -144,7 +144,7 @@ _Avoid_: Settings > Storage
 Installing a new firmware image without a USB cable: pushed over Wi-Fi from the developer's PC, read from the SD card, or downloaded from the project's Gitea **Release**.
 
 **Release**:
-A tag `v*` on the project's Gitea with a signed **Update File**, a factory image for USB, the ELF to decode crashes and checksums, built and published by CI. The device reads them to look for updates. Debug Builds aren't published.
+A tag `v*` on the project's Gitea with a signed **Update File**, a factory image for USB, the ELF to decode crashes and checksums, built and published by CI. The device reads them to look for updates.
 _Avoid_: flash, upgrade (alone)
 
 **Update File**:
@@ -160,16 +160,12 @@ Returning automatically to the previous firmware when new firmware resets or cra
 _Avoid_: revert, downgrade (a downgrade is installing an older version on purpose)
 
 **Safe Mode**:
-What the firmware starts instead of everything else after 3 crash restarts in a row: Wi-Fi and Firmware Updates (and the Debug Console in a Debug Build), so it can be fixed without a cable. A normal restart leaves it.
+What the firmware starts instead of everything else after 3 crash restarts in a row: Wi-Fi and Firmware Updates (and the Debug Console if it's switched on), so it can be fixed without a cable. A normal restart leaves it.
 _Avoid_: recovery mode, failsafe
 
-**Debug Build**:
-A firmware built with the remote debugging aids compiled in (`+debug` in its version). Release builds have none of them.
-_Avoid_: dev build, test build (a test build is one made to fail on purpose, such as a crashing update)
-
 **Debug Console**:
-The console of a Debug Build over Wi-Fi: live log lines and the serial commands, behind a token.
+The console over Wi-Fi, in every firmware but off until switched on in Settings: live log lines and the serial commands, for whoever holds the device's token.
-_Avoid_: telnet, remote shell
+_Avoid_: telnet, remote shell, Debug Build (there is one firmware)
 
 ## Relationships
 

README.md

@@ -26,14 +26,14 @@ The framework is rebuilt with the TLS settings in `platformio.ini` (`custom_sdkc
 
 ## 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 release firmware and the Debug Build: changes reach `main` through pull requests. Pushing a tag `v*` runs all of it and publishes a release on Gitea with:
+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). Debug Builds are built but never published: each carries its builder's Debug Console token.
+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.
 
@@ -87,7 +87,7 @@ The connection is checked against the two ISRG roots Let's Encrypt chains end in
 
 **IRC steps aside.** A secure connection takes about 52 KB of memory at its peak, and IRC's own takes 40 KB of the 107 KB there is. A check or an install you ask for makes IRC disconnect for the few seconds it takes and reconnect afterwards. The daily check never does that: with IRC connected it waits for a moment when IRC isn't, so while IRC stays connected for days it doesn't run, and **Latest release** is the way to check.
 
-**A Debug Build** shows the latest release but doesn't install it: releases have no Debug Console (they aren't built with one, so that nobody's console token is published), and installing one would take it away. A Debug Build is updated from the PC with `scripts/flash.sh --debug --ota`.
+**There is no separate Debug Build** any more (ADR 0010): every firmware installs releases, and the Debug Console is a setting, which an update leaves as it was.
 
 ## Networks without DHCP
 
@@ -163,12 +163,12 @@ A note holds up to 16 KB while it's edited. A bigger text file opens read-only i
 | `sound on` / `sound off` | Toggles the Sound setting (beep + LED) |
 | `short` / `normal` | Screen timeouts 5 s / 10 s, or 30 s / 60 s |
 | `wifi add <ssid><TAB><password>` | Adds a Saved Network (so credentials stay out of the repo) |
-| `wifi ip <ssid> dhcp` / `wifi ip <ssid> <address>/<prefix> [gateway]` | A Saved Network's IP setting: Automatic, or Fixed. Debug Builds: add `try <seconds>` to go back to the previous setting unless `wifi ip keep` follows |
+| `wifi ip <ssid> dhcp` / `wifi ip <ssid> <address>/<prefix> [gateway]` | A Saved Network's IP setting: Automatic, or Fixed. Add `try <seconds>` to go back to the previous setting unless `wifi ip keep` follows |
 | `wifi dns <a> [b]` / `wifi dns always on\|off` / `wifi ntp <a> [b]` | DNS servers (used on Fixed networks, or always), and NTP servers |
 | `log <text>` | Appends a line to a test IRC Log (`/irc/dev/#test/<date>.log`) |
 | `sd card` | What the SD card says it is: type, size, and its identity register (maker, name, revision, serial, date) |
 | `sd list` | Lists the files of each Storage Clean-up category |
-| `sd fill <folder> <count>` | Debug Builds: makes that many small files in a folder, to test a crowded one |
+| `sd fill <folder> <count>` | Makes that many small files in a folder, to test a crowded one |
 | `cat <path>` | Prints the first ~1.2 KB of a file on the SD card |
 | `irc start` | Starts the IRC Service (normally done by opening the IRC App) |
 | `irc stop` | Stops it, as `/quit` does: QUIT if connected, no more retries, and the App stays disconnected until you type |
@@ -185,8 +185,8 @@ A note holds up to 16 KB while it's edited. A bigger text file opens read-only i
 | `ls [folder]` / `du <path>` | Lists a folder of the SD card with sizes and dates, or counts the files and bytes under a path |
 | `cp [-f] <from> <to>` / `mv [-f] <from> <to>` / `rm <path>` / `mkdir <path>` / `cancel` | What the Storage App does, with its rules: copy (folders too), move or rename, delete (a folder with what's in it), new folder. `-f` replaces a file that's in the way; a tab separates paths that hold spaces; `cancel` stops a copy or a delete |
 | `install <path>` | Update from SD with that `.ota` file, as Settings → Firmware does |
-| `update check` / `update list` / `update status` / `update install <tag>` | The project's releases on Gitea: look at the latest, list the last ten, say what's known, or download and install one (not on a Debug Build) |
+| `update check` / `update list` / `update status` / `update install <tag>` | The project's releases on Gitea: look at the latest, list the last ten, say what's known, or download and install one |
-| `update pretend <version>` / `update probe <host>` / `update damage cut\|flip <n>` / `update daily` | Debug Builds: pretend to run another version (so a release counts as an update), see whether a server's certificate is accepted, cut or damage the next download, run the daily check again |
+| `update pretend <version>` / `update probe <host>` / `update damage cut\|flip <n>` / `update daily` | Pretend to run another version (so a release counts as an update), see whether a server's certificate is accepted, cut or damage the next download, run the daily check again |
 | `lora probe` | Finds the radio: chip, oscillator, antenna switch, DIO1 interrupt, noise floor |
 | `lora status` | Radio settings, who's listening, packet and error counters, noise floor, task stack |
 | `lora rx on` / `lora rx off` | Listens and prints each packet on the console |
@@ -194,26 +194,35 @@ A note holds up to 16 KB while it's edited. A bigger text file opens read-only i
 | `lora capture start` / `lora capture stop` | A LoRa Capture, as `c` in the App |
 | `lora sweep on [from MHz] [to MHz] [step kHz]` / `lora sweep off` / `lora sweep dump` | Sweep a band (863 870 100 by default), with a summary every 2 s (floor, strongest, peaks), or print the latest pass |
 | `gnss quiet on` / `gnss quiet off` | The "Pause GNSS for LoRa" setting |
-| `lora noise test [gnss\|quiet]` / `lora noise report` | Debug Builds: Sweep under one changed condition at a time to find what raises the noise floor (Wi-Fi goes off for a few seconds); then the result |
+| `gnss status` / `gnss restart` | The receiver's state, and a restart of it |
-| `lora inject <hex> [rssi] [snr]` | Debug Builds: a packet into the Scanner as if received (nothing is sent) |
+| `gnss track start` / `gnss track stop` | A Track, as `r` in the GNSS App (the reason is printed if it can't start) |
+| `gnss nmea on` / `gnss nmea off` | Prints each NMEA sentence the receiver sends, as `nmea: …` |
+| `gnss send <sentence>` | Sends a sentence to the receiver, without the `$` and the checksum (it adds them) |
+| `lora noise test [gnss\|quiet]` / `lora noise report` | Sweep under one changed condition at a time to find what raises the noise floor (Wi-Fi goes off for a few seconds); then the result |
+| `lora inject <hex> [rssi] [snr]` | A packet into the Scanner as if received (nothing is sent) |
 | `crash` | The last crash: which firmware, why, task, PC and backtrace (from the core dump in flash) |
 | `coredump erase` | Forgets the core dump |
-| `loop spin on` / `loop spin off` | Debug Builds: make the main loop spin without resting, to compare load and radio noise |
+| `loop spin on` / `loop spin off` | Make the main loop spin without resting, to compare load and radio noise |
-| `crash abort` / `crash wdt` | Debug Builds: crash on purpose, or hang the main loop until the watchdog fires |
+| `crash abort` / `crash wdt` | Crash on purpose, or hang the main loop until the watchdog fires |
+| `debug status` / `debug off [seconds]` | The Debug Console: whether it's on, has a token and a client; switch it off. With a number of seconds, it comes back by itself after that long |
+| `debug on` / `debug token <value>` / `debug token new` | USB serial only: switch it on (making a token if there's none), give it a token of 16 to 64 characters, or make a new one. The token is never printed |
 | `help` | Lists the commands |
 
 `scripts/flash.sh` stops a running serial log first, since it would hold the port.
 
-### Debug Builds and the Debug Console
+### The Debug Console
 
-`scripts/flash.sh --debug` (USB) or `scripts/flash.sh --debug --ota <ip>` (Wi-Fi) installs a Debug Build: the same firmware plus the Debug Console on TCP 2323 (ADR 0004). Then, with `RORO_OTA_HOST` set to the device's IP:
+Every firmware has the Debug Console (ADR 0010): the serial console over Wi-Fi, on TCP 2323. It is **off** until you switch it on in **Settings → Debug Console**, which also makes its token and shows it. With the device on USB, `scripts/flash.sh --debug` flashes it, switches the console on and gives it the token in `~/.config/roro9stack/debug-token`, so nothing has to be typed. Then, with `RORO_OTA_HOST` set to the device's IP:
 
 ```sh
 scripts/rdbg.py                 # interactive: the console backlog, live lines, and commands
 scripts/rdbg.py info            # one command and its reply
 scripts/rdbg.py -b tasks        # the same, after the backlog (boot messages and so on)
+scripts/rdbg.py -t K7QF-3M2X-9WBD-HT4P-6RNC info   # another device's token; or $RORO_DEBUG_TOKEN
 ```
 
+The token never crosses the network: the device sends a challenge and `rdbg.py` answers with its HMAC. Five wrong answers in a row close the console for a minute. `debug status` and `debug off` work from anywhere; `debug on`, `debug token <value>` and `debug token new` work over USB serial only.
+
 Every command above works there too, plus a few handled by the PC side or the console's own task:
 
 ```sh
@@ -227,6 +236,6 @@ scripts/rdbg.py get <card path> [file]    # from the SD card
 
 So a Firmware Update can also go `rdbg.py put roro9stack-….ota` then `rdbg.py install /updates/roro9stack-….ota`: the Update from SD path, without touching the device.
 
-Every build keeps its ELF in `.pio/elves/` (version and digest in the name) for that; `scripts/decode_backtrace.sh <version|digest> <addresses>` decodes any backtrace by hand.
+Every build keeps its ELF in `.pio/elves/` (version and digest in the name) for that, and `rdbg.py crash` fetches a release's ELF from Gitea when it isn't there; `scripts/decode_backtrace.sh <version|digest> <addresses>` decodes any backtrace by hand.
 
-After 3 crash restarts in a row the firmware starts in **Safe Mode** (ADR 0005): only Wi-Fi, Firmware Updates and the Debug Console, so a fix can be pushed as usual. `reboot` leaves it. The token is in `~/.config/roro9stack/debug-token`, made by the first build; keep developing on Debug Builds, so the firmware a Rollback returns to always has the console.
+After 3 crash restarts in a row the firmware starts in **Safe Mode** (ADR 0005): only Wi-Fi, Firmware Updates and, if it's switched on, the Debug Console, so a fix can be pushed as usual. `reboot` leaves it.

docs/adr/0004-debug-console-in-debug-builds.md

@@ -1,5 +1,7 @@
 # A Debug Console over Wi-Fi, in Debug Builds only
 
+**Superseded in part by [ADR 0010](0010-debug-console-in-every-build.md) (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 console works (the ring, commands on the main loop, binary commands on its own task, one client) still holds.
+
 The goal of Firmware Updates is to manage the device without a cable, and that includes finding out what went wrong. So a **Debug Build** (`cardputer-adv-debug`, `-DRORO_DEBUG`, version suffix `+debug`) adds a **Debug Console** on TCP 2323: the serial console, over Wi-Fi. A client sends a token as its first line, then gets the last 4 KB of console output (boot messages included), every new line live, and runs the same commands as the serial port, plus a few that only make sense remotely. ESP-IDF's own log lines are teed into it.
 
 It's compiled out of release builds entirely, rather than switched off by a setting. A console that runs commands is a remote control: in a release build, nothing listens.

docs/adr/0005-safe-mode-crash-reports-watchdog.md

@@ -1,9 +1,9 @@
 # Safe Mode, crash reports and a watched main loop, in every build
 
-Rollback protects against new firmware that fails Probation. It does nothing for firmware that was confirmed and crashes later: a corrupt setting, a server that sends something unexpected, a bug that takes an hour to show. Without a cable, such a device would restart forever. Three measures, in release and Debug Builds alike, keep it reachable:
+Rollback protects against new firmware that fails Probation. It does nothing for firmware that was confirmed and crashes later: a corrupt setting, a server that sends something unexpected, a bug that takes an hour to show. Without a cable, such a device would restart forever. Three measures, in every build, keep it reachable:
 
-- **Safe Mode.** The firmware counts starts that follow a crash (panic or watchdog) in NVS, first thing at boot. After 3 in a row, it starts only the clock, Wi-Fi, the Update Service and, in a Debug Build, the Debug Console: no Apps, no IRC, no SD card, and a screen that says so with the address to push an update to. Any normal restart (a `reboot`, an update), or a minute of uptime, resets the count.
+- **Safe Mode.** The firmware counts starts that follow a crash (panic or watchdog) in NVS, first thing at boot. After 3 in a row, it starts only the clock, Wi-Fi, the Update Service and, if it's switched on, the Debug Console: no Apps, no IRC, no SD card, and a screen that says so with the address to push an update to. Any normal restart (a `reboot`, an update), or a minute of uptime, resets the count.
-- **Crash reports.** The same boot record keeps which version was running, so after a crash the firmware knows which one crashed, even when a Rollback has switched slots since. ESP-IDF already writes a core dump to its flash partition on a panic; after the restart the firmware prints its summary (task, PC, reason, backtrace) and raises a Notification. The `crash` command shows it again later. In a Debug Build, `scripts/rdbg.py crash` decodes the backtrace and `scripts/rdbg.py coredump` fetches the whole dump for `esp-coredump`, against the ELF of that exact build (`.pio/elves/`, named by version and ELF digest).
+- **Crash reports.** The same boot record keeps which version was running, so after a crash the firmware knows which one crashed, even when a Rollback has switched slots since. ESP-IDF already writes a core dump to its flash partition on a panic; after the restart the firmware prints its summary (task, PC, reason, backtrace) and raises a Notification. The `crash` command shows it again later. With the Debug Console, `scripts/rdbg.py crash` decodes the backtrace and `scripts/rdbg.py coredump` fetches the whole dump for `esp-coredump`, against the ELF of that exact build (`.pio/elves/`, named by version and ELF digest).
 - **The main loop is watched.** Arduino-ESP32 subscribes only core 0's idle task to the task watchdog, and the main loop runs on core 1: a stuck loop used to hang the device for good, with the screen frozen and the Debug Console unable to run commands. `enableLoopWDT()` makes a loop stuck for 5 s a panic, with a core dump, counted towards Safe Mode. And an installed update no longer depends on the main loop: the Update Service restarts into it by itself after 90 s.
 
 ## Consequences

docs/adr/0010-debug-console-in-every-build.md

@@ -0,0 +1,30 @@
+# The Debug Console is in every build, off until its owner switches it on
+
+There is **one firmware**. The Debug Console of ADR 0004 is compiled into it, and so are the commands that used to exist only in Debug Builds. It listens only while **Settings → Debug Console** is on, which is not the default, and it lets in whoever proves they hold **the device's own token**. The `cardputer-adv-debug` environment, `RORO_DEBUG`, the `+debug` version and the token compiled in from the builder's machine are gone.
+
+ADR 0004 kept the console out of release builds with one argument: a console that runs commands is a remote control, so in a release nothing should listen. That argument was never whole: the Update Service has listened on TCP 3232 in every build since Firmware Updates exist, guarded by a signature. A listener that is off by default and guarded by a secret the device made itself is the same kind of trade, and what the split cost had grown:
+
+- **What was tested wasn't what shipped.** Development ran on Debug Builds; releases were a different binary, built to be published and never run by the person who wrote them.
+- **Debug Builds couldn't be published**, since each carried its builder's token. So the console, `rdbg.py`, screenshots and crash decoding were for whoever built the firmware, and nobody else.
+- **Rules that existed only to protect the console:** a Debug Build never installed a release (it would have lost the console), `update install … force` to do it anyway, "keep a Debug Build in the fallback slot", versions with `+debug` that had to compare equal to their release.
+- **CI built two firmwares** on every pull request and every tag.
+
+## How it works
+
+- **Off means nothing is there.** With the setting off, no socket listens, the console's task doesn't exist and neither does its 4 KB ring: a device that never uses the console pays for it in flash (30 KB more than the release build was) and 88 bytes of static RAM, measured. A missing or invalid stored setting counts as off.
+- **The token is the device's.** The first time the console is switched on, the device makes one from its hardware random generator: 100 bits, as 20 characters of Crockford's base32 (`K7QF-3M2X-9WBD-HT4P-6RNC`), shown on the Debug Console page and nowhere else. It can be replaced by one typed by hand, of 16 to 64 characters. It is stored with the other settings and is never printed on a console.
+- **The token never crosses the network.** The device sends 16 random bytes; the client answers with their HMAC-SHA256 keyed by the token. Someone on the same Wi-Fi who records a login has nothing they can use for the next one.
+- **Five wrong answers in a row** close the console to everyone for a minute, with a Notification naming the address they came from. A wrong answer still costs a second.
+- **`DBG` in the Status Bar** while the console listens, bright while a client is connected.
+- **USB serial can set it up:** `debug on`, `debug token <value>`, `debug token new`. `scripts/flash.sh --debug` uses them to give a freshly flashed device the developer's token. Whoever holds the cable can flash anything anyway (ADR 0003); the console itself can only switch itself off.
+- **Safe Mode** starts the console if it's switched on: the settings are read before Safe Mode is decided.
+
+## Consequences
+
+- **"Nothing listens" now rests on one stored setting**, not on absent code. That setting is typed, validated and host-tested, and its default is off; a bug that flipped it would have to come from code that already runs on the device.
+- **Whoever has the token and the network has the device:** the console, its keys, the SD card's files, a restart. Not its firmware: an update still has to be signed (ADR 0003).
+- **The stream is still plain text.** The token is safe from an eavesdropper; what the console prints, and the files it carries, are not. TLS would cost about 52 KB of the 107 KB there is, next to IRC's own connection: not for a console.
+- **An old `rdbg.py` can't talk to a new firmware**, and the reverse: the first line of the protocol changed. Accepted, with one user.
+- **A device whose settings are damaged has no console in Safe Mode**, only the signed update push. Before, a Debug Build always had it.
+- **The commands that crash, damage a download or fill a folder on purpose** are in every build. They need the cable or the token, like everything else.
+- **Releases already publish their ELF**, so `rdbg.py crash` fetches it when it isn't in `.pio/elves/`: crash reports can be decoded without having built the firmware.

docs/milestones/R1.md

@@ -14,7 +14,7 @@ Until now the tests, the builds, the signing and the flashing all happened on on
 |---|---|
 | Q151 | A push to `main`: the host tests (with their coverage). A push to another branch: nothing, its pull request is what runs (a branch with an open pull request ran twice, once for each). A pull request: the same and both builds; changes reach `main` through pull requests. A tag `v*`: all of it, then a release. (First: everything on every push, which rebuilt the firmware far more often than anyone looked at it.) |
 | Q152 | **CI signs.** The signing key is the repository secret `OTA_SIGNING_KEY`; a tag push makes a complete, signed release with no manual step (ADR 0008). |
-| Q153 | The Debug Build is built in CI with a token of the runner's own, to prove it compiles, and **isn't published**: it would hand everyone its Debug Console token. |
+| Q153 | *Revised by Q188: there is one firmware.* The Debug Build is built in CI with a token of the runner's own, to prove it compiles, and **isn't published**: it would hand everyone its Debug Console token. |
 | Q154 | Pull requests from forks don't start a run. |
 | Q155 | A release carries `roro9stack-<version>.ota` (signed), `-factory.bin` for USB, `.elf.gz` to decode crashes, and `SHA256SUMS`. |
 | Q156 | Its text is the tag's message, what the files are, and the commits since the tag before. |
@@ -64,7 +64,7 @@ The device looks at the project's Gitea for a newer release, says so, and instal
 | Q168 | A version that failed (rolled back) isn't announced again by the background check until a newer one exists; it can still be installed by hand. |
 | Q169 | **Older releases:** a list of the last ten, newest first, the running one marked. Installing an older one asks with a stronger warning. |
 | Q170 | Enter on a release shows its version, date, size and the tag message, with Install. |
-| Q171 | **Debug Builds** check and show the latest release, but don't install it: it would replace the Debug Build and its console (Q153: Debug Builds aren't published). Their updates come from the PC. |
+| Q171 | *Revised by Q188: there is no Debug Build, every firmware installs releases.* **Debug Builds** check and show the latest release, but don't install it: it would replace the Debug Build and its console (Q153: Debug Builds aren't published). Their updates come from the PC. |
 | Q172 | **Memory, as measured:** a TLS connection peaks at about 52 KB of heap, with or without checking the certificate, so it starts with 80 KB free (Q86's 20 KB spare on top), not 55 KB. **A check, list or install someone asked for makes IRC step aside** and come back after; the daily check never does, and with IRC connected it waits. (First: 55 KB and nothing else. With IRC connected a check left 3 KB and a download 836 bytes.) |
 | Q173 | Left out, each with its issue: installing automatically (#52), a release channel (#53), resuming a download (#54). |
 | Q174 | Ships as **v0.11.0**. Tested on the device with the real signed releases; a Debug Build command pretends the device runs an older version, so v0.10.0 counts as an update. |
@@ -123,3 +123,52 @@ The device looks at the project's Gitea for a newer release, says so, and instal
 - **A key press during the hold:** Back on the Firmware page while a check is going doesn't cancel it.
 
 **Two slips during the checks:** a blind sequence of keys on the Firmware page opened the SD card's install dialog (the page keeps its selection between visits); it was cancelled with Back, nothing installed. And my port-polling while waiting for a restart took the Debug Console's only client slot, which made the first install attempt look like a failure.
+
+## One firmware: the Debug Console in every build (issue #68)
+
+The issue asked for a token that could be set, so that Debug Builds could be published. The design round ended somewhere simpler: no Debug Builds. The console is in every firmware, off until switched on, with a token that belongs to the device (ADR 0010, which supersedes part of ADR 0004).
+
+### Decisions (design round 2026-10-06)
+
+| # | Decision |
+|---|---|
+| Q188 | **One firmware,** with the Debug Console and the test commands compiled in. The `cardputer-adv-debug` environment, `RORO_DEBUG`, the `+debug` version and `scripts/debug_flags.py` go; CI builds one firmware. Revises Q153 and Q171. |
+| Q189 | **Off by default,** and off when the stored setting is missing or invalid. Off, nothing listens and no memory is used: the task and the 4 KB ring exist only while it's on. |
+| Q190 | **Settings → Debug Console:** the switch, where to connect, the token, "New token", "Type a token". It stays on across restarts and in Safe Mode. **`DBG` in the Status Bar** while it listens, bright with a client connected. |
+| Q191 | **The device makes the token** the first time the console is switched on: 100 bits as 20 characters of Crockford's base32, shown in groups of four. It can be replaced by one typed by hand, of at least 16 characters. Case and dashes don't count. |
+| Q192 | **USB serial can set it up:** `debug on`, `debug token <value>`, `debug token new`, over USB only; `debug status` and `debug off` from anywhere. `scripts/flash.sh --debug` gives a device the developer's token. The token is never printed. |
+| Q193 | **Challenge and answer:** the device sends 16 random bytes, the client their HMAC-SHA256 keyed by the token. Five wrong answers in a row close the console for a minute, with a Notification. **Old clients and old firmwares don't talk to each other:** accepted, this far from v1 and with one user. |
+| Q194 | `rdbg.py` takes the token from **`-t`/`--token`**, then **`$RORO_DEBUG_TOKEN`**, then `~/.config/roro9stack/debug-token`. |
+| Q195 | **The test commands are in every build** (`crash abort`, `crash wdt`, `update pretend`, `update damage`, `lora inject`, `sd fill`, `loop spin`, `wifi ip … try`). `update install … force` goes: there's nothing left to protect. |
+
+### As built
+
+- **`lib/debug`** (host-tested, 9 tests): the token maker, tidying what a person types, HMAC-SHA256 on the project's own SHA-256 (checked against RFC 4231), the answer to a challenge (the same vector as `rdbg.py`'s), a comparison that takes the same time whatever it's given, and the pause after five wrong answers, right across the clock's wrap.
+- **Two settings,** `DebugConsole` and `DebugToken`, with the others: validated, and invalid stored values count as missing.
+- **The console's task and ring come and go with the setting.** `Console::openRing` allocates the ring; switching off closes the socket, frees it and ends the task. `tick` follows the settings once a second, so a switch off and on again takes a second or two.
+- **Measured against the two builds it replaces:** 1,881,799 bytes of flash and 54,700 of static RAM. The release build was 1,851,387 and 54,612 (so 30 KB more flash and 88 bytes more RAM); the Debug Build was 1,874,887 and 58,780 (4 KB of RAM back: the ring is no longer a static array).
+- **The listener is asked whether it listens.** The framework's `begin()` returns nothing and fails without a word; the task now checks, says so on the console, and tries again every two seconds.
+- **`debug off <seconds>`** closes the console and brings it back by itself: the only way to try its closing and reopening from afar, since switching it on is for the device and the cable only.
+- **`scripts/rdbg.py`** answers the challenge, and fetches a release's ELF from Gitea when a crash names a version that isn't in `.pio/elves/`.
+
+### Checks
+
+| Check | Result |
+|---|---|
+| Host tests | 468 pass (456 before) |
+| The firmware builds | One environment, 1,881,799 bytes of flash used |
+| Pushed over Wi-Fi to a device running a Debug Build | Installed, restarted; the update port answers and **port 2323 refuses connections**: off by default |
+| Switched on at the device (Settings → Debug Console) | A token is made and shown. Its first drawing, in bold at normal size, was misread once: it is now at twice the size, in two lines, and `O`, `I` and `L` are taken for `0` and `1` |
+| A login with `scripts/rdbg.py` | The challenge is answered; `info`, `screenshot` and the backlog work |
+| `DBG` in the Status Bar | There while the console is on, bright while a client is connected (screenshots) |
+| `debug on` and `debug token` over the console | Refused: `over USB serial only` |
+| Six logins with a wrong token | Five are refused, a second apart; the sixth, and the right token after it, get `locked`. After a minute the right token works again. The console's own log and a Notification say so |
+| Three `crash abort` in a row | **Safe Mode**, with the console reachable: `info` works, `ls /` says `not available in Safe Mode`. `rdbg.py crash` decodes the backtrace to `runCommand` at the `abort()` line. `reboot` leaves Safe Mode |
+| An update over Wi-Fi with the console on | The setting and the token survive: the console is back by itself after the restart |
+| `debug off` over the console | The client is dropped and port 2323 refuses connections; the update port still answers |
+| `debug off 2`, 10 times in a row, then 15 | It came back each time, a second after the pause. Free heap dips by about 270 bytes for each connection the device closes and **is all back two minutes later** (107.2 KB before, 103.2 right after 15, 107.0 at two minutes): TCP holds a closed connection that long. Not a leak, though it looked like one for an hour |
+| Memory, console on with a client | 108 KB free (the Debug Build it replaces: 104 KB). In Safe Mode: 178 KB free |
+
+**One false alarm:** after the tests the console "wouldn't come back on". It was off: the setting had been left off by `debug off`, and the page's "Switch it on?" dialog opens on **Cancel**, so Enter twice leaves it off. Nothing was lost.
+
+**Not checked:** `scripts/flash.sh --debug` over USB (no device on USB here); "New token" and "Type a token" from the page (the code paths are the ones `debug token` uses, which need the cable); the Toast itself on screen (the console is closed while it shows; its Notification is in the log); free memory with the console off, which only the serial port could say (the static figures above are the evidence); fetching a release's ELF, which needs a crash on a released version.

docs/milestones/W1.md

@@ -1,6 +1,6 @@
 # W1: Website
 
-**Status:** phase 1 (home, Install, Downloads) is live at roro9stack.net; phase 2 (the user guide) is live; a devlog section is in a pull request. Issue #12.
+**Status:** phases 1 to 3 (home, Install and Downloads; the user guide; how-tos and the FAQ) and the devlog are live at roro9stack.net; phase 4 (the developer docs) is in a pull request. Issue #12.
 
 **Goal:** a public home for the project at **roro9stack.net**, separate from the blog (stories) and from Gitea (developers): what it is, how to install it, how to use each App, and the docs.
 
@@ -110,3 +110,18 @@ Not one of the planned phases: the blog's seven roro9stack posts, imported into
 - **The CI split on a change that touches only `site/` or `docs/`.** This pull request touches both the workflows and the site, so it runs both; the first docs-only pull request will show it.
 - Firefox and Safari rendering, screen readers, and a printed page.
 - The unverified wording in the Install text is kept to what's known: nothing about how long flashing takes, or what the screen shows in download mode.
+
+## As built (phase 3, how-tos and the FAQ)
+
+- **`/howto/`** has eight short recipes: when flashing fails, find your files on the SD card, install an update from the card, use a network without DHCP, record a Track, capture LoRa packets for Wireshark, read Gemini pages offline, and what to do when a connection says "not enough memory". **`/faq/`** is one page of questions with a list at the top. Both use the guide's templates (`guide-index.html`, `guide-page.html`, now generic: the page's parent section gives the eyebrow, the title and the pager).
+- **The FAQ starts from the README** and from the problems the project met (Q183): the flash troubles and the memory limit are the two that were hit most. The issues labelled `kind/docs` turned out to be design rounds for the mesh, not user questions, so they gave nothing to answer.
+- **Every step comes from the README, the milestone documents or the Apps' source.** The privacy answer says plainly that the device contacts the project's server once a day for the update check (on by default, one switch to turn it off).
+- **Linked from the guide's index,** not the navigation, which stays short.
+
+## As built (phase 4, the developer docs)
+
+- **`/dev/`** has four sections: **Debug Builds and the Debug Console** (first, and the longest: Debug Builds, the Console and its protocol, files and screenshots, driving the UI, crashes and Safe Mode, and the command reference), **Build, test and release** (the README's build, CI and flash sections, and how an update works, with the update file, the four ways in and Probation drawn), **Decisions** (the ADRs) and **Milestones** (the plans).
+- **Generated from the repository, not copied by hand:** `site/tools/gen_dev_docs.py` writes the ADR pages, the milestone pages, the README's sections, and the command reference, which is read from the firmware's own `help` text in `src/main.cpp` and then the README's table of what each command does. Zola can't read outside its own folder (not even through a symlink), so the generated pages are **committed**, and the Site workflow runs `gen_dev_docs.py --check` and fails when one is out of date; it now also runs when `src/main.cpp` changes, because the command list lives there. The server's `pull; zola build` is unchanged.
+- **Left out on purpose:** the M0 and M1 milestone documents and `CONTEXT.md` (the glossary) describe Wi-Fi monitoring, which the site does not publish. They stay in the repository.
+- **The Debug Console pages were written against the source and the live console:** the protocol (the token line, the banner, the 4 KB backlog, one client, 8 queued commands, 240-byte lines, `denied` after a second) and the replies shown were checked on a Debug Build, v0.11.0-3, over Wi-Fi. Not run: `crash abort`, `crash wdt` and Safe Mode, which are described from ADR 0005 and the code.
+- **Found while writing it:** the README's table lacked the `gnss` commands (rows added); piping commands into `rdbg.py` returns before the replies unless the input stays open (documented, not changed); `update install` on a Debug Build needs `force` (documented).

lib/apps_model/src/settings_menu.cpp

@@ -24,7 +24,7 @@ const RowDef kRows[] = {
     {Row::Coordinates, Kind::Toggle, "Coordinates"},
     {Row::ProbeMacs, Kind::Toggle, "Probe MACs"}, {Row::Wifi, Kind::Page, "Wi-Fi"},
     {Row::CheckUpdates, Kind::Toggle, "Check for updates"}, {Row::Firmware, Kind::Page, "Firmware"},
-    {Row::About, Kind::Page, "About"},
+    {Row::DebugConsole, Kind::Page, "Debug Console"}, {Row::About, Kind::Page, "About"},
 };
 
 const int kDimSeconds[] = {10, 15, 30, 60, 120, 300};
@@ -86,6 +86,7 @@ std::string SettingsMenu::value(int i) const {
         case Row::Coordinates: return settings_.getBool(Setting::CoordinatesDms) ? "Deg min sec" : "Decimal";
         case Row::ProbeMacs: return settings_.getBool(Setting::ProbeMacRaw) ? "Raw" : "Pseudonymised";
         case Row::Wifi: return settings_.getBool(Setting::WifiEnabled) ? "On" : "Off";
+        case Row::DebugConsole: return settings_.getBool(Setting::DebugConsole) ? "On" : "Off";
         default: return "";
     }
 }

lib/apps_model/src/settings_menu.h

@@ -11,7 +11,7 @@ namespace roro {
 // values, choice lists and validation messages. Rendering and navigation live in the App.
 class SettingsMenu {
    public:
-    enum class Row { LongName, ShortName, Region, Timezone, Brightness, DimTimeout, OffTimeout, Sound, Gnss, GnssQuiet, Coordinates, ProbeMacs, Wifi, CheckUpdates, Firmware, About };
+    enum class Row { LongName, ShortName, Region, Timezone, Brightness, DimTimeout, OffTimeout, Sound, Gnss, GnssQuiet, Coordinates, ProbeMacs, Wifi, CheckUpdates, Firmware, DebugConsole, About };
     enum class Kind { Text, Choice, Toggle, Slider, Page };
 
     explicit SettingsMenu(Settings& settings) : settings_(settings) {}

lib/debug/src/debug_auth.cpp

@@ -0,0 +1,117 @@
+#include "debug_auth.h"
+
+#include <cstring>
+
+#include "sha256.h"
+
+namespace roro::debug {
+
+namespace {
+const char kAlphabet[] = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+}
+
+std::string makeToken(const uint8_t random[kTokenRandom]) {
+    std::string token;
+    uint32_t bits = 0;
+    int have = 0;
+    size_t next = 0;
+    while (token.size() < kTokenChars) {
+        if (have < 5) {
+            bits = (bits << 8) | random[next++];
+            have += 8;
+        }
+        token += kAlphabet[(bits >> (have - 5)) & 31];
+        have -= 5;
+    }
+    return token;
+}
+
+std::string tidyToken(const std::string& typed) {
+    std::string out;
+    for (char c : typed) {
+        if (c == '-' || c == ' ' || c == '\t' || c == '\r' || c == '\n') continue;
+        if (c >= 'a' && c <= 'z') c = static_cast<char>(c - 'a' + 'A');
+        // Crockford's rule for the letters his alphabet leaves out: read as the digit they look like.
+        if (c == 'O') c = '0';
+        if (c == 'I' || c == 'L') c = '1';
+        out += c;
+    }
+    return out;
+}
+
+bool validToken(const std::string& tidied) {
+    if (tidied.size() < kMinTokenChars || tidied.size() > kMaxTokenChars) return false;
+    for (char c : tidied)
+        if (c <= ' ' || c > '~' || c == '-' || (c >= 'a' && c <= 'z') || c == 'O' || c == 'I' || c == 'L') return false;
+    return true;
+}
+
+std::string groupToken(const std::string& token) {
+    std::string out;
+    for (size_t i = 0; i < token.size(); i++) {
+        if (i && i % 4 == 0) out += '-';
+        out += token[i];
+    }
+    return out;
+}
+
+void hmacSha256(const uint8_t* key, size_t keyLen, const uint8_t* message, size_t messageLen, uint8_t out[32]) {
+    uint8_t block[64] = {};
+    if (keyLen > sizeof block) Sha256::hash(key, keyLen, block);  // a long key is hashed first
+    else memcpy(block, key, keyLen);
+
+    uint8_t pad[64];
+    for (size_t i = 0; i < sizeof pad; i++) pad[i] = block[i] ^ 0x36;
+    uint8_t inner[32];
+    Sha256 in;
+    in.update(pad, sizeof pad);
+    in.update(message, messageLen);
+    in.finish(inner);
+
+    for (size_t i = 0; i < sizeof pad; i++) pad[i] = block[i] ^ 0x5c;
+    Sha256 outer;
+    outer.update(pad, sizeof pad);
+    outer.update(inner, sizeof inner);
+    outer.finish(out);
+}
+
+std::string toHex(const uint8_t* data, size_t len) {
+    static const char digits[] = "0123456789abcdef";
+    std::string out;
+    out.reserve(len * 2);
+    for (size_t i = 0; i < len; i++) {
+        out += digits[data[i] >> 4];
+        out += digits[data[i] & 15];
+    }
+    return out;
+}
+
+std::string answerFor(const std::string& token, const uint8_t nonce[kNonceBytes]) {
+    uint8_t mac[32];
+    hmacSha256(reinterpret_cast<const uint8_t*>(token.data()), token.size(), nonce, kNonceBytes, mac);
+    return toHex(mac, sizeof mac);
+}
+
+bool sameText(const std::string& a, const std::string& b) {
+    uint8_t diff = a.size() != b.size();
+    for (size_t i = 0; i < b.size(); i++) diff |= static_cast<uint8_t>((i < a.size() ? a[i] : 0) ^ b[i]);
+    return diff == 0;
+}
+
+bool AuthGate::locked(uint32_t nowMs) {
+    if (locked_ && nowMs - lockedAtMs_ >= kLockMs) {  // unsigned: right across the 49-day wrap too
+        locked_ = false;
+        failures_ = 0;
+    }
+    return locked_;
+}
+
+bool AuthGate::failed(uint32_t nowMs) {
+    if (locked(nowMs)) return false;
+    if (++failures_ < kMaxFailures) return false;
+    locked_ = true;
+    lockedAtMs_ = nowMs;
+    return true;
+}
+
+}  // namespace roro::debug

lib/debug/src/debug_auth.h

@@ -0,0 +1,59 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+
+// Who may use the Debug Console (ADR 0010): a token that only the device and its owner know, proved
+// with a challenge and an answer so that it never crosses the network, and a pause after wrong answers.
+namespace roro::debug {
+
+constexpr size_t kTokenChars = 20;     // a token the device makes: 100 bits
+constexpr size_t kTokenRandom = 13;    // the random bytes it takes
+constexpr size_t kMinTokenChars = 16;  // a token typed by hand, once tidied
+constexpr size_t kMaxTokenChars = 64;
+constexpr size_t kNonceBytes = 16;
+
+// A token from random bytes: 20 characters of Crockford's base32 (no I, L, O or U to misread).
+std::string makeToken(const uint8_t random[kTokenRandom]);
+
+// What a person typed, as it's stored and compared: no dashes or spaces, in capitals, and with O
+// read as 0, I and L as 1. So a token can be read off the screen in groups, typed in any case,
+// and the usual misreadings don't matter.
+std::string tidyToken(const std::string& typed);
+
+// A tidied token that may be stored: 16 to 64 printable ASCII characters, as tidyToken leaves them.
+bool validToken(const std::string& tidied);
+
+// For the screen: K7QF-3M2X-9WBD-HT4P-6RNC.
+std::string groupToken(const std::string& token);
+
+void hmacSha256(const uint8_t* key, size_t keyLen, const uint8_t* message, size_t messageLen, uint8_t out[32]);
+
+std::string toHex(const uint8_t* data, size_t len);
+
+// What a client must send back for a challenge: HMAC-SHA256 of the nonce, keyed by the token, in hex.
+std::string answerFor(const std::string& token, const uint8_t nonce[kNonceBytes]);
+
+// Compares without stopping at the first difference, so timing says nothing about the answer.
+bool sameText(const std::string& a, const std::string& b);
+
+// Five wrong answers in a row, from anyone, and nobody is listened to for a minute.
+class AuthGate {
+   public:
+    static constexpr int kMaxFailures = 5;
+    static constexpr uint32_t kLockMs = 60000;
+
+    bool locked(uint32_t nowMs);
+    // A wrong answer. True if it's the one that starts the pause.
+    bool failed(uint32_t nowMs);
+    void succeeded() { failures_ = 0; }
+    int failures() const { return failures_; }
+
+   private:
+    int failures_ = 0;
+    bool locked_ = false;
+    uint32_t lockedAtMs_ = 0;
+};
+
+}  // namespace roro::debug

lib/release/src/update_check.h

@@ -13,12 +13,6 @@ constexpr const char* kGiteaRepo = "twisla/roro9stack";
 
 inline bool versionNewer(const std::string& a, const std::string& b) { return versionOlder(b, a); }
 
-// "v0.10.0+debug": the Debug Build says so wherever the version shows (scripts/version.py).
-inline bool isDebugBuild(const std::string& version) {
-    static const std::string tail = "+debug";
-    return version.size() >= tail.size() && version.compare(version.size() - tail.size(), tail.size(), tail) == 0;
-}
-
 // Is `release` a newer one than what runs?
 inline bool isNewer(const Release& release, const std::string& running) {
     return release.usable() && versionNewer(release.tag, running);

lib/services/src/settings.cpp

@@ -1,5 +1,6 @@
 #include "settings.h"
 
+#include "debug_auth.h"
 #include "ipv4.h"
 
 namespace roro {
@@ -41,6 +42,8 @@ const Definition kDefinitions[] = {
     {"ntp2", Kind::String, 0, "time.cloudflare.com", 0, 63},
     {"gnss_quiet", Kind::Bool, 0, nullptr, 0, 1},  // off: GNSS stays on, as decided in M2 (Q58)
     {"check_updates", Kind::Bool, 1, nullptr, 0, 1},  // on: it only looks, and says so (R1, Q165)
+    {"debug_on", Kind::Bool, 0, nullptr, 0, 1},  // off: nothing listens until the owner says so (Q189)
+    {"debug_token", Kind::String, 0, "", 0, 64},  // empty, or a valid token
 };
 static_assert(sizeof(kDefinitions) / sizeof(kDefinitions[0]) == static_cast<size_t>(Setting::Count),
               "every Setting needs a definition");
@@ -98,6 +101,7 @@ bool Settings::validString(Setting s, const std::string& value) const {
     if (s == Setting::Dns2) return value.empty() || net::parseIpv4(value, address);
     if (s == Setting::Ntp1) return net::validHost(value);
     if (s == Setting::Ntp2) return value.empty() || net::validHost(value);
+    if (s == Setting::DebugToken) return value.empty() || debug::validToken(value);
     return true;
 }
 

lib/services/src/settings.h

@@ -31,6 +31,8 @@ enum class Setting : uint8_t {
     Ntp2,             // string: the second, or empty
     GnssQuietForLora, // bool: put the GNSS receiver in standby while the LoRa radio listens (issue #20)
     CheckUpdates,     // bool: look for a newer release on Gitea once a day (R1, Q165)
+    DebugConsole,     // bool: the Debug Console listens on Wi-Fi (ADR 0010, Q189: off unless switched on)
+    DebugToken,       // string: its token, tidied (debug_auth.h); empty until the console is first switched on
     Count
 };
 

platformio.ini

@@ -32,15 +32,6 @@ custom_sdkconfig =
     CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA=y
     CONFIG_MBEDTLS_DYNAMIC_FREE_CA_CERT=y
 
-; Debug Build: the same firmware plus the Debug Console on TCP 2323 (see ADR 0004). The token comes
-; from ~/.config/roro9stack/debug-token, passed in by scripts/_docker.sh; it's never committed.
-[env:cardputer-adv-debug]
-extends = env:cardputer-adv
-extra_scripts = pre:scripts/version.py, pre:scripts/debug_flags.py
-build_flags =
-    ${env:cardputer-adv.build_flags}
-    -DRORO_DEBUG
-
 ; Host-side unit tests for pure logic (no hardware).
 [env:native]
 platform = native

scripts/_docker.sh

@@ -6,7 +6,9 @@ ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 
 [ -n "${RORO_NO_DOCKER:-}" ] || docker build -q -t "$IMAGE" "$ROOT/docker" >/dev/null
 
-# The Debug Console token (ADR 0004): made once, kept with the OTA key, never committed.
+# The Debug Console token of the developer's device (ADR 0010): made once, kept with the OTA key, never
+# committed and never compiled in. scripts/flash.sh --debug gives it to a device over USB, and
+# scripts/rdbg.py answers the device's challenge with it.
 DEBUG_TOKEN_FILE="$HOME/.config/roro9stack/debug-token"
 if [ ! -s "$DEBUG_TOKEN_FILE" ]; then
     mkdir -p "$(dirname "$DEBUG_TOKEN_FILE")"

scripts/ci.sh

@@ -7,8 +7,8 @@ DOCKER_EXTRA=()
 
 case "${1:-all}" in
     tests) STEPS='pio test -e native' ;;
-    builds) STEPS='pio run -e cardputer-adv -e cardputer-adv-debug' ;;
+    builds) STEPS='pio run -e cardputer-adv' ;;
-    all) STEPS='pio test -e native && pio run -e cardputer-adv -e cardputer-adv-debug' ;;
+    all) STEPS='pio test -e native && pio run -e cardputer-adv' ;;
     *) echo "Usage: scripts/ci.sh [tests|builds]" >&2; exit 1 ;;
 esac
 run_in_container bash -c 'git config --global --add safe.directory "$PWD" && '"$STEPS"

scripts/debug_flags.py

@@ -1,12 +0,0 @@
-# Debug Builds only: compiles in the Debug Console token from $RORO_DEBUG_TOKEN (set by _docker.sh
-# from ~/.config/roro9stack/debug-token). Refuses to build without one rather than use a default.
-import os
-import re
-import sys
-
-Import("env")  # noqa: F821  (provided by PlatformIO)
-
-token = os.environ.get("RORO_DEBUG_TOKEN", "").strip()
-if not re.fullmatch(r"[0-9a-f]{32}", token):
-    sys.exit("debug build: RORO_DEBUG_TOKEN is missing; build through scripts/ci.sh or scripts/flash.sh --debug")
-env.Append(CPPDEFINES=[("RORO_DEBUG_TOKEN", '\\"%s\\"' % token)])  # noqa: F821

scripts/flash.sh

@@ -1,17 +1,21 @@
 #!/usr/bin/env bash
 # Flash the firmware over USB, then open the serial monitor.
-# Usage: scripts/flash.sh [--debug] [port]        USB (default: the first Espressif device found)
+# Usage: scripts/flash.sh [--debug] [port]   USB (default: the first Espressif device found)
-#        scripts/flash.sh [--debug] --ota [host]  Wi-Fi: build, sign and push a Firmware Update
+#        scripts/flash.sh --ota [host]       Wi-Fi: build, sign and push a Firmware Update
-#                                                 (host: the device's IP from Settings > About, or $RORO_OTA_HOST)
+#                                            (host: the device's IP from Settings > Firmware, or $RORO_OTA_HOST)
-# --debug builds the Debug Build (cardputer-adv-debug): the Debug Console on TCP 2323, see ADR 0004.
+# --debug (USB only): once flashed, switches the Debug Console on and gives it the token in
+#   ~/.config/roro9stack/debug-token, over the serial port (ADR 0010, Q192), so scripts/rdbg.py works
+#   at once. The settings survive later updates: it is needed once for a device, not at each flash.
 set -euo pipefail
 ENV=cardputer-adv
+PROVISION=
 if [ "${1:-}" = "--debug" ]; then
-    ENV=cardputer-adv-debug
+    PROVISION=1
     shift
 fi
 
 if [ "${1:-}" = "--ota" ]; then
+    [ -z "$PROVISION" ] || echo "flash.sh: --debug does nothing over Wi-Fi: the console's setting stays as it is on the device" >&2
     ROOT="$(cd "$(dirname "$0")/.." && pwd)"
     HOST="${2:-${RORO_OTA_HOST:-}}"
     [ -n "$HOST" ] || { echo "Usage: scripts/flash.sh --ota <device IP> (or set RORO_OTA_HOST)" >&2; exit 1; }
@@ -19,7 +23,6 @@ if [ "${1:-}" = "--ota" ]; then
     DOCKER_EXTRA=()
     run_in_container bash -c "git config --global --add safe.directory /work && pio run -e $ENV" | tail -3
     VERSION="$(git -C "$ROOT" describe --tags --always --dirty)"
-    [ "$ENV" = cardputer-adv-debug ] && VERSION="$VERSION+debug"  # as scripts/version.py names it
     OUT="$ROOT/.pio/build/$ENV/roro9stack-$VERSION.ota"
     "$ROOT/scripts/make_ota.py" "$ROOT/.pio/build/$ENV/firmware.bin" "$VERSION" "$OUT"
     exec "$ROOT/scripts/ota_push.py" "$OUT" "$HOST"
@@ -30,4 +33,10 @@ source "$(dirname "$0")/_docker.sh"
 docker rm -f roro9stack-serial >/dev/null 2>&1 || true  # a serial log would hold the port
 DOCKER_EXTRA=(--device "$PORT" --group-add "$(stat -c %g "$PORT")" -it)
 
-run_in_container bash -c "git config --global --add safe.directory /work && pio run -e $ENV -t upload --upload-port $PORT && pio device monitor -p $PORT -b 115200"
+# The token is read from the environment inside the container (_docker.sh passes it), so it is on no
+# command line of the host; serial_log.py prints what the device says, not what it sends.
+SETUP=""
+# serial_log.py finds the port by its name, and follows it when the device re-enumerates after the upload.
+[ -z "$PROVISION" ] || DOCKER_EXTRA=(--group-add "$(stat -c %g "$PORT")" --privileged -v /dev:/dev -it)
+[ -z "$PROVISION" ] || SETUP='&& /pio/penv/bin/python scripts/serial_log.py 8 sleep:4 "debug token $RORO_DEBUG_TOKEN" "debug on"'
+run_in_container bash -c "git config --global --add safe.directory /work && pio run -e $ENV -t upload --upload-port $PORT $SETUP && pio device monitor -p $PORT -b 115200"

scripts/rdbg.py

@@ -1,10 +1,12 @@
 #!/usr/bin/env python3
-"""The Debug Console of a Debug Build, over Wi-Fi (TCP 2323, see ADR 0004).
+"""The Debug Console, over Wi-Fi (TCP 2323, see ADR 0010). Switch it on first: Settings > Debug Console.
 
-Usage: scripts/rdbg.py [-H host] [-b] [command ...]
+Usage: scripts/rdbg.py [-H host] [-t token] [-b] [command ...]
   no command   interactive: type commands, see every console line live; Ctrl-D or `quit` leaves
   command      runs it and prints what follows, until the console has been quiet for a moment
-  -H host      the device's IP (Settings > Firmware), default $RORO_OTA_HOST
+  -H host      the device's IP (Settings > Debug Console), default $RORO_OTA_HOST
+  -t token     the device's token (also --token), as Settings > Debug Console shows it: dashes and
+               case don't matter. Otherwise $RORO_DEBUG_TOKEN, otherwise ~/.config/roro9stack/debug-token
   -b           also print the backlog the device sends on connecting (boot messages and so on)
 
 Commands handled here as well as on the device:
@@ -14,9 +16,11 @@ Commands handled here as well as on the device:
   put <file> [card path]   copy a file to the SD card (default /updates/<name>), checked with SHA-256
   screenshot [file.png]    what the screen shows (default screen-<date>.png), at 2x
   reset                    restart at once, even if the main loop is stuck
-The token is read from ~/.config/roro9stack/debug-token (made by the first build).
+The token never crosses the network: the device sends a challenge, and this answers with its HMAC.
 """
+import gzip
 import hashlib
+import hmac
 import os
 import re
 import select
@@ -26,9 +30,53 @@ import zlib
 import socket
 import sys
 import time
+import urllib.request
 
 PORT = 2323
 TOKEN_FILE = os.path.expanduser("~/.config/roro9stack/debug-token")
+RELEASES = "https://git.twis.la/twisla/roro9stack/releases/download"
+
+
+def tidy_token(typed):
+    """As the device stores it (lib/debug/src/debug_auth.cpp): no dashes or spaces, in capitals."""
+    tidy = "".join(c for c in typed if c not in "- \t\r\n").upper()
+    return tidy.replace("O", "0").replace("I", "1").replace("L", "1")  # read as the digits they look like
+
+
+def answer_for(token, nonce):
+    """What the device expects back for a challenge: HMAC-SHA256 of the nonce, keyed by the token."""
+    return hmac.new(token.encode(), nonce, hashlib.sha256).hexdigest()
+
+
+def find_token(given):
+    token = given or os.environ.get("RORO_DEBUG_TOKEN")
+    if not token and os.path.exists(TOKEN_FILE):
+        token = open(TOKEN_FILE).read()
+    token = tidy_token(token or "")
+    if not token:
+        sys.exit("No token: pass -t <token>, set RORO_DEBUG_TOKEN, or put it in " + TOKEN_FILE +
+                 "\n(the device shows it in Settings > Debug Console)")
+    return token
+
+
+def log_in(sock, token):
+    """Answers the device's challenge; returns the banner line, or exits saying what went wrong."""
+    first = read_until(sock, b"\n", 10)
+    if first is None:
+        sys.exit("device: nothing came back. Is the console switched on (Settings > Debug Console)?")
+    line = first.decode(errors="replace").strip()
+    if line.startswith("locked"):
+        sys.exit("device: closed for a minute after too many wrong tokens")
+    challenge = re.search(r"challenge ([0-9a-f]{32})$", line)
+    if not challenge:
+        sys.exit("device: no challenge (an older firmware?): " + line[:60])
+    sock.sendall((answer_for(token, bytes.fromhex(challenge.group(1))) + "\n").encode())
+    banner = read_until(sock, b"\n", 15)
+    if banner is None:
+        sys.exit("device: no answer")
+    if banner.startswith(b"denied"):
+        sys.exit("device: wrong token (Settings > Debug Console shows the right one)")
+    return banner
 
 
 def read_until(sock, marker, timeout):
@@ -102,17 +150,40 @@ def crash_firmware(reply):
     return version.group(1) if version else None
 
 
+def have_elf(reply):
+    """Makes sure .pio/elves/ holds the ELF of the firmware that crashed: a release's is on Gitea."""
+    folder = os.path.join(os.path.dirname(SCRIPTS), ".pio", "elves")
+    key = crash_firmware(reply)
+    version = re.search(r"last one in (\S+)", reply)
+    version = version.group(1) if version else None
+    names = os.listdir(folder) if os.path.isdir(folder) else []
+    if not key or any(key in n for n in names) or not version or not re.fullmatch(r"v\d+\.\d+\.\d+", version):
+        return  # there already, or not a release: only tags are published
+    url = f"{RELEASES}/{version}/roro9stack-{version}.elf.gz"
+    try:
+        elf = gzip.decompress(urllib.request.urlopen(url, timeout=60).read())
+    except Exception as e:
+        return print(f"(no ELF for {version} here, and none fetched from {url}: {e})")
+    digest = hashlib.sha256(elf).hexdigest()[:16]
+    os.makedirs(folder, exist_ok=True)
+    path = os.path.join(folder, f"{version}.{digest}.elf")  # as scripts/version.py names them
+    open(path, "wb").write(elf)
+    print(f"(fetched the ELF of {version} from its release: {os.path.relpath(path)})")
+
+
 def crash(sock):
     reply = run(sock, "crash")
     trace = re.search(r"backtrace((?: 0x[0-9a-f]+)+)", reply)
     key = crash_firmware(reply)
     if trace and key:
+        have_elf(reply)
         print()
         subprocess.call([os.path.join(SCRIPTS, "decode_backtrace.sh"), key] + trace.group(1).split())
 
 
 def coredump(sock, path):
     info = run(sock, "crash", out=None)
+    have_elf(info)
     sock.sendall(b"coredump get\n")
     # One buffer throughout: the header, the size and the first bytes often share a packet.
     buf = b""
@@ -237,25 +308,27 @@ def interactive(sock):
 
 def main():
     args = sys.argv[1:]
-    host, backlog = os.environ.get("RORO_OTA_HOST"), False
+    host, backlog, token = os.environ.get("RORO_OTA_HOST"), False, None
     while args and args[0].startswith("-"):
         flag = args.pop(0)
         if flag == "-H" and args:
             host = args.pop(0)
+        elif flag in ("-t", "--token") and args:
+            token = args.pop(0)
         elif flag == "-b":
             backlog = True
         else:
             sys.exit(__doc__)
     if not host:
         sys.exit("No device: pass -H <ip> or set RORO_OTA_HOST\n\n" + __doc__)
-    token = open(TOKEN_FILE).read().strip()
+    token = find_token(token)
 
-    with socket.create_connection((host, PORT), timeout=10) as sock:
+    try:
-        sock.sendall((token + "\n").encode())
+        sock = socket.create_connection((host, PORT), timeout=10)
-        # The device may still be finishing a previous client: wait for this connection's banner.
+    except OSError as e:
-        banner = read_until(sock, b"Backlog follows.\n", 15)
+        sys.exit(f"device: can't connect to {host}:{PORT} ({e}). Is the console switched on (Settings > Debug Console)?")
-        if banner is None:
+    with sock:
-            sys.exit("device: no banner (wrong token, or another client is connected)")
+        banner = log_in(sock, token)
         show = sys.stdout if backlog or not args else None
         if show:
             show.write(banner.decode(errors="replace"))

scripts/version.py

@@ -10,9 +10,6 @@ try:
 except Exception:
     version = "unknown"
 
-if env["PIOENV"].endswith("-debug"):  # noqa: F821
-    version += "+debug"  # a Debug Build says so wherever the version shows
-
 env.Append(CPPDEFINES=[("RORO_VERSION", '\\"%s\\"' % version)])  # noqa: F821
 
 

site/content/dev/_index.md

@@ -0,0 +1,13 @@
++++
+title = "Developer docs"
+description = "How roro9stack is built, debugged, tested and released: the Debug Console, the build, the decisions and the plans, from the repository's own documents."
+template = "dev-index.html"
+sort_by = "weight"
+
+[extra]
+eyebrow = "Developer docs"
++++
+
+The firmware is open source (GPL-3.0) and lives on [Gitea](https://git.twis.la/twisla/roro9stack). It is built for one device, the M5Stack Cardputer ADV with the Cap LoRa-1262, and it is built to be **worked on without touching the device**: install a build over Wi-Fi, read its console, press its keys, take screenshots of it, copy files to and from its SD card, and fetch its crash dumps, all from a PC on the same network. The first section is about exactly that.
+
+Some of these pages are written by hand. The rest are **generated from the repository's own documents** (the decisions, the milestone plans, the README and the firmware's own `help` text), so they are never out of date: each says which file it comes from.

site/content/dev/build/_index.md

@@ -0,0 +1,13 @@
++++
+title = "Build, test and release"
+description = "Building the firmware, running the tests, flashing a device, and what happens between a commit and a release."
+template = "guide-index.html"
+page_template = "guide-page.html"
+sort_by = "weight"
+weight = 2
+
+[extra]
+eyebrow = "Developer docs"
++++
+
+The firmware is built, tested and released **in Docker**, so that a clean machine, your machine and the CI runner all get the same result. These pages say how. For the Debug Console, which is how you work on a device once it is flashed, see [The Debug Console](/dev/debug/).

site/content/dev/build/build-and-test.md

@@ -0,0 +1,38 @@
++++
+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)
+
+```sh
+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.

site/content/dev/build/flash.md

@@ -0,0 +1,57 @@
++++
+title = "Flash and update"
+description = "Put the firmware on a Cardputer over USB, then update it over Wi-Fi or from the SD card, and from the project's releases."
+weight = 2
+
+[extra]
+docs = true
+source = "README.md"
+tag = "Flash"
++++
+## Flash
+
+1. Connect the Cardputer by USB-C.
+2. Run:
+
+   ```sh
+   scripts/flash.sh            # auto-detects the port; or: scripts/flash.sh /dev/ttyACM1
+   ```
+
+   This uploads the firmware, then opens the serial monitor. Quit the monitor with `Ctrl+C`.
+
+**If the upload can't connect,** put the device in download mode: hold **G0** (the button next to the screen) while plugging in USB, or while pressing reset. Then retry.
+
+**If you get "permission denied" on the port,** your user needs access to the serial device. Run this once, then log out and back in:
+
+```sh
+sudo usermod -aG dialout "$USER"
+```
+
+## Firmware Updates over Wi-Fi (OTA)
+
+Once the Cardputer runs an OTA-capable firmware (flashed once over USB), updates can go over Wi-Fi:
+
+```sh
+scripts/ota_keygen.sh                  # once: creates the signing key (see ADR 0003)
+scripts/flash.sh --ota 10.39.39.12     # build, sign and push; or set RORO_OTA_HOST
+```
+
+The device shows the push address in **Settings → Firmware**. It installs a correctly signed update right away, restarts (waiting up to 60 s if you're typing), and runs the new firmware on **Probation**. If the new firmware crashes, or can't reconnect Wi-Fi within 3 minutes, it rolls back to the previous one and says so.
+
+To install from the SD card instead, copy the `.ota` file from `.pio/build/cardputer-adv/` into `/updates` on the card, then use **Settings → Firmware**. With the Cardputer on USB, the card can stay in: `scripts/sd_put.sh <file.ota>` sends it over the serial console into `/updates` (about 30 s for 1.6 MB, checked with SHA-256 before it's renamed into place; `SD_PUT_DEBUG=1` shows the console while it runs).
+
+**The private key** lives in `~/.config/roro9stack/ota-key.pem` and must never be committed. If it's lost, generate a new pair and flash once over USB. (CI signs releases with a copy kept as a repository secret, ADR 0008.)
+
+### Updates from Gitea
+
+With no PC and no card, the device can install the project's releases itself (docs/milestones/R1.md). In **Settings → Firmware**:
+
+- **Latest release** checks the server (Enter, or `c`) and says `v0.11.0 (new)` or `(current)`. Enter again opens the release: its version, date, size and the tag's message, with **Install** when it's newer. The download goes straight into the inactive slot, so no card is needed; the signature is checked after the first 160 bytes, before anything is written, and the image's hash at the end. The new firmware then runs on Probation as for any update.
+- **Older releases** lists the last ten, newest first. Opening an older one offers to go back to it, with a different question.
+- **Settings → Check for updates** (on by default): once a day, with Wi-Fi up and the clock set, the device looks at the latest release and says `v0.11.0 is out: see Settings > Firmware`, once per version. It installs nothing by itself, and doesn't announce a version that already failed and rolled back on this device.
+
+The connection is checked against the two ISRG roots Let's Encrypt chains end in (ADR 0009), not the usual bundle of about 130 authorities. Whatever the connection, the Update File's own signature is what decides what gets installed.
+
+**IRC steps aside.** A secure connection takes about 52 KB of memory at its peak, and IRC's own takes 40 KB of the 107 KB there is. A check or an install you ask for makes IRC disconnect for the few seconds it takes and reconnect afterwards. The daily check never does that: with IRC connected it waits for a moment when IRC isn't, so while IRC stays connected for days it doesn't run, and **Latest release** is the way to check.
+
+**There is no separate Debug Build** any more (ADR 0010): every firmware installs releases, and the Debug Console is a setting, which an update leaves as it was.

site/content/dev/build/how-an-update-works/index.md

@@ -0,0 +1,63 @@
++++
+title = "How an update works"
+description = "The signed Update File, the four ways to get one onto a device, Probation and Rollback, and the check that sits in front of all of them."
+weight = 3
+[extra]
+tag = "Updates"
+diagrams = true
++++
+
+A **Firmware Update** installs one signed file, an **Update File** (`.ota`). Every way of delivering it ends at the same gate, and a new firmware must prove itself before it is kept. The decisions are [ADR 0003](/dev/decisions/0003-own-signature-check-not-secure-boot/) (the signature), [ADR 0005](/dev/decisions/0005-safe-mode-crash-reports-watchdog/) (when the new firmware crashes) and [ADR 0008](/dev/decisions/0008-ci-signs-releases/) (who signs releases).
+
+## The Update File
+
+{{ diagram(src="update-file.svg", min_width=580, caption="A 160-byte header, then the image. Bytes 0 to 79 are signed.") }}
+
+- A **160-byte header**: the magic `RORO-OTA`, the format, the header size, the image size, the image's **SHA-256** and the version (bytes 0 to 79, the signed part), then the signature's length, the **signature** and reserved bytes.
+- The signature is **ECDSA P-256 over the SHA-256 of bytes 0 to 79**, checked by the firmware against a **public key compiled into it** (`keys/ota-public.pem`, committed), **before anything is written**.
+- Then the **image**, hashed while it is written; at the end the hash must equal the one in the header.
+
+Make, check and push one:
+
+```sh
+scripts/ota_keygen.sh                                  # once: creates the key pair. The private key goes to ~/.config/roro9stack/ota-key.pem (never committed); the public key to keys/ and the firmware source
+scripts/make_ota.py firmware.bin v0.12.0 out.ota       # wraps and signs an image (the key: $RORO_OTA_KEY or the default path)
+scripts/ota_verify.py out.ota                          # checks a file the way a device does, on the PC
+scripts/ota_push.py out.ota 10.39.39.12                # pushes it to the Update Service, TCP 3232
+scripts/flash.sh --ota 10.39.39.12                     # builds, signs and pushes in one go
+```
+
+`ota_push.py` prints the device's answer (`OK …`), or says the device **refused the update and hung up**, with the reason on the device's screen: the header is checked first, so a refused file stops mid-transfer.
+
+## Four ways in, one gate
+
+{{ diagram(src="ways-in.svg", min_width=580, caption="Every path ends at the same Update Service and the same signature check.") }}
+
+1. **Push over Wi-Fi** to TCP 3232: `scripts/flash.sh --ota`. The device always listens while Wi-Fi is connected.
+2. **From the SD card**: a `.ota` in `/updates`, installed from Settings → Firmware, from the Storage App, or with the `install <path>` command. Put it there by hand, with `scripts/rdbg.py put` over Wi-Fi, or with `scripts/sd_put.sh` over USB.
+3. **From the project's releases** on Gitea, which the device downloads itself over TLS (Settings → Firmware, or `update check` / `update install <tag>`): see [Flash and update](/dev/build/flash/).
+
+All three feed the same parser: the **header and signature are checked first**, the image is written to the **other app slot** while it is hashed, and the slot becomes the next boot **only if the hash matches**. Anything wrong ends in a Toast and **nothing changes**. A downgrade is allowed, and shows "older than the installed version".
+
+The device then restarts (waiting up to 60 seconds if you are typing) into **Probation**.
+
+## Probation and Rollback
+
+{{ diagram(src="probation.svg", min_width=620, caption="The life of an update: install, restart, Probation, confirmed. A crash or a restart before the last step sends the device back to the previous firmware.") }}
+
+A new image is **not trusted** at first:
+
+1. **Install:** the image goes to the other slot and the OTA data marks it *new*.
+2. **Restart:** the bootloader turns *new* into *pending verify* and boots it.
+3. **Probation:** the new firmware must boot, draw its UI, start its Services, run **30 seconds without a crash**, and **reconnect Wi-Fi within 3 minutes** if one is configured.
+4. **Confirmed:** it marks itself valid and a Toast says `Updated`.
+
+If it crashes or restarts first, the bootloader marks the image *aborted* and boots the **previous firmware** again, which says the update failed. Meanwhile that previous firmware stayed in its slot: it is the way back.
+
+**Two lines of defence.** The bootloader's rollback is the first. The firmware counts its own boots on Probation, very first thing in `setup()`, and reverts itself on the second unconfirmed start, as a second line. And Arduino-ESP32 normally marks an image valid *before* `setup()` runs, which once hid the bootloader's rollback entirely; the firmware overrides `verifyRollbackLater()` so an image stays pending until Probation confirms it.
+
+## Who signs releases
+
+A tag `v*` is built, signed and published by Gitea Actions, with the signing key held as a repository secret as well as on the maintainer's machine ([ADR 0008](/dev/decisions/0008-ci-signs-releases/) says what that costs and what limits it). The release step checks the signed file against the public key in the sources it built, so a wrong secret stops the release instead of publishing a file no device accepts.
+
+**If the private key is ever lost,** the next update has to go over USB, carrying a new public key. Someone with USB access can always flash anything: only Wi-Fi and SD card updates are guarded, by design (ADR 0003).

site/content/dev/build/how-an-update-works/probation.svg

@@ -0,0 +1,55 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 316" role="img" aria-label="The life of an update. One: install, the image goes to app1 and the OTA data marks it NEW. Two: restart, the bootloader turns NEW into PENDING_VERIFY and boots app1. Three: Probation, 30 seconds up, a frame drawn, and Wi-Fi within 3 minutes if it is configured. Four: confirmed, the firmware marks itself VALID and a Toast says Updated. If it crashes or restarts before step four, the bootloader turns PENDING_VERIFY into ABORTED and boots app0 again, which says the update failed. Meanwhile app0 kept the previous firmware: the way back. The trap, under step two: Arduino's initArduino marks the image VALID before setup runs, unless verifyRollbackLater returns true.">
+  <defs>
+    <marker id="pb-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="currentColor"/></marker>
+    <marker id="pb-arrow-ok" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path class="f-green" d="M0,0 L10,5 L0,10 z"/></marker>
+    <marker id="pb-arrow-bad" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path class="f-red" d="M0,0 L10,5 L0,10 z"/></marker>
+  </defs>
+  <g font-family="JetBrains Mono, ui-monospace, monospace" fill="currentColor">
+    <rect class="pb-box" x="16" y="40" width="170" height="80" rx="6"/>
+    <text x="28" y="62" font-size="12" font-weight="600">1 install</text>
+    <text x="28" y="84" font-size="11">image → app1</text>
+    <text x="28" y="102" font-size="11" class="pb-dim">otadata: NEW</text>
+
+    <rect class="pb-box" x="206" y="40" width="170" height="80" rx="6"/>
+    <text x="218" y="62" font-size="12" font-weight="600">2 restart</text>
+    <text x="218" y="84" font-size="11">bootloader:</text>
+    <text x="218" y="102" font-size="11" class="pb-dim">NEW → PENDING_VERIFY</text>
+
+    <rect class="pb-hot" x="396" y="40" width="170" height="80" rx="6"/>
+    <text x="408" y="62" font-size="12" font-weight="600">3 Probation</text>
+    <text x="408" y="84" font-size="11">30 s up, a frame</text>
+    <text x="408" y="102" font-size="11" class="pb-dim">Wi-Fi within 3 min</text>
+
+    <rect class="pb-ok" x="586" y="40" width="158" height="80" rx="6"/>
+    <text x="598" y="62" font-size="12" font-weight="600">4 confirmed</text>
+    <text x="598" y="84" font-size="11">→ VALID</text>
+    <text x="598" y="102" font-size="11" class="pb-dim">Toast: Updated to…</text>
+
+    <path class="pb-line" d="M186 80 H202" marker-end="url(#pb-arrow)"/>
+    <path class="pb-line" d="M376 80 H392" marker-end="url(#pb-arrow)"/>
+    <path class="pb-line-ok" d="M566 80 H582" marker-end="url(#pb-arrow-ok)"/>
+
+    <rect class="pb-bad" x="396" y="196" width="348" height="76" rx="6"/>
+    <text x="408" y="218" font-size="12" font-weight="600">crash or restart before 4</text>
+    <text x="408" y="240" font-size="11">bootloader: PENDING_VERIFY → ABORTED</text>
+    <text x="408" y="258" font-size="11" class="pb-dim">boots app0: "Update to … failed"</text>
+    <path class="pb-line-bad" d="M481 120 V192" marker-end="url(#pb-arrow-bad)"/>
+    <text x="408" y="294" font-size="10" class="pb-dim">(second line: bootGuard() in setup() rolls back</text>
+    <text x="408" y="308" font-size="10" class="pb-dim"> a second unconfirmed start by itself)</text>
+
+    <text x="16" y="216" font-size="11" class="pb-dim">app0 keeps the</text>
+    <text x="16" y="232" font-size="11" class="pb-dim">previous firmware:</text>
+    <text x="16" y="248" font-size="11" class="pb-dim">the way back</text>
+
+    <rect class="pb-trap" x="206" y="176" width="170" height="122" rx="6"/>
+    <text class="f-red" x="218" y="198" font-size="12" font-weight="600">the trap</text>
+    <text x="218" y="220" font-size="11">initArduino()</text>
+    <text x="218" y="238" font-size="11">marks it VALID</text>
+    <text x="218" y="256" font-size="11">before setup(),</text>
+    <text x="218" y="274" font-size="11" class="pb-dim">unless verify-</text>
+    <text x="218" y="290" font-size="11" class="pb-dim">RollbackLater()</text>
+    <path class="pb-line-bad" d="M291 176 V124" marker-end="url(#pb-arrow-bad)"/>
+
+    <text x="16" y="22" font-size="13" font-weight="600">The life of an update</text>
+  </g>
+</svg>

site/content/dev/build/how-an-update-works/update-file.svg

@@ -0,0 +1,43 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 196" role="img" aria-label="The Update File: a 160-byte header, then the firmware image. Bytes 0 to 79 are signed: the magic RORO-OTA, the format, the header size, the image size, the image's SHA-256 and the version. Then the signature's length, the signature itself, and reserved bytes up to 160. The signature is ECDSA P-256 over the SHA-256 of bytes 0 to 79, checked before anything is written. The image follows, hashed while it is written, and must match the hash in bytes 16 to 47.">
+  <g font-family="JetBrains Mono, ui-monospace, monospace" fill="currentColor">
+    <text x="16" y="22" font-size="13" font-weight="600">Update File (.ota)</text>
+    <text x="16" y="40" font-size="11" class="uf-dim">a 160-byte header, little-endian, then the image</text>
+
+    <rect class="uf-signed" x="16" y="72" width="380" height="40" rx="4"/>
+    <rect class="uf-cell" x="16" y="72" width="64" height="40"/>
+    <rect class="uf-cell" x="80" y="72" width="40" height="40"/>
+    <rect class="uf-cell" x="120" y="72" width="40" height="40"/>
+    <rect class="uf-cell" x="160" y="72" width="52" height="40"/>
+    <rect class="uf-cell" x="212" y="72" width="100" height="40"/>
+    <rect class="uf-cell" x="312" y="72" width="84" height="40"/>
+    <rect class="uf-cell" x="396" y="72" width="40" height="40"/>
+    <rect class="uf-cell" x="436" y="72" width="92" height="40"/>
+    <rect class="uf-cell" x="528" y="72" width="32" height="40"/>
+    <rect class="uf-image" x="560" y="72" width="184" height="40"/>
+
+    <g font-size="10" text-anchor="middle">
+      <text x="48" y="96">RORO-OTA</text>
+      <text x="100" y="96">fmt</text>
+      <text x="140" y="96">hdr</text>
+      <text x="186" y="96">size</text>
+      <text x="262" y="96">image SHA-256</text>
+      <text x="354" y="96">version</text>
+      <text x="416" y="96">len</text>
+      <text x="482" y="96">signature</text>
+      <text x="544" y="96">0…</text>
+      <text x="652" y="96">the image, ~1.6 MB</text>
+    </g>
+    <g font-size="10" class="uf-dim" text-anchor="middle">
+      <text x="16" y="64">0</text><text x="80" y="64">8</text><text x="120" y="64">10</text><text x="160" y="64">12</text>
+      <text x="212" y="64">16</text><text x="312" y="64">48</text><text x="396" y="64">80</text><text x="436" y="64">82</text>
+      <text x="528" y="64">154</text><text x="560" y="64">160</text>
+    </g>
+
+    <path d="M16 120 V128 H396 V120" fill="none" stroke="var(--accent)" stroke-width="1.5"/>
+    <text x="206" y="150" font-size="11" text-anchor="middle" class="uf-hot">signed: ECDSA P-256 over SHA-256(bytes 0–79)</text>
+    <text x="206" y="168" font-size="11" text-anchor="middle" class="uf-dim">checked before a single byte is written</text>
+    <path d="M560 120 V128 H744 V120" fill="none" stroke="currentColor" stroke-opacity=".5" stroke-width="1.5"/>
+    <text x="652" y="150" font-size="11" text-anchor="middle" class="uf-dim">hashed while it's written;</text>
+    <text x="652" y="168" font-size="11" text-anchor="middle" class="uf-dim">must match bytes 16–47</text>
+  </g>
+</svg>

site/content/dev/build/how-an-update-works/ways-in.svg

@@ -0,0 +1,53 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 352" role="img" aria-label="Four ways in, one gate. scripts/flash.sh --ota signs the firmware and pushes it over Wi-Fi to TCP port 3232, straight to the Update Service. rdbg.py put over Wi-Fi, sd_put.sh over USB serial, or the card by hand all put an Update File in /updates on the SD card, where Settings, Firmware, or the install command picks it up. The Update Service checks the header and signature first, writes the image to the other app slot while hashing it, and makes it the next boot only if the hash matches. Then it restarts into Probation. If anything is wrong, a Toast says so and nothing changes.">
+  <defs>
+    <marker id="wi-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="currentColor"/></marker>
+    <marker id="wi-arrow-hot" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path class="f-accent" d="M0,0 L10,5 L0,10 z"/></marker>
+    <marker id="wi-arrow-bad" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path class="f-red" d="M0,0 L10,5 L0,10 z"/></marker>
+  </defs>
+  <g font-family="JetBrains Mono, ui-monospace, monospace" fill="currentColor">
+    <rect class="wi-box" x="16" y="32" width="220" height="56" rx="6"/>
+    <text x="30" y="55" font-size="12" font-weight="600">flash.sh --ota</text>
+    <text x="30" y="75" font-size="11" class="wi-dim">builds, signs, pushes</text>
+    <rect class="wi-box" x="16" y="112" width="220" height="56" rx="6"/>
+    <text x="30" y="135" font-size="12" font-weight="600">rdbg.py put</text>
+    <text x="30" y="155" font-size="11" class="wi-dim">Debug Console, Wi-Fi 2323</text>
+    <rect class="wi-box" x="16" y="192" width="220" height="56" rx="6"/>
+    <text x="30" y="215" font-size="12" font-weight="600">sd_put.sh</text>
+    <text x="30" y="235" font-size="11" class="wi-dim">USB serial, card stays in</text>
+    <rect class="wi-box" x="16" y="272" width="220" height="56" rx="6" stroke-dasharray="4 3"/>
+    <text x="30" y="295" font-size="12" font-weight="600">the card, by hand</text>
+    <text x="30" y="315" font-size="11" class="wi-dim">the 1990s way</text>
+
+    <rect class="wi-panel" x="288" y="176" width="200" height="88" rx="8"/>
+    <text x="302" y="200" font-size="12" font-weight="600">SD card</text>
+    <text x="302" y="219" font-size="11">/updates/*.ota</text>
+    <text x="302" y="238" font-size="11" class="wi-dim">Settings → Firmware,</text>
+    <text x="302" y="254" font-size="11" class="wi-dim">or install &lt;path&gt;</text>
+
+    <rect class="wi-hot" x="536" y="32" width="208" height="158" rx="8"/>
+    <text x="550" y="56" font-size="12" font-weight="600">Update Service</text>
+    <text x="550" y="80" font-size="11">1 header, signature:</text>
+    <text x="550" y="96" font-size="11" class="wi-dim">  checked first</text>
+    <text x="550" y="118" font-size="11">2 image → other slot,</text>
+    <text x="550" y="134" font-size="11" class="wi-dim">  hashed on the way</text>
+    <text x="550" y="156" font-size="11">3 hash matches:</text>
+    <text x="550" y="172" font-size="11" class="wi-dim">  boot it next</text>
+
+    <rect class="wi-box" x="576" y="216" width="168" height="44" rx="6"/>
+    <text x="660" y="243" font-size="12" text-anchor="middle">restart → Probation</text>
+    <rect class="wi-bad" x="536" y="280" width="208" height="56" rx="6"/>
+    <text x="550" y="303" font-size="11">anything wrong: a Toast,</text>
+    <text x="550" y="321" font-size="11">and nothing changes</text>
+
+    <path class="wi-line-hot" d="M236 60 H532" marker-end="url(#wi-arrow-hot)"/>
+    <text class="f-accent" x="300" y="52" font-size="11">Wi-Fi · TCP 3232</text>
+    <path class="wi-line" d="M236 140 H262 V198 H284" marker-end="url(#wi-arrow)"/>
+    <path class="wi-line" d="M236 220 H284" marker-end="url(#wi-arrow)"/>
+    <path class="wi-line" d="M236 300 H262 V242 H284" marker-end="url(#wi-arrow)"/>
+    <path class="wi-line" d="M488 220 H512 V150 H532" marker-end="url(#wi-arrow)"/>
+    <text x="492" y="238" font-size="10" class="wi-dim">storage</text>
+    <text x="492" y="250" font-size="10" class="wi-dim">task</text>
+    <path class="wi-line" d="M660 190 V212" marker-end="url(#wi-arrow)"/>
+    <path class="wi-line-bad" d="M556 190 V276" marker-end="url(#wi-arrow-bad)"/>
+  </g>
+</svg>

site/content/dev/debug/_index.md

@@ -0,0 +1,22 @@
++++
+title = "The Debug Console"
+description = "A firmware you can drive from your desk: its console over Wi-Fi, its screen as a PNG, its SD card, its crash dumps, and a way back when an update goes wrong."
+template = "guide-index.html"
+page_template = "guide-page.html"
+sort_by = "weight"
+weight = 1
+
+[extra]
+eyebrow = "Developer docs"
++++
+
+The **Debug Console** is the serial console, over Wi-Fi, for whoever holds the device's token. It is in **every firmware**, switched off until you switch it on, and it is the most useful thing in the project. With it you can:
+
+- **see everything the device prints**, boot messages included, without a cable;
+- **run every serial command** from your desk;
+- **press keys** and **take screenshots**, so a UI change can be tested and looked at remotely;
+- **copy files** to and from the SD card;
+- **read crash reports and fetch core dumps**, decoded against the exact build that crashed;
+- **update the firmware** over the same Wi-Fi, and know that a bad update rolls back by itself.
+
+Start with [Switch the console on](/dev/debug/switch-it-on/), then [the Debug Console](/dev/debug/console/). The rest are what you can do with it.

site/content/dev/debug/commands.md

@@ -0,0 +1,112 @@
++++
+title = "Command reference"
+description = "Every command the firmware understands, over USB serial or the Debug Console: what `help` prints, then what each one does."
+weight = 30
+
+[extra]
+docs = true
+source = "src/main.cpp and README.md"
+tag = "Reference"
++++
+## What `help` prints
+
+The firmware's own list, read from `src/main.cpp`. Every firmware has all of them, over USB serial and over the Debug Console. The ones marked *Debug Console only* exist only over Wi-Fi, where [`rdbg.py`](/dev/debug/files-and-screens/) speaks them, and the ones marked *USB serial only* only over the cable:
+
+```
+info              firmware, uptime, memory, Wi-Fi, app slots
+tasks             FreeRTOS tasks over the next second: state, priority, free stack, CPU share
+net               bytes each network service has read and written since boot
+reboot            restart
+boot other        restart into the other app slot (manual Rollback)
+log level <0-5>   ESP-IDF log level (0 none ... 5 verbose)
+ls [folder] | du <path> | mkdir <path> | rm <path> | cp [-f] <from> <to> | mv [-f] <from> <to> | cancel   the SD card, with the Storage App's rules
+lora probe | lora status | lora rx on|off | lora preset <name>   the LoRa radio, receive only
+lora capture start|stop   a LoRa Capture to /captures/lora (pcap, LoRaTap)
+lora sweep on [from MHz] [to MHz] [step kHz] | off | dump   RSSI across a band (863 870 100)
+lora custom <MHz> <BW kHz> <SF> <CR 5-8> <sync hex> [preamble]   e.g. 868.1 125 7 5 34 8 (LoRaWAN)
+gnss quiet on|off   pause the GNSS receiver while the LoRa radio listens (it costs the radio 8 dB)
+gnss status | gnss restart | gnss track start|stop | gnss nmea on|off | gnss send <sentence without $ and checksum>
+crash             the last crash: firmware, reason, task, backtrace
+coredump erase    forget the core dump in flash
+key <name|char>   press a key: up down left right select back home del tab space, or one character
+wifi status | wifi add <ssid><TAB><password>
+wifi ip <ssid> dhcp | wifi ip <ssid> <address>/<prefix> [gateway]   a Saved Network's IP setting
+wifi dns <a> [b] | wifi dns always on|off | wifi ntp <a> [b]   DNS and NTP servers
+gemini get <url>  fetch a Gemini page and report header, size, certificate, heap
+irc start | irc stop | irc dump | irc say <buffer> <text>
+install <path.ota>   Update from SD
+update check | list | status | install <tag>   the project's releases on Gitea
+sd card | sd list | cat <path> | log <text> | burst | sound on|off | short | normal
+debug status | debug off [seconds]   the Debug Console over Wi-Fi (Settings > Debug Console); with seconds, it comes back
+debug on | debug token <16 to 64 characters> | debug token new   (USB serial only) switch it on, set its token
+crash abort|wdt   crash on purpose (to test crash reports and Safe Mode)
+wifi ip ... try <seconds> | wifi ip keep   a trial IP setting: back to the previous one unless kept
+loop spin on|off  make the main loop spin without resting, to compare load and radio noise
+lora noise test [gnss|quiet] | lora noise report   Sweep under one changed condition at a time (Wi-Fi goes off for a moment)
+lora inject <hex> [rssi] [snr]   a packet into the LoRa Scanner as if received (nothing is sent)
+sd fill <folder> <count>   makes that many small files there, to test a crowded folder
+coredump get      (Debug Console only) send the raw core dump: use scripts/rdbg.py coredump
+reset             (Debug Console only) restart at once, even if the main loop is stuck
+get <path> | put <path> <size> <sha256> | screenshot   (Debug Console only) binary, see rdbg.py
+quit              close the Debug Console connection
+```
+
+In **Safe Mode** (see [Crashes and Safe Mode](/dev/debug/crashes/)) only a few run: `help`, `info`, `tasks`, `net`, `reboot`, `boot other`, `wifi status`, and anything starting with `log level`, `crash`, `coredump`, `wifi add`, `debug`. Anything else answers `not available in Safe Mode`.
+
+## What they do
+
+`scripts/serial_log.sh [seconds] [command…]` records the serial output, and can send commands to the firmware first. For example, `scripts/serial_log.sh 30 short sleep:12 burst` sets short screen timeouts, waits 12 s, then sends a burst of Toasts.
+
+| Command | Effect |
+|---|---|
+| `burst` | Publishes 5 Notifications at once |
+| `key up\|down\|left\|right\|select\|back\|home`, or `key <char>` | Injects a key press |
+| `sound on` / `sound off` | Toggles the Sound setting (beep + LED) |
+| `short` / `normal` | Screen timeouts 5 s / 10 s, or 30 s / 60 s |
+| `wifi add <ssid><TAB><password>` | Adds a Saved Network (so credentials stay out of the repo) |
+| `wifi ip <ssid> dhcp` / `wifi ip <ssid> <address>/<prefix> [gateway]` | A Saved Network's IP setting: Automatic, or Fixed. Add `try <seconds>` to go back to the previous setting unless `wifi ip keep` follows |
+| `wifi dns <a> [b]` / `wifi dns always on\|off` / `wifi ntp <a> [b]` | DNS servers (used on Fixed networks, or always), and NTP servers |
+| `log <text>` | Appends a line to a test IRC Log (`/irc/dev/#test/<date>.log`) |
+| `sd card` | What the SD card says it is: type, size, and its identity register (maker, name, revision, serial, date) |
+| `sd list` | Lists the files of each Storage Clean-up category |
+| `sd fill <folder> <count>` | Makes that many small files in a folder, to test a crowded one |
+| `cat <path>` | Prints the first ~1.2 KB of a file on the SD card |
+| `irc start` | Starts the IRC Service (normally done by opening the IRC App) |
+| `irc stop` | Stops it, as `/quit` does: QUIT if connected, no more retries, and the App stays disconnected until you type |
+| `gemini get <url>` | Fetches a Gemini page and prints its header, size, certificate fingerprint and heap use |
+| `gemini trust <host> <port> <sha256>` | Pins a certificate by hand (the Gemini App asks when one changes) |
+| `irc say <buffer> <text>` | Types into a Buffer, commands included (`irc say 0 /join #test`) |
+| `irc dump` | Prints IRC status, memory, and the last lines of each Buffer |
+| `wifi status` | Prints Wi-Fi state, network, signal, clock and free heap, then the address, gateway, DNS and NTP servers in use and where each came from |
+| `info` | Firmware, uptime, last start reason, memory, Wi-Fi, the SD card and its write faults since boot, and both app slots with their versions and OTA states |
+| `tasks` | FreeRTOS tasks over the next second: state, priority, lowest free stack, share of a core, each core's load, and how many passes the main loop made |
+| `net` | Bytes each network service has read and written since boot |
+| `reboot` / `boot other` | Restart, or restart into the other app slot (a manual Rollback) |
+| `log level <0-5>` | ESP-IDF log level |
+| `ls [folder]` / `du <path>` | Lists a folder of the SD card with sizes and dates, or counts the files and bytes under a path |
+| `cp [-f] <from> <to>` / `mv [-f] <from> <to>` / `rm <path>` / `mkdir <path>` / `cancel` | What the Storage App does, with its rules: copy (folders too), move or rename, delete (a folder with what's in it), new folder. `-f` replaces a file that's in the way; a tab separates paths that hold spaces; `cancel` stops a copy or a delete |
+| `install <path>` | Update from SD with that `.ota` file, as Settings → Firmware does |
+| `update check` / `update list` / `update status` / `update install <tag>` | The project's releases on Gitea: look at the latest, list the last ten, say what's known, or download and install one |
+| `update pretend <version>` / `update probe <host>` / `update damage cut\|flip <n>` / `update daily` | Pretend to run another version (so a release counts as an update), see whether a server's certificate is accepted, cut or damage the next download, run the daily check again |
+| `lora probe` | Finds the radio: chip, oscillator, antenna switch, DIO1 interrupt, noise floor |
+| `lora status` | Radio settings, who's listening, packet and error counters, noise floor, task stack |
+| `lora rx on` / `lora rx off` | Listens and prints each packet on the console |
+| `lora preset <name>` / `lora custom <MHz> <BW kHz> <SF> <CR> <sync hex> [preamble]` | Receive settings: a Meshtastic preset, or anything else (`lora custom 868.1 125 7 5 34 8` for LoRaWAN) |
+| `lora capture start` / `lora capture stop` | A LoRa Capture, as `c` in the App |
+| `lora sweep on [from MHz] [to MHz] [step kHz]` / `lora sweep off` / `lora sweep dump` | Sweep a band (863 870 100 by default), with a summary every 2 s (floor, strongest, peaks), or print the latest pass |
+| `gnss quiet on` / `gnss quiet off` | The "Pause GNSS for LoRa" setting |
+| `gnss status` / `gnss restart` | The receiver's state, and a restart of it |
+| `gnss track start` / `gnss track stop` | A Track, as `r` in the GNSS App (the reason is printed if it can't start) |
+| `gnss nmea on` / `gnss nmea off` | Prints each NMEA sentence the receiver sends, as `nmea: …` |
+| `gnss send <sentence>` | Sends a sentence to the receiver, without the `$` and the checksum (it adds them) |
+| `lora noise test [gnss\|quiet]` / `lora noise report` | Sweep under one changed condition at a time to find what raises the noise floor (Wi-Fi goes off for a few seconds); then the result |
+| `lora inject <hex> [rssi] [snr]` | A packet into the Scanner as if received (nothing is sent) |
+| `crash` | The last crash: which firmware, why, task, PC and backtrace (from the core dump in flash) |
+| `coredump erase` | Forgets the core dump |
+| `loop spin on` / `loop spin off` | Make the main loop spin without resting, to compare load and radio noise |
+| `crash abort` / `crash wdt` | Crash on purpose, or hang the main loop until the watchdog fires |
+| `debug status` / `debug off [seconds]` | The Debug Console: whether it's on, has a token and a client; switch it off. With a number of seconds, it comes back by itself after that long |
+| `debug on` / `debug token <value>` / `debug token new` | USB serial only: switch it on (making a token if there's none), give it a token of 16 to 64 characters, or make a new one. The token is never printed |
+| `help` | Lists the commands |
+
+`scripts/flash.sh` stops a running serial log first, since it would hold the port.

site/content/dev/debug/console/debug-console.svg

@@ -0,0 +1,54 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 340" role="img" aria-label="Inside the Debug Console. On the PC, rdbg.py connects to TCP 2323 and sends the token first. On the device, the Debug Console task checks the token, serves one client, sends the console ring to the socket, and queues command lines for the main loop. It answers binary commands itself: get, put, screenshot, coredump get and reset. The main loop runs queued commands with runCommand, the same as the USB serial commands, and prints through console.printf into a 4 KB ring, which also goes to USB serial when there is room. ESP-IDF's own log lines are teed into the ring. Card work runs as jobs on the storage task: ls, rm and install from the main loop, get and put from the Debug Console task.">
+  <defs>
+    <marker id="dc-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="currentColor"/></marker>
+    <marker id="dc-arrow-hot" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path class="f-accent" d="M0,0 L10,5 L0,10 z"/></marker>
+  </defs>
+  <g font-family="JetBrains Mono, ui-monospace, monospace" fill="currentColor">
+    <rect class="dc-box" x="16" y="40" width="160" height="80" rx="6" stroke-dasharray="4 3"/>
+    <text x="28" y="62" font-size="12" font-weight="600">your PC</text>
+    <text x="28" y="84" font-size="11">rdbg.py</text>
+    <text x="28" y="102" font-size="11" class="dc-dim">token first</text>
+
+    <rect class="dc-hot" x="236" y="24" width="260" height="176" rx="8"/>
+    <text x="250" y="48" font-size="12" font-weight="600">Debug Console task</text>
+    <text x="250" y="72" font-size="11">token check, one client</text>
+    <text x="250" y="90" font-size="11">ring → socket, live</text>
+    <text x="250" y="108" font-size="11">lines → command queue</text>
+    <text x="250" y="134" font-size="11" class="dc-dim">answers these itself:</text>
+    <text x="250" y="152" font-size="11">get · put · screenshot</text>
+    <text x="250" y="170" font-size="11">coredump get · reset</text>
+    <text x="250" y="188" font-size="10" class="dc-dim">(they work with the loop stuck)</text>
+
+    <rect class="dc-panel" x="236" y="244" width="260" height="80" rx="8"/>
+    <text x="250" y="268" font-size="12" font-weight="600">main loop</text>
+    <text x="250" y="290" font-size="11">runCommand(): the same</text>
+    <text x="250" y="308" font-size="11" class="dc-dim">commands as USB serial</text>
+
+    <rect class="dc-panel" x="560" y="24" width="184" height="96" rx="8"/>
+    <text x="574" y="48" font-size="12" font-weight="600">console</text>
+    <text x="574" y="70" font-size="11">4 KB ring</text>
+    <text x="574" y="88" font-size="11" class="dc-dim">+ USB serial,</text>
+    <text x="574" y="106" font-size="11" class="dc-dim">  if there's room</text>
+
+    <rect class="dc-box" x="560" y="150" width="184" height="40" rx="6" stroke-dasharray="4 3"/>
+    <text x="652" y="175" font-size="11" text-anchor="middle">ESP-IDF logs (tee)</text>
+
+    <rect class="dc-panel" x="560" y="244" width="184" height="80" rx="8"/>
+    <text x="574" y="268" font-size="12" font-weight="600">storage task</text>
+    <text x="574" y="290" font-size="11">SD card jobs</text>
+    <text x="574" y="308" font-size="11" class="dc-dim">ls rm install get put</text>
+
+    <path class="dc-line-hot" d="M180 80 H232" marker-start="url(#dc-arrow-hot)" marker-end="url(#dc-arrow-hot)"/>
+    <text class="f-accent" x="184" y="72" font-size="10">TCP 2323</text>
+    <path class="dc-line-hot" d="M300 200 V240" marker-end="url(#dc-arrow-hot)"/>
+    <text class="f-accent" x="308" y="226" font-size="10">queue</text>
+    <path class="dc-line" d="M556 56 H500" marker-end="url(#dc-arrow)"/>
+    <text x="508" y="48" font-size="10" class="dc-dim">read</text>
+    <path class="dc-line" d="M652 150 V124" marker-end="url(#dc-arrow)"/>
+    <path class="dc-line" d="M496 262 H516 V100 H556" marker-end="url(#dc-arrow)"/>
+    <text x="510" y="232" font-size="10" text-anchor="end" class="dc-dim">printf</text>
+    <path class="dc-line" d="M496 180 H540 V290 H556" marker-end="url(#dc-arrow)"/>
+    <path class="dc-line" d="M496 306 H556" marker-end="url(#dc-arrow)"/>
+    <text x="512" y="322" font-size="10" class="dc-dim">jobs</text>
+  </g>
+</svg>

site/content/dev/debug/console/index.md

@@ -0,0 +1,99 @@
++++
+title = "The Debug Console"
+description = "Connect to the console over Wi-Fi: the protocol, what you get when you connect, how commands run, and what the console can and cannot do."
+weight = 2
+[extra]
+tag = "Console"
+diagrams = true
++++
+
+## Connect
+
+```sh
+export RORO_OTA_HOST=10.39.39.12   # or pass -H <ip>
+
+scripts/rdbg.py            # interactive: the backlog, then live lines; type commands
+scripts/rdbg.py info       # one command, and its reply
+scripts/rdbg.py -b tasks   # the same, with the backlog shown first
+```
+
+`scripts/rdbg.py` is a Python script with no dependencies. A one-shot command prints the reply and what follows, until the console has been quiet for a moment (1.5 seconds). It takes the token from `-t`, `$RORO_DEBUG_TOKEN` or `~/.config/roro9stack/debug-token` ([Switch the console on](/dev/debug/switch-it-on/)) and talks to **TCP 2323** on the device's address. In interactive mode, <kbd>Ctrl</kbd>+<kbd>D</kbd> or `quit` leaves. Piped input works too, but `rdbg.py` leaves **as soon as its input ends**, before the replies arrive: keep the input open for a few seconds, as in `(printf 'info\ntasks\n'; sleep 3) | scripts/rdbg.py`. For one command, the one-shot form above is simpler.
+
+The device listens **only while the console is switched on and Wi-Fi is connected**, and the console follows Wi-Fi: it stops listening when Wi-Fi drops and starts again when it is back.
+
+## What you get
+
+On connecting, in order:
+
+1. a **banner**: `roro9stack v0.12.0 debug console. 'help' lists the commands. Backlog follows.`
+2. the **backlog**: the last **4 KB** of console output, oldest first (a ring buffer in RAM, kept while the console is switched on: boot messages included, if it was on at boot);
+3. then **every new line, live**: everything the firmware prints, and ESP-IDF's own log lines, which are copied into the same stream (they still reach the USB port too);
+4. the **replies to your commands**, in the same stream, each preceded by the `> command` line when it runs.
+
+A line `status: heap <free> min <lowest>` appears every 10 seconds in the stream: a free-memory trace you get without asking.
+
+```
+> net
+net: IRC            in          0  out          0
+net: Gemini         in          0  out          0
+net: Debug Console  in       1038  out     205115
+net: Updates        in       4788  out        204
+```
+
+If you are not reading fast enough (a slow link), the device says so in the stream instead of stalling: `[... 312 bytes lost: the console ran faster than the network]`.
+
+## The protocol
+
+It is a plain line protocol, easy to speak from anything. This is what `rdbg.py` does, and all it needs:
+
+| Step | Detail |
+|---|---|
+| Connect | TCP 2323. **One client at a time**: a second one waits until the first leaves |
+| Challenge | The device sends one line: `roro9stack debug console, challenge <32 hex digits>`. Those are 16 random bytes, new each time |
+| Answer | Within **10 seconds**, send the **HMAC-SHA256 of those 16 bytes, keyed by the token**, as 64 hex digits and `\n`. The token is the tidied one: capitals, no dashes |
+| Accepted | The banner line, then the backlog |
+| Refused | After about a second the device sends `denied\n` and hangs up, and prints `debug: refused a client from <ip>` on its own console |
+| Locked | **Five wrong answers in a row** close the console to everyone for 60 seconds: it answers `locked\n` and hangs up, and a Toast on the device names the address they came from |
+| Commands | One line each, up to 240 bytes. The device **queues at most 8**; past that, `debug: busy, command dropped` |
+| Leave | `quit` or `exit` closes the connection |
+| Binary commands | `get`, `put`, `screenshot`, `coredump get`: a text header line, then raw bytes (see [files and screens](/dev/debug/files-and-screens/)) |
+
+**The token never crosses the network.** Someone on the same Wi-Fi who records a login gets a challenge and its answer, which are no use for the next challenge. The comparison on the device takes the same time whatever it is given.
+
+A command that never runs has not been dropped by the network: the main loop is busy or stuck. That is what the next section is about.
+
+## How commands run
+
+{{ diagram(src="debug-console.svg", min_width=580, caption="The console task only queues command lines. The main loop runs them with the same code as USB serial commands. Binary commands are answered by the console task itself, so they work when the main loop is stuck.") }}
+
+- **Text commands run on the main loop**, exactly like serial ones: they touch the Apps and the Services from the one task allowed to. The main loop prints `> command` as it starts, and the reply follows in the stream.
+- **Binary commands run on the console's own task**: `get`, `put`, `screenshot`, `coredump get` and `reset`. A failed `put` closes the connection, so the rest of the file is never read as commands.
+- That split is the point: with the **main loop stuck** (an infinite loop, a deadlock), text commands queue forever, but **`reset` still restarts the device at once**, `coredump get` still reads the dump, and `get` still reads files. A loop stuck for 5 seconds is a panic with a core dump anyway: see [Crashes and Safe Mode](/dev/debug/crashes/).
+- **Card work stays on the storage task**: `ls`, `rm`, `cp` and `install` from the main loop, `get` and `put` from the console task, all as jobs the storage task runs, so the card is only ever touched from one place.
+- Writes to the console **never wait for USB**: a host attached to the USB port but not reading used to stall the main loop for up to two seconds per line.
+
+## Security
+
+- **Off by default.** Nothing listens until the console is switched on at the device, or over USB.
+- The login is a **challenge and an answer**: the token itself is never sent, and five wrong answers close the console for a minute.
+- Anyone on the same network **with the token** can read the console, press keys, copy the SD card's files and restart the device. The console never prints stored secrets (the token, Wi-Fi and IRC passwords), but the IRC traffic it shows is readable.
+- They cannot change the firmware: an update still has to be **signed**.
+- The stream after the login is **plain text**: fine on a home network, not across the internet. Do not forward port 2323.
+
+The decisions are [ADR 0010](/dev/decisions/0010-debug-console-in-every-build/) and, for how the console works inside, [ADR 0004](/dev/decisions/0004-debug-console-in-debug-builds/).
+
+## Without `rdbg.py`
+
+Anything that can open a TCP connection and compute an HMAC works:
+
+```python
+import hashlib, hmac, socket
+token = "K7QF3M2X9WBDHT4P6RNC"                    # tidied: capitals, no dashes
+s = socket.create_connection(("10.39.39.12", 2323))
+challenge = s.makefile().readline().split()[-1]   # "... challenge 0f1e2d..."
+answer = hmac.new(token.encode(), bytes.fromhex(challenge), hashlib.sha256).hexdigest()
+s.sendall((answer + "\n").encode())               # then read the banner line
+s.sendall(b"info\n")                              # and what follows, until the stream goes quiet
+```
+
+`scripts/rdbg.py` adds the parts that need work on the PC side: decoding crash backtraces, saving files and screenshots, and checking checksums.

site/content/dev/debug/crashes.md

@@ -0,0 +1,71 @@
++++
+title = "Crashes, core dumps and Safe Mode"
+description = "What happens when the firmware crashes: the report, the core dump, the build it is decoded against, the main-loop watchdog and Safe Mode."
+weight = 5
+[extra]
+tag = "Console"
++++
+
+Rollback (see [How an update works](/dev/build/how-an-update-works/)) protects against **new** firmware that fails Probation. These measures cover firmware that was **confirmed and then crashes**: a corrupt setting, a server that sends something unexpected, a bug that takes an hour to show. They are in every firmware; the Debug Console is what makes them convenient. The decision is [ADR 0005](/dev/decisions/0005-safe-mode-crash-reports-watchdog/).
+
+## What a crash leaves behind
+
+- **A core dump** in a flash partition: ESP-IDF writes it on a panic.
+- **A crash record** in NVS, written first thing at the next boot: which **version** was running (so after a Rollback has switched slots, the firmware still knows which one crashed), and how many starts in a row followed a crash.
+- **A summary on the console** after the restart (task, program counter, reason, backtrace), and a **Notification** on screen.
+
+The `crash` command prints it again whenever you like:
+
+```
+> crash
+crash: last one in v0.9.0-1-g4ab873e-dirty (panic)
+crash: task loopTask, pc 0x4037e179, cause 0, address 0x00000000
+crash: reason: abort() was called at PC 0x421209b3 on core 1
+crash: backtrace 0x4037e179 0x4037e141 0x4038582d 0x421209b3 ...
+crash: elf sha256 3c6a185e5
+```
+
+`coredump erase` forgets the dump.
+
+## Decode it: `rdbg.py crash` and `rdbg.py coredump`
+
+An address is no use without the **exact build** that crashed. Every build archives its ELF in **`.pio/elves/`**, named by version and the first 16 hex digits of its SHA-256 (`scripts/version.py`); the core dump names the crashed firmware by the same digest. So a crash can be decoded **after later builds**, including a build you have since replaced:
+
+```sh
+scripts/rdbg.py crash              # the crash report, with the backtrace turned into functions and source lines
+scripts/rdbg.py coredump           # fetch the whole core dump, then decode it
+scripts/rdbg.py coredump my.bin    # ...to a file you name
+```
+
+- **`crash`** runs the device's `crash`, finds the ELF by digest (or by version), and passes the backtrace to `scripts/decode_backtrace.sh`, which runs `addr2line` from the build container: one line for each frame, with function and file:line.
+- **`coredump`** fetches the raw dump over the console (it works when the main loop is stuck) and runs `scripts/decode_coredump.sh`: `esp-coredump` and GDB, giving **every task's backtrace, the registers, and the crashed task's stack**.
+- By hand: `scripts/decode_backtrace.sh <version|digest> <address>...`, and `scripts/decode_coredump.sh <core.bin> <version|digest>`. Both say which ELF they used.
+- **A release's ELF is fetched for you.** When the crash names a released version (`v0.12.0`) and no local ELF matches, `rdbg.py` downloads `roro9stack-<version>.elf.gz` from the release on Gitea into `.pio/elves/`, so a crash on a firmware you did not build can be decoded. Decoding itself still runs in the build container.
+- If nothing matches, the scripts say so: an unreleased build made on another machine, or `.pio/` was cleaned.
+
+## The main loop is watched
+
+Arduino-ESP32 puts only core 0's idle task on the task watchdog, and the main loop runs on core 1: a stuck loop used to hang the device for good, with a frozen screen and a console that could not run commands. Now **a loop stuck for 5 seconds is a panic**, with a core dump, counted towards Safe Mode. The rule that follows: **nothing in the main loop may block for 5 seconds.** Network and card work already run on their own tasks.
+
+An installed update no longer depends on the main loop either: the Update Service restarts into it by itself after 90 seconds.
+
+## Safe Mode
+
+The count of starts that follow a crash (a panic or the watchdog) is kept in NVS. After **three in a row**, the firmware starts **Safe Mode** instead of everything else:
+
+- only the **clock, Wi-Fi, the Update Service and, if it is switched on, the Debug Console** start: no Apps, no IRC, no SD card;
+- the screen says so, with the **address to push an update to**;
+- only a few commands run (the [command reference](/dev/debug/commands/) lists them); anything else answers `not available in Safe Mode`.
+
+Any **normal restart** (`reboot`, an update) or **a minute of uptime** resets the count. So Safe Mode is reached by crashing three times *quickly*, and a crash loop costs about half a minute before the device becomes reachable. To leave it: push a fix (`scripts/flash.sh --ota`), or `reboot`. Over USB, `debug on` works in Safe Mode too, if the console was off.
+
+**Its limit:** if Wi-Fi or the Update Service is what crashes, Safe Mode cannot help, and it takes USB.
+
+## Crash on purpose
+
+```
+crash abort      # abort(): a panic with a core dump
+crash wdt        # hang the main loop until the task watchdog fires
+```
+
+Use them to see a real report and decode it, to check that **the counter reaches Safe Mode**, and to prove that a build you are about to rely on will survive its own crashes. The device restarts by itself after either, and the report is there to read when the console comes back.

site/content/dev/debug/drive-the-ui.md

@@ -0,0 +1,122 @@
++++
+title = "Drive the UI from your desk"
+description = "Press keys, take screenshots, fake inputs and test the awkward paths (updates, crashes, fixed IPs, crowded folders) without touching the device."
+weight = 4
+[extra]
+tag = "Console"
++++
+
+Everything the keyboard can do, a command can do, and everything on the screen can be looked at remotely. That makes the Cardputer testable like a web page: **act, look, repeat**.
+
+## Keys
+
+```
+key up|down|left|right|select|back|home|del|tab|space
+key a        # any single character: it is typed
+```
+
+Two things to know before you use them:
+
+1. **A name `key` does not know is `select`.** `key sleect` presses Enter. A single character is typed as that character; anything else that is not a known name is treated as Enter. Check what you type.
+2. **A key that wakes a dark screen only wakes it.** The device's power policy swallows the key press that turns the screen back on, as it does for the real keyboard: the first `key` after the screen went off does nothing else. Send `key back` (harmless) first, or keep the screen on with the `normal` and `short` commands below.
+
+`Fn` combinations, modifiers and the compose key have no command: the arrows are `key up|down|left|right`, and `key back` is the back key (`` ` `` on the device). Text is typed one character at a time.
+
+## Look before you press
+
+**Take a screenshot before any key that deletes, renames or installs.** A blind sequence of `key` commands goes wrong the moment the screen is not where you think it is, and the screen is often not where you think it is: a Toast, a dialog that has not closed, a different App. A sequence that was meant to open a note once renamed real data instead.
+
+```sh
+scripts/rdbg.py key home          # to the Launcher
+scripts/rdbg.py screenshot a.png  # look: is it the Launcher?
+scripts/rdbg.py key down
+scripts/rdbg.py key select
+scripts/rdbg.py screenshot b.png  # look again before the next destructive step
+```
+
+- Prefer **reading a state** to assuming it: `info`, `ls <folder>`, `cat <file>`, `irc dump`, `gnss status`, `lora status`, `wifi status`, `update status`.
+- Test on a **scratch folder** on the card, not on your real files.
+- For anything that deletes (`rm`, a delete dialog), `ls` first and `ls` after.
+
+## Keep the screen on, and make timeouts short
+
+```
+short     # screen dims after 5 s, turns off after 10 s: to test the screen policy
+normal    # back to 30 s and 60 s
+burst     # five Toasts at once: to test notifications
+sound on | sound off
+```
+
+## Fake the inputs
+
+Each of these puts something in, **without** the outside world:
+
+| Command | What it does |
+|---|---|
+| `lora inject <hex> [rssi] [snr]` | A packet into the LoRa Scanner as if the radio had received it. Nothing is sent |
+| `irc say <buffer> <text>` | Types into an IRC buffer, commands included: `irc say 0 /join #test` |
+| `log <text>` | Adds a line to a test IRC log |
+| `gnss send <sentence>` | Sends an NMEA sentence **to** the GNSS receiver (the checksum is added), to configure it |
+| `gemini get <url>` | Fetches a page and reports header, size, certificate and heap use, without the App |
+| `gemini trust <host> <port> <sha256>` | Pins a certificate by hand |
+| `sd fill <folder> <count>` | Makes that many small files in a folder, to test a crowded one (the Storage App shows the first 256) |
+| `wifi add <ssid><TAB><password>` | Adds a Saved Network, so credentials stay out of the repository |
+
+## Test the update path
+
+An update that goes wrong is the case you most want to rehearse, and the firmware can make it go wrong **on purpose**:
+
+```
+update status                       # what the device runs, what failed here before, the daily check, heap
+update check | update list          # look at the server: the latest release, or the last ten
+update pretend v0.9.0               # take the running version to be v0.9.0: the latest release now counts as "new"
+update damage cut 50000             # the next download is cut after 50000 bytes
+update damage flip 100000           # ...or has the byte at offset 100000 damaged
+update install v0.11.0              # try the install
+update probe git.twis.la            # is that server's certificate accepted? (the two ISRG roots only)
+update daily                        # forget today's daily check: it runs again at the next tick
+update pretend off                  # back to the real version
+```
+
+- **A damaged download must be refused cleanly:** the Update Service checks the signature after the first 160 bytes and the image hash at the end, so a cut or a flipped byte must end in a refusal with **nothing switched**. Check `info` afterwards: both slots, and `update: confirmed`.
+- **An undamaged install really installs** the release, into the other slot, and the device restarts into it. Your build stays in the slot it was in until the next update overwrites it, and the console's setting and token are untouched: the release has the console too.
+- The server is read by the device itself, with Wi-Fi up; the download is one TLS connection, about 52 KB of heap at its peak, so IRC steps aside (see [the memory limit](/howto/not-enough-memory/)). `status: heap` in the stream shows it happen.
+
+For crashes during Probation, see [Crashes and Safe Mode](/dev/debug/crashes/).
+
+## Test a network change without losing the console
+
+The Debug Console runs over the Wi-Fi you are about to change, which is the usual way to lock yourself out. A **trial IP setting** takes care of it:
+
+```
+wifi ip MyNet 10.39.39.50/24 10.39.39.1 try 60     # use this address for 60 s...
+wifi ip keep                                       # ...and keep it, if you could still reach the device
+```
+
+If you do not send `wifi ip keep` in time, the device goes back to the **previous** setting by itself, and the console comes back with it. 
+
+## Measure
+
+```
+info       # firmware, uptime, last start reason, heap now/lowest/largest block, chip temperature, Wi-Fi, SD faults, both app slots
+tasks      # each task over the next second: state, priority, least free stack, CPU share; each core's load; main-loop passes
+net        # bytes each network service has read and written since start
+```
+
+`tasks` takes a second to answer. A low number in the `stack` column is a risk (the System App shows it in the warning colour under 512 bytes). `loop spin on|off` makes the main loop spin without resting, to compare load and radio noise. And the `status: heap` line every 10 seconds in the stream is the cheapest memory trace there is: watch it while you do the thing you suspect.
+
+```
+task             st   pri  stack   cpu% core
+loopTask         R      1   1828    1.3 1
+wifi             B     23   4072    0.7 0
+debug            B      1   3088    0.5 -1
+...
+load: core 0 2 %, core 1 1 %
+loop: 50 passes in the last second, chip 35.3 C
+```
+
+The [System App](/guide/system/) shows the same, live, on the device.
+
+## Radio experiments
+
+`lora preset <name>` and `lora custom <MHz> <BW kHz> <SF> <CR> <sync hex> [preamble]` change what the receiver listens to (receive only: the radio never transmits), `lora sweep on [from] [to] [step]` takes a survey, and `lora noise test [gnss|quiet]` runs a Sweep under one changed condition at a time, with Wi-Fi off for a moment, to find what raises the noise floor. `lora probe` finds the radio and reports its chip, oscillator, antenna switch, interrupt line and noise floor. Details in the [command reference](/dev/debug/commands/).

site/content/dev/debug/files-and-screens.md

@@ -0,0 +1,60 @@
++++
+title = "Files, screenshots and the SD card"
+description = "Copy files to and from the card, take a screenshot, fetch a core dump and restart the device, all over Wi-Fi, with checksums."
+weight = 3
+[extra]
+tag = "Console"
++++
+
+These are the **binary commands**: a text header line, then raw bytes. The console task answers them itself, so they keep working when the main loop is stuck. `scripts/rdbg.py` handles each one on the PC side; the protocol is given too, for your own tools.
+
+## `get`: card to PC
+
+```sh
+scripts/rdbg.py get /gnss/tracks/20261004-142530.gpx          # saved here, under its own name
+scripts/rdbg.py get /captures/lora/capture.pcap my-capture.pcap
+```
+
+The device answers `get: data <size>`, then exactly `<size>` bytes, then `get: end`. A path it cannot open (missing, or a folder) gives `get: error cannot open <path>`. The script prints the size and the speed.
+
+## `put`: PC to card
+
+```sh
+scripts/rdbg.py put roro9stack-v0.12.0.ota                     # to /updates/roro9stack-v0.12.0.ota
+scripts/rdbg.py put notes.txt /notes/from-the-pc.txt           # to a path you choose
+```
+
+The default destination is `/updates/<name>`, so this is also the way to **install an update from the SD card without touching the device**: `put` the `.ota` file, then `scripts/rdbg.py install /updates/<name>`.
+
+The device does a few things you want from a file transfer:
+
+- the PC sends the **size and the SHA-256** first (`put <path> <size> <sha256>`); the device answers `put: ready <size>` or `put: error <why>` (no card, **not enough space**: it wants the size plus 64 KB free, or a path or size it refuses);
+- it writes to a **temporary `.part` file**, creating missing folders, and only **renames it into place after the whole file has been read back from the card and its SHA-256 matches**: the checksum covers what is on the card, not what arrived;
+- a write the card refuses is **retried up to 3 times**, cutting the file back to the last good byte, and gives up rather than leave a hole in the middle;
+- it ends with `put: done <path> <size> B`, or `put: error <why>` and **a closed connection** (so the rest of the file is never read as commands). A failed transfer leaves nothing on the card.
+
+Speed is about 300 KB/s. The same transfer exists over USB serial, for a device with no Wi-Fi: `scripts/sd_put.sh <file> [card path]` (about 30 seconds for 1.6 MB, with the card left in).
+
+## `screenshot`: the screen as a PNG
+
+```sh
+scripts/rdbg.py screenshot ui.png     # 480x270: the 240x135 screen at 2x
+```
+
+The device sends `screenshot: rgb332 <width> <height>` and then **one byte per pixel**: the frame the UI composed off-screen, in RGB332 (RRRGGGBB), the way M5GFX stores an 8-bit sprite. The script expands it and doubles it into a PNG.
+
+- It is read **as it stands**, while the UI may be drawing, so it can **tear**. It is for looking at, not for pixel-exact comparison.
+- It is the real thing: the screenshots on this site, in the [user guide](/guide/) and the [devlog](/devlog/), were taken this way.
+- Its main use is in a loop: send a key, wait a moment, take a screenshot, look. See [Drive the UI](/dev/debug/drive-the-ui/).
+
+## `coredump get`: the crash dump
+
+The raw contents of the core dump partition: `coredump: data <size>`, the bytes, `coredump: end`, or `coredump: none`. `scripts/rdbg.py coredump` fetches and decodes it in one go: see [Crashes and Safe Mode](/dev/debug/crashes/).
+
+## `reset`: restart now
+
+```sh
+scripts/rdbg.py reset
+```
+
+The console prints `debug: restarting now` and restarts the chip after a moment. It does not go through the main loop, so it works when the loop is stuck. (The text command `reboot` does go through the main loop: a clean restart. `boot other` restarts into the other app slot: a manual rollback.)

site/content/dev/debug/switch-it-on.md

@@ -0,0 +1,77 @@
++++
+title = "Switch the console on"
+description = "The Debug Console is in every firmware, and off. How to switch it on, where its token comes from, and how to set a device up without typing anything."
+weight = 1
+[extra]
+tag = "Start here"
++++
+
+## One firmware
+
+There is no special build. **Every roro9stack firmware has the Debug Console**, the same one, and the commands made for testing (crash on purpose, fake an installed version, damage a download, inject a LoRa packet). It is **off** until its owner switches it on.
+
+**Off means nothing is there:** no socket listens, the console's task does not exist, and neither does its 4 KB buffer. A device that never uses it pays 30 KB of flash and 88 bytes of memory.
+
+Before version 0.12 this was a separate *Debug Build* with a token compiled in from the builder's machine, which is why it could not be published. [ADR 0010](/dev/decisions/0010-debug-console-in-every-build/) says why that changed.
+
+## On the device
+
+**Settings → Debug Console:**
+
+| Row | Does |
+|---|---|
+| **Debug Console** | The switch. Switching it **on** asks first (the question opens on *Cancel*: move to *Switch on*), and makes a token if there is none |
+| **Connect to** | The address and port: `10.39.39.12:2323` |
+| **New token** | Makes another one. The old one stops working, and whoever is connected is cut off |
+| **Type a token** | One of your own, of 16 to 64 characters |
+
+Under the rows, the **token**, in large type on two lines, in groups of four: `K7QF-3M2X-9WBD-HT4P-6RNC`. This page is the only place it is ever shown. The Status Bar shows **`DBG`** while the console listens, and brighter while someone is connected.
+
+The setting **stays** across restarts and updates, and in Safe Mode.
+
+## The token
+
+- **The device makes it,** from its hardware random generator, the first time the console is switched on: 100 bits, written as 20 characters without the letters that get misread (no I, L, O or U).
+- **Dashes and case do not count,** and an `O`, `I` or `L` is taken for the `0` or `1` it was. Type it as you read it.
+- **One you type** must have at least 16 characters. A short one would be the weakest part of the whole thing.
+- It is **never printed** on a console, and it **never crosses the network** ([the Debug Console](/dev/debug/console/) says how).
+- It guards against **the network**, not against someone who holds the device: anyone with USB access can flash anything anyway ([ADR 0003](/dev/decisions/0003-own-signature-check-not-secure-boot/)).
+
+## Give `rdbg.py` the token
+
+`scripts/rdbg.py` looks for it in this order:
+
+```sh
+scripts/rdbg.py -t K7QF-3M2X-9WBD-HT4P-6RNC info     # 1. on the command line (also --token)
+RORO_DEBUG_TOKEN=K7QF-3M2X-9WBD-HT4P-6RNC scripts/rdbg.py info   # 2. in the environment
+echo K7QF-3M2X-9WBD-HT4P-6RNC > ~/.config/roro9stack/debug-token # 3. in a file, for the device you use every day
+```
+
+## Without typing: over USB
+
+With the device on a cable, the console can be set up from the PC:
+
+```sh
+scripts/flash.sh --debug        # flashes over USB, then switches the console on and gives it your token
+```
+
+It sends two commands over the serial port, which you can also type there yourself:
+
+```
+debug on                 # switch it on (a token is made if there is none)
+debug token <value>      # give it this token: 16 to 64 characters
+debug token new          # make a new one
+debug status             # on or off, token set or not, a client or not (the token itself is never shown)
+debug off                # switch it off
+debug off 30             # ...for 30 seconds: it comes back by itself
+```
+
+`debug on` and `debug token` work **over USB serial only**: the console cannot be used to open itself wider. `debug status` and `debug off` work from anywhere, and a screenshot taken over the console while this page is open shows the token, to someone who already had it. Your token file is made by the first build (`scripts/_docker.sh`), 32 hex digits, and is never committed.
+
+Since the setting survives updates, this is needed **once for a device**, not at each flash. Later builds go over Wi-Fi with `scripts/flash.sh --ota`.
+
+## Should it be on?
+
+On your own network, on a device you are working on: yes, that is what it is for. Remember what it gives to whoever has the token **and** is on the same network: the console, the keys, the files on the SD card, a restart. It does not give them the firmware: an update still has to be signed.
+
+On a network you share with strangers, switch it off, or at least know that what the console prints is not encrypted. The token is safe there; the conversation is not.

site/content/dev/decisions/0001-own-firmware-speaking-meshtastic.md

@@ -0,0 +1,23 @@
++++
+title = "Own firmware that speaks Meshtastic, not a Meshtastic fork"
+description = "We build our own firmware from existing libraries (PlatformIO + Arduino-ESP32, M5Cardputer/M5Unified, RadioLib, TinyGPSPlus, nanopb with Meshtastic's published protobufs). We implement the Meshtastic protocol ourselves as one…"
+weight = 1
+
+[extra]
+docs = true
+source = "docs/adr/0001-own-firmware-speaking-meshtastic.md"
+tag = "ADR 0001"
++++
+We build our own firmware from existing libraries (PlatformIO + Arduino-ESP32, M5Cardputer/M5Unified, RadioLib, TinyGPSPlus, nanopb with Meshtastic's published protobufs). We implement the Meshtastic protocol ourselves as one pluggable Mesh Protocol, rather than forking the Meshtastic firmware, which already supports this exact hardware.
+
+A fork would give full compatibility on day one, but its architecture is built around being a single-purpose Meshtastic node. That conflicts with our goals: a multi-app OS with a fully custom UX, and room for other mesh protocols (e.g. MeshCore) later.
+
+## Consequences
+
+- We accept partial Meshtastic compatibility at first: text on channels, Direct Messages, node list, position and relaying.
+- The phone-app (BLE) API and PKI-encrypted Direct Messages are deferred, and we must re-implement protocol details ourselves.
+- Multi-boot with stock Meshtastic via a launcher was rejected: it gives none of our own UX.
+
+## Note (2026-10-04, M2)
+
+NMEA is parsed by our own small, host-tested parser instead of TinyGPSPlus: the GNSS App's Sky view needs the satellite list (GSV) across several constellations, which TinyGPSPlus doesn't track. See docs/milestones/M2.md, Q66.

site/content/dev/decisions/0002-own-widget-kit-on-m5gfx.md

@@ -0,0 +1,18 @@
++++
+title = "Own small widget kit on M5GFX, not LVGL"
+description = "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."
+weight = 2
+
+[extra]
+docs = true
+source = "docs/adr/0002-own-widget-kit-on-m5gfx.md"
+tag = "ADR 0002"
++++
+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.
+
+LVGL would give us ready-made widgets, but it costs roughly 40–60 KB of RAM on a device with no PSRAM. It would also need to coexist with the Mesh Service, the Wi-Fi stack and TLS, and it brings a large learning surface. Most of our Apps are lists and text on a 240×135 screen, and full control of the UX is a primary goal.
+
+## Consequences
+
+- We write and maintain our own widgets.
+- Switching to LVGL later would mean rewriting every App's view layer.

site/content/dev/decisions/0003-own-signature-check-not-secure-boot.md

@@ -0,0 +1,20 @@
++++
+title = "Signed Update Files checked by the firmware, not ESP32 Secure Boot"
+description = "Firmware Updates are accepted only when their Update File carries a valid ECDSA P-256 signature over the image's SHA-256. The firmware itself checks it, against a public key compiled into it, before switching the boot partition.…"
+weight = 3
+
+[extra]
+docs = true
+source = "docs/adr/0003-own-signature-check-not-secure-boot.md"
+tag = "ADR 0003"
++++
+Firmware Updates are accepted only when their Update File carries a valid ECDSA P-256 signature over the image's SHA-256. The firmware itself checks it, against a public key compiled into it, before switching the boot partition. The private key lives outside the repository, in `~/.config/roro9stack/ota-key.pem`.
+
+We chose this over the ESP32's hardware Secure Boot. Secure Boot is enforced by the chip, but it burns eFuses one-way: a mistake bricks the device, and the device can never run unsigned firmware again, which makes recovery over USB harder. On a single development device, a software check that refuses unsigned pushes is enough, and it stays reversible: a new firmware can carry a new public key.
+
+## Consequences
+
+- Someone with physical USB access can still flash anything. Only Wi-Fi and SD card updates are guarded.
+- **Losing the private key** means the next update has to go over USB, carrying a new public key.
+- P-256 rather than Ed25519, because the firmware's TLS library (mbedTLS) already verifies it, so it costs no extra code.
+- **Rollback: the bootloader first, the firmware as a second line.** Arduino-ESP32 marks a new image valid before `setup()` unless the sketch overrides `verifyRollbackLater()`, which once made every update look good and hid the bootloader's rollback (it had looked like the prebuilt bootloader ignored it). With the override, an image stays pending until Probation confirms it, and the bootloader reverts one that restarts unconfirmed, however early it crashes. The firmware also counts its own boots on Probation, very first thing in `setup()`, and reverts itself on the second unconfirmed start.

site/content/dev/decisions/0004-debug-console-in-debug-builds.md

@@ -0,0 +1,33 @@
++++
+title = "A Debug Console over Wi-Fi, in Debug Builds only"
+description = "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…"
+weight = 4
+
+[extra]
+docs = true
+source = "docs/adr/0004-debug-console-in-debug-builds.md"
+tag = "ADR 0004"
++++
+**Superseded in part by [ADR 0010](/dev/decisions/0010-debug-console-in-every-build/) (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 console works (the ring, commands on the main loop, binary commands on its own task, one client) still holds.
+
+The goal of Firmware Updates is to manage the device without a cable, and that includes finding out what went wrong. So a **Debug Build** (`cardputer-adv-debug`, `-DRORO_DEBUG`, version suffix `+debug`) adds a **Debug Console** on TCP 2323: the serial console, over Wi-Fi. A client sends a token as its first line, then gets the last 4 KB of console output (boot messages included), every new line live, and runs the same commands as the serial port, plus a few that only make sense remotely. ESP-IDF's own log lines are teed into it.
+
+It's compiled out of release builds entirely, rather than switched off by a setting. A console that runs commands is a remote control: in a release build, nothing listens.
+
+## How it fits
+
+- **Console, not Serial.** All human-readable output goes through `console`, which writes to the USB port and, in a Debug Build, to a ring buffer the Debug Console drains. Writes never wait for USB: a host that's attached but not reading used to stall the main loop for up to 2 s per line.
+- **Commands run on the main loop.** The socket lives on the Debug Console's own task, which only queues command lines. The main loop runs them, as it does serial commands, so they touch Apps and Services from the one task allowed to.
+- **The token** is 128 random bits in `~/.config/roro9stack/debug-token`, made by the first build and passed into the container. It's never committed; a Debug Build refuses to compile without one. Like the OTA key, it guards against the network, not against someone holding the device.
+- **One client at a time**, to keep memory flat (4 KB for the ring since M2, 6 KB of task stack).
+- **Binary commands are answered on the console's own task**, not queued: `get`/`put` (SD card files, run as one Storage Service job each so card access stays on the storage task, with TCP doing the flow control), `screenshot` (the 32 KB RGB332 frame the UI composes into, read as it stands, so it may tear), `coredump get` and `reset`. These keep working when the main loop is stuck. A failed `put` closes the connection, so the rest of the file is never read as commands.
+
+## Keep a Debug Build in the fallback slot
+
+Rollback returns to the previous firmware, whatever it is. As long as development goes through Debug Builds, the firmware a crash falls back to has the Debug Console, so a bad update never costs remote access. A release build pushed over a Debug Build leaves the Debug Build in the other slot until the next update overwrites it.
+
+## Consequences
+
+- Anyone on the same network with the token can read the console, inject keys and reboot the device. The console never prints stored secrets (Wi-Fi and IRC passwords), but the IRC traffic it shows is readable.
+- The TCP stream is plain text: fine on a home network, not across the internet.
+- `+debug` versions compare equal to their release counterparts, so moving between the two is never refused as a downgrade.

site/content/dev/decisions/0005-safe-mode-crash-reports-watchdog.md

@@ -0,0 +1,21 @@
++++
+title = "Safe Mode, crash reports and a watched main loop, in every build"
+description = "Rollback protects against new firmware that fails Probation. It does nothing for firmware that was confirmed and crashes later: a corrupt setting, a server that sends something unexpected, a bug that takes an hour to show.…"
+weight = 5
+
+[extra]
+docs = true
+source = "docs/adr/0005-safe-mode-crash-reports-watchdog.md"
+tag = "ADR 0005"
++++
+Rollback protects against new firmware that fails Probation. It does nothing for firmware that was confirmed and crashes later: a corrupt setting, a server that sends something unexpected, a bug that takes an hour to show. Without a cable, such a device would restart forever. Three measures, in every build, keep it reachable:
+
+- **Safe Mode.** The firmware counts starts that follow a crash (panic or watchdog) in NVS, first thing at boot. After 3 in a row, it starts only the clock, Wi-Fi, the Update Service and, if it's switched on, the Debug Console: no Apps, no IRC, no SD card, and a screen that says so with the address to push an update to. Any normal restart (a `reboot`, an update), or a minute of uptime, resets the count.
+- **Crash reports.** The same boot record keeps which version was running, so after a crash the firmware knows which one crashed, even when a Rollback has switched slots since. ESP-IDF already writes a core dump to its flash partition on a panic; after the restart the firmware prints its summary (task, PC, reason, backtrace) and raises a Notification. The `crash` command shows it again later. With the Debug Console, `scripts/rdbg.py crash` decodes the backtrace and `scripts/rdbg.py coredump` fetches the whole dump for `esp-coredump`, against the ELF of that exact build (`.pio/elves/`, named by version and ELF digest).
+- **The main loop is watched.** Arduino-ESP32 subscribes only core 0's idle task to the task watchdog, and the main loop runs on core 1: a stuck loop used to hang the device for good, with the screen frozen and the Debug Console unable to run commands. `enableLoopWDT()` makes a loop stuck for 5 s a panic, with a core dump, counted towards Safe Mode. And an installed update no longer depends on the main loop: the Update Service restarts into it by itself after 90 s.
+
+## Consequences
+
+- Nothing in the main loop may block for 5 s. Network and card work already run on their own tasks.
+- Safe Mode can't help when Wi-Fi or the Update Service itself is what crashes; that still needs USB.
+- Three crashes within a minute of each restart are needed to reach Safe Mode, so a crash loop costs about half a minute before the device becomes reachable.

site/content/dev/decisions/0006-framework-rebuilt-for-smaller-tls-buffers.md

@@ -0,0 +1,27 @@
++++
+title = "The framework is rebuilt with our own SDK settings, for smaller TLS buffers"
+description = "Arduino-ESP32 ships its ESP-IDF libraries prebuilt, with one sdkconfig for every ESP32-S3 board. Its TLS settings give every connection a 16 KB receive buffer and a 16 KB send buffer for its whole life. On a device with no PSRAM…"
+weight = 6
+
+[extra]
+docs = true
+source = "docs/adr/0006-framework-rebuilt-for-smaller-tls-buffers.md"
+tag = "ADR 0006"
++++
+Arduino-ESP32 ships its ESP-IDF libraries prebuilt, with one `sdkconfig` for every ESP32-S3 board. Its TLS settings give every connection a 16 KB receive buffer and a 16 KB send buffer for its whole life. On a device with no PSRAM and about 340 KB of RAM, an IRC connection over TLS left a 12.6 KB low in M2, against a 40 KB floor.
+
+Those settings are compiled into the libraries, so changing them means rebuilding them. pioarduino supports this as a "hybrid compile": `custom_sdkconfig` in `platformio.ini` lists the settings, and the build regenerates the framework's libraries from ESP-IDF (the same 5.5.5 the prebuilt ones come from) before building the app. We set:
+
+- `MBEDTLS_ASYMMETRIC_CONTENT_LEN`, with 16 KB to receive (servers send full TLS records) and **4 KB to send** (IRC lines are short): 12 KB less per connection.
+- `MBEDTLS_DYNAMIC_BUFFER`, `DYNAMIC_FREE_CONFIG_DATA`, `DYNAMIC_FREE_CA_CERT`: buffers allocated when needed, and handshake-only data (the CA chain) freed once connected.
+
+The rebuild also follows the board definition instead of the generic one: PSRAM support is off (the Cardputer ADV has none) and the flash size is 8 MB.
+
+## Consequences
+
+- With IRC connected over TLS, a Debug Build has 78 KB free and a 59 KB low (it was 31 KB and 12.6 KB), and 46 KB at the lowest under the heaviest combined load measured (IRC, two refused installs, a 1.6 MB put and get).
+- The first build after a fresh checkout, or after changing `custom_sdkconfig`, takes about 4 minutes instead of 45 s: it downloads ESP-IDF into the PlatformIO volume and compiles it. Later builds reuse it.
+- Everything the firmware depends on was checked in the regenerated `sdkconfig`: app rollback, core dumps to flash (ELF), the 5 s task watchdog, FreeRTOS run-time stats, the certificate bundle.
+- The project now owns its partition table (`default_8MB.csv`, identical to the framework's), which the hybrid build requires. Changing it would break updates over the air: the app slots must stay where they are.
+- Generated files (`sdkconfig.*`, `managed_components/`, `.dummy/`) are ignored by git.
+- A TLS server that sends records over 16 KB would still fail, as before; one that needs us to send records over 4 KB would now fail. Neither happens with IRC.

site/content/dev/decisions/0007-own-copy-of-the-sd-driver.md

@@ -0,0 +1,28 @@
++++
+title = "Our own copy of the SD driver, for one missing byte"
+description = "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…"
+weight = 7
+
+[extra]
+docs = true
+source = "docs/adr/0007-own-copy-of-the-sd-driver.md"
+tag = "ADR 0007"
++++
+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 upload failed about three times in ten; before M3, the retry on top of it then filled the gap with zeros.
+
+The cause, measured with a driver that records where it stops: after the "Stop Tran" token that ends a multi-block write, a card takes about a byte of clock to signal busy. The driver deselects, selects again, and reads one byte to see whether the card is ready. Read too early, that byte is 0xFF, "ready"; the status check (CMD13) then goes out while the card is still programming, and its answer (0xFF, 0x1F) is taken for an error. Every failure seen was this one: all blocks accepted, then a status that isn't one. ChaN's reference driver, which FatFs ships as its example, sends a dummy byte after selecting the card for this reason. Arduino's doesn't.
+
+PlatformIO links the framework's library objects directly, so one file can't be replaced from `src`. A project library with the same name takes its place: **`lib/SD` is Arduino-ESP32 3.3.12's SD library (Apache-2.0), with `sd_diskio.cpp` changed** and the other files as they came. The changes are marked `roro:`:
+
+- A dummy byte after selecting the card, before the ready test, and one after Stop Tran.
+- Each place a write gives up records the step and the card's answer (`sd_fault.h`): `info` shows the count, and the Debug Console's `put` prints the detail.
+
+Halving the SPI clock to 10 MHz didn't change the failure rate, so the card stays at 20 MHz.
+
+## Consequences
+
+- 30 uploads of 1.7 MB in a row, each read back and compared by SHA-256, ten of them with the LoRa radio listening on the same bus: no write fault. Before: 3 failures in 10.
+- Every writer gains: Logs, Tracks, Gemini pages, Saved Pages, Captures and Update Files installed from the card all go through this driver, and none of them checked.
+- **The copy has to follow the framework.** When the platform is updated, compare `lib/SD` with the new `libraries/SD` and carry the `roro:` changes over. If upstream fixes the ready test, drop the copy. Reported as [arduino-esp32#12970](https://github.com/espressif/arduino-esp32/issues/12970); issue #39 follows it.
+- One more defect was read in the code and left alone, because nothing here exercises it: the driver tests the card's answer to a data block against 0x0A and 0x0C, values it can't take (accepted is 0x05, CRC error 0x0B, write error 0x0D), so a block rejected for a CRC error is never resent. No such rejection was seen in any failure. If `DataToken` faults ever show in `info`, that's the next fix.
+- A fault is now counted and explained instead of silent, so the next cause, if there is one, starts with evidence.

site/content/dev/decisions/0008-ci-signs-releases.md

@@ -0,0 +1,25 @@
++++
+title = "CI signs releases with the project's key"
+description = "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…"
+weight = 8
+
+[extra]
+docs = true
+source = "docs/adr/0008-ci-signs-releases.md"
+tag = "ADR 0008"
++++
+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 repository secret `OTA_SIGNING_KEY`, which the release step writes to a file for as long as it runs.
+
+We chose this over signing by hand after CI has built (a command per release, the key in one place), and over a second key for CI that the firmware would also trust. A release that needs a manual step isn't made on the day it's ready, and issue #6, the device installing releases by itself, needs releases that are always there and always signed.
+
+## What it costs
+
+- **Whoever can run a workflow in this repository can sign firmware every device accepts.** That means: anyone who can push to it, the runner's host and whoever administers it, and the Gitea instance with its database, where the secret is stored. Before, it took the development machine.
+- The runner executes jobs **on its own host**, not in a container, as a user who can use Docker. A workflow is not confined.
+- Pull requests from forks must never run with this secret. Gitea doesn't pass secrets to them; the workflow also only runs on pushes and by hand.
+
+## What limits it
+
+- The release step checks the signed file against the public key in the sources it built (`scripts/ota_verify.py`): a wrong or replaced secret stops the release instead of publishing a file no device takes.
+- ADR 0003's way out stays: a firmware release can carry a new public key. If the secret is ever in doubt, make a new pair, ship it in a release signed with the old key, and replace the secret.
+- A device still only installs what it's told to (until #6), keeps a new image on Probation, and rolls back one that doesn't hold.

site/content/dev/decisions/0009-the-device-trusts-the-isrg-roots.md

@@ -0,0 +1,30 @@
++++
+title = "The device trusts the two ISRG roots for what it fetches"
+description = "The firmware talks to the project's Gitea over HTTPS (issue #6, and #4 after it). A TLS client has to decide whose certificates it believes. Three ways were possible:"
+weight = 9
+
+[extra]
+docs = true
+source = "docs/adr/0009-the-device-trusts-the-isrg-roots.md"
+tag = "ADR 0009"
++++
+The firmware talks to the project's Gitea over HTTPS (issue #6, and #4 after it). A TLS client has to decide whose certificates it believes. Three ways were possible:
+
+- **The framework's bundle**, about 130 certificate authorities (about 60 KB of flash). Any of them could vouch for `git.twis.la`.
+- **Pin the server's certificate**, as the Gemini App does for capsules. The server's certificate is replaced every few months, so a pin would ask the question again at every renewal.
+- **Carry the roots the server's chain ends in:** `ISRG Root X1` (RSA 4096) and `ISRG Root X2` (ECDSA P-384), the Let's Encrypt roots, about 2.7 KB of flash (`src/platform/ca_roots.h`).
+
+We chose the third. The chain and the name are checked by mbedTLS during the handshake. It trusts one organisation's two roots, valid until 2035 and 2040, and a renewal changes nothing.
+
+## What it costs
+
+- **If the server moves to another CA, the device can no longer reach it**, and the next firmware, carrying that CA's root, has to come from the PC or the SD card. Both still work; they don't use TLS.
+- The roots are public data checked against the published fingerprints (listed in the file), refreshed by hand if Let's Encrypt ever changes them.
+
+## What it doesn't change
+
+The Update File's own signature (ADR 0003) is what decides what gets installed. A hijacked connection could hide a release, or serve an older signed one, but never make the device install firmware that isn't ours. The TLS check matters more for #4, where a token will travel over it.
+
+## Measured while building it
+
+A TLS connection to this server peaks at about 52 KB of heap, **the same whether the certificate is checked or not**, so skipping the check would have saved nothing. The cost is the connection itself (record buffers and handshake), not the trust decision.

site/content/dev/decisions/0010-debug-console-in-every-build.md

@@ -0,0 +1,38 @@
++++
+title = "The Debug Console is in every build, off until its owner switches it on"
+description = "There is one firmware. The Debug Console of ADR 0004 is compiled into it, and so are the commands that used to exist only in Debug Builds. It listens only while Settings → Debug Console is on, which is not the default, and it…"
+weight = 10
+
+[extra]
+docs = true
+source = "docs/adr/0010-debug-console-in-every-build.md"
+tag = "ADR 0010"
++++
+There is **one firmware**. The Debug Console of ADR 0004 is compiled into it, and so are the commands that used to exist only in Debug Builds. It listens only while **Settings → Debug Console** is on, which is not the default, and it lets in whoever proves they hold **the device's own token**. The `cardputer-adv-debug` environment, `RORO_DEBUG`, the `+debug` version and the token compiled in from the builder's machine are gone.
+
+ADR 0004 kept the console out of release builds with one argument: a console that runs commands is a remote control, so in a release nothing should listen. That argument was never whole: the Update Service has listened on TCP 3232 in every build since Firmware Updates exist, guarded by a signature. A listener that is off by default and guarded by a secret the device made itself is the same kind of trade, and what the split cost had grown:
+
+- **What was tested wasn't what shipped.** Development ran on Debug Builds; releases were a different binary, built to be published and never run by the person who wrote them.
+- **Debug Builds couldn't be published**, since each carried its builder's token. So the console, `rdbg.py`, screenshots and crash decoding were for whoever built the firmware, and nobody else.
+- **Rules that existed only to protect the console:** a Debug Build never installed a release (it would have lost the console), `update install … force` to do it anyway, "keep a Debug Build in the fallback slot", versions with `+debug` that had to compare equal to their release.
+- **CI built two firmwares** on every pull request and every tag.
+
+## How it works
+
+- **Off means nothing is there.** With the setting off, no socket listens, the console's task doesn't exist and neither does its 4 KB ring: a device that never uses the console pays for it in flash (30 KB more than the release build was) and 88 bytes of static RAM, measured. A missing or invalid stored setting counts as off.
+- **The token is the device's.** The first time the console is switched on, the device makes one from its hardware random generator: 100 bits, as 20 characters of Crockford's base32 (`K7QF-3M2X-9WBD-HT4P-6RNC`), shown on the Debug Console page and nowhere else. It can be replaced by one typed by hand, of 16 to 64 characters. It is stored with the other settings and is never printed on a console.
+- **The token never crosses the network.** The device sends 16 random bytes; the client answers with their HMAC-SHA256 keyed by the token. Someone on the same Wi-Fi who records a login has nothing they can use for the next one.
+- **Five wrong answers in a row** close the console to everyone for a minute, with a Notification naming the address they came from. A wrong answer still costs a second.
+- **`DBG` in the Status Bar** while the console listens, bright while a client is connected.
+- **USB serial can set it up:** `debug on`, `debug token <value>`, `debug token new`. `scripts/flash.sh --debug` uses them to give a freshly flashed device the developer's token. Whoever holds the cable can flash anything anyway (ADR 0003); the console itself can only switch itself off.
+- **Safe Mode** starts the console if it's switched on: the settings are read before Safe Mode is decided.
+
+## Consequences
+
+- **"Nothing listens" now rests on one stored setting**, not on absent code. That setting is typed, validated and host-tested, and its default is off; a bug that flipped it would have to come from code that already runs on the device.
+- **Whoever has the token and the network has the device:** the console, its keys, the SD card's files, a restart. Not its firmware: an update still has to be signed (ADR 0003).
+- **The stream is still plain text.** The token is safe from an eavesdropper; what the console prints, and the files it carries, are not. TLS would cost about 52 KB of the 107 KB there is, next to IRC's own connection: not for a console.
+- **An old `rdbg.py` can't talk to a new firmware**, and the reverse: the first line of the protocol changed. Accepted, with one user.
+- **A device whose settings are damaged has no console in Safe Mode**, only the signed update push. Before, a Debug Build always had it.
+- **The commands that crash, damage a download or fill a folder on purpose** are in every build. They need the cable or the token, like everything else.
+- **Releases already publish their ELF**, so `rdbg.py crash` fetches it when it isn't in `.pio/elves/`: crash reports can be decoded without having built the firmware.

site/content/dev/decisions/_index.md

@@ -0,0 +1,13 @@
++++
+title = "Decisions"
+description = "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."
+template = "guide-index.html"
+page_template = "guide-page.html"
+sort_by = "weight"
+weight = 3
+
+[extra]
+eyebrow = "Developer docs"
++++
+
+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.

site/content/dev/milestones/_index.md

@@ -0,0 +1,13 @@
++++
+title = "Milestones"
+description = "The plan of each stretch of work: the goal, the decisions made in the design round, what done means, and what was measured. Generated from docs/milestones/ in the repository."
+template = "guide-index.html"
+page_template = "guide-page.html"
+sort_by = "weight"
+weight = 4
+
+[extra]
+eyebrow = "Developer docs"
++++
+
+Each milestone starts with a design round of numbered questions, each with a recommended answer to accept or overrule, then a list of what "done" means, and ends with what was actually measured on the device. They are listed in the order they were done. Generated from `docs/milestones/` in the repository: edit those files, not these pages.

site/content/dev/milestones/f1.md

@@ -0,0 +1,169 @@
++++
+title = "Files and Notes"
+description = "Get at what's on the SD card from the device itself: browse it, look inside the files the firmware writes, copy, move, rename and delete, and keep notes. A side milestone, like G1 and S1; Files and Notes were M3's original second…"
+weight = 60
+
+[extra]
+docs = true
+source = "docs/milestones/F1.md"
+tag = "F1"
++++
+**Status:** in progress. The Storage App (issue #3) shipped as **v0.9.0** on 2026-10-06. Notes (#19) shipped as **v0.10.0** the same day. The card as a USB drive (#1) comes after.
+
+**Goal:** get at what's on the SD card from the device itself: browse it, look inside the files the firmware writes, copy, move, rename and delete, and keep notes. A side milestone, like G1 and S1; Files and Notes were M3's original second half (Q30, Q89).
+
+## The Storage App (issue #3)
+
+Until now the card could be looked at only through the Debug Console (`ls`, `get`, `put`), and Settings > Storage could only delete whole categories by age.
+
+**On the card today:** six top-level folders, `irc`, `wifi`, `updates`, `gnss`, `gemini` and `captures`. No `notes` yet; settings are in flash, not on the card.
+
+### Decisions (design round 2026-10-06)
+
+| # | Decision |
+|---|---|
+| Q128 | An App of its own, **Storage**, in the Launcher. **Settings > Storage goes away:** its usage figures, Storage Clean-up and "Erase SD card" move into the App, under **Maintenance**, behind a warning that these delete things for good. |
+| Q129 | A row shows the name, then the size or "folder", then the date modified. Folders first, then by name; `s` cycles the sort (name, date, size). The top line shows the path and the card's free space. |
+| Q130 | Nothing is hidden. **Read-only:** `/gemini/cache`; any file the firmware has open right now (today's IRC log, a Track or Capture being recorded, a file being received); and the top-level folders themselves, which can't be renamed or deleted though their contents can. **Everything else, the user's own data included, can be renamed, moved or deleted**, always after a confirmation. |
+| Q131 | One item at a time, with a clipboard: Enter opens; Back goes up, and leaves the App at the top; `c` copy, `x` cut, `v` paste into the current folder; `r` rename; `d` delete; `n` new folder; `i` details. |
+| Q132 | Copy, move and delete work on folders too, recursively. The confirmation says what's inside: "Delete *saved* and its 42 files?". |
+| Q133 | A copy is a job on the storage task in 4 KB pieces, with a progress Toast; Back cancels it. It checks free space first and asks before replacing anything. **Afterwards the sizes are compared**, not the contents: the driver is trusted since v0.6.1 (ADR 0007). A move within the card is a rename. |
+| Q134 | Viewers by type. **Text** (`.txt`, `.log`, `.gmi`, `.csv`, `.gpx`, and anything that looks like text): read from the card as you scroll, so size doesn't matter; logs open at the end. **`.pcap`:** the LoRa Scanner's packet list. **`.gpx`:** a summary (start, duration, points, distance), Tab for the text. **`.ota`:** version, size, whether the signature is valid; Enter installs through Update from SD. **Anything else:** a hex dump. |
+| Q135 | No editing: that comes with Notes (#19). |
+| Q136 | A listing holds **up to 256 entries**, packed, about 10 KB; a bigger folder shows the first 256 by name and says how many more there are. The App refuses to open below the memory floors (Q86). |
+| Q137 | **The Clock also sets the system time**, so files are dated correctly with GNSS alone and not only after NTP. A file dated before 2020 shows "-". |
+| Q138 | Console: `cp`, `mv` and `mkdir`, next to `ls` and `rm`. |
+| Q139 | Left out, each with its issue: selecting several items (#41), finding files by name (#42), opening a `.gmi` in the Gemini App (#43), a table view for `.csv` (#44), images (#45). |
+| Q140 | Ships as **v0.9.0** when done and checked. |
+
+### Done when
+
+- The Storage App lists any folder of the card with sizes and dates, sorted three ways, and says so when a folder has more than 256 entries.
+- A file can be copied, moved, renamed and deleted, and a folder too; a new folder can be made. Each destructive action asks first; a copy shows progress and can be cancelled.
+- The read-only rules of Q130 hold, with a reason given when something is refused.
+- Each viewer of Q134 opens its type, and a 1 MB text file scrolls without loading whole.
+- Maintenance shows the card's usage and does what Settings > Storage did, behind its warning; Settings no longer has a Storage row; the Storage Warning points at the Storage App.
+- A file written with only a GNSS Fix (no Wi-Fi) is dated correctly.
+- Free heap stays above the floors with the App open, Wi-Fi and IRC on TLS.
+
+### Work breakdown
+
+1. **Model** (host-tested): paths and names, the read-only rules, the packed listing and its sorts, file types, sizes and dates for display, the GPX summary.
+2. **Card operations:** listing a folder, copy, move, delete (recursive, counted), new folder, as storage jobs with progress and cancel; `cp`, `mv`, `mkdir`; the Clock sets the system time.
+3. **The App:** browsing, the clipboard, dialogs, details.
+4. **Maintenance:** usage, Clean-up and Erase moved in from Settings, with the warning.
+5. **Viewers:** text, hex, `.pcap`, `.gpx`, `.ota`.
+6. **Checks on the device**, recorded here.
+
+### As built
+
+- **`FileOps`** (`src/services/file_ops`) does the card's work for the App and for the console alike: list, count, copy, move, delete, new folder. One operation at a time on the storage task, **in turns of about 150 ms** that queue themselves again, so Log lines and a Capture are written in between. The rules of Q130 are checked there, whoever asks.
+- **A listing reads the folder straight from FatFs.** Through the Arduino `File`, every entry was looked up by name again for its size and again for its date: 329 entries took over two seconds. One pass now, and it's there before the screen has redrawn. Counting, copying and deleting still walk with `File`; they show progress and can be stopped.
+- **A copy shows its progress in a box in the App**, not a Toast (Q133): it has a bar and says Back cancels. A cancelled or failed copy deletes what it had written. The copy gets today's date, like `cp`.
+- **The viewers** (`src/apps/file_viewer`, models in `lib/files`): text through `TextPager`, which reads about a kilobyte around the screen and wraps at spaces, 38 columns; going back a line wraps the paragraph before again, so a file reads the same in both directions. A `.pcap`, a `.gpx` and an `.ota` are read through once by a storage job, in the same 150 ms turns. An Update File is fed to the installer's own parser with a sink that writes nothing, so "would it install" is the same answer an install gives.
+- **Tab** in a viewer shows the same file as hex, or as text (not in Q134).
+- **Maintenance** is the last row at the top of the card, and `m` anywhere in the App. It's the old Settings > Storage page behind a dialog.
+- **The Storage Warning** was only ever a Toast; "selecting it opens Storage Clean-up" (CONTEXT.md) was never built. It now reads "SD card over 80% full: see Storage".
+- **Console:** `cp`, `mv`, `mkdir` (Q138), and `rm` and `du` through the same code, so `rm` now takes folders and follows the rules; `ls` shows dates. Debug Builds: `sd fill <folder> <count>` makes test files.
+
+### Checks on the device (2026-10-06, v0.8.1-2 Debug Build)
+
+All in a scratch folder, `/f1test`, removed afterwards.
+
+| Check | Result |
+|---|---|
+| Host tests | 424 pass (411 before the viewers' models) |
+| Browsing | Folders first, sizes and dates, the three sorts; a 300-file and a 329-file folder show "first 256 of 300" and "of 329" |
+| New folder, rename, copy, cut and paste, delete | Each works on a file and on a folder; a copy next to its original is named `(2)`; a name in the way asks "Replace it?" |
+| A folder of 11 files, 8.4 MB, copied | 19.4 s, 435 KB/s, the bar moving; two Log lines queued meanwhile were written |
+| The same copy cancelled at 1.8 MB | "Cancelled: nothing was copied", and nothing was left behind |
+| Delete | 341 files in 9.7 s; the dialog had counted them first |
+| Read-only rules | `/irc`, `/gnss` (top-level folders), `/`, `/gemini/cache` and a folder made inside it, a folder into itself, a name with `:`; a Capture being recorded and the folder holding it; a folder under `/irc` while IRC runs. Each refused with its reason; the Capture could still be copied |
+| Text | A 1 MB log opens at its last line at once; top, pages, lines; a file without an extension that looks like text opens as text |
+| Hex | A 5 KB binary file; Tab from any other viewer |
+| `.pcap` | A LoRa Capture: 3 packets as the Scanner lists them, Enter shows the Meshtastic header and bytes |
+| `.gpx` | 400 points: start, 33 min 15 s, 4.68 km; Tab shows the text |
+| `.ota` | A signed file: version, "intact", "older than what's running", Enter asks to install (not confirmed). A tampered one: "image corrupted (hash mismatch)" |
+| Maintenance | The warning, then usage, Clean-up's categories and Erase (not run) |
+| Date with GNSS only | NTP pointed at an address that doesn't answer, restart: the Clock came from the Fix, and a folder made then is dated 2026-10-06 08:39. A Track from the day before, written the same way by v0.8.1, shows "-" |
+| Memory | IRC connected, the App open on 256 entries: 61 KB free (70 KB before opening). Lowest since boot 29.7 KB, during IRC's TLS handshake |
+| Stacks | `storage` 3.1 KB free of 6 KB at worst, `loopTask` 1.5 KB |
+
+**Not checked by hand:** how the keys feel on the device itself; everything above was driven through the Debug Console's `key` command and screenshots.
+
+**One slip during the checks:** a scripted key sequence ran in the wrong folder and renamed `/gemini/saved` to `saved2`, then copied it to the top of the card. Both were put right at once (renamed back, the copy deleted; 7 files, 53,798 bytes, as before).
+
+**Found on the way:** a panic at Wi-Fi join, there since v0.7.0 (SNTP started twice, issue #46). Fixed in v0.9.0.
+
+## Notes (issue #19)
+
+Plain text notes on the SD card, written on the device. Q30 settled the base: `.txt` files in `/notes`, created, edited and deleted from the device, never offered by Storage Clean-up.
+
+### Decisions (design round 2026-10-06)
+
+| # | Decision |
+|---|---|
+| Q141 | A **Notes** App in the Launcher. One row per note: its first line as the title, then the date. Newest first; `s` switches to by name. `n` new, Enter opens, `d` deletes after a confirmation, `r` renames the file. |
+| Q142 | A new note's file name is never typed: it comes from the first line when the note is first saved (`shopping-list.txt`), or `note-20261006-0919.txt` if that line is empty. It doesn't change afterwards unless the note is renamed. |
+| Q143 | **Autosave, no "discard changes?" prompt:** five seconds after the last key, on leaving the note or the App, and when the screen turns off. A save writes a temporary file and renames it over the note, so a power cut loses the last few seconds at most. A temporary file left behind is offered back at the next open. |
+| Q144 | The whole note is in memory while it's edited, up to **16 KB**. A bigger text file opens read-only in the Storage App's viewer. The App refuses to open below the memory floors (Q86). **Editing files of any size must come in a later release: issue #47.** |
+| Q145 | The editor wraps at spaces, 38 columns by 8 rows, with a line for the name and the state. Enter is a new line, Del deletes backwards, Fn+arrows move (the Text Entry rule), Ctrl+A and Ctrl+E go to the start and the end of the line, Tab types two spaces, Back saves and returns. The Compose Key works as elsewhere. |
+| Q146 | The Storage App's text viewer gets `e`: edit this file with the same editor, for a text file up to 16 KB that isn't read-only. That lifts Q135 without Apps opening each other (#43 stays). |
+| Q147 | The list is flat: the files directly in `/notes`. Sub-folders are reached through the Storage App. |
+| Q148 | UTF-8, LF line ends; a file with CRLF is saved back with LF. Characters the font lacks are kept on save. |
+| Q149 | Left out, each with its issue: editing files of any size (#47), searching inside notes (#48), undo (#49), selecting and copying text (#50). |
+| Q150 | Ships as **v0.10.0** when built and checked on the device. |
+
+### Done when
+
+- A note can be started, typed with accents, left and found again in the list under its first line; renamed; deleted after a confirmation.
+- What's typed is on the card five seconds after the last key, and after Back, Home, or the screen turning off, without a prompt.
+- Pulling the power while typing loses a few seconds at most, and the note is never left empty or half-written.
+- The cursor moves by character and by line through wrapped text, and the screen follows it; a 16 KB note edits without lag.
+- A note at 16 KB refuses more text and says so; a bigger file opens read-only.
+- `e` in the Storage App's text viewer edits a file; a read-only one is refused with its reason.
+- Free heap stays above the floors with a 16 KB note open and IRC connected.
+
+### Work breakdown
+
+1. **Model** (host-tested): the text buffer with its cursor, wrapping and scrolling; file names from first lines.
+2. **The editor on the device:** loading, drawing, keys, autosave through a temporary file, recovery.
+3. **The Notes App:** the list with titles, new, rename, delete.
+4. **`e` in the Storage App.**
+5. **Checks on the device**, recorded here.
+
+### As built
+
+- **`NoteText`** (`lib/notes`, host-tested) is the text, its cursor and the screen around it. A line owns the space or the newline it ends with, so every byte is on exactly one line and the cursor has one place for each. **No index of lines is kept:** a note of newlines alone would need twice its own size for one. Where a line starts is worked out from the start of its paragraph.
+- **One buffer, 16 KB, for as long as the editor is open.** It's reserved when the note is opened, the file is read straight into it, and typing never makes it grow. On this device a failed allocation is an abort, and with IRC connected the largest free block is about 31 KB whatever the total says: the first version read the file into one string and copied it into another, and opening a full note with IRC connected restarted the device. The editor now also refuses to open without a free block of 24 KB.
+- **`NoteEditor`** (`src/apps/note_editor`) is shared by the Notes App and the Storage App's `e`. A save runs on the storage task while the main loop waits for it: no second copy of the note, and at 16 KB the wait is a fraction of a second at a moment when nobody has typed for five.
+- **A save** writes `<note>.tmp`, checks its size, deletes the note and renames the temporary file (FAT can't rename onto a file). A cut between the last two steps leaves only the `.tmp`: the Notes list puts such a file back under its name. A `.tmp` next to its note is an unfinished save: opening the note offers it.
+- **Titles** in the list are read from the card for the eight rows on screen, when the list moves.
+- **Before powering off**, the firmware now leaves the foreground App (`PowerService::beforePowerOff`), which makes the editor save.
+- Shift or Alt with Fn+Up and Fn+Down moves a page (not in Q145).
+
+### Found on the way
+
+- **The screen could go "off" for one tick after a key sent through the Debug Console**, and the next key was then swallowed as a wake-up: the `key` command stamps the power timer from `millis()`, the power tick compares with its pass's older time, and the unsigned difference read as 49 days idle. The same shape as #46. Fixed in `PowerPolicy::update` with a test. Keys from the keyboard were never affected. It explains remote keys "lost" in earlier sessions.
+- **`scripts/rdbg.py` held back piped lines** written while it was still connecting, until the next line came (a buffered `readline()` behind `select()`). Fixed.
+
+### Checks on the device (2026-10-06, Debug Build of branch `notes`)
+
+Test notes were made in `/notes` and removed afterwards; the folder is left, empty.
+
+| Check | Result |
+|---|---|
+| Host tests | 439 pass |
+| A first note | "No notes yet", `n`, typed three lines: the top line says "typing", then "saved" five seconds after the last key, under `shopping-list.txt`. 63 keys in a row all arrived |
+| Leaving | Back saves and returns to the list, which shows the note under its first line. Home in the middle of a new note saved it as `ideas.txt` |
+| The cursor | Down, Right, an insertion in the middle of a line; the screen scrolls through a note of about 230 lines |
+| A power cut | Typed, waited seven seconds, typed more and restarted the device at once (`reset`): the note has what was saved, whole, and not the last keys |
+| An unfinished save | A `.tmp` next to its note: "Unsaved copy... Keep the note / Use the copy"; using it brings its text back and saves it. A `.tmp` alone was put back under its name when the list opened |
+| 16 KB | A note of exactly 16,384 bytes opens and scrolls; one more character: "This note is full: 16 KB". A file of 16,398 bytes: "Too big to edit: 16 KB at most" |
+| Rename, delete, sort | `r` renamed `orphan.txt` to `orphan2.txt`; `d` asked, then deleted; `s` switched between newest first and by file name |
+| `e` in the Storage App | A note opened from the text viewer, edited, saved on Back; the listing shows its new size |
+| Memory | IRC connected, the full 16 KB note open: 55 KB free, largest block 31.7 KB (72 KB free before opening) |
+
+**Not checked:** accents through the Compose Key and Ctrl+A / Ctrl+E (the remote `key` command can't send them; the model's tests cover both), the power button's save (it needs a hand on the device), a missing card, and how typing feels on the keyboard itself.
+
+**One slip during the checks:** a key sequence sent right after a restart opened IRC instead of Notes, and the test letters went into IRC's input line. Nothing was sent: the line was cleared and the App left. IRC connected to Libera as it does when opened.

site/content/dev/milestones/g1.md

@@ -0,0 +1,69 @@
++++
+title = "Gemini client"
+description = "Browse Geminispace from the Cardputer: fetch and read gemtext over TLS, follow links, answer input prompts, keep bookmarks, and save pages to the SD card to read later, offline. A side milestone between M2 and M3, tagged v0.5.0…"
+weight = 30
+
+[extra]
+docs = true
+source = "docs/milestones/G1.md"
+tag = "G1"
++++
+**Status:** done, tagged v0.5.0. Every step was checked on the device; reading Saved Pages with Wi-Fi off was checked by hand (2026-10-05).
+
+**Goal:** browse Geminispace from the Cardputer: fetch and read gemtext over TLS, follow links, answer input prompts, keep bookmarks, and save pages to the SD card to read later, offline. A side milestone between M2 and M3, tagged v0.5.0 when done.
+
+Gemini (geminiprotocol.net): one request per TLS connection on port 1965, the request is the URL and CRLF, the response a `<status> <meta>` header line, then the body. Most capsules use self-signed certificates: trust on first use is the norm.
+
+## Decisions (design round 2026-10-05)
+
+| # | Decision |
+|---|---|
+| Q70 | A milestone of its own, **G1**, before M3: plan, tests first, measured on the device, tagged v0.5.0. |
+| Q71 | **TOFU:** the first certificate seen for a host is pinned (SHA-256, in NVS). If it changes, the page isn't shown; a dialog shows both fingerprints and asks whether to trust the new one. Self-signed or expired certificates are fine; only a change counts. |
+| Q72 | Responses: 1x input (11 hidden, for passwords), 2x content, up to 5 redirects (3x), 4x/5x errors with the server's message. 6x (client certificates): "not supported". |
+| Q73 | `text/gemini` is rendered, other `text/*` shown as plain text. Anything else can be saved to `/gemini/downloads/`, not shown. |
+| Q74 | Up to **64 KB on screen**, larger pages truncated with a notice. Saving streams to the card, so a larger page is saved whole. |
+| Q75 | Gemtext rendering: text wrapped to the 40-column screen; `#`/`##`/`###` headings in bold and accent; `*` lists with bullets; `>` quotes indented and muted; preformatted blocks unwrapped, Left/Right to scroll; `=>` links with their label, numbered. |
+| Q76 | Up/Down scroll; Tab and Shift+Tab move between links; Enter follows; Backspace goes back; `g` opens the address line. Links to other protocols show their URL and aren't followed. |
+| Q77 | Back history of 20 URLs in RAM, with scroll positions; going back refetches (or reopens a Saved Page). **Bookmarks** in `/gemini/bookmarks.gmi` (a gemtext page, shown on the start page); `b` adds the current page. Without a card, a built-in start page. |
+| Q78 | Start page: bookmarks, then Saved Pages, then defaults: geminiprotocol.net, a search engine (kennedy.gemi.dev), an aggregator (Cosmos; Antenna was down when measured). |
+| Q79 | UTF-8 decoded; characters outside the Latin-1 fonts shown as `?`. |
+| Q80 | IRC and Gemini can run together: each fetch opens one connection, reads and closes it. If there isn't memory for a second TLS connection, the fetch fails with a clear message and IRC is untouched. Measured in step 1. |
+| Q81 | Debug aid: `gemini get <url>` prints the status, MIME type, size, certificate fingerprint and the first lines. URL resolution (RFC 3986), the response header and gemtext parsing are host-tested. |
+| Q82 | `s` saves the page on screen as a **Saved Page**: `/gemini/saved/<host>/<path>.gmi`, the gemtext as received plus a first line with its URL and save date. Saving again replaces it, and says so. |
+| Q83 | `S` saves the page and the pages it links to, one level deep: gemtext only, same host only, at most 30 pages, in the background with a progress Toast. |
+| Q84 | The start page lists Saved Pages, newest first, grouped by capsule; they open with no network. In a Saved Page, a link to another Saved Page opens the saved copy; other links fetch online if Wi-Fi is up, or say "not saved, offline". A Saved Page shows when it was saved; `r` refreshes it. |
+| Q86 | *Decided after step 1, revised after Q88.* **Two floors:** free heap stays above 40 KB in steady state; a fetch refuses to start below **55 KB** free ("not enough memory: stop IRC or retry"). The firmware's own allocations during a fetch (a page in RAM, a window) keep 20 KB free. With IRC connected, the TLS connection itself can briefly take the heap lower, depending on the server's record sizes: measured 24, 19.5, 15.5 and **13 KB**. *Accepted:* about 12 KB for a moment during a fetch with IRC up, rather than refusing most fetches (a 70 KB start floor) or dropping IRC's connection for each page. |
+| Q87 | *Decided in step 3.* **With a card, every page streams to `/gemini/cache/page.gmi`** in 1 KB pieces while its TLS connection is open; once the connection closes and its ~45 KB is back, the page is loaded into RAM as far as the 40 KB floor allows. The whole page stays on the card (Saved Pages copy it). Without a card, the page goes straight to RAM under the same two floors. Pages are held as lines in 4 KB chunks, never one large block (the largest free block with IRC connected is about 31 KB). |
+| Q88 | *Added after step 6.* **A page bigger than memory allows is read from the card as you scroll.** Opening it, one pass over its file counts the lines, records where every 64th starts (and whether it's inside a preformatted block), and loads the first window. Scrolling near either end of the window reads the next or previous one in the background, keeping the line on top of the screen where it is; the scrollbar follows the whole page. Display pages alternate between two cache files, so the one on screen is never overwritten by the next fetch; background jobs use a third. |
+| Q85 | Saved Pages are deleted from the App only (`d`, with confirmation), never by Storage Clean-up's age rules, like Notes. |
+
+## Measured (step 1)
+
+- `gemini://geminiprotocol.net/`: `20 text/gemini`, 1,184 bytes, TLS handshake 0.7–1.1 s, whole fetch 0.7–1.1 s; kennedy.gemi.dev 1.9 s. The fetch task's stack peaks at about 3.6 KB of 6.
+- **Heap, Debug Build, IRC connected over TLS:** about 68 KB free before a fetch. After the handshake the fetch holds about 32 KB (36–40 KB left); the handshake itself (certificate chain parsed with the 16 KB receive buffer allocated) dips to about **24 KB** for a second or two. Nothing leaks: the heap after matches the heap before.
+- **Step 3, Cosmos (31.6 KB) with IRC connected:** first stopped at 4.6 KB (RAM only, the transfer's 20 KB floor). Streamed to the card: the whole page on the card, 20 KB of it loaded, lowest free heap 19.5 KB during the transfer and 43 KB once loaded. Without IRC: the whole page in RAM. Redirects (Cosmos `31`), input (`10`), not found (`51`) and a changed certificate (refused, both fingerprints shown) all checked on the device.
+- **Steps 4–6 on the device:** Project Gemini and its relative links, Back with the scroll restored, a refused YouTube link; `b` bookmarks, `s` saves (and says when it replaced an older copy), `S` saved 6 of 6 pages, the start page lists both; a Saved Page opens from the card with its origin, its saved links open saved copies, `r` refreshes, `d` asks first; Kennedy's input prompt sent "cardputer" and got 87 results; emoji drawn as `?`.
+- **A bug found there:** refreshing first loaded the whole Saved Page into RAM just to read its origin, next to the App's copy and a TLS connection: the heap fell to 436 bytes. Now only the first line is read, and every fetch (pages, saves, refreshes) checks the 55 KB start floor. Lowest since boot afterwards: 53.8 KB.
+- **Windowed pages (Q88), Cosmos with IRC connected:** 226 of 419 lines in memory at first; paging down loaded lines 192–419 in one window, scrolling back up loaded 64 onwards, then 0 onwards. Window budgets count the memory the old window gives back.
+- **Heap during a fetch with IRC connected:** lowest 13–15.5 KB in later runs (24 and 19.5 KB earlier), the TLS receive buffers varying with the server's records. Accepted (Q86, revised).
+- Antenna (`warmedal.se`) doesn't answer, from the PC either; the default aggregator becomes Cosmos (`gemini://skyjake.fi/~Cosmos/`, which redirects to `cosmos.skyjake.fi`).
+
+## Done when
+
+- `gemini get gemini://geminiprotocol.net/` prints the header, size and fingerprint on the console.
+- The Gemini App opens the start page, follows links (relative ones included), goes back, and follows redirects.
+- An input prompt (e.g. a search) takes a query and shows the results.
+- A changed certificate stops the page and asks.
+- `s` saves a page, `S` a page and its links; with Wi-Fi off, Saved Pages open and their saved links work.
+- Bookmarks are added with `b` and listed on the start page.
+- With IRC connected over TLS, a fetch still works, and the free heap stays above 40 KB.
+
+## Work breakdown
+
+1. **Two TLS connections:** measure the heap with IRC connected while a Gemini fetch runs.
+2. **Parsers** (host-tested): URL parsing and relative resolution, the response header, gemtext lines.
+3. **Fetch** on its own task, with TOFU and `gemini get`.
+4. **Gemini App:** rendering, scrolling, links, history, the address line.
+5. **Input prompts, redirects, bookmarks, downloads.**
+6. **Saved Pages,** then saving with linked pages.

site/content/dev/milestones/m2.md

@@ -0,0 +1,67 @@
++++
+title = "GNSS"
+description = "The device knows where it is and what time it is without a network: a GNSS Service in the background, a GNSS App with the position and a sky view of the satellites, the clock set from satellites when there's no NTP, and Tracks…"
+weight = 20
+
+[extra]
+docs = true
+source = "docs/milestones/M2.md"
+tag = "M2"
++++
+**Status:** done on the device (branch `m2`): every "Done when" item below is met.
+
+## Measured
+
+- **Cold start** (`$PCAS10,2`) to a 3D Fix, by a window: **73 s**, 5 satellites used of 8 in view. A restart of the ESP32 alone keeps the receiver's Fix (the Cap stays powered).
+- By a window: 3D Fix from GPS, GLONASS, Galileo and BeiDou, up to 14 of 17 satellites used, HDOP 1.0–1.3.
+- **Heap, Debug Build, GNSS on, IRC on TLS** (floor 40 KB; v0.2.1 had a 79 KB low):
+
+  | | Free | Lowest |
+  |---|---|---|
+  | Start of M2 | 31 KB | 12.6 KB |
+  | Stacks and buffers trimmed by measurement | 46 KB | 18 KB |
+  | mDNS removed | 54 KB | 34 KB |
+  | Framework rebuilt with smaller TLS buffers (ADR 0006) | **78 KB** | **59 KB** |
+
+  Under the heaviest combined load measured (IRC, two refused installs, a 1.6 MB put and get), the low is 46 KB. The cost had come mostly from the OTA and Debug Build work, not GNSS. Stacks were set to measured peak plus about 2 KB (loop 6 KB, update 5, storage 6, irc 6); after a TLS handshake the irc task has 1.7 KB left. IRC can now be stopped by hand (`/quit` in any state, `irc stop`), which frees its TLS memory.
+
+**Goal:** the device knows where it is and what time it is without a network: a GNSS Service in the background, a GNSS App with the position and a sky view of the satellites, the clock set from satellites when there's no NTP, and Tracks recorded to the SD card.
+
+**Hardware:** the Cap LoRa-1262 carries an ATGM336H-6N (AT6668), multi-constellation (GPS, BeiDou, Galileo, GLONASS, QZSS), with a ceramic antenna. NMEA over UART, 115200 8N1. **Measured (step 1, `gnss probe`): RX GPIO 15, TX GPIO 13, 115200 8N1**, as in Meshtastic's board file; M5Stack's page names GPIO 8 and 9, which are the internal I2C bus the keyboard controller sits on. Output is NMEA 4.10 style: `GN` RMC, VTG and GGA, one GSA per constellation with the system ID (1 GPS, 2 GLONASS, 3 Galileo, 4 BeiDou, 5 QZSS) in its last field, and a GSV sequence per constellation and signal (`GP`, `GL`, `GA`, …) with the signal ID last. RMC carries a time even without a Fix (status `V`), so only a Fix makes it trustworthy.
+
+## Decisions (design round 2026-10-04)
+
+| # | Decision |
+|---|---|
+| Q58 | Settings has a GNSS On/Off switch, **On by default**. Off puts the receiver in standby. *Measured:* `$PCAS12,<seconds>` (CASIC) stops its output within a second, for up to at least 65535 s, and any command wakes it within a second; Off sends `PCAS12,65535` (renewed hourly), On sends a hot start, `PCAS10,0`. |
+| Q59 | The **GNSS App** has two views, switched with Tab. *Position*: latitude, longitude, altitude, speed, course, Fix (none / 2D / 3D), satellites used and in view, HDOP, UTC time. *Sky*: the satellites placed by azimuth and elevation, coloured by constellation, filled when used in the Fix. |
+| Q60 | "Radar" in M2 means the Sky view. A radar of other Nodes by distance and bearing needs the mesh: M4. |
+| Q61 | The **Status Bar** shows a GNSS mark: absent when off, muted while searching, normal with a 2D Fix, with the satellite count with a 3D Fix. |
+| Q62 | GNSS time **sets the clock once there's a Fix**, and refreshes it every 10 minutes. *Revised in step 3:* the clock's trust order from M0 (Mesh < NTP < GNSS) already ranks GNSS above NTP, which is right: GNSS time is at least as accurate. So GNSS also corrects a clock NTP set, not only an unset one. |
+| Q63 | A **Track** is started and stopped in the GNSS App. It's written as GPX to `/gnss/tracks/<YYYYMMDD-HHMMSS>.gpx`, a point every 5 s when the position moved more than 5 m. It keeps recording with the App closed, with a Toast on start and stop and a Status Bar mark, and gets its own Storage Clean-up category. |
+| Q64 | Coordinates in **decimal degrees plus the Maidenhead locator**; a Settings switch for degrees, minutes and seconds. Metric units only. |
+| Q65 | **The position never leaves the device in M2.** Sharing it over the mesh, and at what precision, is decided in M4. |
+| Q66 | **Our own NMEA parser**, host-tested: RMC, GGA, GSA and GSV, with each talker ID mapped to its constellation. TinyGPSPlus (named in ADR 0001) doesn't track the satellite list across constellations, which the Sky view needs. |
+| Q67 | The receiver keeps its **defaults** (all constellations, 1 Hz). No receiver settings. Time to first fix is measured and recorded here. |
+| Q68 | Debug aids: `gnss status`, and `gnss nmea on/off` to stream the raw sentences to the console (USB serial and Debug Console). Raw NMEA is never written to the card. |
+
+**Lesson (step 3):** the first probe also tried the pins swapped, driving the receiver's output line from the ESP32 for about a second. The receiver then went silent until a full power cycle (an ESP32 restart doesn't cut the Cap's power). Never drive GPIO 15.
+
+## Done when
+
+- The GNSS Service reads NMEA in the background whatever App is on screen, and a 3D Fix appears outdoors.
+- The GNSS App shows the Position and Sky views, both live.
+- The Status Bar shows the GNSS mark per Q61.
+- With no Wi-Fi, the clock is set from GNSS after the first Fix.
+- A Track records while the App is closed, survives the screen turning off, and opens as valid GPX on the PC.
+- Settings → GNSS Off stops it (and the Status Bar mark goes away); On brings it back.
+- Free heap stays above about 40 KB with GNSS, Wi-Fi, IRC on TLS and the UI running.
+
+## Work breakdown
+
+1. **Hardware check:** a `gnss probe` command reads the candidate UART pins and reports which carries NMEA, at what baud rate, and which talker IDs. Then the standby command (Q58) and a first time to first fix.
+2. **NMEA parser** (host-tested): checksum, RMC, GGA, GSA, GSV across constellations, merged into one GNSS state (Fix, position, time, satellites).
+3. **GNSS Service:** UART on its own task, the parser, `gnss status` and `gnss nmea`, Settings On/Off.
+4. **Clock from GNSS** (Q62), and the Status Bar mark (Q61).
+5. **GNSS App:** Position view, Maidenhead and coordinate formats (host-tested), then the Sky view.
+6. **Tracks:** the 5 s / 5 m rule and GPX writing (host-tested), background recording, Clean-up category.

site/content/dev/milestones/m3.md

@@ -0,0 +1,77 @@
++++
+title = "Radio bring-up: the LoRa Scanner"
+description = "The LoRa radio on the Cap works, receive only: a Radio Service owns it and shares the SPI bus with the SD card safely, and a LoRa Scanner App shows what's on the air, either packets (Sniffer) or energy across the band (Sweep).…"
+weight = 40
+
+[extra]
+docs = true
+source = "docs/milestones/M3.md"
+tag = "M3"
++++
+**Status:** done, tagged v0.6.0. Everything was checked on the device except one "Done when" item: Sweep was never tried against a known transmitter (see below). The listening hour heard nothing, so by Q104 **a reference Meshtastic node is a requirement for M4**.
+
+**Goal:** the LoRa radio on the Cap works, receive only: a Radio Service owns it and shares the SPI bus with the SD card safely, and a LoRa Scanner App shows what's on the air, either packets (Sniffer) or energy across the band (Sweep). Nothing in M3 can transmit. The mesh comes on top of this in M4 (receive) and M5 (transmit).
+
+**Hardware:** the Cap LoRa-1262 carries an SX1262 (868–923 MHz, +22 dBm) with an RP-SMA antenna. Pins, as in Meshtastic's board file for the Cardputer ADV: **NSS 5, RST 3, DIO1 (IRQ) 4, BUSY 6**, on the SPI bus shared with the microSD card (SCK 40, MISO 39, MOSI 14; card CS 12). Meshtastic uses DIO2 as the RF switch and DIO3 for a 1.8 V TCXO, marked optional. M5Stack's page adds an FM8625H antenna switch enabled by P0 of a PI4IOE5V6408 I/O expander on the internal I2C bus, address not given; Meshtastic doesn't mention it. Step 1 measures which is true.
+
+**No other LoRa device yet.** meshmap.net (2026-10-05) lists two Meshtastic nodes within 10 km of the desk and six within 30 km, with positions blurred by a few km; none is known to be in range. M3 needs none: it only receives.
+
+## Measured
+
+- **Internal I2C bus (8/9):** 0x18 (ES8311 codec), 0x34 (TCA8418 keyboard), **0x43 (PI4IOE5V6408, ID register 0xA2)**, 0x69 (BMI270 IMU).
+- **The SX1262 answers** on NSS 5, RST 3, DIO1 4, BUSY 6. Its version string reads `SX1261 V2D 2D02`, which SX1262 chips report too. **The 1.8 V TCXO works** on the first try; the radio is ready 38 ms after `begin`.
+- **The expander's P0 connects the antenna; it's required.** At power-on P0 is an input (direction 0x00, high-impedance 0xFF), and the receiver reads a flat **-111.9 dBm** at 869.525 MHz, BW 250 kHz: the chip's own floor, deaf. With P0 driven high, the noise floor is **-87 to -94 dBm**: the antenna hearing the room. So the Radio Service drives P0 high at boot (Q91).
+- **DIO2 doesn't change reception** (within ±2 dB over three runs, P0 high). It likely selects TX versus RX in the FM8625H; it stays the RF switch, as in Meshtastic.
+- **The noise floor at the desk is high** (-87 to -94 dBm, varying run to run), about 25 dB above thermal noise for 250 kHz. Something nearby is loud, possibly the Cardputer itself or the PC; Sweep (step 5) should show where it sits.
+- **Step 2:** presets, frequencies and the channel hash are checked against Meshtastic's source (`MeshRadio.h`, `RadioInterface.cpp`): LongFast and the default key give hash 8, MediumFast 31, as Meshtastic shows. Captures were checked with TShark 4.2.5: every LoRaTap field reads back. Wireshark ignores the spec's quarter-dB packet RSSI below 0 dB SNR, so packet RSSI is plain dBm.
+- **Step 3:** the DIO1 interrupt works (a 100 ms receive timeout wakes the task after 105 ms). While listening: four 1.7 MB uploads and Gemini pages to the card, no radio or card errors (the card refuses a write about once in five uploads with the radio asleep too; `put` now catches it, and issue #21 follows the cause). The ring takes 9.8 KB while listening; the radio task's stack peaks at 2.0 KB.
+- **No packets yet, and a loud desk.** Twenty minutes on LongFast and on LoRaWAN's three uplink frequencies (SF7, SF9, SF12): no packet and no header, valid or not. The noise floor reads -83 to -94 dBm, against -112 dBm with the antenna switched off: 20 to 30 dB lost to something nearby, not the screen and not the GNSS receiver. Preamble detections are false alarms at this noise level (more on an empty frequency, 869.0 MHz, than on LongFast).
+- **Step 4:** a Capture made on the device reads back in TShark field for field (time, frequency, SF, RSSI, SNR, payload). A Capture keeps the radio listening with the App closed; stopping it puts the radio back to sleep.
+- **Step 5:** a pass across 863–870 MHz (71 steps, the strongest of three RSSI readings at each, measured at 125 kHz) takes about 607 ms. At the desk the band is **flat at -100 to -102 dBm**, about 15 dB above the chip's own floor at 125 kHz, with a steady carrier at 863.2 MHz (-89 dBm at its strongest) and fainter lines elsewhere: broadband noise from nearby electronics rather than a transmitter. Sweep's waterfall takes 2.6 KB while shown; 91.9 KB free during a Sweep. The radio task's stack peaks at 1.9 KB.
+- **Outside, on battery (step 6).** The noise is no lower than at the desk: a Sweep floor of -96 to -99 dBm (median -97) with Wi-Fi on, -99 to -100 with Wi-Fi off, so Wi-Fi accounts for 2 or 3 dB. The same narrow peaks come back on every pass, at 863.2, 863.6, 864.4, 864.8, 865.9, 866.3, 867.8, 869.0 and 869.4 MHz (-88 to -91 dBm), several of them 400 kHz apart; 869.4 MHz is the lower edge of LongFast's channel. A source that follows the device outside and onto its battery is the device: **about 15 dB of the floor is the Cardputer's own** (issue #20). At SF11 that puts the weakest decodable packet near -114 dBm on LongFast, against about -130 dBm for a quiet receiver.
+- **The listening hour (step 6, Q104):** 20:33 to 21:34 on 2026-10-05, outside, on battery, LongFast, with a Capture running. **0 packets, 0 headers**, 0 radio errors; noise -85 to -87 dBm at 250 kHz throughout; 860 preamble detections, all false alarms. The Capture holds its 24-byte header and nothing else. No restart in 1 h 10 min.
+- **Floors (Q86):** with the radio listening, Wi-Fi and IRC connected over TLS, 52.6 KB free (lowest 22.7 KB during the TLS handshake, the dip accepted in G1). Without IRC, 93 KB.
+- **Receive only:** nothing in `src` or `lib` calls a transmit function.
+- **Cost:** RadioLib 7.8.1 and the probe add 23.6 KB of flash and 656 bytes of static RAM to the release firmware (1,679,843 bytes of 3,342,336). The whole milestone: 51.8 KB of flash (1,708,091 bytes), 365 tests (27 new).
+
+## Decisions (design round 2026-10-05)
+
+| # | Decision |
+|---|---|
+| Q89 | **M3 is the radio only:** Radio Service, Sniffer, Sweep. Notes and the File Browser (Q30) move out to issue #3 and a Notes issue, as a later side milestone. |
+| Q90 | **RadioLib**, pinned (ADR 0001). SX1262 on NSS 5, RST 3, DIO1 4, BUSY 6; DIO2 as RF switch; TCXO at 1.8 V tried first, falling back to the crystal (Meshtastic's `TCXO_OPTIONAL`). |
+| Q91 | Step 1 is `lora probe`: chip status and version, which oscillator setting worked, and an I2C scan of the internal bus for the PI4IOE5V6408. If present, its P0 is set high at boot (harmless) and DIO2 stays the switch. A wrong switch receives deaf, so compare noise floors. |
+| Q92 | A **Radio Service** owns the SX1262: driver, bus lock, IRQ task. The LoRa Scanner uses it in M3; the Mesh Service sits on top of it in M4. |
+| Q93 | Every radio transfer takes the shared bus lock (`SPI.beginTransaction`, as the card does). DIO1's interrupt only wakes the task; no SPI in the ISR. **Done when** a Gemini page streams to the card while the Sniffer receives, with no lost packets and no card errors (`lora status` counters). |
+| Q94 | **Receive only:** the Radio Service has no transmit function in M3. It doesn't exist, rather than being unused. |
+| Q95 | Sniffer defaults: **EU868 LongFast**, 869.525 MHz, BW 250 kHz, SF 11, CR 4/5, sync word 0x2B, preamble 16 (Q19). The other Meshtastic presets are offered, plus custom settings. |
+| Q96 | The Sniffer lists packets (time, RSSI, SNR, frequency error, length; hex dump on Enter) **and decodes the Meshtastic header**: the first 16 bytes are never encrypted (destination, sender, packet ID, hop limit and hop start, channel hash, next hop, relay node). Host-tested. Payload decryption is M4. |
+| Q97 | A Sniffer **Capture** is pcap with **LoRaTap** headers (link type 270), for Wireshark. Started by hand, Status Bar mark, its own Clean-up category, the 90% rule. |
+| Q98 | **Sweep** steps across the Region's band (863–870 MHz) in 100 kHz steps by default, reading instant RSSI: bars with peak hold, and a waterfall, Wi-Fi Tools style. Optionally CAD on the preset's frequency to tell LoRa traffic from noise. |
+| Q99 | Sweep takes the radio and pauses the Sniffer, visibly (Q18). From M4 it pauses the Mesh Service the same way. |
+| Q100 | The Sniffer runs while the App is open **or a Capture is recording**; otherwise the radio sleeps. From M4 the Mesh Service keeps it on. |
+| Q101 | **Status Bar:** a radio mark while receiving, flashing on each packet; muted during a Sweep. |
+| Q102 | Debug aids: `lora status` (settings, counters, last RSSI/SNR, noise floor), `lora probe`, `lora rx on/off` (packets on the consoles). Raw packets are never written to the card outside a Capture. |
+| Q103 | A ring of the **last 32 packets** in RAM (about 9 KB at full length); older ones are dropped unless capturing. IRQ task stack trimmed by measurement; RadioLib's flash and RAM measured in step 1 against the floors. |
+| Q104 | **Done when** (below) includes an hour of listening on LongFast by a window. Real packets heard become M4 test fixtures. If none are heard, M3 still closes, and a reference Meshtastic node (Q21) becomes a requirement for M4. |
+
+## Done when
+
+- `lora probe` reports the SX1262, its oscillator setting and the RF switch arrangement, and the result is written here.
+- The Sniffer receives on LongFast with the App open or a Capture running, and the radio sleeps otherwise.
+- Sweep shows the noise floor across 863–870 MHz, and a known signal (a remote key fob, a 868 MHz sensor, anything) stands out. *Half met: the floor and the device's own steady peaks show; no known transmitter was tried.*
+- The shared-bus test passes (Q93): a Gemini page to the card while the Sniffer receives, no lost packets, no card errors.
+- A Capture opens in Wireshark with LoRaTap fields.
+- The Status Bar mark follows Q101.
+- One hour of LongFast listening by a window has been run and its result recorded here. *Run outside, on battery.*
+- Free heap stays above the floors (Q86) with the Sniffer, Wi-Fi, IRC on TLS and the UI running.
+- Nothing in the firmware can transmit.
+
+## Work breakdown
+
+1. **Hardware check:** RadioLib in the build, `lora probe` (Q91), flash and RAM cost measured.
+2. **Meshtastic header and LoRaTap** (host-tested): header parsing, presets and their radio settings, pcap/LoRaTap writing.
+3. **Radio Service:** receive on its own task behind the bus lock, the packet ring, `lora status` and `lora rx`, the shared-bus test.
+4. **LoRa Scanner App, Sniffer:** the packet list, details, preset choice, Captures, Status Bar mark.
+5. **Sweep:** the RSSI sweep, bars and waterfall, pausing the Sniffer.
+6. **Listening hour** and the measurements above, recorded here.

site/content/dev/milestones/ota.md

@@ -0,0 +1,41 @@
++++
+title = "Firmware Updates over Wi-Fi and from the SD card"
+description = "Install new firmware without a USB cable. Push it from the PC over Wi-Fi, or drop it on the SD card. Unsigned images are refused, and a broken update rolls back by itself."
+weight = 10
+
+[extra]
+docs = true
+source = "docs/milestones/OTA.md"
+tag = "OTA"
++++
+**Goal:** install new firmware without a USB cable. Push it from the PC over Wi-Fi, or drop it on the SD card. Unsigned images are refused, and a broken update rolls back by itself.
+
+## Decisions (design round 2026-10-03)
+
+| # | Decision |
+|---|---|
+| Q52 | Two sources: **push over Wi-Fi** from the PC, and **from the SD card**. Pulling from Gitea releases is deferred. |
+| Q53 | **Signed Update Files** (ECDSA P-256 over SHA-256). The private key stays in `~/.config/roro9stack/`, and the firmware embeds the public key (ADR 0003). |
+| Q54 | The device **always listens** for pushes on the LAN while Wi-Fi is Connected. *Revised in M2:* it was announced over mDNS as `roro9stack-<id>.local`; mDNS was removed to save RAM (it never crossed the dev box's routed network anyway). Pushes go to the IP shown in Settings → Firmware. |
+| Q55 | New firmware runs on **Probation**. It's confirmed once booted, UI drawn, Services started, 30 s without a crash, and Wi-Fi connected (if configured). Otherwise **Rollback**. A Toast reports either outcome. |
+| Q56 | **Downgrades are allowed**, with "older than the installed version" shown. |
+| Q57 | A valid push **installs right away**: progress screen, then reboot. The reboot waits for Text Entry to end, 60 s at most. |
+
+## Done when
+
+- `scripts/ota_keygen.sh` creates the key pair once. The public key is committed; the private key never is.
+- `scripts/flash.sh --ota` builds, signs and pushes to `roro9stack-<id>.local`. The device shows progress, reboots, and a Toast confirms the new version.
+- An Update File with a bad signature, a truncated or corrupted image, or no signature is refused, and the device keeps running.
+- Settings → About → **Update from SD** lists the `.ota` files in `/updates` and installs one.
+- A firmware that crashes during Probation rolls back to the previous version, and says so after the reboot.
+
+## Work breakdown
+
+1. **Update File format** (host-tested): header (magic, format, version, image size, SHA-256), signature, image. A streaming parser that hashes as it goes and decides accept / refuse / downgrade. The signature verifier sits behind an interface, so tests can inject one.
+2. **PC side:** key generation, `make_ota.py` (wraps `firmware.bin` into a signed `.ota`), and the push client. `flash.sh --ota` ties them together.
+3. **Device:** the Update Service.
+   - A listener on TCP 3232 plus mDNS.
+   - Writes the image to the inactive app slot, with the ECDSA check through mbedTLS.
+   - A progress screen, and a reboot that waits out Text Entry.
+4. **Probation and Rollback:** the health checks, confirming the image, and detecting a rollback after reboot to report it.
+5. **Update from SD:** the same parser, fed from the Storage Service's task (all card access stays there).

site/content/dev/milestones/r1.md

@@ -0,0 +1,182 @@
++++
+title = "Releases"
+description = "A tag is a release, built the same way every time and published where a device can find it."
+weight = 70
+
+[extra]
+docs = true
+source = "docs/milestones/R1.md"
+tag = "R1"
++++
+**Status:** in progress. CI and signed releases on Gitea (issue #5) are in place since 2026-10-06: every tag from v0.1.0 to v0.10.0 has its release. Updates from Gitea (issue #6) is built and checked on the device, on branch `gitea-updates`, not merged yet. The Issues App (#4) comes after.
+
+**Goal:** a tag is a release, built the same way every time and published where a device can find it.
+
+## CI and releases (issue #5)
+
+Until now the tests, the builds, the signing and the flashing all happened on one machine, through `scripts/ci.sh` and `scripts/flash.sh`. Nothing was published.
+
+### Decisions (design round 2026-10-06)
+
+| # | Decision |
+|---|---|
+| Q151 | A push to `main`: the host tests (with their coverage). A push to another branch: nothing, its pull request is what runs (a branch with an open pull request ran twice, once for each). A pull request: the same and both builds; changes reach `main` through pull requests. A tag `v*`: all of it, then a release. (First: everything on every push, which rebuilt the firmware far more often than anyone looked at it.) |
+| Q152 | **CI signs.** The signing key is the repository secret `OTA_SIGNING_KEY`; a tag push makes a complete, signed release with no manual step (ADR 0008). |
+| Q153 | *Revised by Q188: there is one firmware.* The Debug Build is built in CI with a token of the runner's own, to prove it compiles, and **isn't published**: it would hand everyone its Debug Console token. |
+| Q154 | Pull requests from forks don't start a run. |
+| Q155 | A release carries `roro9stack-<version>.ota` (signed), `-factory.bin` for USB, `.elf.gz` to decode crashes, and `SHA256SUMS`. |
+| Q156 | Its text is the tag's message, what the files are, and the commits since the tag before. |
+| Q157 | No cache service to begin with: measure first. |
+| Q158 | Reproducible builds aren't needed for signing any more (Q152); not pursued here. |
+| Q159 | **The tags from before CI get their releases too**, v0.1.0 to v0.10.0, built from each tag's own sources by running the workflow by hand. |
+| Q160 | Actions is switched on for the repository. |
+| Q161 | **Changes reach `main` through pull requests, merged as "rebase, then a merge commit"**, the only style the repository allows: the branch's commits keep their messages, the merge commit marks the pull request, and what CI tested is what lands. No squash, no fast-forward. |
+
+### As built
+
+- **One workflow, `.gitea/workflows/ci.yml`, one job**, on the runner `runner0` (label `ubuntu`). The job asks for a `python:3.12-slim` container, installs git, a compiler, openssl and PlatformIO, and runs the same scripts as a developer's machine. No Docker inside the job.
+- **The cache is a Docker volume**, `roro9stack-pio`, mounted at `/pio`; the runner's `config.yaml` allows it under `container.valid_volumes`. A first run downloads about 1 GB and rebuilds the framework. Measured from the jobs' own start and end times: the first full run on an empty cache took 11.4 minutes (tests and both builds); the first run in a container, 8.1; a pull request now takes about 8.7 (tests, coverage and both builds), a release build alone 5.5, and a push to `main` (tests and coverage) 1.1. (An earlier version of this note said 17 minutes: that was the waiting time, not the job's.)
+- **No JavaScript actions**, so the image needs no Node and nothing is fetched from GitHub: the checkout is four git commands.
+- **`scripts/_docker.sh`** runs the command in place when `RORO_NO_DOCKER` is set (a CI job is already in a build container), and in the project's image otherwise. The Debug Build's token is made on the spot in CI and goes with the container.
+- **`scripts/release_build.sh <checkout> <out>`** builds a tag's own sources with today's tools, signs, verifies against the public key in those sources, and writes the files and the release's text. **`scripts/release_publish.py`** creates the Gitea release or completes it; run twice, it replaces what's there. Both run the same on a developer's machine.
+- **`scripts/ota_verify.py`** checks an Update File as a device does, on a PC.
+- **The job's own token** (`secrets.GITEA_TOKEN`) is enough to create a release and upload its files.
+- **Old tags.** v0.1.0 to v0.3.0 are from before the framework was rebuilt with our settings (ADR 0006) and can't link against a rebuilt one left in the cache: the release build puts the stock framework libraries back for them. v0.1.0 to v0.2.1 have no public key in their sources (Firmware Updates came with v0.3.0); their files are checked against today's.
+
+### How it went
+
+- **The runner's label took three tries.** Registered as `ubuntu://docker:ubuntu:resolute` and then as `ubuntu::docker://...`, Gitea took the whole string for the label's name; with the first, jobs ran on the runner's host itself. The first version of the workflow was written for that (plain shell, `docker run` for the build) and published v0.10.0 that way. `ubuntu:docker://docker.gitea.com/runner-images:ubuntu-latest` is the form that works.
+- **Gitea 1.27's API can't cancel a run that isn't finished**, only delete a finished one; switching Actions off and on for the repository doesn't either. Runs queued for a label that no longer exists stay queued until cancelled in the web UI.
+- **CI's image isn't byte-identical to a local build of the same tag** (same size, different bytes). Not pursued (Q158).
+
+## Updates from Gitea (issue #6)
+
+The device looks at the project's Gitea for a newer release, says so, and installs it on request, with the same signed Update Files, Probation and rollback as a push from the PC or an install from the card.
+
+### What the server gives (checked 2026-10-06)
+
+- **Its certificate** is Let's Encrypt, all ECDSA: leaf `git.twis.la` (renewed every few months, next expiry 2026-12-14) under the intermediate YE2, Root YE and ISRG Root X2, which X1 cross-signs. Pinning the leaf would ask a question at every renewal.
+- **The API** answers over HTTP/1.1, chunked: `releases/latest` is 3.2 KB (about 350 bytes of it matter), a list of ten releases is 33 KB.
+- **A download** is a direct 200 with `Content-Length` and no redirect; ranges work.
+
+### Decisions (design round 2026-10-06)
+
+| # | Decision |
+|---|---|
+| Q162 | **Trust:** the firmware carries ISRG Root X1 and X2 and checks the server's chain and name against them, not the framework's bundle of about 130 CAs (ADR 0009). Shared with #4. If the server moves to another CA, the next firmware comes from the PC. |
+| Q163 | The Update File's own signature stays the real guard. A hijacked connection could hide a release or offer an older signed one, never install firmware that isn't ours. |
+| Q164 | The source, `git.twis.la` and `twisla/roro9stack`, is a constant in the firmware. A fork changes it, and has its own key. |
+| Q165 | **When:** on request in Settings > Firmware, and once a day in the background while Wi-Fi is up and the Clock is set (certificate dates need it). A setting, **Check for updates**, on by default. It installs nothing by itself; it skips quietly below the memory floor and never runs during an install. |
+| Q166 | A Toast, "Update v0.11.0 available: see Settings > Firmware", once per version per boot. |
+| Q167 | **The download goes straight into the inactive slot,** no card needed. A truncated or tampered file is refused after 160 bytes or at its end, and the running firmware is untouched. A failed download starts over. |
+| Q168 | A version that failed (rolled back) isn't announced again by the background check until a newer one exists; it can still be installed by hand. |
+| Q169 | **Older releases:** a list of the last ten, newest first, the running one marked. Installing an older one asks with a stronger warning. |
+| Q170 | Enter on a release shows its version, date, size and the tag message, with Install. |
+| Q171 | *Revised by Q188: there is no Debug Build, every firmware installs releases.* **Debug Builds** check and show the latest release, but don't install it: it would replace the Debug Build and its console (Q153: Debug Builds aren't published). Their updates come from the PC. |
+| Q172 | **Memory, as measured:** a TLS connection peaks at about 52 KB of heap, with or without checking the certificate, so it starts with 80 KB free (Q86's 20 KB spare on top), not 55 KB. **A check, list or install someone asked for makes IRC step aside** and come back after; the daily check never does, and with IRC connected it waits. (First: 55 KB and nothing else. With IRC connected a check left 3 KB and a download 836 bytes.) |
+| Q173 | Left out, each with its issue: installing automatically (#52), a release channel (#53), resuming a download (#54). |
+| Q174 | Ships as **v0.11.0**. Tested on the device with the real signed releases; a Debug Build command pretends the device runs an older version, so v0.10.0 counts as an update. |
+
+### Done when
+
+- A check, by hand or daily, tells the right thing: up to date, newer available, no network, bad certificate, no clock, too little memory.
+- A newer release installs from the Firmware page with no card and no PC, and the device restarts into it and confirms it.
+- A tampered or truncated download is refused and the running firmware keeps running.
+- The Older releases list shows ten, and installing one asks first.
+- A release that rolled back isn't announced again.
+- A Debug Build shows the latest release and doesn't install it.
+- The daily check never runs below the memory floor, during an install, or without a clock.
+
+### Work breakdown
+
+1. **Model** (host-tested): a streaming JSON scanner, the release list read from it, HTTP response heads and chunked bodies, URLs, which release counts as an update.
+2. **The connection:** the root certificates, an HTTPS client, a check and a list from the Update Service's task; console commands to try them.
+3. **The download:** an HTTPS source for the existing install path.
+4. **The screens:** the Firmware page's release rows, the release page, Older releases, the setting, the daily check and its Toast.
+5. **Checks on the device**, recorded here.
+
+### As built
+
+- **`lib/release`** (host-tested): a streaming JSON scanner, the release reader built on it, HTTP heads and chunked bodies, URLs, and the decisions (which release is an update, whether to announce it, which download URLs are taken). A list of ten releases is 33 KB of JSON and costs a few hundred bytes of memory, because nothing is kept but the path.
+- **`HttpsGet`** (`src/platform`): one GET, the answer read as a stream, redirects not followed. **`GiteaReleases`** keeps the latest and the list. **The Update Service** serves the requests on its own task (about 5.4 KB of its 7 KB stack at the peak) and installs through the install path that already existed, with an HTTPS source in place of the card or the TCP port.
+- **The daily check** is scheduled from the Update Service's tick: Wi-Fi up, the Clock set, no Probation, nothing else going on, memory for a connection. The day it last succeeded is kept in flash.
+- **A version that failed** (rolled back) is remembered as `ota_failed`, and isn't announced again by the daily check.
+- **The screens:** the Firmware page's Latest release and Older releases rows, a release page with the tag's message, and the install dialog.
+- **Debug Builds** get knobs to try what can't be tried otherwise: `update pretend`, `probe`, `damage` and `daily`.
+- **The first message,** `... available: see Settings > Firmware`, was cut at 48 bytes by the notification's own limit; it now reads `v0.11.0 is out: see Settings > Firmware`.
+
+### Checks on the device (2026-10-06, Debug Builds of branch `gitea-updates`)
+
+| Check | Result |
+|---|---|
+| Host tests | 456 pass |
+| Check and list against the live server | The certificate is accepted against the two embedded roots; `releases/latest` read; a list of ten (33 KB) streamed |
+| Servers that must be refused | github.com, example.com, expired.badssl.com, self-signed.badssl.com, wrong.host.badssl.com, untrusted-root.badssl.com and the router: each "isn't accepted" or a TLS error |
+| A download cut short at 800,000 bytes | Refused, "update file too short"; the running firmware untouched |
+| One byte flipped in the signature | Refused after 160 bytes, "bad signature"; the image isn't read further |
+| One byte flipped in the image | Downloaded in full, refused at its end, "image corrupted (hash mismatch)" |
+| The real v0.10.0, from the console and then from the screen | Downloaded, restarted, confirmed on Probation: the slot table read `v0.10.0, valid` both times. The Debug Build was pushed back from the PC after each |
+| The screens | Latest release (checking, then `(current)` or `(new)`), the release page with the tag's message, Older releases with ten rows, the install dialog (Cancel by default, Back cancels), the progress screen at 28% |
+| IRC connected, before the hold | A check left 3 KB of heap; a full download, 836 bytes |
+| IRC connected, with the hold | The lowest free heap during a full download: 38 KB. IRC reconnected afterwards (its counters kept growing) |
+| The daily check | It ran by itself, announced `v0.10.0 is out: see Settings > Firmware` once; with IRC connected (68 KB free) it didn't run |
+| Speed | 1.9 MB in about 46 s, 40 KB/s, over the guest Wi-Fi at -65 dBm; not investigated further |
+
+**Not checked:** the certificate's **name** on its own. Connecting by IP makes the server end the handshake before it shows its certificate, so that test proved nothing; the library sets the name it verifies, and OpenSSL on the PC refused the wrong name against the same chain. A failed daily check retrying, the clock not being set, the release that failed before not being announced (host-tested, not on the device), and the hold when IRC isn't connected but Gemini holds memory.
+
+**Limits worth knowing:**
+- **With IRC connected for days, the daily check doesn't run.** It would have to take IRC down to make room. Opening Latest release does.
+- **A server that changes CA can't be reached** until a firmware carrying the new root comes from the PC (ADR 0009).
+- **No resuming:** a broken download starts over (#54).
+- **A key press during the hold:** Back on the Firmware page while a check is going doesn't cancel it.
+
+**Two slips during the checks:** a blind sequence of keys on the Firmware page opened the SD card's install dialog (the page keeps its selection between visits); it was cancelled with Back, nothing installed. And my port-polling while waiting for a restart took the Debug Console's only client slot, which made the first install attempt look like a failure.
+
+## One firmware: the Debug Console in every build (issue #68)
+
+The issue asked for a token that could be set, so that Debug Builds could be published. The design round ended somewhere simpler: no Debug Builds. The console is in every firmware, off until switched on, with a token that belongs to the device (ADR 0010, which supersedes part of ADR 0004).
+
+### Decisions (design round 2026-10-06)
+
+| # | Decision |
+|---|---|
+| Q188 | **One firmware,** with the Debug Console and the test commands compiled in. The `cardputer-adv-debug` environment, `RORO_DEBUG`, the `+debug` version and `scripts/debug_flags.py` go; CI builds one firmware. Revises Q153 and Q171. |
+| Q189 | **Off by default,** and off when the stored setting is missing or invalid. Off, nothing listens and no memory is used: the task and the 4 KB ring exist only while it's on. |
+| Q190 | **Settings → Debug Console:** the switch, where to connect, the token, "New token", "Type a token". It stays on across restarts and in Safe Mode. **`DBG` in the Status Bar** while it listens, bright with a client connected. |
+| Q191 | **The device makes the token** the first time the console is switched on: 100 bits as 20 characters of Crockford's base32, shown in groups of four. It can be replaced by one typed by hand, of at least 16 characters. Case and dashes don't count. |
+| Q192 | **USB serial can set it up:** `debug on`, `debug token <value>`, `debug token new`, over USB only; `debug status` and `debug off` from anywhere. `scripts/flash.sh --debug` gives a device the developer's token. The token is never printed. |
+| Q193 | **Challenge and answer:** the device sends 16 random bytes, the client their HMAC-SHA256 keyed by the token. Five wrong answers in a row close the console for a minute, with a Notification. **Old clients and old firmwares don't talk to each other:** accepted, this far from v1 and with one user. |
+| Q194 | `rdbg.py` takes the token from **`-t`/`--token`**, then **`$RORO_DEBUG_TOKEN`**, then `~/.config/roro9stack/debug-token`. |
+| Q195 | **The test commands are in every build** (`crash abort`, `crash wdt`, `update pretend`, `update damage`, `lora inject`, `sd fill`, `loop spin`, `wifi ip … try`). `update install … force` goes: there's nothing left to protect. |
+
+### As built
+
+- **`lib/debug`** (host-tested, 9 tests): the token maker, tidying what a person types, HMAC-SHA256 on the project's own SHA-256 (checked against RFC 4231), the answer to a challenge (the same vector as `rdbg.py`'s), a comparison that takes the same time whatever it's given, and the pause after five wrong answers, right across the clock's wrap.
+- **Two settings,** `DebugConsole` and `DebugToken`, with the others: validated, and invalid stored values count as missing.
+- **The console's task and ring come and go with the setting.** `Console::openRing` allocates the ring; switching off closes the socket, frees it and ends the task. `tick` follows the settings once a second, so a switch off and on again takes a second or two.
+- **Measured against the two builds it replaces:** 1,881,799 bytes of flash and 54,700 of static RAM. The release build was 1,851,387 and 54,612 (so 30 KB more flash and 88 bytes more RAM); the Debug Build was 1,874,887 and 58,780 (4 KB of RAM back: the ring is no longer a static array).
+- **The listener is asked whether it listens.** The framework's `begin()` returns nothing and fails without a word; the task now checks, says so on the console, and tries again every two seconds.
+- **`debug off <seconds>`** closes the console and brings it back by itself: the only way to try its closing and reopening from afar, since switching it on is for the device and the cable only.
+- **`scripts/rdbg.py`** answers the challenge, and fetches a release's ELF from Gitea when a crash names a version that isn't in `.pio/elves/`.
+
+### Checks
+
+| Check | Result |
+|---|---|
+| Host tests | 468 pass (456 before) |
+| The firmware builds | One environment, 1,881,799 bytes of flash used |
+| Pushed over Wi-Fi to a device running a Debug Build | Installed, restarted; the update port answers and **port 2323 refuses connections**: off by default |
+| Switched on at the device (Settings → Debug Console) | A token is made and shown. Its first drawing, in bold at normal size, was misread once: it is now at twice the size, in two lines, and `O`, `I` and `L` are taken for `0` and `1` |
+| A login with `scripts/rdbg.py` | The challenge is answered; `info`, `screenshot` and the backlog work |
+| `DBG` in the Status Bar | There while the console is on, bright while a client is connected (screenshots) |
+| `debug on` and `debug token` over the console | Refused: `over USB serial only` |
+| Six logins with a wrong token | Five are refused, a second apart; the sixth, and the right token after it, get `locked`. After a minute the right token works again. The console's own log and a Notification say so |
+| Three `crash abort` in a row | **Safe Mode**, with the console reachable: `info` works, `ls /` says `not available in Safe Mode`. `rdbg.py crash` decodes the backtrace to `runCommand` at the `abort()` line. `reboot` leaves Safe Mode |
+| An update over Wi-Fi with the console on | The setting and the token survive: the console is back by itself after the restart |
+| `debug off` over the console | The client is dropped and port 2323 refuses connections; the update port still answers |
+| `debug off 2`, 10 times in a row, then 15 | It came back each time, a second after the pause. Free heap dips by about 270 bytes for each connection the device closes and **is all back two minutes later** (107.2 KB before, 103.2 right after 15, 107.0 at two minutes): TCP holds a closed connection that long. Not a leak, though it looked like one for an hour |
+| Memory, console on with a client | 108 KB free (the Debug Build it replaces: 104 KB). In Safe Mode: 178 KB free |
+
+**One false alarm:** after the tests the console "wouldn't come back on". It was off: the setting had been left off by `debug off`, and the page's "Switch it on?" dialog opens on **Cancel**, so Enter twice leaves it off. Nothing was lost.
+
+**Not checked:** `scripts/flash.sh --debug` over USB (no device on USB here); "New token" and "Type a token" from the page (the code paths are the ones `debug token` uses, which need the cable); the Toast itself on screen (the console is closed while it shows; its Notification is in the log); free memory with the console off, which only the serial port could say (the static figures above are the evidence); fetching a release's ELF, which needs a crash on a released version.

site/content/dev/milestones/s1.md

@@ -0,0 +1,146 @@
++++
+title = "System basics"
+description = "The device works on any network, the card can be trusted, and you can see what the system is doing. A side milestone, like G1."
+weight = 50
+
+[extra]
+docs = true
+source = "docs/milestones/S1.md"
+tag = "S1"
++++
+**Status:** the three planned items are done: the SD driver fix in v0.6.1 (issue #21, ADR 0007), fixed IPv4 settings in v0.7.0 (issue #7), the System App in v0.8.0 (issue #11). v0.8.1 adds the resting main loop (issue #40) and the GNSS pause for the radio's noise (issue #20, still open for the 11 dB that remain). Still open in the milestone: #39, following the SD driver upstream.
+
+**Goal:** the device works on any network, the card can be trusted, and you can see what the system is doing. A side milestone, like G1.
+
+## Fixed IPv4, DNS and NTP (issue #7)
+
+Not every network has a DHCP server: a lab bench, a direct link to a router, a network where addresses are handed out by hand. Until now every Saved Network used DHCP, DNS always came from DHCP, and the NTP server was `pool.ntp.org`, hard-coded.
+
+**IPv4 only.** IPv6 isn't part of this, now or as a planned follow-up.
+
+### Decisions (design round 2026-10-05)
+
+| # | Decision |
+|---|---|
+| Q105 | The IP setting is **per Saved Network**: *Automatic* (DHCP, as before) or *Fixed*, with its own address, prefix and gateway. New networks start Automatic. |
+| Q106 | The subnet is entered as a **prefix length** (`24`), with the mask shown next to it. |
+| Q107 | The **gateway is optional**: left empty, the device talks to its own subnet only. |
+| Q108 | **DNS is global:** two servers in Settings, used on every Fixed network. On Automatic networks DHCP's DNS is used, unless **"Always use my DNS"** is on. |
+| Q109 | DNS defaults: **9.9.9.9** (Quad9), then **1.1.1.1** (Cloudflare). |
+| Q110 | **NTP is global:** two servers in Settings, names or addresses, defaulting to `pool.ntp.org` and `time.cloudflare.com`. NTP servers offered by DHCP are used first. GNSS still outranks NTP for the clock. |
+| Q111 | What's typed is checked, host-tested in `lib/wifi`: an address is four numbers from 0 to 255; a prefix is 1 to 30; the address isn't the subnet's network or broadcast address; the gateway is inside the subnet and isn't the device's own address. Refusals say why. |
+| Q112 | Addresses are typed in the line editor, limited to digits and dots. |
+| Q113 | Enter on a Saved Network opens **its page** (IP, Address, Prefix, Gateway, Forget) instead of asking to forget it. Settings > Wi-Fi gains DNS servers, "Always use my DNS" and NTP servers. The Status row opens **connection details**: address, mask, gateway, DNS and NTP in use, and where each came from. |
+| Q114 | A change applies **at once**: the network in use reconnects with the new settings. No automatic way back; the keyboard still works if Wi-Fi is cut. |
+| Q115 | Console: `wifi status` shows address, gateway, DNS, NTP and their sources; `wifi ip <ssid> dhcp`, `wifi ip <ssid> <address>/<prefix> [gateway]`, `wifi dns <a> [b]`, `wifi ntp <a> [b]`. Debug Builds: `wifi ip … try 60` goes back to the previous setting after 60 s unless confirmed with `wifi ip keep`. |
+| Q116 | Left out: checking whether the address is already taken, and per-network DNS. |
+
+The SDK already allows 3 NTP servers and 3 DNS servers and can take NTP servers from DHCP (`CONFIG_LWIP_SNTP_MAX_SERVERS=3`, `CONFIG_LWIP_DHCP_GET_NTP_SRV=y`), so the framework isn't rebuilt for this.
+
+### Done when
+
+- A Saved Network set to Fixed joins with that address, mask and gateway, and the device reaches the internet (IRC, Gemini, NTP) through the DNS servers from Settings.
+- Set back to Automatic, it gets its address from DHCP again.
+- With "Always use my DNS" on, an Automatic network resolves through the servers from Settings.
+- The NTP servers from Settings set the clock.
+- Wrong entries are refused with a reason, in Settings and on the console.
+- Connection details show what's in use and where it came from.
+- Tested on `knbg-guests` with 10.39.39.12 (the device's DHCP lease) and 10.39.39.13 (free: the device is alone on that network).
+
+### Measured (2026-10-05 and 06, on `knbg-guests`)
+
+The network is 10.39.39.0/24, gateway 10.39.39.1; DHCP gives 10.39.39.1 as DNS and offers no NTP server.
+
+- **Fixed 10.39.39.12/24** (the device's own lease) and **Fixed 10.39.39.13/24**, gateway 10.39.39.1: the device joins with that address, DNS is 9.9.9.9 and 1.1.1.1 from Settings, and a Gemini page loads (name resolution, routing, TLS). On .13, .12 no longer answers.
+- **A wrong gateway** (10.39.39.254) on a 60 s trial: the device stops answering from another subnet, and comes back by itself with the previous setting.
+- **Back to Automatic:** 10.39.39.12 by DHCP again, DNS 10.39.39.1 from DHCP.
+- **"Always use my DNS"** on an Automatic network: DNS becomes 9.9.9.9 and 1.1.1.1; switched off, the device joins again and has DHCP's DNS back.
+- **NTP:** `pool.ntp.org` answers; set to `time.cloudflare.com` alone, that one answers within 25 s.
+- **Refusals**, on the console and in Settings: the network's own address, a gateway outside the subnet, a prefix of 31 or 99, 10.39.39.300, an unknown network, a DNS name where an address is needed, a host name with an underscore.
+- **In Settings:** the network's page pre-fills Fixed with the address, prefix and gateway in use; leaving the page applies it; connection details show each value and where it came from.
+- **Not tested:** NTP servers offered by DHCP (this network offers none), and a Fixed network with no gateway.
+
+### Work breakdown
+
+1. **IPv4 logic** (host-tested): parsing and formatting addresses, prefix and mask, the checks of Q111.
+2. **Storage:** the IP setting in each Saved Network; DNS, "Always use my DNS" and NTP in Settings.
+3. **Wi-Fi Service:** apply it when joining; DNS and NTP; `wifi status` and the console commands.
+4. **Settings:** the network page, the DNS and NTP rows, connection details.
+5. **Tests on the device**, recorded here.
+
+## System Monitor (issue #11)
+
+Every milestone so far was driven by measurements, heap floors, stack sizes, TLS dips, that needed a Debug Build and a computer. The System App shows them on the device, in any build.
+
+### Decisions (design round 2026-10-06)
+
+| # | Decision |
+|---|---|
+| Q117 | An App of its own, **System**, in release builds too. Read-only. |
+| Q118 | Four views, switched with Tab: **Overview** (CPU per core, memory, network, battery), **Tasks**, **Memory**, **System**. |
+| Q119 | Sampled once a second. A task's share is its run time over the last second; a core's load is 100 % minus its idle task's share. |
+| Q120 | **History only while the App is open:** two minutes at one sample a second, about 1 KB. The system already keeps what matters afterwards: the lowest free heap since boot and each task's lowest free stack. |
+| Q121 | **Bytes are counted per service:** IRC, Gemini, the Debug Console and Firmware Updates add what they read and write to a shared counter. The network view shows the connection details, each service's bytes in and out, and the signal strength. |
+| Q122 | Tasks: name, core, share, state and lowest free stack, sorted by share; `s` cycles the sort (share, stack, name). **Under 512 bytes of stack left shows in the warning colour.** |
+| Q123 | Memory: free heap, lowest since boot, largest free block, and a two-minute graph of free heap **with the floors of Q86 drawn as lines** (55, 40 and 20 KB). |
+| Q124 | System: uptime and why it last started, firmware and both app slots, chip temperature and CPU frequency, battery voltage and percentage, SD usage and write faults, the radio's and the GNSS receiver's state. |
+| Q125 | `info` and `tasks` are split into a **snapshot** that the console and the App share; the arithmetic (shares from two samples, sorting, the stack warning) is host-tested. |
+| Q126 | Left out: acting on tasks, an event log, exporting snapshots to the card. |
+| Q127 | The main loop uses about 81 % of a core. The App shows it; fixing it is issue #40, not part of #11. |
+
+The App has five views, not four: Q121's network view is one of its own (Overview, Tasks, Memory, Network, System).
+
+### Measured (2026-10-06)
+
+- **Traffic counters are exact.** A Gemini fetch of a 164,970-byte page counts 164,986 bytes in (the page and its 16-byte header line) and 42 out (the 40-character URL and CRLF). A 1,797,760-byte upload counts 1,798,123 in for the Debug Console, commands included.
+- **The Memory view shows a TLS dip as it happens.** Starting IRC and a 165 KB Gemini fetch together: free heap falls from about 100 KB through the three floors to a low of 12.1 KB, then settles near 50 KB. That's the dip accepted in G1 (Q86).
+- **A run-time counter only moves when its task is switched out.** FreeRTOS adds to a task's run time at the context switch. The main loop takes the samples, and with core 1 to itself it's never switched out: its counter said 2 % while the core's idle task had 0 %. So the task that samples gets what's left of its core. With that: **the main loop uses 100 % of core 1 at rest** (issue #40 said 81 %, an average since boot).
+- **`tasks` on the console** sampled twice inside one command at first, a quarter second apart, and showed the loop at 1 %: it was asleep in the command's own wait. It now samples, lets the loop run for a second, and prints.
+- **Low stack, flagged:** `IDLE0` (232 bytes left), `IDLE1` (328 to 352) and `spk_task` (256 to 264), all the framework's own tasks.
+- **Cost:** 15.6 KB of flash for the App and the counters (1,742,723 bytes, release). Nothing while it's closed; about 2 KB of history and samples while it's open.
+
+## The main loop rests (issue #40)
+
+The loop polled the keyboard, ticked the Services, ran the consoles and redrew when needed, then came straight back: 50,000 passes a second, and core 1 100 % busy with the device idle and the screen off.
+
+Nothing needs that. The keyboard controller buffers key events; the consoles and the radio have their own tasks or interrupts; no Service asks for a tick more often than every 50 ms. So after each pass the loop now rests: **5 ms with the screen on, 20 ms with it off**, and not at all during a serial file transfer (`sd put`), which reads its bytes from the loop. Safe Mode's loop rests 5 ms too. Debug Builds have `loop spin on|off` to bring the old behaviour back for comparison.
+
+### Measured (2026-10-06, Debug Build, Wi-Fi connected, GNSS on, on USB power)
+
+| | Spinning | Resting |
+|---|---|---|
+| Passes a second, screen off | 50,160 | 50 |
+| Core 1 load, screen off | 100 % | 1 % |
+| Passes a second, screen on (Launcher) | 1,203 | 167 |
+| Core 1 load, screen on | 62 % | 10 % |
+| Chip temperature at rest, settled | 38.3 C | 34.3 C |
+| A 1.8 MB upload over the Debug Console | about 230 KB/s | 288 KB/s |
+
+- Still working at this pace: GNSS (a 3D Fix, 22 satellites), a Gemini fetch (52 KB), the upload read back by SHA-256, the Sweep (still 606 to 610 ms a pass), the radio's DIO1 interrupt.
+- **Not measured:** the current drawn (no meter on the battery line), and how typing feels on the real keyboard: a key now waits up to 5 ms for the loop, 20 ms if it's the one that wakes the screen.
+- **The radio's noise floor didn't move** (-97 to -99 dBm at 125 kHz either way): the spinning loop wasn't the source (issue #20).
+- **Not done:** real sleep. The framework is built without power management (`CONFIG_PM_ENABLE` is off), so an idle core only halts until the next interrupt. Automatic light sleep would need the framework rebuilt with it, Wi-Fi in modem sleep, and the USB serial port's behaviour checked. A next step if battery life calls for it.
+
+## The radio's noise: the GNSS receiver (issue #20)
+
+M3 found the LoRa radio's noise floor about 15 dB above what the chip hears alone, and that the source travels with the device. Which part? Debug Builds got a self-test, `lora noise test`: it changes one thing at a time, Sweeps the band eight passes (568 readings), records the median as the floor, and puts the thing back. It runs on the device by itself, because one condition switches Wi-Fi off, and `lora noise report` prints the result afterwards.
+
+### Measured (2026-10-06, indoors, on USB power, dBm at 125 kHz)
+
+| Condition | Floor |
+|---|---|
+| Antenna switched off (the chip alone) | -117 |
+| Antenna on, GNSS in standby | -106 |
+| Antenna on, GNSS running (as shipped) | -98 |
+
+- **The GNSS receiver, while it runs, raises the floor by 8 dB.** Three runs: -98 or -99 with it running, -106 in standby, every time. On LongFast (250 kHz) the Sniffer's own reading goes from about -93.5 to -101.5 dBm.
+- **It's the receiver working, not its serial line:** with one NMEA sentence a second instead of twenty (`PCAS03`), the receiver still tracking, the floor stays at -98.
+- **Nothing else moves it by more than 1 dB**, with GNSS running or in standby: the main loop spinning or resting, the CPU at 240, 160 or 80 MHz, Wi-Fi on or off, the screen on or off, the radio chip's regulator as DC-DC or LDO, its receive gain boosted or not.
+- **11 dB remain** between the antenna connected with GNSS quiet (-106) and the chip alone (-117). It comes in through the antenna and none of those switches changes it: the surroundings, or parts of the Cardputer that can't be switched off. Not separated: that needs another place, or the antenna on a cable away from the case.
+- M3's quick check had GNSS at "1 or 2 dB": it read one frequency for a few seconds, in a noisier spot. The median over the band is the better measure.
+
+### What the firmware does about it
+
+**Settings > Pause GNSS for LoRa**, off by default: while the LoRa radio listens or sweeps, the GNSS receiver waits in standby, and wakes when the radio goes back to sleep (a Fix again after about 7 s here). Never during a Track. The GNSS App says "GNSS is paused" meanwhile. `gnss quiet on|off` on the console.
+
+It's off by default because GNSS on by default was decided in M2 (Q58), and from M4 the radio listens all the time: then "pause while listening" means GNSS mostly off, which is a decision about position, the clock and Tracks, for M4's design round (issue #23).

site/content/dev/milestones/w1.md

@@ -0,0 +1,135 @@
++++
+title = "Website"
+description = "A public home for the project at roro9stack.net, separate from the blog (stories) and from Gitea (developers): what it is, how to install it, how to use each App, and the docs."
+weight = 80
+
+[extra]
+docs = true
+source = "docs/milestones/W1.md"
+tag = "W1"
++++
+**Status:** phases 1 to 3 (home, Install and Downloads; the user guide; how-tos and the FAQ) and the devlog are live at roro9stack.net; phase 4 (the developer docs) is in a pull request. Issue #12.
+
+**Goal:** a public home for the project at **roro9stack.net**, separate from the blog (stories) and from Gitea (developers): what it is, how to install it, how to use each App, and the docs.
+
+The home page was designed on a canvas in a Claude chat (a dark and a light theme, built on the device's own 256-colour palette, pixel-notched corners, DM Mono and Hanken Grotesk). It is the starting point, not the final copy: it has to say only what the firmware does today.
+
+## What was found while planning (2026-10-06)
+
+- `roro9stack.net` already points at the server that hosts Gitea. Plain HTTP redirects to HTTPS; HTTPS has no certificate yet, which is the server's side to set up.
+- **Release downloads from Gitea carry no CORS header,** so a browser can't fetch the factory image from another origin as things are. Gitea is behind Caddy, which can add the header (below).
+- Zola can read JSON from a URL at build time (`load_data`), so the home page's "latest version" can come from the Gitea API.
+- There is no Gitea wiki: the design's "Wiki" links would 404.
+- The blog is published by pulling its repository on the web server and running `zola build`. The site does the same.
+
+## Decisions (design round 2026-10-06)
+
+| # | Decision |
+|---|---|
+| Q175 | The site lives in this repository, in `site/`, so the documentation is built from `docs/`, `CONTEXT.md` and the README instead of being copied. |
+| Q176 | **Zola,** like the blog. The design becomes a template, its tokens CSS custom properties. Dark and light follow the visitor's setting, with a visible switch. No JavaScript except the flasher's. |
+| Q177 | Domain: **roro9stack.net.** The blog stays at experiments.twis.la. |
+| Q178 | **Publishing is the blog's way:** the web server pulls `main` and runs `zola build`; that part is the maintainer's. Changes reach `main` through pull requests as everywhere. **CI is split:** a dedicated `site` job builds the site (`zola build`) when `site/`, `docs/`, `README.md` or `CONTEXT.md` change, and the firmware tests and builds skip a change that touches nothing else. A change that touches both runs both. |
+| Q179 | Phases, each its own pull request: **1.** the CI split, the home page, an Install page with the browser flasher, downloads and the changelog. **2.** a user guide page per App. **3.** how-tos and the FAQ. **4.** developer docs generated from the repository. |
+| Q180 | **A browser flasher** (ESP Web Tools), **without copying the firmware.** Caddy, in front of Gitea, adds `Access-Control-Allow-Origin: https://roro9stack.net` (and `Vary: Origin`) to GET and HEAD on `/twisla/roro9stack/releases/download/*` and `/api/v1/repos/twisla/roro9stack/releases*`: both are public already. The Install page asks the API for the latest release in the browser, finds the asset ending `-factory.bin`, and gives ESP Web Tools a manifest built on the spot, so it offers a new release as soon as it exists, with no rebuild. The library is **vendored** into `site/static/` (Apache-2.0), not loaded from a CDN. The file's SHA-256 is shown on the page. Chrome or Edge on a desktop only; other browsers, and visitors without JavaScript, get the `esptool` steps on the same page. |
+| Q181 | Docs for the latest version only. The changelog is the Gitea releases, read at build time. |
+| Q182 | English only. |
+| Q183 | The FAQ starts from real questions: the README, and issues labelled `kind/docs`. |
+| Q184 | Fonts are **self-hosted** (no request to a third party). The hero keeps the design's illustrations, labelled as illustrations, and a section of **real device screenshots** is added. |
+| Q185 | **The site says only what the firmware does today.** Planned features are marked as planned, with their milestone. The mesh messenger is **planned**: the LoRa Scanner listens, nothing is sent. |
+| Q186 | Left out, each with its issue: a Gemini capsule mirror (#57), French (#58), docs per version (#59), search (#60). |
+| Q187 | The site has no version of its own. Contact is **contact@roro9stack.net,** and the issue tracker. |
+
+## The design, reviewed
+
+Kept as designed: the layout, the tokens, the nine App cards (their facts check out against the code: Probation 3 minutes, Safe Mode after 3 crashes, 60 seconds of typing before an update restarts the device).
+
+Changed before it ships:
+
+- **Install, not Download, is the first action.** Downloads are for developers; a visitor wants to try it.
+- **A "what you need" strip:** Cardputer ADV, the Cap LoRa-1262 (only the radio needs it), a microSD card, Wi-Fi. And a plain status line: the version, and what isn't there yet.
+- **The mesh card and the hero** no longer promise sending and reading mesh messages.
+- **The latest version is read from the API,** not typed.
+- **"Wiki" is replaced by Docs.** The updates section gains what v0.11.0 added: the device installs releases from the project's server itself.
+- **An independence line:** not affiliated with or endorsed by M5Stack or Meshtastic.
+- **No cookies, no analytics, no third-party requests,** said on the page (fonts self-hosted).
+- **The keyboard focus ring** is invisible on the notched buttons: `clip-path` clips an outline. Another way to show focus is needed.
+- **The wordmark SVGs** carry an embedded C2PA content-credentials block: stripped from the site's copies.
+
+## Done when (phase 1)
+
+- Pushing a change under `site/` runs the `site` job and not the firmware tests; a firmware change runs the firmware jobs and not the site's.
+- The home page renders in both themes, at phone width, with the keyboard, and says nothing the firmware doesn't do.
+- The latest version on the page is the latest release.
+- The browser flasher installs the latest release on a Cardputer ADV from Chrome (tried by hand), the page shows the file's SHA-256, and the `esptool` steps are on the same page.
+- A release published after the site was built is the one the Install page offers.
+- The home and Downloads pages make no request to another origin, and the Install page only asks git.twis.la.
+
+## Work breakdown
+
+1. **CI split:** a `site` workflow, path filters on the firmware workflow.
+2. **The skeleton:** `site/` with the tokens, fonts, base template and the theme switch.
+3. **The home page,** from the design, with the changes above.
+4. **Install and downloads:** the flasher with its manifest built in the page, the `esptool` steps, the changelog. Needs the Caddy headers on the Gitea host (the maintainer's side); the page is tested against them once they're in.
+5. **Checks,** recorded here.
+
+## As built (phase 1)
+
+- **CI is split.** `ci.yml` (the firmware) has `paths-ignore: site/**, docs/**, README.md, CONTEXT.md` on pushes to `main` and on pull requests. `site.yml` runs `zola check` and `zola build` with a Zola pinned by its checksum, then `site/tools/check_site.py`, when those files change. Gitea's own source (v1.24, read, not run against the 1.27 server) shows that path filters count as matched for tag pushes, so a tag still releases. A change that touches both runs both.
+- **The build output** goes to `public/` at the root of the repository, not into `site/`: `output_dir = "../public"` in `site/config.toml`, so `zola build` in `site/` and `zola --root site build` from the root agree, and git ignores `/public/`.
+- **The site** is in `site/`: `config.toml`, templates (base, home, install, downloads, 404), `data/` for the App cards and the screenshots' captions, `static/` (stylesheet, theme switch, fonts, wordmark, icons, real screenshots, the vendored flasher). `site/README.md` says how to build it and what the server needs.
+- **The home page** follows the design. Changed from it: the hero and the mesh card promise nothing that isn't built (the mesh messenger is a "planned" card), an Install button first, a status box, a "what you need" row, a section of real screenshots, the updates section says the device installs releases itself, an independence line and a statement about cookies and third-party requests in the footer, the latest version read from the Gitea API at build time, and the nav's Wiki replaced. The two hero drawings are generated by `site/tools/make_illustrations.py` (a port of the design's scripted shapes) as inline SVG.
+- **The focus ring.** `clip-path` clips outlines, so a focused notched control drops its notches and shows square corners and its ring.
+- **The Install page** asks the API for the latest release in the browser, builds the ESP Web Tools manifest as a blob, shows the version, size and SHA-256, and only ever hands the flasher a download from the project's own server for this repository. The flasher library (ESP Web Tools 10.4.0, Apache-2.0) is vendored, trimmed to the ESP32-S3. Fonts (DM Mono, Hanken Grotesk, SIL OFL) are self-hosted.
+- **The Downloads page** lists the last 30 releases with their files, read at build time.
+- **The wordmark SVGs** from the design carried an embedded C2PA content-credentials block; it is removed from the site's copies.
+
+## As built (phase 2, the user guide)
+
+- **`/guide/`** is a section of 11 pages, `site/content/guide/`, each with `template` from the section's `page_template` and an order from `weight`: the basics (keys, Launcher, Status Bar, first start, the card), then one page per App (LoRa Scanner, GNSS, Gemini, IRC, Wi-Fi tools, Notes, Storage, System), Settings and Updates. Pages with real screenshots list them in `extra.screens`, looked up in `data/screens.toml`.
+- **Facts come from the README, the milestone documents and the Apps' own source** (key handlers, labels, the Status Bar's drawing code), not from memory. Some wording was corrected against the source while writing: the Track folder is `/gnss/tracks`, the reasons a Track won't start, what the Status Bar shows.
+- **Not covered:** the mesh messenger (planned), the debug console and Debug Builds beyond a pointer to the README. How-tos and the FAQ are phase 3.
+
+## As built (the devlog)
+
+Not one of the planned phases: the blog's seven roro9stack posts, imported into `site/content/devlog/` and shown in the site's own style, with the **Blog** link in the navigation and the footer replaced by **Devlog**. The posts' text, tone and structure are unchanged; what changed:
+
+- **Links:** the posts' links to each other point to `/devlog/<same name>/`, and one link to an unpublished work-in-progress post became plain text. Each post keeps its old directory name, so the old URL `/<name>/` maps to `/devlog/<name>/`.
+- **The posts' parts** (the sign, the cast, the steps, asides, folded sections, diagrams, captions) are shortcodes in `site/templates/shortcodes/`, restyled in `static/css/devlog.css`: the site's palette, notched boxes, DM Mono and Hanken Grotesk. The two older posts about other subjects (a vinyl remote, a ZFS rescue) stay on the blog.
+- **The 17 diagrams are inline SVG**, and carried `<style>` blocks and `style` attributes that the site's Content-Security-Policy refuses. Their rules moved to `static/css/devlog-diagrams.css` (one block per diagram, plus colour classes for what the attributes did), and a diagram's minimum width is a class, not a style attribute. The Caddy policy needs no change.
+- **The diagrams' four colours** (red, green, yellow, accent) are defined for `.devlog` on the site's RGB332 grid, one value for each theme.
+- **Links between posts:** every post's reference to another ("the last post", "the first post", the milestone lists) is a link to it. `check_site.py` now also checks every link inside the site, and its #fragment: a broken one fails the Site job. External links are checked by `zola check` run by hand (without `--skip-external-links`, which CI uses); its only complaints today are line-range and heading anchors on Gitea, which Gitea resolves in the browser.
+- **An Atom feed** at `/devlog/atom.xml`, linked from every devlog page.
+- **Checked** in Chromium with the production CSP applied to every response: the index and the seven posts, at 1100 and 390 px, no policy violation, no broken image, no sideways scroll; `check_site.py` 24 pages, 0 problems.
+
+## Checks (2026-10-06)
+
+| Check | Result |
+|---|---|
+| The Site workflow's own commands, in a clean container with the pinned Zola | `zola check` clean, build and page checks pass |
+| `tools/check_site.py` | 4 pages, 0 problems: titles, descriptions, a language, every image with alt text, every local file referenced exists, nothing loaded from another origin |
+| Browser tests (Chromium, 16 checks) | All pass: no request to another origin from the home, Downloads and 404 pages; no horizontal scroll at 1280 and 390 px; a visible focus ring on a notched button; the Install page reads the latest release, shows its version, size and SHA-256, builds a blob manifest naming an ESP32-S3 factory image at offset 0, and loads only git.twis.la; a download on another host is refused; the real server (no CORS header today) makes the page fall back to the esptool steps |
+| The pages looked at | Home in dark and light, at desktop and phone width; Install; Downloads |
+| `esptool` against the real v0.11.0 factory image | An ESP32-S3 image, bootloader at 0x0, partition table at 0x8000: flashing at offset 0 is right. The command's syntax was checked, not a flash |
+
+**Not checked:**
+- **Flashing a real Cardputer from Chrome.** It needs the device on a machine with a browser; the page's flasher logic is tested, the flashing itself isn't.
+- **Caddy's headers** on the real server (not applied yet), and **HTTPS on roro9stack.net** (the name resolves, the certificate isn't there).
+- **The CI split on a change that touches only `site/` or `docs/`.** This pull request touches both the workflows and the site, so it runs both; the first docs-only pull request will show it.
+- Firefox and Safari rendering, screen readers, and a printed page.
+- The unverified wording in the Install text is kept to what's known: nothing about how long flashing takes, or what the screen shows in download mode.
+
+## As built (phase 3, how-tos and the FAQ)
+
+- **`/howto/`** has eight short recipes: when flashing fails, find your files on the SD card, install an update from the card, use a network without DHCP, record a Track, capture LoRa packets for Wireshark, read Gemini pages offline, and what to do when a connection says "not enough memory". **`/faq/`** is one page of questions with a list at the top. Both use the guide's templates (`guide-index.html`, `guide-page.html`, now generic: the page's parent section gives the eyebrow, the title and the pager).
+- **The FAQ starts from the README** and from the problems the project met (Q183): the flash troubles and the memory limit are the two that were hit most. The issues labelled `kind/docs` turned out to be design rounds for the mesh, not user questions, so they gave nothing to answer.
+- **Every step comes from the README, the milestone documents or the Apps' source.** The privacy answer says plainly that the device contacts the project's server once a day for the update check (on by default, one switch to turn it off).
+- **Linked from the guide's index,** not the navigation, which stays short.
+
+## As built (phase 4, the developer docs)
+
+- **`/dev/`** has four sections: **Debug Builds and the Debug Console** (first, and the longest: Debug Builds, the Console and its protocol, files and screenshots, driving the UI, crashes and Safe Mode, and the command reference), **Build, test and release** (the README's build, CI and flash sections, and how an update works, with the update file, the four ways in and Probation drawn), **Decisions** (the ADRs) and **Milestones** (the plans).
+- **Generated from the repository, not copied by hand:** `site/tools/gen_dev_docs.py` writes the ADR pages, the milestone pages, the README's sections, and the command reference, which is read from the firmware's own `help` text in `src/main.cpp` and then the README's table of what each command does. Zola can't read outside its own folder (not even through a symlink), so the generated pages are **committed**, and the Site workflow runs `gen_dev_docs.py --check` and fails when one is out of date; it now also runs when `src/main.cpp` changes, because the command list lives there. The server's `pull; zola build` is unchanged.
+- **Left out on purpose:** the M0 and M1 milestone documents and `CONTEXT.md` (the glossary) describe Wi-Fi monitoring, which the site does not publish. They stay in the repository.
+- **The Debug Console pages were written against the source and the live console:** the protocol (the token line, the banner, the 4 KB backlog, one client, 8 queued commands, 240-byte lines, `denied` after a second) and the replies shown were checked on a Debug Build, v0.11.0-3, over Wi-Fi. Not run: `crash abort`, `crash wdt` and Safe Mode, which are described from ADR 0005 and the code.
+- **Found while writing it:** the README's table lacked the `gnss` commands (rows added); piping commands into `rdbg.py` returns before the replies unless the input stays open (documented, not changed); `update install` on a Debug Build needs `force` (documented).

site/content/devlog/roro9stack-console/index.md

@@ -0,0 +1,266 @@
++++
+title = '''It was off'''
+description = '''roro9stack gets a website, and writing down how its Debug Console works shows that only one person could ever use it. So the Debug Build is retired: one firmware, with the console in it, off until its owner switches it on. Then an evening of chasing a console that wouldn't come back and a memory leak, neither of which existed.'''
+date = 2026-10-07T00:30:00+02:00
+
+[extra]
+topics = '''ESP32-S3 · Debugging · Security'''
+read_label = '''Read what was off →'''
+uid = '''<b>debug:</b> on, token set, client connected'''
+dek = "A day of writing for [roro9stack](/devlog/roro9stack/), my firmware for the M5Stack Cardputer: a website, a user guide, and developer docs about the thing I like best in it, a console over Wi-Fi. Documenting it properly made one fact hard to miss: nobody else could have it. Fixing that deleted more than it added, and then cost me an evening looking for two bugs that turned out to be a switch in the Off position and TCP minding its own business."
+byline = '''designed by interrogation, round twelve: fourteen questions thrown away, eight kept'''
+
+[extra.sign]
+label = "Tokens leaked by the feature built to protect them"
+note = "In a screenshot, taken over the console, of the one page that shows the token."
+count = "1"
+tone = "red"
+
+[[extra.cast]]
+name = "The Debug Build"
+role = "retired, v0.3.0 to v0.11.0"
+text = "The same firmware plus a console over Wi-Fi, with its builder's token compiled in. Which is why it could never be published, and why the firmware I tested was never the one I released."
+
+[[extra.cast]]
+name = "Port 3232"
+role = "the Update Service, in every build since v0.3.0"
+text = "Listens on the network in release builds, guarded by a signature. The counter-example to \"in a release, nothing listens\" that had been sitting there all along."
+
+[[extra.cast]]
+name = "The token"
+role = "100 bits, 20 characters"
+text = "Made by the device, shown on one page of Settings and nowhere else. Read off a 240-pixel screen by a human, which is where the trouble started."
+
+[[extra.cast]]
+name = "The dialog"
+role = "\"Switch it on?\""
+text = "Opens with Cancel selected, as a question about a remote control should. Enter, Enter: still off. Works exactly as designed."
+
+[[extra.cast]]
+name = "TIME_WAIT"
+role = "two minutes, per closed connection"
+text = "What TCP does with a connection it has closed, in case a late packet turns up. About 270 bytes each. Looks exactly like a leak if you only watch for one minute."
++++
+
+## TL;DR
+
+- **roro9stack has a website:** [roro9stack.net](/), with an Install page that flashes a Cardputer from the browser, a [user guide](/guide/), [how-tos](/howto/), an [FAQ](/faq/), [developer docs](/dev/) generated from the repository, and this devlog, which moved here.
+- **The Debug Build is gone.** There is one firmware (**v0.12.0**), and the Debug Console is in it: **off** until you switch it on in Settings, with a token the device makes itself.
+- **The token never crosses the network.** The device sends a challenge, the client answers with an HMAC. Five wrong answers close the console for a minute.
+- **It costs** 30 KB of flash and 88 bytes of RAM over the old release build. Off, nothing listens and nothing is allocated.
+- Then I spent an evening on **a console that wouldn't come back on** (it was off) and **a memory leak of 230 bytes per reopening** (it was TCP). Both produced a real fix on the way, and one design change I had to undo.
+- 468 host tests, 12 more than last time. The decision is [ADR 0010](/dev/decisions/0010-debug-console-in-every-build/).
+
+## The cast
+
+{{ cast() }}
+
+## A site, in four phases
+
+The [last post](/devlog/roro9stack-f1-r1/) ended with a device that installs its own releases. That makes it something another person could use, and another person needs somewhere to start that isn't a Gitea README. So the first half of the day was a website: a home page, an Install page, then a guide to each App, how-tos, an FAQ, and developer docs.
+
+Three things from that half are worth keeping.
+
+**Flashing from the browser, without a copy of the firmware.** The Install page uses ESP Web Tools and Web Serial. The obvious way is to copy the firmware image next to the page; then every release needs a rebuild of the site. Instead the page asks Gitea's API for the latest release, in the browser, and hands the flasher a manifest it builds on the spot. That only needed one header: Caddy, in front of Gitea, adds `Access-Control-Allow-Origin: https://roro9stack.net` to the release downloads and to the releases API, which are public anyway. A new release shows up on the page the moment it exists.
+
+**"Generated from the repository" met Zola.** The developer docs were to be built from `docs/`, the README and the firmware's own `help` text, not copied by hand. Zola refuses to read a file outside its own folder, and it resolves symlinks before deciding, so that door is closed too. So a small script writes those pages, they are committed, and CI fails when one is out of date. The command reference is the part I like: it is parsed from the `kHelp` string in `main.cpp`, so the site can't describe a command the firmware doesn't have.
+
+**The posts you're reading had `<style>` in them.** This devlog came over from my blog, seventeen diagrams included, each an inline SVG with its own `<style>` block. The site's Content-Security-Policy is `style-src 'self'`, which refuses exactly that. The rules moved into a stylesheet and the `style="…"` attributes became classes. Tested in a real browser with the production policy on every response: no violations.
+
+The site says only what the firmware does today, which meant writing the same sentence several times: the mesh messenger isn't built. The radio listens. It doesn't talk yet.
+
+## Documenting a feature only I could use
+
+The part of the developer docs I cared most about is the Debug Console: the serial console over Wi-Fi, with key presses, screenshots, file transfer and crash dumps. I wrote six pages on it, checked the protocol against the live device, and by the end had described, in detail, a feature with this property:
+
+> A Debug Build carries its builder's token, so Debug Builds are never published.
+
+Everything in those pages was for whoever builds the firmware. That's me.
+
+The issue I filed was the obvious patch: make the token configurable, so that Debug Builds can be published. The design round for it had fourteen questions. Where does a published Debug Build go, so that devices in the field don't install it by accident (v0.11.0 takes the last `.ota` it finds in a release)? What is its tag called, so that CI doesn't start itself again? How does a device that runs one get the next?
+
+Then one question from the other side of the table replaced all fourteen: *why have Debug Builds at all?*
+
+## The argument that was never whole
+
+[ADR 0004](/dev/decisions/0004-debug-console-in-debug-builds/) kept the console out of release builds with one sentence, which I was rather proud of:
+
+> A console that runs commands is a remote control: in a release build, nothing listens.
+
+Except something does. The Update Service has listened on TCP 3232 in every build since v0.3.0, guarded by a signature. "Nothing listens" was never true; "nothing listens without a lock on it" was. A console that is off by default, behind a secret the device made itself, is the same trade.
+
+And the split had been charging rent the whole time:
+
+- **What I tested wasn't what I shipped.** I lived on Debug Builds. Releases were a different binary that nobody ran before it was published.
+- **Rules that only protected the console.** A Debug Build refused to install a release (it would have lost its console), so there was `update install … force` to do it anyway, and advice about which firmware to keep in the other slot.
+- **Versions ending in `+debug`** that had to compare equal to their release.
+- **Two firmwares built by CI** on every pull request and every tag.
+
+One firmware deletes all four.
+
+## What off means
+
+The new argument only holds if "off" is as good as "not compiled in". So:
+
+- **Off is the default,** and what a missing or damaged setting falls back to.
+- **Off, nothing exists:** no socket, no task, and no 4 KB buffer, which used to be a static array and is now allocated when the console is switched on.
+- **On needs someone at the device,** or on the USB cable. Over the console itself, `debug on` and `debug token` answer `over USB serial only`: it can switch itself off, not open itself wider.
+
+{% table() %}
+| Build | Flash | Static RAM |
+|---|---|---|
+| The release build, before | 1,851,387 | 54,612 |
+| The Debug Build, before | 1,874,887 | 58,780 |
+| **The one firmware** | **1,881,799** | **54,700** |
+{% end %}
+
+Thirty kilobytes of flash, and 88 bytes of RAM, for a console in every device. The Debug Build's extra 4 KB of RAM was the buffer, sitting there whether anyone connected or not.
+
+## A token you can read, and one you can't steal
+
+The token used to be 32 hex digits in a file on my laptop, compiled in. Now the device makes it, the first time the console is switched on: 100 bits from the hardware generator, as twenty characters of Crockford's base32, the alphabet that leaves out I, L, O and U because people misread them.
+
+The old login sent the token as the first line of a plain TCP connection. That was fine for a secret that lived on one laptop and one device on one network. It's not fine for a secret in every device, on whatever Wi-Fi its owner uses: mine is called `knbg-guests`, and anyone with the Wi-Fi password can watch it.
+
+So the token no longer travels:
+
+{% code(caption="The whole login. A recorded answer is no use for the next challenge.") %}
+```
+device:  roro9stack debug console, challenge 3f9a…c1   (16 random bytes)
+client:  HMAC-SHA256(key = token, message = those bytes), in hex
+device:  roro9stack v0.12.0 debug console. 'help' lists the commands. Backlog follows.
+```
+{% end %}
+
+HMAC is twenty lines on top of the SHA-256 the firmware already had for update files, checked against the RFC's vectors and against the same vector as the Python client. Five wrong answers in a row and the console answers `locked` to everyone for a minute:
+
+{% code(caption="Six tries with a wrong token, then the right one.") %}
+```
+try 1 at  1s: wrong token
+try 2 at  3s: wrong token
+try 3 at  4s: wrong token
+try 4 at  5s: wrong token
+try 5 at  6s: wrong token
+try 6 at  6s: closed for a minute after too many wrong tokens
+right token:  closed for a minute after too many wrong tokens
+```
+{% end %}
+
+This breaks every old client. I'm the only user, and v1 is a long way off; this is exactly when to break things.
+
+## Three ways it went wrong
+
+### I couldn't read my own token
+
+First login, on the real device: `wrong token`. The firmware was right. I had typed one character wrong, reading a 20-character token drawn in bold at the normal size, where 8 and B, 5 and S, 2 and Z are a matter of opinion.
+
+The token is now drawn at twice the size, in regular weight, on two lines. And what I should have done from the start: Crockford's rule says that if someone types an O, an I or an L, they meant 0 or 1, because the alphabet doesn't have those letters. Both ends now apply it.
+
+### The screenshot
+
+To check the new layout I did what I always do: took a screenshot over the console.
+
+{{ figure(src="token.png", alt="The Cardputer's Settings, Debug Console page at 2x: Debug Console On, Connect to 10.39.39.12:2323, New token, Type a token, and below them a token in large type on two lines, T49R-HQXB-NDJX then BNSB-XSWD. The Status Bar shows DBG in blue.", width=480, height=270, caption="The page that shows the token \"and nowhere else\", in a file on my laptop. This token was replaced within the hour.") }}
+
+The documentation I had written an hour earlier says the token is shown on one page and never printed anywhere. And there it is, in a PNG. No escalation: whoever can take a screenshot already has the token. But a secret now sits in a file because of a habit, and the sign at the top of this post is for that. The docs now say it in so many words: a screenshot of that page is a copy of the token.
+
+### The console that wouldn't come back
+
+The last test was `debug off`, sent over the console: the client is dropped, the port refuses connections. Good. I switched it back on at the device, made a new token, and tried to log in.
+
+Connection refused.
+
+The device was up. Its update port answered. And it stayed refused across another firmware push and a restart. So, I reasoned, the console fails to come back once it has been closed, and I went looking:
+
+- **The framework's `begin()` returns nothing.** `NetworkServer::begin()` can fail at `socket()`, `bind()` or `listen()` and says nothing either way; my code set `listening = true` and never asked. A real hole. Fixed: it asks, complains on the console, and tries again every two seconds.
+- **I couldn't reproduce it from my desk.** Switching the console on is for the device and the cable only, by design, so the one path I wanted to test was the one I had made unreachable. Hence `debug off <seconds>`: the console closes and comes back by itself after the pause. It can't open anything wider (same state, same token), and it makes closing and reopening something a script can do twenty times.
+
+Then I went and looked at the device's screen.
+
+It said **Off**.
+
+The "Switch it on?" dialog opens with **Cancel** selected. Enter on the row, Enter on the dialog: nothing changes, and the page says so in plain letters that I hadn't read. I had filed a bug against a switch for being in the position I left it in.
+
+### The leak that was TCP
+
+With `debug off <seconds>` I could finally hammer the path. It came back every time. And free memory fell by about 230 bytes per cycle.
+
+A leak in code I had just written, in a firmware where 836 bytes was [once all that was left](/devlog/roro9stack-f1-r1/). I had a suspect: the console's task is deleted when the console goes off and made again when it comes back. Twenty plain logins leaked nothing, so it wasn't connections. I changed the design: the task stays, asleep, while the console is off. That breaks the promise that off means nothing is there, but a leak is worse.
+
+It leaked exactly as much as before.
+
+So I did what I should have done first, and measured for longer:
+
+{% table() %}
+| | Free heap |
+|---|---|
+| Before | 107,248 |
+| Right after 15 closings and reopenings | 103,180 |
+| 60 s later | 105,008 |
+| 120 s later | 107,004 |
+| 240 s later | 106,924 |
+{% end %}
+
+All of it comes back. When the device closes a connection, TCP keeps it for two minutes in case a late packet arrives, and each one holds about 270 bytes. Fifteen cycles in a minute and a half look like a leak; fifteen cycles and a cup of tea look like nothing at all.
+
+The design change went back out. Off means the task is gone too, as decided.
+
+## What held
+
+{{ figure(src="dbg.png", alt="The Cardputer's Launcher at 2x, listing IRC, Wi-Fi Tools, GNSS, Gemini, LoRa Scanner, Storage, Notes, System and Settings. The Status Bar shows DBG in blue between the GNSS and Wi-Fi indicators.", width=480, height=270, caption="`DBG` in the Status Bar: there while the console listens, bright while someone is connected. Taken over the console, so: bright.") }}
+
+Checked on the device, not just in tests:
+
+- **Off by default.** Pushed over a Debug Build, the new firmware came up with port 2323 refusing connections.
+- **The setting survives updates.** Four pushes later the console came back by itself each time.
+- **Safe Mode has the console.** Three `crash abort` in a row, and the device started in Safe Mode with 178 KB free and the console reachable. `ls /` answered `not available in Safe Mode`, and the crash decoded to the line of `main.cpp` with `abort()` on it.
+- **25 closings and reopenings,** each back a second after its pause.
+- **More memory than before.** 108 KB free with the console on and a client connected, against 104 KB on the Debug Build.
+
+And what I didn't check: `scripts/flash.sh --debug`, which now sets a device up over USB, with no cable attached to the VM that night; typing a token of my own on the device; and the notification on the screen during a lockout, which nobody connected can see, the console being closed.
+
+## By the numbers
+
+{% table() %}
+| | |
+|---|---|
+| Design questions written, then thrown away | 14 |
+| Design questions kept | 8 |
+| Host tests | 468 |
+| Bits in a token | 100 |
+| Wrong answers before the console closes | 5 |
+| Flash it costs every device | 30,412 bytes |
+| RAM it costs every device, off | 88 bytes |
+| Bytes TCP holds for a closed connection, for two minutes | about 270 |
+| Pages on the website | 66 |
+| Bugs found in the console that evening | 1 (the silent `begin()`) |
+| Bugs I thought I'd found | 3 |
+{% end %}
+
+## Where it stands
+
+{% steps() %}
+1. ~~M0 and M1: the skeleton, Wi-Fi, IRC, Wi-Fi Tools.~~ v0.1.0 to v0.2.1, [the first post](/devlog/roro9stack/).
+
+2. ~~Updates and debugging over the air.~~ v0.3.0, [Look, no cables](/devlog/roro9stack-ota/).
+
+3. ~~M2: GNSS.~~ v0.4.0, [Seventeen satellites](/devlog/roro9stack-gnss/).
+
+4. ~~G1: Gemini.~~ v0.5.0, [A browser in the RAM IRC left over](/devlog/roro9stack-gemini/).
+
+5. ~~M3: the LoRa radio, listening.~~ v0.6.0, [The loudest thing it hears is itself](/devlog/roro9stack-lora/).
+
+6. ~~S1: the card, fixed addresses, the System App.~~ v0.6.1 to v0.8.1, [One byte too early](/devlog/roro9stack-s1/).
+
+7. ~~F1 and the start of R1: files, notes, signed releases, updates from Gitea.~~ v0.9.0 to v0.11.0, [836 bytes](/devlog/roro9stack-f1-r1/).
+
+8. ~~W1: the website.~~ You're on it.
+
+9. ~~One firmware, with the Debug Console in it.~~ v0.12.0, this post.
+
+10. Next: notes of any size, a shell on the device itself for the same commands, and one help key everywhere instead of a hint line on every screen. And M4, the mesh, which still wants a second node.
+{% end %}
+
+{% signoff() %}
+I wrote a feature whose whole point is that it's off until you switch it on, and then spent an evening debugging it for being off. The switch works. So does TCP. The only thing that leaked was the token, and I did that myself.
+{% end %}

site/content/faq.md

@@ -0,0 +1,76 @@
++++
+title = "Questions and answers"
+description = "What the firmware does and does not do today, what it talks to over the network, and how to run, update and fix it."
+template = "guide-page.html"
+[extra]
+toc = true
++++
+
+## Can I send messages over the mesh?
+
+**Not yet.** The LoRa Scanner **listens** to Meshtastic traffic and shows what it hears, but nothing is transmitted. A mesh messenger is the goal and is planned in two milestones, one for receiving and one for transmitting; it waits for a second node to test against.
+
+## Is this Meshtastic?
+
+No. roro9stack is its own firmware, written from scratch, which aims to be **compatible** with Meshtastic on the air. Today that means the Scanner can read a Meshtastic packet's header. The project isn't affiliated with or endorsed by Meshtastic or M5Stack.
+
+## Does it ever transmit on LoRa?
+
+No. The radio is receive-only in the current firmware. Nothing will transmit until you have confirmed your region in Settings, and the region's limits (frequencies, power, duty cycle) will bound anything that does.
+
+## What do I need?
+
+- an **M5Stack Cardputer ADV**: that is the device the firmware is built and tested for;
+- the **Cap LoRa-1262**, for the LoRa Scanner and GNSS only: the other Apps do not need it;
+- a **microSD card**, for notes, logs, tracks, captures and saved pages;
+- **Wi-Fi** (2.4 GHz) for IRC, Gemini and updates.
+
+## Which regions are supported?
+
+**EU868** only, today. Setup asks for your region once, and the radio does not transmit until you confirm it.
+
+## Why do I need Chrome or Edge to install it?
+
+The browser flasher uses Web Serial, which Chrome and Edge have on desktop and Firefox and Safari don't. Without it, the **esptool** steps on the [Install page](/install/) flash the same file from a terminal.
+
+## How do I update it?
+
+Three ways, all with the same signed update file: from the project's releases on the device itself (**Settings → Firmware**), from the SD card, or pushed over Wi-Fi from a PC. See [Updates](/guide/updates/) and [Install an update from the SD card](/howto/update-from-sd/).
+
+## Is it safe to update? What if it goes wrong?
+
+A new firmware runs on **Probation**: if it crashes, restarts, or cannot get Wi-Fi back within 3 minutes, the device returns to the previous version by itself. If a confirmed firmware crashes 3 times in a row, it starts in **Safe Mode** with only Wi-Fi and updates, so a fix can be installed without a cable. And an update that is not signed with the project's key is refused before anything is written.
+
+## Can I run my own build?
+
+Yes: it is [open source](https://git.twis.la/twisla/roro9stack) (GPL-3.0). The device only accepts updates signed with the key that its firmware was built with, so a build of your own, signed with your own key, is flashed once over USB (the README explains it); after that, your own updates go over Wi-Fi or the card. Releases from this project are signed with the project's key.
+
+## Does it phone home? What about privacy?
+
+**The firmware contacts the project's server once a day,** to see whether a new release exists: **Settings → Check for updates**, on by default, only when Wi-Fi is up and the clock is set. It installs nothing by itself, and you can switch it off. Besides that, the device talks to what you ask it to: the IRC server and Gemini capsules you open, DNS servers (9.9.9.9 and 1.1.1.1 by default) and time servers (pool.ntp.org and time.cloudflare.com by default), all of which you can change. There is no account, no analytics and no telemetry.
+
+**This website** sets no cookies and has no analytics, loads nothing from other sites, and its server logs keep only a masked part of visitors' addresses. The Install page asks the project's own server for the latest release.
+
+## Why does IRC disconnect when I update, or when I open a Gemini page?
+
+A secure connection takes about 52 KB of the 107 KB the device has, and IRC's takes about 40 KB. Both together do not always fit. See [When a connection says "not enough memory"](/howto/not-enough-memory/).
+
+## Do I need an SD card?
+
+For the radio, GNSS position, Wi-Fi tools, IRC chat and Gemini browsing, no. For anything that is *kept*, yes: notes, IRC logs, Wi-Fi scan logs, GNSS Tracks, LoRa captures, saved Gemini pages and update files. See [Find your files on the SD card](/howto/sd-files/).
+
+## How big can a note be?
+
+Up to 16 KB while it is edited. A larger text file opens read-only in the [Storage App](/guide/storage/). Editing a text file of any size is planned.
+
+## Why can't I rename or delete some folders?
+
+The firmware keeps its files in the top-level folders of the card, and `/gemini/cache` and any file being written right now are protected. What is inside the top-level folders can be changed. The Storage App says why when it refuses.
+
+## The upload can't connect, or the port is missing
+
+Try a data cable, put the Cardputer in download mode (hold **G0** while plugging in USB), and see [When flashing fails](/howto/flash-fails/).
+
+## Something is wrong, or missing from this site
+
+Write to the [issue tracker](https://git.twis.la/twisla/roro9stack/issues) or to contact@roro9stack.net. Security problems: the address in the site's `security.txt`, and please not in the public tracker.

site/content/guide/_index.md

@@ -10,4 +10,6 @@ This guide says what the firmware does **today** and nothing else. Start with th
 
 **The mesh messenger is planned, not built.** The LoRa Scanner listens to Meshtastic traffic and shows it, but the device sends nothing yet: that is the next milestone and waits for a second node to test with.
 
+Looking for a recipe or a quick answer? There are [how-tos](/howto/) and a [FAQ](/faq/).
+
 Something missing or wrong? Write to the [issue tracker](https://git.twis.la/twisla/roro9stack/issues) or to contact@roro9stack.net.

site/content/guide/basics.md

@@ -38,6 +38,7 @@ A strip at the top of every screen: the name of the App on the left, and on the
 | `97%` | The battery (in the warning colour at 15% and under) |
 | `SD` | A card is in; the warning colour at 80% full |
 | bars and `W` | Wi-Fi connected, with its signal; `W?` is searching; `MON` is the Wi-Fi radio in its monitoring mode, which pauses IRC |
+| `DBG` | The Debug Console is switched on (Settings → Debug Console); brighter while a PC is connected to it |
 | `REC` | A GNSS Track is being recorded |
 | `CAP` | A LoRa capture is being recorded |
 | `L` | The radio is listening; it lights up for a moment on each packet. `SW` while a Sweep runs |

site/content/guide/settings.md

@@ -22,6 +22,7 @@ Move with the arrows. On a toggle, a choice or a slider, left and right change t
 | **Wi-Fi** | The page below |
 | **Check for updates** | Once a day, see [Updates](/guide/updates/) |
 | **Firmware** | The page described in [Updates](/guide/updates/) |
+| **Debug Console** | Off unless you switch it on. It lets a PC on the same network read the device's console and drive it, with a token shown on this page: see [the developer docs](/dev/debug/switch-it-on/). Leave it off if that means nothing to you |
 | **About** | The firmware version, the node number, battery, memory, uptime, clock and licence |
 
 ## Wi-Fi

site/content/guide/updates.md

@@ -41,4 +41,4 @@ The connection to the project's server is checked against the two root certifica
 
 ## For developers
 
-Updates can also be pushed from a PC over Wi-Fi, with `scripts/flash.sh --ota <ip>`, or put on the card with `scripts/sd_put.sh`: see the [README](https://git.twis.la/twisla/roro9stack#firmware-updates-over-wi-fi-ota). **Debug Builds** show the latest release but do not install it, because a release has no debug console: update a Debug Build from the PC.
+Updates can also be pushed from a PC over Wi-Fi, with `scripts/flash.sh --ota <ip>`, or put on the card with `scripts/sd_put.sh`: see the [README](https://git.twis.la/twisla/roro9stack#firmware-updates-over-wi-fi-ota). The firmware's console can be reached over Wi-Fi too: see [The Debug Console](/dev/debug/).

site/content/howto/_index.md

@@ -0,0 +1,12 @@
++++
+title = "How-tos"
+description = "Short recipes for things you will want to do: put a file on the card, record a track, capture radio packets, and what to try when something does not work."
+template = "guide-index.html"
+page_template = "guide-page.html"
+sort_by = "weight"
+
+[extra]
+eyebrow = "How-tos"
++++
+
+Each recipe is a handful of steps and says what you should see after each one. For what a screen or a key does, the [user guide](/guide/) has a page for every App; for quick answers, there is the [FAQ](/faq/).

site/content/howto/flash-fails.md

@@ -0,0 +1,35 @@
++++
+title = "When flashing fails"
+description = "What to try when the browser or esptool cannot find the Cardputer, cannot connect, or loses the connection halfway."
+weight = 1
+[extra]
+tag = "Install"
++++
+
+## 1. Use a cable that carries data
+
+A charge-only USB-C cable powers the device but never shows up as a serial port. If a cable has worked for data before, use that one.
+
+## 2. Put the Cardputer in download mode
+
+Hold **G0**, the button next to the screen, while you plug in the USB cable, or while you press the reset button. Then try again. This is the first thing to try when an upload "can't connect".
+
+## 3. Browser flashing: Chrome or Edge, on a desktop
+
+The Install page flashes through the browser's Web Serial feature, which Firefox and Safari don't have. In Chrome or Edge, the browser asks you to pick the serial port from a list: pick the one that appears when you plug the Cardputer in. If the list is empty, go back to steps 1 and 2.
+
+## 4. Linux: "permission denied" on the port
+
+Your user needs access to serial devices. Run this once, then log out and back in:
+
+```
+sudo usermod -aG dialout "$USER"
+```
+
+## 5. In a virtual machine
+
+USB passthrough can fail with `OSError: [Errno 71] Protocol error`. Retrying alone doesn't help; **resetting the Cardputer does**, and putting it in download mode moves the serial port to a new name, so pick the port again afterwards.
+
+## Still stuck?
+
+The **esptool** steps on the [Install page](/install/) flash the same file without a browser, and their error messages are more detailed. If it still fails, open an [issue](https://git.twis.la/twisla/roro9stack/issues) and say what you see.

site/content/howto/gemini-offline.md

@@ -0,0 +1,22 @@
++++
+title = "Read Gemini pages offline"
+description = "Save pages to the SD card, and read them later with Wi-Fi off."
+weight = 7
+[extra]
+tag = "Gemini"
++++
+
+You need an **SD card**.
+
+1. **Open the page** in the [Gemini App](/guide/gemini/).
+2. **Press <kbd>s</kbd>** to save it. It is kept with the address it came from and the time it was saved. Saving the same page again replaces it, and says so.
+3. **To keep a whole capsule corner,** press <kbd>S</kbd> instead: it saves the page and the pages it links to on the **same capsule**, as text only, up to 30, in the background.
+4. **Later, offline:** open the Gemini App. The start page lists **Saved Pages**, newest first, grouped by capsule, below your bookmarks. They open with no network.
+5. **Links inside a saved page** open the saved copy when there is one. Any other link needs Wi-Fi, or says `not saved, offline`.
+
+## Keeping it tidy
+
+- <kbd>r</kbd> **refreshes** a saved page from the web, and <kbd>d</kbd> **deletes** it.
+- **Bookmarks** (<kbd>b</kbd>) are a list of addresses, not copies: they need Wi-Fi to open.
+- Saved Pages are never offered for deletion by the clean-up. They are in `/gemini/saved/` if you want to move them.
+- A file that is not text (a picture, say) is saved to `/gemini/downloads/` and cannot be shown on the device.

site/content/howto/lora-capture.md

@@ -0,0 +1,20 @@
++++
+title = "Capture LoRa packets and open them in Wireshark"
+description = "Record what the radio hears into a pcap file, then read it on a computer."
+weight = 6
+[extra]
+tag = "LoRa Scanner"
++++
+
+The radio only **listens**: nothing is transmitted. You need the **Cap LoRa-1262** and an **SD card**.
+
+1. **Open the LoRa Scanner.** The Status Bar shows `L` while the radio listens.
+2. **Pick a preset with <kbd>p</kbd>.** The Scanner offers the 7 Meshtastic presets allowed in EU868; LongFast is the default.
+3. **Wait for packets.** Each line is a packet: the time, RSSI and SNR, and for a Meshtastic packet the sender, the receiver and the hops. <kbd>Enter</kbd> shows a packet's header and its bytes.
+4. **Press <kbd>c</kbd> to start a capture.** The Status Bar shows `CAP`. It keeps recording with the App closed.
+5. **Press <kbd>c</kbd> again to stop.**
+6. **Get the file.** It is in `/captures/lora/`, a `.pcap` with LoRaTap headers. In the [Storage App](/guide/storage/) you can already look at its packets; on a computer, open it in Wireshark.
+
+**What you will and will not see.** Meshtastic's header is never encrypted, so who sent a packet and how far it hopped is visible. The message itself is encrypted with the channel's key, and the Scanner does not decrypt it.
+
+**Hearing nothing is normal** if no node is in range, or if the preset does not match what the nodes nearby use. The [Sweep](/guide/lora-scanner/) (<kbd>Tab</kbd>) shows whether anything is on the air at all across 863 to 870 MHz.

site/content/howto/no-dhcp.md

@@ -0,0 +1,22 @@
++++
+title = "Use a network without DHCP"
+description = "Give the device a fixed IP address, and your own DNS and time servers, on a network that does not hand out addresses."
+weight = 4
+[extra]
+tag = "Wi-Fi"
++++
+
+1. **Add the network first.** In **Settings → Wi-Fi**, choose **Add a network**, pick it and type the password. (A hidden network has its own entry, which asks for the name first.)
+2. **Open the network's page:** <kbd>Enter</kbd> on it in the list of saved networks.
+3. **Set *IP address* to *Fixed*.** The address, the prefix and the gateway start from what the network is giving the device at that moment, so you only change what is wrong.
+   - **Address:** four numbers, like `10.39.39.13`.
+   - **Prefix:** 1 to 30. 24 is 255.255.255.0.
+   - **Gateway:** optional; empty means none.
+4. **Leave the page.** The setting is checked and applied then; a bad address is refused with the reason.
+5. **Check it.** Back in **Settings → Wi-Fi**, <kbd>Enter</kbd> on **Status** shows the address, the mask, the gateway, the DNS and NTP servers, and where each came from.
+
+## DNS and time
+
+**DNS and NTP** on the Wi-Fi page holds two DNS servers (9.9.9.9 and 1.1.1.1 by default) and two NTP servers (pool.ntp.org and time.cloudflare.com). They are used on Fixed networks, or on every network if **Always use my DNS** is on. Leave a second server empty if you only have one. IPv4 only.
+
+To go back, set *IP address* to *Automatic*. **Forget this network** is at the bottom of the same page.

site/content/howto/not-enough-memory.md

@@ -0,0 +1,25 @@
++++
+title = "When a connection says \"not enough memory\""
+description = "The device has about 107 KB to share, and a secure connection takes about 52 KB. How to free some, and why it happens."
+weight = 8
+[extra]
+tag = "Memory"
++++
+
+## What you see
+
+Opening a Gemini page fails with *not enough memory: stop IRC or retry*. Or an update check or install makes IRC disconnect for a moment.
+
+## What to do
+
+1. **Stop IRC.** In the IRC App, type `/quit` and press <kbd>Enter</kbd>. IRC disconnects and **stays** disconnected until you type something again, so it does not take the memory back.
+2. **Try again.** A Gemini fetch needs 55 KB free before it starts.
+3. **Start IRC again** when you are done: type a line in the IRC App, and it reconnects and rejoins its channels.
+
+## See it
+
+The [System App](/guide/system/)'s **Memory** view shows free memory, the lowest since the device started, and the largest free block, drawn against the three memory floors (55, 40 and 20 KB). Watch it fall when a connection opens, and recover when it closes.
+
+## Why it happens
+
+The Cardputer's chip has no extra memory (no PSRAM). A secure (TLS) connection costs about **52 KB** at its peak, and IRC's own connection holds about 40 KB of the 107 KB there is. A second secure connection on top does not fit, so the firmware refuses it early instead of crashing. This is also why IRC steps aside during an update, and why the daily update check waits until IRC is not connected: see [Updates](/guide/updates/).

site/content/howto/record-track.md

@@ -0,0 +1,18 @@
++++
+title = "Record a Track and open it"
+description = "Record where you have been with the GNSS receiver, and open the file in a mapping tool."
+weight = 5
+[extra]
+tag = "GNSS"
++++
+
+You need the **Cap LoRa-1262**, an **SD card**, and a place with a view of the sky.
+
+1. **Switch the receiver on:** **Settings → GNSS** to *On*. The Status Bar shows `G` once it is searching.
+2. **Open the GNSS App** and wait for a fix. The first line says `Searching: n in view` and how long it has been, then `3D Fix, n of m satellites`. The first fix outdoors can take a while.
+3. **The clock must be set.** A fix sets it, and so does Wi-Fi. A Track will not start without one: the App says `Waiting for the time`.
+4. **Press <kbd>r</kbd>.** The bottom line says `REC`, with the number of points and how long it has been going, and the Status Bar shows `REC`. You can leave the App: the Track keeps recording.
+5. **Press <kbd>r</kbd> again to stop,** in the GNSS App.
+6. **Open it.** In the [Storage App](/guide/storage/), go to `/gnss/tracks` and open the `.gpx` file: it shows the number of points, the start, the duration and the distance. To see the route on a map, take the card to a computer and open the file in any GPX viewer or mapping tool.
+
+If *Pause GNSS for LoRa* is on, the receiver stays awake while a Track is being recorded, so recording is not interrupted by the radio.

site/content/howto/sd-files.md

@@ -0,0 +1,28 @@
++++
+title = "Find your files on the SD card"
+description = "Where the notes, tracks, captures, logs and saved pages are written, so you can take the card to a computer and use them."
+weight = 2
+[extra]
+tag = "SD card"
++++
+
+Everything the firmware writes goes in a folder at the top of the card. Switch the Cardputer off, take the card out and read it in a computer; or look at the same folders in the [Storage App](/guide/storage/).
+
+| What | Where | Kind of file |
+|---|---|---|
+| Notes | `/notes` | `.txt`, named after the first line |
+| GNSS Tracks | `/gnss/tracks` | `.gpx`, named by date and time |
+| LoRa captures | `/captures/lora` | `.pcap` |
+| IRC logs | `/irc` | one text file per buffer and day |
+| Wi-Fi scan logs | `/wifi/scans` | `<date>.csv` |
+| Gemini Saved Pages | `/gemini/saved/<host>/…` | `.gmi` |
+| Gemini bookmarks | `/gemini/bookmarks.gmi` | gemtext |
+| Files saved from Gemini that are not text | `/gemini/downloads` | whatever they were |
+| Update files | `/updates` | `.ota` |
+
+## Rules worth knowing
+
+- **Eject first.** A file being written (today's IRC log, a Track or a capture being recorded) is not complete until it stops. Stop it, or switch the device off, before you take the card out.
+- **Notes are yours.** You can edit them on a computer and they show up on the device; the clean-up never offers them for deletion.
+- **Don't rename the top-level folders.** The firmware looks for them by name.
+- **Logs stop at 90% full,** so the remaining space is kept for captures. The [Storage App](/guide/storage/)'s Maintenance shows what is using the card and clears old logs and captures, after showing what it would free.

site/content/howto/update-from-sd.md

@@ -0,0 +1,15 @@
++++
+title = "Install an update from the SD card"
+description = "Update the firmware with no Wi-Fi and no cable: copy one file onto the card and install it from the device."
+weight = 3
+[extra]
+tag = "Updates"
++++
+
+1. **Get the update file.** On the [Downloads page](/downloads/), take the `.ota` file of the release you want: `roro9stack-<version>.ota`. Every release has one.
+2. **Copy it to `/updates`** on the SD card, from a computer. If the folder is not there, create it. (With the Cardputer on USB, a developer can also send it with `scripts/sd_put.sh`; see the [README](https://git.twis.la/twisla/roro9stack#firmware-updates-over-wi-fi-ota).)
+3. **Put the card in the Cardputer.** Open **Settings → Firmware.** Under *On the SD card* the file is listed. If it says `No .ota files in /updates`, the name or the folder is wrong.
+4. **Press Enter on the file,** then **Install**. The device checks the signature and the contents before it writes anything, installs, and restarts. It waits up to 60 seconds if you are typing.
+5. **After the restart** the new firmware is on **Probation**: if it crashes or cannot get Wi-Fi back within 3 minutes, the device goes back to the previous version by itself and says so.
+
+You can also open the file in the [Storage App](/guide/storage/): it shows the version and whether the file would install, then <kbd>Enter</kbd> installs it. A file that is not signed with the project's key is refused, and nothing changes.

site/static/css/site.css

@@ -242,3 +242,15 @@ footer small { display: block; max-width: 760px; }
 .prose kbd { font: 500 13px/16px var(--mono); background: var(--s2); padding: 1px 6px; border: 1px solid var(--line); }
 .prose .note { background: var(--s2); padding: 16px 20px; }
 .prose h3 { margin-top: 12px; }
+
+/* The developer docs: generated pages hold wide tables and long code lines */
+.docs { max-width: 820px; }
+.docs table { display: block; overflow-x: auto; }
+.docs h2 { margin-top: 32px; }
+.docs h3 { font-size: 22px; line-height: 28px; margin-top: 8px; }
+.docs h4 { font: 500 12px/16px var(--mono); letter-spacing: .08em; text-transform: uppercase; color: var(--muted); }
+.docs code { overflow-wrap: anywhere; }
+.docs pre code { overflow-wrap: normal; }
+.source { max-width: 820px; font-size: 14px; line-height: 20px; }
+.source code { background: var(--s2); padding: 0 6px; }
+.card.featured { flex-basis: 100%; }

site/templates/base.html

@@ -30,6 +30,7 @@
     <a href="/#apps">Apps</a>
     <a href="/install/">Install</a>
     <a href="/guide/">Guide</a>
+    <a href="/dev/">Developers</a>
     <a href="/downloads/">Downloads</a>
     <a href="/devlog/">Devlog</a>
     <button class="link-btn js-only" id="theme-toggle" type="button">Light</button>

site/templates/dev-index.html

@@ -0,0 +1,26 @@
+{% extends "base.html" %}
+{% block title %}{{ section.title }}: roro9stack{% endblock %}
+{% block description %}{{ section.description }}{% endblock %}
+{% block main %}
+<div class="wrap page">
+  <header>
+    <span class="eyebrow">{{ section.extra.eyebrow }}</span>
+    <h1>{{ section.title }}</h1>
+    <p class="lead">{{ section.description }}</p>
+  </header>
+
+  <div class="prose">{{ section.content | safe }}</div>
+
+  <div class="cards">
+    {% for path in section.subsections %}
+    {% set sub = get_section(path=path) %}
+    <article class="card n-lg{% if loop.first %} featured{% endif %}">
+      <div class="card-top"><span class="tag">{% if loop.first %}Start here{% else %}{{ sub.pages | length }} pages{% endif %}</span><span class="num">{% if loop.index < 10 %}0{% endif %}{{ loop.index }}</span></div>
+      <h2><a href="{{ sub.permalink }}">{{ sub.title }}</a></h2>
+      <p>{{ sub.description }}</p>
+      {% if loop.first %}<p class="fact">{% for p in sub.pages %}{{ p.title }}{% if not loop.last %} · {% endif %}{% endfor %}</p>{% endif %}
+    </article>
+    {% endfor %}
+  </div>
+</div>
+{% endblock main %}

site/templates/downloads.html

@@ -11,7 +11,7 @@
   </header>
 
   <div class="prose">
-    <p>Each release has a <strong>signed update file</strong> (<code>.ota</code>: copy it to <code>/updates</code> on the SD card and install it from Settings → Firmware or the Storage App, or push it over Wi-Fi), a <strong>factory image</strong> (<code>-factory.bin</code>, the whole flash at offset 0 for a first install over USB), the <strong>symbols</strong> (<code>.elf.gz</code>, to decode a crash report) and <code>SHA256SUMS</code>. Debug Builds aren't published.</p>
+    <p>Each release has a <strong>signed update file</strong> (<code>.ota</code>: copy it to <code>/updates</code> on the SD card and install it from Settings → Firmware or the Storage App, or push it over Wi-Fi), a <strong>factory image</strong> (<code>-factory.bin</code>, the whole flash at offset 0 for a first install over USB), the <strong>symbols</strong> (<code>.elf.gz</code>, to decode a crash report) and <code>SHA256SUMS</code>.</p>
   </div>
 
   {% if releases %}

site/templates/guide-index.html

@@ -4,7 +4,7 @@
 {% block main %}
 <div class="wrap page">
   <header>
-    <span class="eyebrow">User guide</span>
+    <span class="eyebrow">{% if section.extra.eyebrow %}{{ section.extra.eyebrow }}{% else %}User guide{% endif %}</span>
     <h1>{{ section.title }}</h1>
     <p class="lead">{{ section.description }}</p>
   </header>

site/templates/guide-page.html

@@ -1,11 +1,19 @@
 {% extends "base.html" %}
-{% block title %}{{ page.title }}: roro9stack user guide{% endblock %}
+{% block title %}{% set parent_path = page.ancestors | last %}{% set parent = get_section(path=parent_path) %}{{ page.title }}: roro9stack {% if parent_path == "_index.md" %}FAQ{% else %}{{ parent.title | lower }}{% endif %}{% endblock %}
 {% block description %}{{ page.description }}{% endblock %}
+{% block head %}
+{% if page.extra.diagrams %}
+<link rel="stylesheet" href="/css/devlog.css">
+<link rel="stylesheet" href="/css/devlog-diagrams.css">
+{% endif %}
+{% endblock %}
 {% block main %}
+{% set parent_path = page.ancestors | last %}
+{% set parent = get_section(path=parent_path) %}
 {% set screens = load_data(path="data/screens.toml", format="toml") %}
-<div class="wrap page">
+<div class="wrap page{% if page.extra.diagrams %} devlog{% endif %}">
   <header>
-    <span class="eyebrow"><a href="/guide/">User guide</a>{% if page.extra.tag %} · {{ page.extra.tag }}{% endif %}</span>
+    <span class="eyebrow">{% if parent_path != "_index.md" %}<a href="{{ parent.permalink }}">{{ parent.title }}</a>{% else %}FAQ{% endif %}{% if page.extra.tag %} · {{ page.extra.tag }}{% endif %}</span>
     <h1>{{ page.title }}</h1>
     <p class="lead">{{ page.description }}</p>
   </header>
@@ -21,11 +29,23 @@
   </div>
   {% endif %}
 
-  <div class="prose">{{ page.content | safe }}</div>
+  {% if page.extra.toc %}
+  <nav class="prose toc" aria-label="Questions">
+    <ul>{% for h in page.toc %}<li><a class="accent-link" href="{{ h.permalink }}">{{ h.title }}</a></li>{% endfor %}</ul>
+  </nav>
+  {% endif %}
 
-  <nav class="pager" aria-label="User guide">
+  <div class="prose{% if page.extra.docs %} docs{% endif %}">{{ page.content | safe }}</div>
+
+  {% if page.extra.source %}
+  <p class="muted source">This page is generated from <code>{{ page.extra.source }}</code> in <a class="accent-link" href="{{ config.extra.repo }}/src/branch/main">the repository</a>. To change it, change that file and run <code>site/tools/gen_dev_docs.py</code>.</p>
+  {% endif %}
+
+  {% if page.lower or page.higher %}
+  <nav class="pager" aria-label="{{ parent.title }}">
     {% if page.lower %}<a class="accent-link" href="{{ page.lower.permalink }}">← {{ page.lower.title }}</a>{% else %}<span></span>{% endif %}
     {% if page.higher %}<a class="accent-link" href="{{ page.higher.permalink }}">{{ page.higher.title }} →</a>{% endif %}
   </nav>
+  {% endif %}
 </div>
 {% endblock main %}

site/tools/gen_dev_docs.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""Writes the developer pages of the site from the repository's own documents (docs/milestones/W1.md, phase 4).
+
+    python3 site/tools/gen_dev_docs.py            writes site/content/dev/... (committed, so the server only runs `zola build`)
+    python3 site/tools/gen_dev_docs.py --check    changes nothing; exits 1 if a generated page is out of date (CI)
+
+Zola cannot read a file outside its own folder, so the pages are generated and committed. What is generated:
+  decisions/  one page for each docs/adr/*.md
+  milestones/ one page for each docs/milestones/*.md
+  build/build-and-test, build/flash   sections of README.md
+  debug/commands   the commands the firmware's `help` prints (parsed from src/main.cpp), then README's table of them
+Every generated page says where it comes from; edit that file, not the page. Hand-written pages sit next to them.
+"""
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+SITE = HERE.parent
+REPO = SITE.parent
+OUT = SITE / "content" / "dev"
+REPO_URL = re.search(r'repo\s*=\s*"([^"]+)"', (SITE / "config.toml").read_text()).group(1)
+
+MILESTONES = ["OTA", "M2", "G1", "M3", "S1", "F1", "R1", "W1"]  # in the order they were done
+# Left out on purpose: docs/milestones/M0.md, M1.md and CONTEXT.md (the glossary) describe Wi-Fi monitoring, which this site does not publish.
+# They stay in the repository.
+
+
+def plain(md, limit=230):
+    """One line of plain text from the start of some Markdown, for a description."""
+    text = re.sub(r"`([^`]*)`", r"\1", md)
+    text = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", text)
+    text = re.sub(r"\*{1,3}", "", text)
+    text = re.sub(r"\s+", " ", text).strip()
+    text = text[:1].upper() + text[1:]
+    if len(text) <= limit:
+        return text
+    cut = text[:limit].rsplit(" ", 1)[0].rstrip(",;:")
+    return cut + "…"
+
+
+def front(title, description, weight, source, tag=None, template=None):
+    lines = ["+++", f"title = {json.dumps(title, ensure_ascii=False)}", f"description = {json.dumps(description, ensure_ascii=False)}", f"weight = {weight}"]
+    if template:
+        lines.append(f'template = "{template}"')
+    lines += ["", "[extra]", "docs = true", f"source = {json.dumps(source)}"]
+    if tag:
+        lines.append(f"tag = {json.dumps(tag, ensure_ascii=False)}")
+    lines += ["+++", ""]
+    return "\n".join(lines)
+
+
+def relink(md, source):
+    """Links between the repository's documents become links between the site's pages, or to Gitea."""
+    here = Path(source).parent
+
+    def fix(m):
+        label, target = m.group(1), m.group(2)
+        if re.match(r"[a-z]+:|#|/", target):
+            return m.group(0)
+        path, _, frag = target.partition("#")
+        full = os.path.normpath(here / path)
+        frag = "#" + frag if frag else ""
+        m_adr = re.fullmatch(r"docs/adr/(.+)\.md", full)
+        m_ms = re.fullmatch(r"docs/milestones/(.+)\.md", full)
+        if m_adr:
+            return f"[{label}](/dev/decisions/{m_adr.group(1)}/{frag})"
+        if m_ms:
+            return f"[{label}](/dev/milestones/{m_ms.group(1).lower()}/{frag})"
+        if full == "CONTEXT.md":
+            return f"[{label}](/dev/glossary/{frag})"
+        return f"[{label}]({REPO_URL}/src/branch/main/{full}{frag})"
+
+    return re.sub(r"\[([^\]]*)\]\(([^)\s]+)\)", fix, md)
+
+
+def title_and_body(text):
+    m = re.match(r"#\s+(.+)\n", text)
+    return (m.group(1).strip(), text[m.end():].lstrip("\n")) if m else ("", text)
+
+
+def first_paragraph(body):
+    for block in re.split(r"\n\s*\n", body):
+        b = block.strip()
+        if b and not b.startswith(("#", "|", "```", "- ", "1.", "![")):
+            return b
+    return ""
+
+
+def goal_or_first(body):
+    m = re.search(r"\*\*Goal:\*\*\s*(.+?)(?:\n\s*\n|\Z)", body, re.S)
+    return m.group(1) if m else first_paragraph(re.sub(r"^\*\*Status:\*\*.*\n", "", body, flags=re.M))
+
+
+def sections(readme):
+    """README's `## ` sections by heading, each with its heading line and everything up to the next `## `."""
+    out, name, buf = {}, None, []
+    for line in readme.splitlines(keepends=True):
+        if line.startswith("## "):
+            if name:
+                out[name] = "".join(buf).rstrip() + "\n"
+            name, buf = line[3:].strip(), [line]
+        elif name:
+            buf.append(line)
+    if name:
+        out[name] = "".join(buf).rstrip() + "\n"
+    return out
+
+
+def help_text():
+    """The two lists `help` prints: for every build, and for Debug Builds only, from kHelp in src/main.cpp."""
+    src = (REPO / "src" / "main.cpp").read_text()
+    m = re.search(r"static const char\* const kHelp =(.*?)\n\s*;", src, re.S)
+    if not m:
+        sys.exit("gen_dev_docs: kHelp not found in src/main.cpp")
+    common, debug, in_debug = [], [], False
+    for line in m.group(1).splitlines():
+        stripped = line.strip()
+        if stripped.startswith("#ifdef RORO_DEBUG"):
+            in_debug = True
+        elif stripped.startswith("#endif"):
+            in_debug = False
+        else:
+            for lit in re.findall(r'"((?:[^"\\]|\\.)*)"', line):
+                (debug if in_debug else common).append(lit.replace("\\n", "\n").replace('\\"', '"'))
+    return "".join(common).rstrip("\n"), "".join(debug).rstrip("\n")
+
+
+def safe_mode_commands():
+    src = (REPO / "src" / "main.cpp").read_text()
+    m = re.search(r"static bool safeModeCommand\(const String& line\) \{(.*?)\n\}", src, re.S)
+    if not m:
+        sys.exit("gen_dev_docs: safeModeCommand not found in src/main.cpp")
+    body = m.group(1)
+    exact = re.findall(r'line == "([^"]+)"', body)
+    prefix = re.findall(r'line\.startsWith\("([^"]+)"\)', body)
+    return exact, prefix
+
+
+def build():
+    pages = {}
+
+    for path in sorted((REPO / "docs" / "adr").glob("*.md")):
+        title, body = title_and_body(path.read_text())
+        number = path.stem[:4]
+        source = f"docs/adr/{path.name}"
+        pages[f"decisions/{path.stem}.md"] = front(title, plain(first_paragraph(body)), int(number), source, tag=f"ADR {number}") + relink(body, source)
+
+    for i, code in enumerate(MILESTONES):
+        path = REPO / "docs" / "milestones" / f"{code}.md"
+        title, body = title_and_body(path.read_text())
+        title = re.sub(rf"^{code}\s*[—:-]\s*", "", title)
+        source = f"docs/milestones/{path.name}"
+        pages[f"milestones/{code.lower()}.md"] = front(title, plain(goal_or_first(body)), (i + 1) * 10, source, tag=code) + relink(body, source)
+
+    readme = sections((REPO / "README.md").read_text())
+    pages["build/build-and-test.md"] = (
+        front("Build, test and release", "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.", 1, "README.md", tag="Build")
+        + relink("\n".join(readme[k] for k in ("Requirements", "Build and test (local CI)", "CI and releases")), "README.md"))
+    pages["build/flash.md"] = (
+        front("Flash and update", "Put the firmware on a Cardputer over USB, then update it over Wi-Fi or from the SD card, and from the project's releases.", 2, "README.md", tag="Flash")
+        + relink("\n".join(readme[k] for k in ("Flash", "Firmware Updates over Wi-Fi (OTA)")), "README.md"))
+
+    common, debug = help_text()
+    if debug:
+        sys.exit("gen_dev_docs: kHelp has a RORO_DEBUG part again: there is one firmware (ADR 0010)")
+    exact, prefix = safe_mode_commands()
+    safe = ", ".join(f"`{c}`" for c in exact) + ", and anything starting with " + ", ".join(f"`{p.strip()}`" for p in prefix)
+    dev = readme["Development aids"].split("### The Debug Console")[0]
+    dev = re.sub(r"^## Development aids\n", "", dev).strip() + "\n"
+    pages["debug/commands.md"] = (
+        front("Command reference", "Every command the firmware understands, over USB serial or the Debug Console: what `help` prints, then what each one does.", 30, "src/main.cpp and README.md", tag="Reference")
+        + "## What `help` prints\n\n"
+        + "The firmware's own list, read from `src/main.cpp`. Every firmware has all of them, over USB serial and over the Debug Console. The ones marked *Debug Console only* exist only over Wi-Fi, where [`rdbg.py`](/dev/debug/files-and-screens/) speaks them, and the ones marked *USB serial only* only over the cable:\n\n```\n" + common + "\n```\n\n"
+        + f"In **Safe Mode** (see [Crashes and Safe Mode](/dev/debug/crashes/)) only a few run: {safe}. Anything else answers `not available in Safe Mode`.\n\n"
+        + "## What they do\n\n" + dev)
+    return pages
+
+
+def main():
+    check = "--check" in sys.argv
+    pages = build()
+    stale = []
+    for rel, text in sorted(pages.items()):
+        path = OUT / rel
+        have = path.read_text() if path.exists() else None
+        if have != text:
+            stale.append(rel)
+            if not check:
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text(text)
+    if check:
+        for rel in stale:
+            print(f"gen_dev_docs: content/dev/{rel} is out of date: run site/tools/gen_dev_docs.py and commit the result")
+        print(f"gen_dev_docs: {len(pages)} pages, {len(stale)} out of date")
+        sys.exit(1 if stale else 0)
+    print(f"gen_dev_docs: {len(pages)} pages, {len(stale)} written")
+
+
+if __name__ == "__main__":
+    main()

src/apps/debug_console_page.cpp

@@ -0,0 +1,144 @@
+#include "apps/debug_console_page.h"
+
+#include "debug_auth.h"
+#include "services/debug_console.h"
+#include "ui/fonts.h"
+#include "ui/widgets.h"
+
+namespace roro {
+
+void DebugConsolePage::enter() {
+    list_.setCount(kRows);
+    confirm_.reset();
+    typing_ = false;
+    refusal_.clear();
+}
+
+bool DebugConsolePage::onKey(const KeyEvent& e) {
+    if (confirm_) {
+        confirm_->onKey(e);
+        if (confirm_->result() == 1) {
+            if (ask_ == Ask::SwitchOn) DebugConsole::switchOn(settings_);
+            else settings_.setString(Setting::DebugToken, DebugConsole::freshToken());
+        }
+        if (confirm_->result() != DialogModel::kPending) confirm_.reset();
+        return true;
+    }
+    if (typing_) {
+        switch (e.key) {
+            case Key::Char: editor_.insert(e.ch); break;
+            case Key::Delete: editor_.backspace(); break;
+            case Key::Left: editor_.left(); break;
+            case Key::Right: editor_.right(); break;
+            case Key::Back: typing_ = false; break;
+            case Key::Select: {
+                std::string token = debug::tidyToken(editor_.text());
+                if (debug::validToken(token) && settings_.setString(Setting::DebugToken, token)) typing_ = false;
+                else refusal_ = "16 to 64 characters, please";
+                break;
+            }
+            default: break;
+        }
+        return true;
+    }
+    switch (e.key) {
+        case Key::Up: list_.up(); break;
+        case Key::Down: list_.down(); break;
+        case Key::Back: return false;
+        case Key::Left:
+        case Key::Right:
+        case Key::Select:
+            if (e.key != Key::Select && list_.selected() != kSwitch) break;
+            switch (list_.selected()) {
+                case kSwitch:
+                    if (settings_.getBool(Setting::DebugConsole)) settings_.setBool(Setting::DebugConsole, false);
+                    else {  // on is the one to think about
+                        ask_ = Ask::SwitchOn;
+                        confirm_.reset(new DialogModel({"Cancel", "Switch on"}));
+                    }
+                    break;
+                case kNewToken:
+                    ask_ = Ask::NewToken;
+                    confirm_.reset(new DialogModel({"Cancel", "New token"}));
+                    break;
+                case kTypeToken:
+                    editor_ = LineEditor(64);
+                    refusal_.clear();
+                    typing_ = true;
+                    break;
+                default: break;
+            }
+            break;
+        default: break;
+    }
+    return true;
+}
+
+void DebugConsolePage::draw(Canvas& c) {
+    const auto& area = theme::kContent;
+    c.setTextDatum(top_left);
+    if (typing_) {
+        c.setFont(&fonts::body);
+        c.setTextColor(theme::kMuted);
+        c.drawString("A token of your own", 4, area.y + 4);
+        widgets::lineEditor(c, editor_, {4, area.y + 22, area.w - 8, 0});
+        c.setTextColor(refusal_.empty() ? theme::kMuted : theme::kWarning);
+        c.drawString(refusal_.empty() ? "16 to 64 characters. Capitals or not, it's the same." : refusal_.c_str(), 4, area.y + 44);
+        c.setTextColor(theme::kMuted);
+        c.drawString("Enter: save   `: cancel", 4, area.y + 44 + theme::kLineHeight);
+        return;
+    }
+
+    bool on = settings_.getBool(Setting::DebugConsole);
+    std::string ip = wifi_.ip();
+    widgets::list(
+        c, list_, {area.x, area.y, area.w, kRows * theme::kLineHeight},
+        [](int i) -> std::string {
+            switch (i) {
+                case kSwitch: return "Debug Console";
+                case kAddress: return "Connect to";
+                case kNewToken: return "New token";
+                default: return "Type a token";
+            }
+        },
+        [&](int i) -> std::string {
+            switch (i) {
+                case kSwitch: return on ? "On" : "Off";
+                case kAddress: return !on ? "-" : ip.empty() ? "Wi-Fi not connected" : ip + ":" + std::to_string(DebugConsole::kPort);
+                default: return ">";
+            }
+        });
+
+    // The token: here, in full, and nowhere else (it's never printed on a console). One the device
+    // made is drawn at twice the size, three groups then two: it has to be read and typed.
+    int y = area.y + kRows * theme::kLineHeight + 4;
+    c.drawFastHLine(4, y - 2, area.w - 8, theme::kMuted);
+    const std::string& token = settings_.getString(Setting::DebugToken);
+    std::string shown = debug::groupToken(token);
+    c.setFont(&fonts::body);
+    if (token.empty()) {
+        c.setTextColor(theme::kMuted);
+        c.drawString("No token yet: one is made when", 4, y + 4);
+        c.drawString("you switch the console on.", 4, y + 4 + theme::kLineHeight);
+    } else if (token.size() <= debug::kTokenChars) {
+        c.setTextColor(theme::kText);
+        c.setTextSize(2);
+        c.drawString(shown.substr(0, 14).c_str(), 4, y + 2);
+        if (shown.size() > 15) c.drawString(shown.substr(15).c_str(), 4, y + 2 + 2 * theme::kLineHeight - 3);
+        c.setTextSize(1);
+    } else {
+        c.setTextColor(theme::kText);
+        for (size_t at = 0; at < shown.size(); at += 35, y += theme::kLineHeight) c.drawString(shown.substr(at, 35).c_str(), 4, y + 2);
+    }
+    c.setFont(&fonts::small);
+    c.setTextColor(on ? theme::kWarning : theme::kMuted);
+    c.drawString(on ? "On this Wi-Fi, the token is full control." : "Off: nothing listens.", 4, area.y + area.h - 9);
+
+    if (confirm_) {
+        if (ask_ == Ask::SwitchOn)
+            widgets::dialog(c, "Switch it on?", "With the token, anyone on this Wi-Fi can read the console, press keys and copy files.", *confirm_);
+        else widgets::dialog(c, "A new token?", "The one in use stops working, and whoever is connected is cut off.", *confirm_);
+    }
+}
+
+}  // namespace roro

src/apps/debug_console_page.h

@@ -0,0 +1,43 @@
+#pragma once
+
+#include <memory>
+#include <string>
+
+#include "dialog_model.h"
+#include "key_event.h"
+#include "line_editor.h"
+#include "list_model.h"
+#include "services/wifi_service.h"
+#include "settings.h"
+#include "ui/canvas.h"
+#include "ui/theme.h"
+
+namespace roro {
+
+// Settings → Debug Console (ADR 0010): the switch, where to connect, and the token, which is shown
+// here and nowhere else. Switching on makes a token if there's none; a new one, or one typed by
+// hand, ends the connection of whoever holds the old one.
+class DebugConsolePage {
+   public:
+    DebugConsolePage(Settings& settings, WifiService& wifi) : settings_(settings), wifi_(wifi) {}
+
+    void enter();
+    bool onKey(const KeyEvent& e);  // false: leave the page
+    bool textEntryActive() const { return typing_; }
+    void draw(Canvas& c);
+
+   private:
+    enum Row { kSwitch, kAddress, kNewToken, kTypeToken, kRows };
+    enum class Ask { None, SwitchOn, NewToken };
+
+    Settings& settings_;
+    WifiService& wifi_;
+    ListModel list_{kRows};
+    std::unique_ptr<DialogModel> confirm_;
+    Ask ask_ = Ask::None;
+    bool typing_ = false;
+    LineEditor editor_{64};
+    std::string refusal_;
+};
+
+}  // namespace roro

src/apps/firmware_page.cpp

@@ -80,7 +80,6 @@ bool FirmwarePage::installable(std::string& why) const {
     std::string running = update_.runningVersion();
     if (!shown_.usable()) why = "Nothing to install in it";
     else if (!release::versionNewer(shown_.tag, running) && !versionOlder(shown_.tag, running)) why = "That's the version running";
-    else if (release::isDebugBuild(running)) why = "Debug Build: update from the PC";  // it keeps its console (Q171)
     else if (wifi_.state() != WifiController::State::Connected) why = "Not connected to Wi-Fi";
     else return true;
     return false;

src/apps/settings_app.cpp

@@ -34,6 +34,9 @@ bool SettingsApp::onKey(const KeyEvent& e) {
         case Page::Firmware:
             if (!firmwarePage_.onKey(e)) page_ = Page::Menu;
             return true;
+        case Page::Debug:
+            if (!debugPage_.onKey(e)) page_ = Page::Menu;
+            return true;
     }
     return false;
 }
@@ -75,6 +78,10 @@ bool SettingsApp::onMenuKey(const KeyEvent& e) {
                     page_ = Page::Firmware;
                     firmwarePage_.enter();
                     break;
+                case Row::DebugConsole:
+                    page_ = Page::Debug;
+                    debugPage_.enter();
+                    break;
                 default: page_ = Page::About; break;
             }
             break;
@@ -124,7 +131,7 @@ bool SettingsApp::onAboutKey(const KeyEvent& e) {
 
 void SettingsApp::update(uint32_t nowMs) {
     // Live values on About and Firmware.
-    bool live = page_ == Page::About || page_ == Page::Firmware ||
+    bool live = page_ == Page::About || page_ == Page::Firmware || page_ == Page::Debug ||
                 (page_ == Page::Wifi && wifiPage_.live());
     if (live && nowMs - lastRefreshMs_ >= 500) {
         lastRefreshMs_ = nowMs;
@@ -184,6 +191,7 @@ void SettingsApp::draw(Canvas& c) {
         case Page::About: widgets::textLines(c, aboutLines(), 0, area); break;
         case Page::Wifi: wifiPage_.draw(c); break;
         case Page::Firmware: firmwarePage_.draw(c); break;
+        case Page::Debug: debugPage_.draw(c); break;
     }
 }
 

src/apps/settings_app.h

@@ -13,6 +13,7 @@
 #include "services/battery_service.h"
 #include "services/clock_service.h"
 #include "services/storage_service.h"
+#include "apps/debug_console_page.h"
 #include "apps/firmware_page.h"
 #include "apps/wifi_settings_page.h"
 #include "settings_menu.h"
@@ -32,24 +33,26 @@ struct SettingsAppDeps {
     UpdateService& update;
 };
 
-// Settings: every user-facing setting, plus the Wi-Fi, Firmware and About pages.
+// Settings: every user-facing setting, plus the Wi-Fi, Firmware, Debug Console and About pages.
 class SettingsApp : public App {
    public:
     explicit SettingsApp(const SettingsAppDeps& deps)
         : d_(deps),
           menu_(deps.settings),
           wifiPage_(deps.settings, deps.savedNetworks, deps.wifi, deps.bus),
-          firmwarePage_(deps.update, deps.wifi, deps.storage) {}
+          firmwarePage_(deps.update, deps.wifi, deps.storage),
+          debugPage_(deps.settings, deps.wifi) {}
     void onEnter() override;
     bool onKey(const KeyEvent& e) override;
     void update(uint32_t nowMs) override;
     bool textEntryActive() const override {
-        return page_ == Page::Text || (page_ == Page::Wifi && wifiPage_.textEntryActive());
+        return page_ == Page::Text || (page_ == Page::Wifi && wifiPage_.textEntryActive()) ||
+               (page_ == Page::Debug && debugPage_.textEntryActive());
     }
     void draw(Canvas& c) override;
 
    private:
-    enum class Page { Menu, Text, Choice, About, Wifi, Firmware };
+    enum class Page { Menu, Text, Choice, About, Wifi, Firmware, Debug };
 
     bool onMenuKey(const KeyEvent& e);
     bool onTextKey(const KeyEvent& e);
@@ -62,6 +65,7 @@ class SettingsApp : public App {
     SettingsMenu menu_;
     WifiSettingsPage wifiPage_;
     FirmwarePage firmwarePage_;
+    DebugConsolePage debugPage_;
     Page page_ = Page::Menu;
     ListModel list_{theme::kContent.h / theme::kLineHeight};
     ListModel choices_{theme::kContent.h / theme::kLineHeight};

src/main.cpp

@@ -74,17 +74,13 @@ static ClockService* clockService;
 static GnssService* gnssService;
 static RadioService* radioService;
 static LoraCaptureService* loraCapture;
-#ifdef RORO_DEBUG
 static NoiseTest* noiseTest;
-#endif
 static GeminiService* geminiService;
 static SavedNetworks* savedNetworks;
 static WifiService* wifi;
 static IrcService* irc;
 static UpdateService* update;
-#ifdef RORO_DEBUG
 static DebugConsole* debugConsole;
-#endif
 static Notifier* notifier;
 static LauncherApp launcher;
 static AppManager* apps;
@@ -131,6 +127,7 @@ static StatusInfo currentStatus() {
         s.radio = last && millis() - last < 400 ? StatusInfo::Radio::Packet : StatusInfo::Radio::Listening;
     }
     s.capturing = loraCapture && loraCapture->capturing();
+    s.debug = !debugConsole->on() ? StatusInfo::Debug::Off : debugConsole->clientConnected() ? StatusInfo::Debug::Client : StatusInfo::Debug::On;
     using WifiState = WifiController::State;
     switch (wifi->state()) {
         case WifiState::Connected: {
@@ -194,18 +191,14 @@ void setup() {
     services.add(*gnssService);
     services.add(*radioService);
     loraCapture = new LoraCaptureService(*radioService, *storageService, *clockService, bus);
-#ifdef RORO_DEBUG
     noiseTest = new NoiseTest(*radioService);
-#endif
     services.add(*loraCapture);
     services.add(*storageService);
     services.add(*wifi);
     services.add(*irc);
     services.add(*update);
-#ifdef RORO_DEBUG
+    debugConsole = new DebugConsole(*wifi, *storageService, settings);
-    debugConsole = new DebugConsole(*wifi, *storageService);
     services.add(*debugConsole);
-#endif
 
     apps = new AppManager(launcher);
     launcher.setManager(*apps);
@@ -228,9 +221,7 @@ void setup() {
     bus.subscribe(EventType::Notification, [](const Event& e) { console.printf("notification: %s\n", e.text); });
 
     if (!screen.begin()) console.println("frame buffer allocation failed");
-#ifdef RORO_DEBUG
     debugConsole->setFrame(screen.canvas());  // for `screenshot`
-#endif
     services.startAll(millis());
     apps->begin();
     if (!settings.getBool(Setting::SetupDone)) apps->openModal("setup");
@@ -246,7 +237,7 @@ void setup() {
     enableLoopWDT();
 }
 
-// Safe Mode: Wi-Fi, the clock, Firmware Updates and (in a Debug Build) the Debug Console. No Apps,
+// Safe Mode: Wi-Fi, the clock, Firmware Updates and (if it's switched on) the Debug Console. No Apps,
 // no IRC, no SD card: whatever crashed three times in a row is most likely among them.
 static void setupSafeMode(int crashes) {
     clockService = new ClockService(settings, bus);
@@ -258,15 +249,11 @@ static void setupSafeMode(int crashes) {
     services.add(*clockService);
     services.add(*wifi);
     services.add(*update);
-#ifdef RORO_DEBUG
+    debugConsole = new DebugConsole(*wifi, *storageService, settings);
-    debugConsole = new DebugConsole(*wifi, *storageService);
     services.add(*debugConsole);
-#endif
     bus.subscribe(EventType::Notification, [](const Event& e) { console.printf("notification: %s\n", e.text); });
     screen.begin();
-#ifdef RORO_DEBUG
     debugConsole->setFrame(screen.canvas());
-#endif
     services.startAll(millis());
     console.printf("%s %s in SAFE MODE: %d crash restarts in a row. Only Wi-Fi and Firmware Updates run.\n",
                    kProductName, versionString(), crashes);
@@ -385,7 +372,6 @@ static void uploadStep() {
     }
 }
 
-#ifdef RORO_DEBUG
 // `wifi ip ... try <seconds>`: a trial IP setting that reverts unless `wifi ip keep` arrives, so a
 // wrong address tried over Wi-Fi doesn't cut the device off for good.
 static struct {
@@ -404,7 +390,6 @@ static void ipTrialStep() {
                    ipTrial.wasFixed ? net::formatFixed(ipTrial.was).c_str() : "Automatic (DHCP)");
     wifi->ipSettingChanged(ipTrial.ssid);
 }
-#endif
 
 // `tasks`: the first sample, and when to take the second and print.
 static std::vector<TaskSample> tasksBefore;
@@ -467,13 +452,11 @@ static void printReleases(bool list) {
 
 static void updateStep() {
     if (!updateWatch || update->giteaBusy()) return;
-#ifdef RORO_DEBUG
     if (updateWatch == 3) {
         console.printf("update: probe: %s\n", update->probeResult().c_str());
         updateWatch = 0;
         return;
     }
-#endif
     printReleases(updateWatch == 2);
     updateWatch = 0;
 }
@@ -492,14 +475,8 @@ static void updateCommand(const String& args) {
         printReleases(false);
     } else if (args.startsWith("install ")) {
         String rest = args.substring(8);
-        bool force = rest.endsWith(" force");
+        std::string why = update->requestInstall(rest.c_str());
-        if (force) rest.remove(rest.length() - 6);
-#ifndef RORO_DEBUG
-        force = false;  // only the Debug Console may install on a Debug Build, which a release isn't
-#endif
-        std::string why = update->requestInstall(rest.c_str(), force);
         console.printf("update: %s\n", why.empty() ? "installing" : why.c_str());
-#ifdef RORO_DEBUG
     } else if (args.startsWith("probe ")) {  // update probe <host> [path]: is that server's certificate accepted?
         String rest = args.substring(6);
         int space = rest.indexOf(' ');
@@ -516,7 +493,6 @@ static void updateCommand(const String& args) {
     } else if (args.startsWith("pretend ")) {  // update pretend v0.9.0 | off: what the comparisons take as running
         update->pretendVersion(args.substring(8) == "off" ? "" : args.substring(8).c_str());
         console.printf("update: running %s\n", update->runningVersion().c_str());
-#endif
     } else {
         console.println("update: check | list | status | install <tag>");
     }
@@ -553,9 +529,7 @@ static void fileCommand(const String& line) {
 }
 
 static uint32_t loopPasses = 0;  // counted in loop(), for `tasks` (issue #40)
-#ifdef RORO_DEBUG
 static bool loopSpin = false;  // `loop spin on`: no rest between passes, to compare load and radio noise
-#endif
 static uint32_t tasksPasses = 0;
 
 static void tasksStep() {
@@ -590,7 +564,8 @@ static const char* const kHelp =
     "install <path.ota>   Update from SD\n"
     "update check | list | status | install <tag>   the project's releases on Gitea\n"
     "sd card | sd list | cat <path> | log <text> | burst | sound on|off | short | normal\n"
-#ifdef RORO_DEBUG
+    "debug status | debug off [seconds]   the Debug Console over Wi-Fi (Settings > Debug Console); with seconds, it comes back\n"
+    "debug on | debug token <16 to 64 characters> | debug token new   (USB serial only) switch it on, set its token\n"
     "crash abort|wdt   crash on purpose (to test crash reports and Safe Mode)\n"
     "wifi ip ... try <seconds> | wifi ip keep   a trial IP setting: back to the previous one unless kept\n"
     "loop spin on|off  make the main loop spin without resting, to compare load and radio noise\n"
@@ -601,34 +576,75 @@ static const char* const kHelp =
     "reset             (Debug Console only) restart at once, even if the main loop is stuck\n"
     "get <path> | put <path> <size> <sha256> | screenshot   (Debug Console only) binary, see rdbg.py\n"
     "quit              close the Debug Console connection\n"
-#endif
     ;
 
 // Commands that only touch what Safe Mode starts.
 static bool safeModeCommand(const String& line) {
     return line == "help" || line == "info" || line == "tasks" || line == "net" || line == "reboot" || line == "boot other" ||
            line.startsWith("log level ") || line.startsWith("crash") || line.startsWith("coredump") ||
-           line == "wifi status" || line.startsWith("wifi add ");
+           line == "wifi status" || line.startsWith("wifi add ") || line.startsWith("debug ");
 }
 
-static void runCommand(String line) {
+// `debug off <seconds>`: the console closes and comes back by itself. It can't open itself wider
+// that way (it was on, with the same token), and it's how its closing and reopening is tested from afar.
+static bool debugResumes = false;
+static uint32_t debugResumeMs = 0;
+static void debugResumeStep() {
+    if (!debugResumes || static_cast<int32_t>(millis() - debugResumeMs) < 0) return;
+    debugResumes = false;
+    settings.setBool(Setting::DebugConsole, true);
+}
+
+// `debug ...`: the Debug Console's switch and token (ADR 0010). Switching it on and setting its token
+// are for USB serial only (Q192): whoever holds the cable holds the device anyway, and the console
+// can't be used to open itself wider. The token is never printed.
+static void debugCommand(const String& args, bool fromSerial) {
+    if (args == "status") {
+        console.printf("debug: %s, token %s, client %s\n", settings.getBool(Setting::DebugConsole) ? "on" : "off",
+                       settings.getString(Setting::DebugToken).empty() ? "not set" : "set", debugConsole->clientConnected() ? "connected" : "none");
+    } else if (args == "off") {
+        settings.setBool(Setting::DebugConsole, false);
+        console.println("debug: off");
+    } else if (args.startsWith("off ")) {  // debug off <seconds>: a pause, then on again as it was
+        uint32_t seconds = constrain(args.substring(4).toInt(), 1, 600);
+        if (!settings.getBool(Setting::DebugConsole)) return (void)console.println("debug: it is off");
+        settings.setBool(Setting::DebugConsole, false);
+        debugResumeMs = millis() + seconds * 1000;
+        debugResumes = true;
+        console.printf("debug: off for %lu s\n", (unsigned long)seconds);
+    } else if (!fromSerial) {
+        console.println("debug: over USB serial only (or Settings > Debug Console)");
+    } else if (args == "on") {
+        DebugConsole::switchOn(settings);
+        console.println("debug: on (the token is in Settings > Debug Console)");
+    } else if (args == "token new") {
+        settings.setString(Setting::DebugToken, DebugConsole::freshToken());
+        console.println("debug: a new token (it is in Settings > Debug Console)");
+    } else if (args.startsWith("token ")) {
+        std::string token = debug::tidyToken(args.substring(6).c_str());
+        bool ok = debug::validToken(token) && settings.setString(Setting::DebugToken, token);
+        console.println(ok ? "debug: token set" : "debug: a token is 16 to 64 characters");
+    } else console.println("debug: status | off [seconds] | on | token <16 to 64 characters> | token new");
+}
+
+static void runCommand(String line, bool fromSerial = false) {
     line.trim();
     if (line.isEmpty()) return;
     if (safeMode && !safeModeCommand(line)) return (void)console.println("not available in Safe Mode");
     if (line == "help") console.print(kHelp);
+    if (line.startsWith("debug ")) return debugCommand(line.substring(6), fromSerial);
     if (line == "info") {
         system_info::printSystem(console);
         console.printf("wifi: %s, ip %s, rssi %d | sd: %s, %u write faults\n", wifi->ssid().c_str(), wifi->ip().c_str(),
                        wifi->rssi(), storageService->state().present ? "present" : "none", (unsigned)sdLastFault().count);
-        console.printf("update: %s\n", update->onProbation() ? "on probation" : "confirmed");
+        console.printf("update: %s | debug console: %s\n", update->onProbation() ? "on probation" : "confirmed",
+                       !debugConsole->on() ? "off" : debugConsole->clientConnected() ? "on, a client connected" : "on");
         system_info::printSlots(console, nvs);
     }
-#ifdef RORO_DEBUG
     if (line == "loop spin on" || line == "loop spin off") {
         loopSpin = line.endsWith("on");
         console.printf("loop: %s\n", loopSpin ? "spinning, no rest" : "resting between passes");
     }
-#endif
     if (line == "tasks") {  // sampled now, printed a second later by tasksStep(): the loop must run in between
         tasksTotal = system_info::sampleTasks(tasksBefore);
         tasksDueMs = millis() + 1000;
@@ -670,7 +686,6 @@ static void runCommand(String line) {
         });
     }
     if (line.startsWith("install ")) update->installFromSd(line.substring(8).c_str());  // Update from SD
-#ifdef RORO_DEBUG
     if (line.startsWith("sd fill ")) {  // sd fill <folder> <count>: small files, to test a crowded folder
         int space = line.lastIndexOf(' ');
         std::string folder = line.substring(8, space).c_str();
@@ -689,11 +704,9 @@ static void runCommand(String line) {
             console.printf("sd fill: %d files in %s\n", made, folder.c_str());
         });
     }
-#endif
     if (line == "lora probe" && radioService) radioService->probe(console);
     if (line == "lora status" && radioService) radioService->printStatus(console);
     if ((line == "lora rx on" || line == "lora rx off") && radioService) radioService->setEcho(line.endsWith("on"));
-#ifdef RORO_DEBUG
     if (line == "lora noise report" && noiseTest) noiseTest->printReport(console);
     if (line == "lora noise test" && noiseTest && !noiseTest->running()) {
         // One thing changed at a time, each put back before the next (issue #20). Wi-Fi off cuts the
@@ -758,7 +771,6 @@ static void runCommand(String line) {
         };
         noiseTest->start(std::move(conditions));
     }
-#endif
     if (line.startsWith("lora sweep") && radioService) {  // on [from MHz] [to MHz] [step kHz] | off | dump
         if (line == "lora sweep dump") radioService->printSweep(console);
         else if (line == "lora sweep off") {
@@ -776,7 +788,6 @@ static void runCommand(String line) {
         console.printf("lora capture: %s\n", why.empty() ? loraCapture->path().c_str() : why.c_str());
     }
     if (line == "lora capture stop" && loraCapture) loraCapture->stop();
-#ifdef RORO_DEBUG
     if (line.startsWith("lora inject ") && radioService) {  // <hex> [rssi] [snr]: as if received
         String hex = line.substring(12);
         int space = hex.indexOf(' ');
@@ -787,7 +798,6 @@ static void runCommand(String line) {
         for (size_t i = 0; i + 1 < hex.length() && n < sizeof data; i += 2) data[n++] = strtoul(hex.substring(i, i + 2).c_str(), nullptr, 16);
         radioService->inject(data, n, rssi, snr);
     }
-#endif
     if (line.startsWith("lora custom ") && radioService) {
         double mhz = 0, bw = 0;
         unsigned sf = 0, cr = 0, sync = 0, preamble = 8;
@@ -822,11 +832,9 @@ static void runCommand(String line) {
         console.println(gnssService->send(line.substring(10).c_str()) ? "gnss: sent" : "gnss: off");
     if (line == "crash") crash_report::print(console, nvs);
     if (line == "coredump erase") console.println(crash_report::erase() ? "coredump: erased" : "coredump: nothing to erase");
-#ifdef RORO_DEBUG
     if (line == "crash abort") abort();
     if (line == "crash wdt")
         for (;;) {}  // the main loop never yields: the task watchdog fires
-#endif
     if (line == "burst")
         for (int i = 1; i <= 5; i++)
             bus.publish(Event::withText(EventType::Notification, ("Burst " + String(i)).c_str(), 0));
@@ -933,7 +941,6 @@ static void runCommand(String line) {
     }
     if (line.startsWith("wifi ip ")) {  // wifi ip <ssid> dhcp | <address>/<prefix> [gateway]  (the SSID may hold spaces)
         std::string rest = line.substring(8).c_str();
-#ifdef RORO_DEBUG
         if (rest == "keep") {  // the trial setting stays
             console.println(ipTrial.active ? "wifi ip: kept" : "wifi ip: no trial running");
             ipTrial.active = false;
@@ -945,7 +952,6 @@ static void runCommand(String line) {
             trialS = strtoul(rest.c_str() + tryAt + 5, nullptr, 10);
             rest = rest.substr(0, tryAt);
         }
-#endif
         std::string ssid, why;
         net::FixedIp fixed;
         bool dhcp = rest.size() > 5 && rest.compare(rest.size() - 5, 5, " dhcp") == 0;
@@ -959,9 +965,7 @@ static void runCommand(String line) {
             }
         }
         const SavedNetwork* before = why.empty() ? savedNetworks->find(ssid) : nullptr;
-#ifdef RORO_DEBUG
         if (before && trialS) ipTrial = {true, millis() + trialS * 1000, ssid, before->fixed, before->ip};
-#endif
         if (why.empty()) why = savedNetworks->setIp(ssid, dhcp ? nullptr : &fixed);
         if (!why.empty()) return (void)console.printf("wifi ip: %s\n", why.c_str());
         console.printf("wifi ip: %s is now %s\n", ssid.c_str(), dhcp ? "Automatic (DHCP)" : net::formatFixed(fixed).c_str());
@@ -1007,18 +1011,19 @@ static void serialCommands() {
             line += c;
             continue;
         }
-        runCommand(line);
+        runCommand(line, true);
         line = "";
     }
 }
 
 static void remoteCommands() {
-#ifdef RORO_DEBUG
     for (std::string remote; debugConsole->takeCommand(remote);) {
         console.printf("> %s\n", remote.c_str());  // so the transcript reads the same on both ends
         runCommand(remote.c_str());
     }
-#endif
+    debugResumeStep();
+    for (std::string alert; debugConsole->takeAlert(alert);)
+        bus.publish(Event::withText(EventType::Notification, alert.c_str(), static_cast<int32_t>(NotificationLevel::Warning)));
 }
 
 // After a minute up, the crash streak is over (SafeMode counts starts that crash in a row).
@@ -1069,9 +1074,7 @@ void loop() {
         return;
     }
     loopPass();
-#ifdef RORO_DEBUG
     if (loopSpin) return;
-#endif
     if (upload.active()) return;  // a serial file transfer: every byte is read promptly
     delay(power->screen() == ScreenState::Off ? kLoopRestScreenOffMs : kLoopRestScreenOnMs);
 }
@@ -1088,10 +1091,8 @@ static void loopPass() {
     serialCommands();
     remoteCommands();
     tasksStep();
-#ifdef RORO_DEBUG
     ipTrialStep();
     if (noiseTest) noiseTest->step(now);
-#endif
     noteStableOnce(now);
     updateStep();
     fileOpsStep();

src/platform/console.cpp

@@ -2,19 +2,16 @@
 
 #include <Arduino.h>
 
-#ifdef RORO_DEBUG
 #include <esp_log.h>
 #include <freertos/FreeRTOS.h>
 
 #include <algorithm>
 #include <cstdio>
-#endif
 
 namespace roro {
 
 Console console;
 
-#ifdef RORO_DEBUG
 namespace {
 
 // Any task may write (ESP-IDF logs come from everywhere), so the ring is behind a spinlock, held
@@ -34,7 +31,28 @@ int teeEspLog(const char* format, va_list args) {
 
 }  // namespace
 
-void Console::captureEspLogs() { espLogNext = esp_log_set_vprintf(teeEspLog); }
+void Console::captureEspLogs() {
+    if (!espLogNext) espLogNext = esp_log_set_vprintf(teeEspLog);  // once: it stays, and costs nothing with the ring closed
+}
+
+bool Console::openRing() {
+    if (ring_) return true;
+    auto* fresh = static_cast<uint8_t*>(malloc(kRingBytes));
+    if (!fresh) return false;
+    portENTER_CRITICAL(&ringLock);
+    head_ = 0;
+    ring_ = fresh;
+    portEXIT_CRITICAL(&ringLock);
+    return true;
+}
+
+void Console::closeRing() {
+    portENTER_CRITICAL(&ringLock);
+    uint8_t* old = ring_;
+    ring_ = nullptr;
+    portEXIT_CRITICAL(&ringLock);
+    free(old);
+}
 
 void Console::toRing(const uint8_t* data, size_t len) {
     if (len > kRingBytes) {
@@ -42,11 +60,13 @@ void Console::toRing(const uint8_t* data, size_t len) {
         len = kRingBytes;
     }
     portENTER_CRITICAL(&ringLock);
-    size_t at = head_ % kRingBytes;
+    if (ring_) {
-    size_t first = std::min(len, kRingBytes - at);
+        size_t at = head_ % kRingBytes;
-    memcpy(ring_ + at, data, first);
+        size_t first = std::min(len, kRingBytes - at);
-    memcpy(ring_, data + first, len - first);
+        memcpy(ring_ + at, data, first);
-    head_ += len;
+        memcpy(ring_, data + first, len - first);
+        head_ += len;
+    }
     portEXIT_CRITICAL(&ringLock);
 }
 
@@ -59,24 +79,25 @@ uint32_t Console::oldest() const {
 
 size_t Console::readSince(uint32_t& pos, uint8_t* out, size_t max, uint32_t& skipped) {
     portENTER_CRITICAL(&ringLock);
-    uint32_t from = head_ > kRingBytes ? head_ - kRingBytes : 0;
+    size_t n = 0;
-    skipped = pos < from ? from - pos : 0;
+    skipped = 0;
-    if (pos < from) pos = from;
+    if (ring_) {
-    size_t n = std::min<size_t>(max, head_ - pos);
+        uint32_t from = head_ > kRingBytes ? head_ - kRingBytes : 0;
-    size_t at = pos % kRingBytes;
+        skipped = pos < from ? from - pos : 0;
-    size_t first = std::min(n, kRingBytes - at);
+        if (pos < from) pos = from;
-    memcpy(out, ring_ + at, first);
+        n = std::min<size_t>(max, head_ - pos);
-    memcpy(out + first, ring_, n - first);
+        size_t at = pos % kRingBytes;
-    pos += n;
+        size_t first = std::min(n, kRingBytes - at);
+        memcpy(out, ring_ + at, first);
+        memcpy(out + first, ring_, n - first);
+        pos += n;
+    }
     portEXIT_CRITICAL(&ringLock);
     return n;
 }
-#endif
 
 size_t Console::write(const uint8_t* data, size_t len) {
-#ifdef RORO_DEBUG
     toRing(data, len);
-#endif
     // Never wait for the USB host. One that's attached but not reading (a VM, a closed terminal)
     // would stall the caller for up to 2 s per write while HWCDC retries; the ring keeps it anyway.
     if (Serial.availableForWrite() >= static_cast<int>(len)) Serial.write(data, len);

src/platform/console.h

@@ -7,18 +7,23 @@
 
 namespace roro {
 
-// Where the firmware's console output goes: the USB serial port, and in a Debug Build also a ring
+// Where the firmware's console output goes: the USB serial port, and while the Debug Console is
-// buffer the Debug Console sends over Wi-Fi (with what came before the connection, so boot messages
+// switched on (ADR 0010) also a ring buffer it sends over Wi-Fi, with what came before the connection.
-// aren't lost). Use `console` instead of Serial for anything a human should be able to read remotely.
+// Use `console` instead of Serial for anything a human should be able to read remotely.
 class Console : public Print {
    public:
     size_t write(uint8_t c) override { return write(&c, 1); }
     size_t write(const uint8_t* data, size_t len) override;
     using Print::write;
 
-#ifdef RORO_DEBUG
     static constexpr size_t kRingBytes = 4096;
 
+    // The ring exists only while the Debug Console is on: 4 KB of heap a device that never uses it
+    // keeps. False if there's no memory for it.
+    bool openRing();
+    void closeRing();
+    bool ringOpen() const { return ring_ != nullptr; }
+
     // Also copies ESP-IDF's own log lines into the ring (they still reach the serial port).
     void captureEspLogs();
     // Copies bytes written since `pos` into `out`, and advances `pos`. A reader that fell more than
@@ -30,9 +35,8 @@ class Console : public Print {
     void toRing(const uint8_t* data, size_t len);
 
    private:
-    uint8_t ring_[kRingBytes];
+    uint8_t* ring_ = nullptr;
-    uint32_t head_ = 0;  // total bytes ever written; the ring holds the last kRingBytes of them
+    uint32_t head_ = 0;  // total bytes written since the ring opened; it holds the last kRingBytes of them
-#endif
 };
 
 extern Console console;

src/services/debug_console.cpp

@@ -1,4 +1,3 @@
-#ifdef RORO_DEBUG
 
 #include "services/debug_console.h"
 
@@ -7,6 +6,7 @@
 #include <algorithm>
 #include <esp_core_dump.h>
 #include <esp_flash.h>
+#include <esp_random.h>
 
 #include <SD.h>
 #include <unistd.h>
@@ -29,14 +29,6 @@ constexpr uint32_t kAuthTimeoutMs = 10000;
 constexpr size_t kMaxLine = 240;
 constexpr size_t kMaxQueued = 8;
 
-// Compares without stopping at the first difference, so timing says nothing about the token.
-bool sameToken(const std::string& a, const char* b) {
-    size_t n = strlen(b);
-    uint8_t diff = a.size() != n;
-    for (size_t i = 0; i < n; i++) diff |= (i < a.size() ? a[i] : 0) ^ b[i];
-    return diff == 0;
-}
-
 // Reads one line (without its \r\n) within `timeoutMs`; false on a timeout, a drop or an overlong line.
 bool readLine(NetworkClient& c, std::string& line, uint32_t timeoutMs) {
     line.clear();
@@ -77,12 +69,40 @@ void sendCoreDump(NetworkClient& client) {
 
 }  // namespace
 
-DebugConsole::DebugConsole(WifiService& wifi, StorageService& storage)
+DebugConsole::DebugConsole(WifiService& wifi, StorageService& storage, Settings& settings)
-    : wifi_(wifi), storage_(storage), lock_(xSemaphoreCreateMutex()) {}
+    : wifi_(wifi), storage_(storage), settings_(settings), lock_(xSemaphoreCreateMutex()) {}
 
-void DebugConsole::start() {
+std::string DebugConsole::freshToken() {
+    uint8_t random[debug::kTokenRandom];
+    esp_fill_random(random, sizeof random);  // the hardware generator: true random with the radio on
+    return debug::makeToken(random);
+}
+
+void DebugConsole::switchOn(Settings& settings) {
+    if (settings.getString(Setting::DebugToken).empty()) settings.setString(Setting::DebugToken, freshToken());
+    settings.setBool(Setting::DebugConsole, true);
+}
+
+void DebugConsole::tick(uint32_t) { apply(); }
+
+// The main loop's side. The task frees what it holds and clears task_ when it sees wanted_ go:
+// until then a new one isn't started, so switching off and on again quickly takes a tick or two.
+void DebugConsole::apply() {
+    const std::string& token = settings_.getString(Setting::DebugToken);
+    bool want = settings_.getBool(Setting::DebugConsole) && !token.empty();  // no token, nobody could get in: stay closed
+    xSemaphoreTake(lock_, portMAX_DELAY);
+    if (token != token_) {
+        token_ = token;
+        tokenSeq_ = tokenSeq_ + 1;
+    }
+    xSemaphoreGive(lock_);
+    wanted_ = want;
+    if (!want || task_) return;
+    if (!console.openRing()) return (void)console.println("debug: no memory for the console");
     console.captureEspLogs();
-    if (!task_) xTaskCreate(taskEntry, "debug", 6144, this, 1, &task_);
+    TaskHandle_t made = nullptr;
+    if (xTaskCreate(taskEntry, "debug", 6144, this, 1, &made) == pdPASS) task_ = made;
+    else console.closeRing();
 }
 
 bool DebugConsole::takeCommand(std::string& line) {
@@ -96,38 +116,95 @@ bool DebugConsole::takeCommand(std::string& line) {
     return any;
 }
 
+bool DebugConsole::takeAlert(std::string& text) {
+    xSemaphoreTake(lock_, portMAX_DELAY);
+    bool any = !alert_.empty();
+    if (any) text = std::move(alert_);
+    alert_.clear();
+    xSemaphoreGive(lock_);
+    return any;
+}
+
 void DebugConsole::taskEntry(void* self) { static_cast<DebugConsole*>(self)->listen(); }
 
 void DebugConsole::listen() {
-    NetworkServer server(kPort);
+    {
-    bool listening = false;
+        NetworkServer server(kPort);
-    for (;;) {
+        bool listening = false, complained = false;
-        bool up = wifi_.state() == WifiController::State::Connected;
+        while (wanted_) {
-        if (up && !listening) {
+            bool up = wifi_.state() == WifiController::State::Connected;
-            server.begin();
+            if (up && !listening) {
-            listening = true;
+                // begin() gives up without a word (no socket, the port taken): ask whether it
-        } else if (!up && listening) {
+                // listens, and try again rather than believe it.
-            server.end();
+                server.begin();
-            listening = false;
+                listening = static_cast<bool>(server);
-        }
+                if (!listening) {
-        if (listening) {
+                    if (!complained) console.printf("debug: can't listen on port %u (errno %d), trying again\n", kPort, errno);
-            Counted<NetworkClient> client(server.accept(), net::User::DebugConsole);
+                    complained = true;
-            if (client) {
+                    server.end();  // closes the socket a failed begin() leaves open
-                client.setNoDelay(true);
+                    vTaskDelay(pdMS_TO_TICKS(2000));
-                if (authenticate(client)) serve(client);
+                } else if (complained) {
-                client.stop();
+                    console.printf("debug: listening on port %u\n", kPort);
+                    complained = false;
+                }
+            } else if (!up && listening) {
+                server.end();
+                listening = false;
             }
+            if (listening) {
+                Counted<NetworkClient> client(server.accept(), net::User::DebugConsole);
+                if (client) {
+                    client.setNoDelay(true);
+                    if (authenticate(client)) serve(client);
+                    client.stop();
+                }
+            }
+            vTaskDelay(pdMS_TO_TICKS(200));
         }
-        vTaskDelay(pdMS_TO_TICKS(200));
+        if (listening) server.end();
     }
+    // Switched off: nothing is left behind (Q189). The commands a client queued die with it. (Free
+    // heap dips by about 270 bytes for each connection the device closed, for two minutes: TCP keeps
+    // them that long. Measured over 15 switches: all of it comes back.)
+    xSemaphoreTake(lock_, portMAX_DELAY);
+    commands_.clear();
+    xSemaphoreGive(lock_);
+    console.closeRing();
+    task_ = nullptr;
+    vTaskDelete(nullptr);
 }
 
+// The token never crosses the network (Q193): the device sends 16 random bytes, the client sends
+// back their HMAC-SHA256 keyed by the token. A recorded answer is no use for the next challenge.
 bool DebugConsole::authenticate(NetworkClient& client) {
-    std::string token;
+    if (gate_.locked(millis())) {
-    if (readLine(client, token, kAuthTimeoutMs) && sameToken(token, RORO_DEBUG_TOKEN)) return true;
+        client.print("locked\n");
-    console.printf("debug: refused a client from %s\n", client.remoteIP().toString().c_str());
+        return false;
+    }
+    xSemaphoreTake(lock_, portMAX_DELAY);
+    std::string token = token_;
+    xSemaphoreGive(lock_);
+    uint8_t nonce[debug::kNonceBytes];
+    esp_fill_random(nonce, sizeof nonce);
+    client.printf("%s debug console, challenge %s\n", kProductName, debug::toHex(nonce, sizeof nonce).c_str());
+
+    std::string answer;
+    bool answered = readLine(client, answer, kAuthTimeoutMs);
+    if (answered && !token.empty() && debug::sameText(answer, debug::answerFor(token, nonce))) {
+        gate_.succeeded();
+        return true;
+    }
+    std::string from = client.remoteIP().toString().c_str();
+    console.printf("debug: refused a client from %s\n", from.c_str());
     delay(1000);  // no quick retries
     client.print("denied\n");
+    if (answered && gate_.failed(millis())) {  // a connection that says nothing isn't a guess
+        console.printf("debug: %d wrong tokens in a row, closed for %lu s\n", debug::AuthGate::kMaxFailures,
+                       (unsigned long)(debug::AuthGate::kLockMs / 1000));
+        xSemaphoreTake(lock_, portMAX_DELAY);
+        alert_ = "Console closed, wrong tokens: " + from;  // an Event's text holds 47 characters
+        xSemaphoreGive(lock_);
+    }
     return false;
 }
 
@@ -135,10 +212,11 @@ void DebugConsole::serve(NetworkClient& client) {
     console.printf("debug: client %s connected\n", client.remoteIP().toString().c_str());
     client.printf("%s %s debug console. 'help' lists the commands. Backlog follows.\n", kProductName, versionString());
     connected_ = true;
+    uint32_t tokenSeq = tokenSeq_;
     uint32_t pos = console.oldest();
     uint8_t buf[512];
     std::string line;
-    while (client.connected()) {
+    while (client.connected() && wanted_ && tokenSeq == tokenSeq_) {  // switched off, or a new token: out
         // Console output since last time, including the replies to this client's commands.
         uint32_t skipped = 0;
         size_t n;
@@ -313,4 +391,3 @@ void DebugConsole::screenshot(NetworkClient& client) {
 
 }  // namespace roro
 
-#endif

src/services/debug_console.h

@@ -1,7 +1,5 @@
 #pragma once
 
-#ifdef RORO_DEBUG
-
 #include <freertos/FreeRTOS.h>
 #include <freertos/semphr.h>
 
@@ -9,18 +7,22 @@
 #include <functional>
 #include <string>
 
+#include "debug_auth.h"
 #include "service.h"
 #include "services/storage_service.h"
 #include "services/wifi_service.h"
+#include "settings.h"
 #include "ui/canvas.h"
 
 class NetworkClient;
 
 namespace roro {
 
-// Debug Builds only (ADR 0004): the console over Wi-Fi, on TCP 2323 while Wi-Fi is Connected. A
+// The console over Wi-Fi, on TCP 2323 while Wi-Fi is Connected, in every build but only while it's
-// client sends the debug token as its first line, then gets the recent console backlog, every new
+// switched on in Settings (ADR 0010): off, nothing listens, and neither its task nor the console's
-// console line, and runs the same commands as the serial port. One client at a time.
+// ring exists. A client answers a challenge with its token (debug_auth.h), then gets the recent
+// console backlog, every new console line, and runs the same commands as the serial port. One
+// client at a time.
 //
 // The socket lives on this Service's own task; commands are handed to the main loop (takeCommand),
 // which runs them where touching Apps and Services is safe. Their output reaches the client
@@ -29,18 +31,29 @@ class DebugConsole : public Service {
    public:
     static constexpr uint16_t kPort = 2323;
 
-    DebugConsole(WifiService& wifi, StorageService& storage);
+    DebugConsole(WifiService& wifi, StorageService& storage, Settings& settings);
     // The off-screen frame the UI composes into: `screenshot` sends it as it stands.
     void setFrame(Canvas& frame) { frame_ = &frame; }
     const char* name() const override { return "debug"; }
-    void start() override;
+    void start() override { apply(); }
+    // Follows the settings: starts or stops listening, and takes a changed token (which drops a client).
+    void tick(uint32_t nowMs) override;
+
+    // Switches the console on, making a token first if there's none (Q191). The settings are what
+    // counts: this only writes them.
+    static void switchOn(Settings& settings);
+    static std::string freshToken();
 
     // The next command line a client sent, for the main loop to run.
     bool takeCommand(std::string& line);
+    // News for the user that the task can't publish itself (a pause after wrong tokens).
+    bool takeAlert(std::string& text);
+    bool on() const { return wanted_; }
     bool clientConnected() const { return connected_; }
 
    private:
     static void taskEntry(void* self);
+    void apply();
     void listen();
     void serve(::NetworkClient& client);
     bool authenticate(::NetworkClient& client);
@@ -55,13 +68,16 @@ class DebugConsole : public Service {
 
     WifiService& wifi_;
     StorageService& storage_;
+    Settings& settings_;
     Canvas* frame_ = nullptr;
-    TaskHandle_t task_ = nullptr;
+    volatile TaskHandle_t task_ = nullptr;  // null once the task has freed everything and gone
-    SemaphoreHandle_t lock_;
+    SemaphoreHandle_t lock_;                // commands_, token_, alert_
     std::deque<std::string> commands_;
+    std::string token_, alert_;
+    volatile uint32_t tokenSeq_ = 0;  // changes with the token: an open connection ends
+    volatile bool wanted_ = false;
     volatile bool connected_ = false;
+    debug::AuthGate gate_;  // the task's own
 };
 
 }  // namespace roro
-
-#endif

src/services/noise_test.cpp

@@ -1,4 +1,3 @@
-#ifdef RORO_DEBUG
 
 #include "services/noise_test.h"
 
@@ -107,4 +106,3 @@ void NoiseTest::printReport(Print& out) const {
 
 }  // namespace roro
 
-#endif  // RORO_DEBUG

src/services/noise_test.h

@@ -1,6 +1,5 @@
 #pragma once
 
-#ifdef RORO_DEBUG
 
 #include <Print.h>
 
@@ -56,4 +55,3 @@ class NoiseTest {
 
 }  // namespace roro
 
-#endif  // RORO_DEBUG

src/services/radio_service.cpp

@@ -190,7 +190,6 @@ void RadioService::store(RadioPacket& p) {
     lastPacketMs_ = p.ms;
 }
 
-#ifdef RORO_DEBUG
 void RadioService::debugAntenna(bool on) {
     auto& i2c = M5.In_I2C;
     uint8_t out = i2c.readRegister8(kExpander, kOutput, kI2cFreq);
@@ -208,7 +207,6 @@ void RadioService::inject(const uint8_t* data, size_t len, float rssi, float snr
     store(p);
     console.printf("lora inject: #%lu, %u B\n", (unsigned long)p.seq, p.len);
 }
-#endif
 
 // Continuous receive. Only RX done raises DIO1; preambles and headers are only recorded in the
 // IRQ status, which sampleNoise() reads.

src/services/radio_service.h

@@ -99,7 +99,6 @@ class RadioService : public Service {
     void printStatus(Print& out) const;
     void setEcho(bool echo);
     void probe(Print& out);  // `lora probe`: runs on the radio task
-#ifdef RORO_DEBUG
     // For the noise self-test (issue #20): the chip's regulator as an LDO instead of its DC-DC
     // converter, and receive gain boosted or not. Used the next time the radio is set up.
     void debugOptions(bool ldo, bool boostedGain) {
@@ -112,7 +111,6 @@ class RadioService : public Service {
     // `lora inject`: a packet into the ring as if received, to test the App and Captures with no
     // transmitter in range. Nothing goes on air.
     void inject(const uint8_t* data, size_t len, float rssi, float snr);
-#endif
 
    private:
     enum Notify : uint32_t { kIrq = 1, kRequest = 2 };

src/services/update_service.cpp

@@ -215,9 +215,8 @@ std::string UpdateService::failedVersion() const {
     return failed;
 }
 
-std::string UpdateService::requestInstall(const std::string& tag, bool force) {
+std::string UpdateService::requestInstall(const std::string& tag) {
     if (phase_ != Phase::Idle || giteaBusy()) return "Busy with something else";
-    if (!force && release::isDebugBuild(runningVersion())) return "Debug Build: update from the PC";  // short: it is drawn in one line at the screen's foot
     if (wifi_.state() != WifiController::State::Connected) return "No Wi-Fi";
     release::Release r;
     if (!gitea_.find(tag, r)) return "Look for releases first";
@@ -295,14 +294,12 @@ void UpdateService::serve() {
             if (gitea_.find(installTag_, release)) installFromGitea(release);
             break;
         }
-#ifdef RORO_DEBUG
         case Request::Probe: {
             HttpsGet get(net::User::Updates);
             std::string why = get.open(probeHost_, probePath_, "*/*");
             probeResult_ = why.empty() ? "accepted, the server answered 200" : why;
             break;
         }
-#endif
         case Request::None: break;
     }
     // A check or a list someone asked for that failed says so; the daily one stays quiet.
@@ -328,12 +325,8 @@ void UpdateService::installFromGitea(const release::Release& r) {
         notify("Update refused: " + why, NotificationLevel::Warning);
         return;
     }
-#ifdef RORO_DEBUG
     GiteaSource source(get, damageCut_, damageFlip_);
     damageCut_ = damageFlip_ = -1;
-#else
-    GiteaSource source(get, -1, -1);
-#endif
     install(source, "Gitea");
 }
 

src/services/update_service.h

@@ -50,9 +50,8 @@ class UpdateService : public Service {
     void requestCheck() { request_ = Request::Check; }
     void requestList() { request_ = Request::List; }
     // Downloads `tag` (a release known from the last check or list) into the inactive slot and
-    // installs it. "" when it started, or why not. A Debug Build doesn't install a release (Q171,
+    // installs it. "" when it started, or why not.
-    // it would take its Debug Console away) unless `force`, which only the Debug Console passes.
+    std::string requestInstall(const std::string& tag);
-    std::string requestInstall(const std::string& tag, bool force = false);
     bool giteaBusy() const { return request_ != Request::None || serving_; }
     // Asked to make room for a TLS connection (R1, Q172): IRC steps aside while the Update Service
     // talks to Gitea. Set by the main loop; `true` to step aside, `false` to come back.
@@ -63,14 +62,12 @@ class UpdateService : public Service {
     std::string runningVersion() const { return fakeVersion_.empty() ? versionString() : fakeVersion_; }
     void pretendVersion(const std::string& v) { fakeVersion_ = v; }
     std::string failedVersion() const;  // a release that rolled back here, "" if none
-#ifdef RORO_DEBUG
     // Debug Builds only, to try the refusals on the real network path: one HTTPS GET to any host
     // (is its certificate accepted?), and a download cut short or with one byte flipped.
     void requestProbe(const std::string& host, const std::string& path) { probeHost_ = host; probePath_ = path; probeResult_ = "..."; request_ = Request::Probe; }
     std::string probeResult() const { return probeResult_; }
     void damageNextDownload(long cutAfter, long flipAt) { damageCut_ = cutAfter; damageFlip_ = flipAt; }
     void forgetToday() { store_.putInt("rel_day", 0); nextCheckMs_ = 0; announced_.clear(); }  // the daily check runs at the next tick
-#endif
 
     // The main loop calls this once it has drawn a frame (part of Probation).
     void firstFrameDrawn() { firstFrame_ = true; }
@@ -109,11 +106,9 @@ class UpdateService : public Service {
     std::string installTag_, fakeVersion_, announced_;
     bool dailyCheck_ = false;
     uint32_t nextCheckMs_ = 90000;  // not before the device has settled
-#ifdef RORO_DEBUG
     std::string probeHost_, probePath_;
     volatile long damageCut_ = -1, damageFlip_ = -1;
     std::string probeResult_;
-#endif
 };
 
 }  // namespace roro

src/services/wifi_service.h

@@ -56,11 +56,9 @@ class WifiService : public Service {
     void ipSettingChanged(const std::string& ssid);
     // The DNS or NTP settings changed: use them now.
     void serversChanged() { applyServers(Why::SettingsChanged); }
-#ifdef RORO_DEBUG
     // The noise self-test switches the radio off for a few seconds. Not saved anywhere: a restart
     // during the test brings Wi-Fi back, which a changed setting wouldn't.
     void debugPause(bool paused) { paused_ = paused; }
-#endif
 
     // A Saved Network was added: try it now rather than after the retry delay.
     void savedNetworksChanged() { controller_.retryNow(millis()); }