Site: the posts link to each other wherever they refer to one; check_site.py checks every link of the site

"The last post" and "the first post" in the LoRa, Gemini and S1 posts are
now links. check_site.py follows every link to another page of the site and
the #fragment it names, so a broken one fails the Site job.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT

.gitea/workflows/ci.yml

@@ -0,0 +1,114 @@
+# 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 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).
+#
+# The job runs in a plain Python image, as scripts/ci.sh does on a developer's machine, with the
+# toolchains in a Docker volume the runner allows (container.valid_volumes: roro9stack-pio): that
+# volume is the cache. No JavaScript actions, so the image needs no Node: the checkout is git.
+name: CI
+on:
+  push:
+    branches: [main]  # other branches are tested by their pull request: one run, not two
+    tags: ['v*']
+    # A change that touches nothing but the site and the documents it is built from runs the Site
+    # workflow only (a tag always runs this one: Gitea doesn't apply path filters to tags).
+    paths-ignore: ['site/**', 'docs/**', 'README.md', 'CONTEXT.md']
+  pull_request:
+    paths-ignore: ['site/**', 'docs/**', 'README.md', 'CONTEXT.md']
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: An existing tag to build and publish as a release
+        required: true
+
+jobs:
+  build:
+    runs-on: ubuntu
+    # A pull request from a fork would run someone else's code on our runner: not without us (Q154).
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    container:
+      image: python:3.12-slim
+      volumes:
+        - roro9stack-pio:/pio
+    env:
+      PLATFORMIO_CORE_DIR: /pio
+      RORO_NO_DOCKER: 1
+    steps:
+      - name: Tools
+        run: |
+          apt-get update -qq
+          apt-get install -y -qq --no-install-recommends git build-essential openssl >/dev/null
+          pip install -q --no-cache-dir --root-user-action=ignore platformio gcovr
+          pio --version; df -h /pio | tail -1; ls /pio | head
+
+      - name: Check out
+        run: |
+          find . -mindepth 1 -maxdepth 1 -exec rm -rf {} +
+          git config --global --add safe.directory '*'
+          git init -q .
+          git remote add origin "${{ github.server_url }}/${{ github.repository }}.git"
+          git fetch -q --tags origin '+refs/heads/*:refs/remotes/origin/*' '+refs/pull/*/head:refs/remotes/pull/*'
+          git checkout -q --detach "${{ github.sha }}"
+          git describe --tags --always
+
+      - name: Host tests, and their coverage of lib/
+        if: github.event_name != 'workflow_dispatch'
+        run: scripts/coverage.sh
+
+      - name: The release firmware and the Debug Build
+        if: github.event_name == 'pull_request' || github.ref_type == 'tag'
+        run: scripts/ci.sh builds
+
+      # The README's badges are files on a branch of their own, replaced at each push to main and
+      # at each tag (the release badge says which tag is the latest)
+      - name: Publish the badges
+        if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref_type == 'tag')
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+        run: |
+          rm -rf /tmp/badges && mkdir /tmp/badges
+          cp .pio/coverage/coverage.svg .pio/coverage/summary.json /tmp/badges/
+          scripts/coverage_badge.py --plain release "$(git describe --tags --abbrev=0)" /tmp/badges/release.svg
+          cd /tmp/badges
+          git init -q -b badges .
+          git add .
+          git -c user.name="roro9stack CI" -c user.email="ci@git.twis.la" commit -q -m "Coverage of ${{ github.ref_name }} at ${{ github.sha }}"
+          git push -q --force "$(echo "${{ github.server_url }}" | sed "s#://#://ci:${GITEA_TOKEN}@#")/${{ github.repository }}.git" badges
+
+      - name: Which release
+        id: release
+        run: |
+          if [ "${{ github.event_name }}" = workflow_dispatch ]; then
+            echo "tag=${{ inputs.tag }}" >> "$GITHUB_OUTPUT"
+          elif [ "${{ github.ref_type }}" = tag ]; then
+            echo "tag=${{ github.ref_name }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build and sign the release
+        if: steps.release.outputs.tag != ''
+        env:
+          OTA_SIGNING_KEY: ${{ secrets.OTA_SIGNING_KEY }}
+        run: |
+          # The sources of the tag in a clone of their own; the tools are this commit's.
+          rm -rf /tmp/release-src dist
+          git clone -q . /tmp/release-src
+          git -C /tmp/release-src checkout -q --detach "refs/tags/${{ steps.release.outputs.tag }}"
+          # The key exists as a file only while this step runs, in a container that goes with the job.
+          umask 077
+          export RORO_OTA_KEY="$(mktemp)"
+          trap 'rm -f "$RORO_OTA_KEY"' EXIT
+          printf '%s\n' "$OTA_SIGNING_KEY" > "$RORO_OTA_KEY"
+          umask 022
+          scripts/release_build.sh /tmp/release-src dist
+
+      - name: Publish the release
+        if: steps.release.outputs.tag != ''
+        env:
+          GITEA_API: ${{ github.server_url }}/api/v1
+          GITEA_REPO: ${{ github.repository }}
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+        run: scripts/release_publish.py dist

.gitea/workflows/site.yml

@@ -0,0 +1,49 @@
+# The project site (docs/milestones/W1.md): built with Zola to see that it builds and that its pages
+# are sound. Publishing is the maintainer's: the web server pulls main and runs `zola build`.
+#
+# 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.
+name: Site
+on:
+  push:
+    branches: [main]
+    paths: ['site/**', 'docs/**', 'README.md', 'CONTEXT.md', '.gitea/workflows/site.yml']
+  pull_request:
+    paths: ['site/**', 'docs/**', 'README.md', 'CONTEXT.md', '.gitea/workflows/site.yml']
+
+jobs:
+  build:
+    runs-on: ubuntu
+    # A pull request from a fork would run someone else's code on our runner: not without us.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    container:
+      image: python:3.12-slim
+    steps:
+      - name: Tools
+        run: |
+          apt-get update -qq
+          apt-get install -y -qq --no-install-recommends git ca-certificates curl >/dev/null
+          # Zola, pinned by its checksum.
+          curl -fsSL -o /tmp/zola.tgz https://github.com/getzola/zola/releases/download/v0.22.0/zola-v0.22.0-x86_64-unknown-linux-gnu.tar.gz
+          echo "f1d491f8956b94384c27d75cb6b2bf60d3916d1ade9564bcbfe7c03f0258aebf  /tmp/zola.tgz" | sha256sum -c -
+          tar xzf /tmp/zola.tgz -C /usr/local/bin zola
+          zola --version
+
+      - name: Check out
+        run: |
+          find . -mindepth 1 -maxdepth 1 -exec rm -rf {} +
+          git config --global --add safe.directory '*'
+          git init -q .
+          git remote add origin "${{ github.server_url }}/${{ github.repository }}.git"
+          git fetch -q origin '+refs/heads/*:refs/remotes/origin/*' '+refs/pull/*/head:refs/remotes/pull/*'
+          git checkout -q --detach "${{ github.sha }}"
+
+      - name: Build the site
+        run: |
+          cd site
+          zola check --skip-external-links
+          zola build --output-dir /tmp/site-out
+
+      - name: Check the pages
+        run: python3 site/tools/check_site.py /tmp/site-out

.gitignore

@@ -9,3 +9,6 @@
 .dummy/
 managed_components/
 sdkconfig.*
+
+# The built site (site/config.toml sends it here)
+/public/

CONTEXT.md

@@ -123,13 +123,28 @@ Data the user explicitly starts recording, such as Wi-Fi packet captures and LoR
 _Avoid_: dump, log
 
 **Storage Warning**:
-The Notification raised once per boot when the SD card passes 80% full. Selecting it opens Storage Clean-up.
+The Notification raised once per boot when the SD card passes 80% full. It points at the Storage App, where Maintenance holds Storage Clean-up.
 
 **Storage Clean-up**:
-The screen where the user deletes old Logs and Captures by category and age, with a preview of the space freed. Notes are never offered for deletion.
+The screen where the user deletes old Logs and Captures by category and age, with a preview of the space freed. Notes are never offered for deletion. It lives in the Storage App, under Maintenance.
+
+**Note**:
+A plain text file in `/notes`, written on the device in the Notes App. Listed by its first line. Saved without being asked; never offered by Storage Clean-up.
+_Avoid_: memo, document
+
+**Storage App**:
+The App that browses the SD card: folders and files, a clipboard for one item at a time (copy, cut, paste), rename, delete, new folder, and a viewer for each kind of file the firmware writes. The top-level folders, `/gemini/cache` and files being written are read-only.
+_Avoid_: file manager, Files, explorer
+
+**Maintenance**:
+The part of the Storage App that deletes in bulk: the card's usage, Storage Clean-up and erasing the card. Reached through a warning.
+_Avoid_: Settings > Storage
 
 **Firmware Update**:
-Installing a new firmware image without a USB cable: pushed over Wi-Fi from the developer's PC, or read from the SD card.
+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.
 _Avoid_: flash, upgrade (alone)
 
 **Update File**:

README.md

@@ -1,5 +1,7 @@
 # roro9stack
 
+[![CI](https://git.twis.la/twisla/roro9stack/actions/workflows/ci.yml/badge.svg?branch=main)](https://git.twis.la/twisla/roro9stack/actions?workflow=ci.yml) [![Coverage of lib/ by the host tests](https://git.twis.la/twisla/roro9stack/raw/branch/badges/coverage.svg)](#build-and-test-local-ci) [![Latest release](https://git.twis.la/twisla/roro9stack/raw/branch/badges/release.svg)](https://git.twis.la/twisla/roro9stack/releases/latest)
+
 A multi-app firmware for the **M5Stack Cardputer ADV** with the **Cap LoRa-1262**. It's a Meshtastic-compatible mesh messenger, plus Wi-Fi tools, IRC, GNSS and more. Licensed GPL-3.0.
 
 - Domain language: [CONTEXT.md](CONTEXT.md)
@@ -18,8 +20,27 @@ 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 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:
+
+- `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.
+
+`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.
+
+## The website
+
+The project's site, **roro9stack.net**, is built from `site/` with Zola (see `site/README.md`): the home page, an Install page that flashes a Cardputer from the browser, and every release. Changes under `site/`, `docs/`, `README.md` and `CONTEXT.md` run only the site's CI job, not the firmware tests and builds.
+
 ## Flash
 
 1. Connect the Cardputer by USB-C.
@@ -52,7 +73,21 @@ The device shows the push address in **Settings → Firmware**. It installs a co
 
 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.
+**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.
+
+**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`.
 
 ## Networks without DHCP
 
@@ -80,7 +115,42 @@ On a page, `b` bookmarks it, `s` saves it to the SD card to read offline (a non-
 
 ## LoRa Scanner
 
-The LoRa Scanner (docs/milestones/M3.md) listens with the Cap's radio and **never transmits**. The Sniffer lists what it hears, newest first: time, RSSI, SNR, and for Meshtastic packets the sender and receiver (their last 4 hex digits) and hops. Enter shows a packet's details: the Meshtastic header (which is never encrypted) and a hex dump. `p` picks one of the 7 Meshtastic presets allowed in EU868 (LongFast by default), `c` starts or stops a Capture: a pcap file with LoRaTap headers in `/captures/lora/`, for Wireshark. A Capture keeps recording with the App closed; otherwise the radio sleeps when the App isn't open. Tab switches to **Sweep**: the signal strength across 863–870 MHz in 100 kHz steps, as bars with peak hold and a waterfall, with the Sniffer's frequency marked; the Sniffer is paused meanwhile and picks up where it was. The Status Bar shows `L` while the radio listens (bright for a moment on each packet), `SW` while sweeping, and `CAP` while capturing.
+The LoRa Scanner (docs/milestones/M3.md) listens with the Cap's radio and **never transmits**. The Sniffer lists what it hears, newest first: time, RSSI, SNR, and for Meshtastic packets the sender and receiver (their last 4 hex digits) and hops. Enter shows a packet's details: the Meshtastic header (which is never encrypted) and a hex dump. `p` picks one of the 7 Meshtastic presets allowed in EU868 (LongFast by default), `c` starts or stops a Capture: a pcap file with LoRaTap headers in `/captures/lora/`, for Wireshark. A Capture keeps recording with the App closed; otherwise the radio sleeps when the App isn't open. Tab switches to **Sweep**: the signal strength across 863–870 MHz in 100 kHz steps, as bars with peak hold and a waterfall, with the Sniffer's frequency marked; the Sniffer is paused meanwhile and picks up where it was. The GNSS receiver on the same Cap raises the radio's noise floor by 8 dB while it runs: Settings > "Pause GNSS for LoRa" (off by default) puts it in standby while the radio listens, except during a Track. The Status Bar shows `L` while the radio listens (bright for a moment on each packet), `SW` while sweeping, and `CAP` while capturing.
+
+## Storage
+
+The Storage App (docs/milestones/F1.md) shows what's on the SD card: each folder's entries with their size and date, folders first. Enter opens a folder, Back goes up; `s` sorts by name, date or size. It works on one item at a time, with a clipboard:
+
+| Key | Does |
+|---|---|
+| `c` / `x` | Copies or cuts the selected file or folder; the footer shows what `v` would paste |
+| `v` | Pastes it into the folder shown. A copy next to its original is named `name (2).txt`; anything in the way is asked about first |
+| `r` | Renames |
+| `d` | Deletes, after saying what's inside: "Delete saved and its 42 files (1.2 MB)?" |
+| `n` | Makes a folder |
+| `i` | Details: type, exact size, date, and why an item is read-only if it is |
+
+A copy runs in the background of the card (about 400 KB a second) in short turns, so Logs and Captures keep being written; it shows its progress, Back cancels it and takes back what was copied, and each file's size is checked afterwards. Three things can't be changed: the top-level folders the firmware keeps its files in (what's inside them can), `/gemini/cache`, and any file being written right now (today's IRC Logs, a Track or a Capture being recorded). The App says why when it refuses. A folder with more than 256 entries shows the first 256 by name and says so.
+
+Enter on a file opens it by type; Tab switches to the same file as a hex dump or as text:
+
+- **Text** (`.txt`, `.log`, `.gmi`, `.csv`, and anything that looks like text): only the screen's worth is read from the card, so a file of any size opens at once. Logs open at the end. Up and Down move a line, Left and Right a page, `t` and `b` go to the top and the end, `e` edits it (up to 16 KB, see Notes).
+- **Captures** (`.pcap`): the packets as the LoRa Scanner lists them; Enter shows one with its Meshtastic header and bytes.
+- **Tracks** (`.gpx`): the number of points, the start, the duration and the distance.
+- **Update Files** (`.ota`): the version, and whether the file would install: it's checked as an install checks it (signature and contents) without writing anything. Enter then installs it.
+- **Anything else:** a hex dump.
+
+At the top of the card the last row, **Maintenance** (also `m`), holds the card's usage, Storage Clean-up and "Erase SD card", behind a warning: those delete for good. It replaces Settings > Storage.
+
+## Notes
+
+The Notes App (docs/milestones/F1.md) keeps plain text notes in `/notes` on the SD card. The list shows each note's first line and its date, newest first; `s` switches to by file name. `n` starts a note, Enter opens one, `r` renames its file, `d` deletes it after asking.
+
+In the editor, type. Enter starts a line, Del deletes backwards, Fn with the arrows moves the cursor through the wrapped text, Ctrl+A and Ctrl+E go to the start and the end of the line, Tab types two spaces, and the Compose Key gives accents as everywhere. **There's no save key:** the note is written five seconds after the last key, on Back, on leaving the App, when the screen turns off and before the device powers off. The top line says "typing" or "saved". Each save writes a temporary file and then puts it in the note's place, so a power cut costs a few seconds of typing and never the note; if a save was cut short, opening the note offers its copy back.
+
+A new note has no file until something is typed; its file is then named after its first line (`shopping-list.txt`), or `note-<date>-<time>.txt`.
+
+A note holds up to 16 KB while it's edited. A bigger text file opens read-only in the Storage App (editing any size is issue #47). The Storage App's text viewer has `e` to edit a file with the same editor, anywhere on the card, unless the file is read-only.
 
 ## Development aids
 
@@ -98,6 +168,7 @@ The LoRa Scanner (docs/milestones/M3.md) listens with the Cap's radio and **neve
 | `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 |
 | `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 |
@@ -107,21 +178,27 @@ The LoRa Scanner (docs/milestones/M3.md) listens with the Cap's radio and **neve
 | `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, and each core's load |
+| `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]` / `rm <path>` | Lists a folder of the SD card, or deletes a file |
+| `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 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 |
 | `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 |
+| `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 |
 | `lora inject <hex> [rssi] [snr]` | Debug Builds: 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 |
 | `crash abort` / `crash wdt` | Debug Builds: crash on purpose, or hang the main loop until the watchdog fires |
 | `help` | Lists the commands |
 

docker/Dockerfile

@@ -5,7 +5,7 @@ RUN apt-get update \
  && apt-get install -y --no-install-recommends git build-essential \
  && rm -rf /var/lib/apt/lists/*
 
-RUN pip install --no-cache-dir platformio
+RUN pip install --no-cache-dir platformio gcovr
 
 # Toolchains and libraries are cached in a named volume mounted here.
 RUN mkdir -p /pio && chmod 777 /pio

docs/adr/0008-ci-signs-releases.md

@@ -0,0 +1,17 @@
+# CI signs releases with the project's key
+
+A tag `v*` is built, signed and published by Gitea Actions with nobody at a keyboard. The signing key of ADR 0003 is therefore held twice: in `~/.config/roro9stack/ota-key.pem` on the development machine, as before, and as the 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.

docs/adr/0009-the-device-trusts-the-isrg-roots.md

@@ -0,0 +1,22 @@
+# The device trusts the two ISRG roots for what it fetches
+
+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.

docs/milestones/F1.md

@@ -0,0 +1,161 @@
+# F1 — Files and Notes
+
+**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.

docs/milestones/R1.md

@@ -0,0 +1,125 @@
+# R1 — Releases
+
+**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 | 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 | **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.

docs/milestones/S1.md

@@ -1,6 +1,6 @@
 # S1 — System basics
 
-**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). Still open in the milestone: #39, following the SD driver upstream, and #40, the main loop's CPU use.
+**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.
 
@@ -90,3 +90,49 @@ The App has five views, not four: Q121's network view is one of its own (Overvie
 - **`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).

docs/milestones/W1.md

@@ -0,0 +1,112 @@
+# 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.
+
+**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.

lib/apps_model/src/settings_menu.cpp

@@ -20,10 +20,10 @@ const RowDef kRows[] = {
     {Row::Region, Kind::Choice, "Region"},      {Row::Timezone, Kind::Choice, "Timezone"},
     {Row::Brightness, Kind::Slider, "Brightness"}, {Row::DimTimeout, Kind::Choice, "Dim after"},
     {Row::OffTimeout, Kind::Choice, "Screen off after"}, {Row::Sound, Kind::Toggle, "Sound & LED"},
-    {Row::Gnss, Kind::Toggle, "GNSS"}, {Row::Coordinates, Kind::Toggle, "Coordinates"},
+    {Row::Gnss, Kind::Toggle, "GNSS"}, {Row::GnssQuiet, Kind::Toggle, "Pause GNSS for LoRa"},
+    {Row::Coordinates, Kind::Toggle, "Coordinates"},
     {Row::ProbeMacs, Kind::Toggle, "Probe MACs"}, {Row::Wifi, Kind::Page, "Wi-Fi"},
-    {Row::Storage, Kind::Page, "Storage"},
-    {Row::Firmware, Kind::Page, "Firmware"},
+    {Row::CheckUpdates, Kind::Toggle, "Check for updates"}, {Row::Firmware, Kind::Page, "Firmware"},
     {Row::About, Kind::Page, "About"},
 };
 
@@ -81,6 +81,8 @@ std::string SettingsMenu::value(int i) const {
         case Row::OffTimeout: return formatSeconds(settings_.getInt(Setting::OffTimeoutS));
         case Row::Sound: return settings_.getBool(Setting::Sound) ? "On" : "Off";
         case Row::Gnss: return settings_.getBool(Setting::GnssEnabled) ? "On" : "Off";
+        case Row::GnssQuiet: return settings_.getBool(Setting::GnssQuietForLora) ? "On" : "Off";
+        case Row::CheckUpdates: return settings_.getBool(Setting::CheckUpdates) ? "Daily" : "Off";
         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";
@@ -126,6 +128,8 @@ std::string SettingsMenu::choose(int i, int c) {
 void SettingsMenu::toggle(int i) {
     if (row(i) == Row::Sound) settings_.setBool(Setting::Sound, !settings_.getBool(Setting::Sound));
     if (row(i) == Row::Gnss) settings_.setBool(Setting::GnssEnabled, !settings_.getBool(Setting::GnssEnabled));
+    if (row(i) == Row::GnssQuiet) settings_.setBool(Setting::GnssQuietForLora, !settings_.getBool(Setting::GnssQuietForLora));
+    if (row(i) == Row::CheckUpdates) settings_.setBool(Setting::CheckUpdates, !settings_.getBool(Setting::CheckUpdates));
     if (row(i) == Row::Coordinates) settings_.setBool(Setting::CoordinatesDms, !settings_.getBool(Setting::CoordinatesDms));
     if (row(i) == Row::ProbeMacs) settings_.setBool(Setting::ProbeMacRaw, !settings_.getBool(Setting::ProbeMacRaw));
 }

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, Coordinates, ProbeMacs, Wifi, Storage, Firmware, About };
+    enum class Row { LongName, ShortName, Region, Timezone, Brightness, DimTimeout, OffTimeout, Sound, Gnss, GnssQuiet, Coordinates, ProbeMacs, Wifi, CheckUpdates, Firmware, About };
     enum class Kind { Text, Choice, Toggle, Slider, Page };
 
     explicit SettingsMenu(Settings& settings) : settings_(settings) {}

lib/files/src/file_list.cpp

@@ -0,0 +1,137 @@
+#include "file_list.h"
+
+#include <algorithm>
+#include <cctype>
+#include <cstdio>
+#include <cstring>
+#include <ctime>
+
+namespace roro::files {
+
+namespace {
+
+// Names compare letters only, whatever the case; ties by the bytes, so the order is total.
+int compareNames(const char* a, const char* b) {
+    for (const char *x = a, *y = b;; ++x, ++y) {
+        int cx = std::tolower(static_cast<unsigned char>(*x)), cy = std::tolower(static_cast<unsigned char>(*y));
+        if (cx != cy) return cx < cy ? -1 : 1;
+        if (!cx) break;
+    }
+    return std::strcmp(a, b);
+}
+
+constexpr uint32_t kYear2020 = 1577836800;
+
+std::string sizeText(uint32_t bytes) {
+    char s[16];
+    if (bytes < 1024) std::snprintf(s, sizeof s, "%u B", static_cast<unsigned>(bytes));
+    else if (bytes < 10 * 1024) std::snprintf(s, sizeof s, "%.1f KB", bytes / 1024.0);
+    else if (bytes < 1024 * 1024) std::snprintf(s, sizeof s, "%u KB", static_cast<unsigned>(bytes / 1024));
+    else if (bytes < 10u * 1024 * 1024) std::snprintf(s, sizeof s, "%.1f MB", bytes / 1048576.0);
+    else if (bytes < 1024u * 1024 * 1024) std::snprintf(s, sizeof s, "%u MB", static_cast<unsigned>(bytes / 1048576));
+    else std::snprintf(s, sizeof s, "%.1f GB", bytes / 1073741824.0);
+    return s;
+}
+
+}  // namespace
+
+void FileList::clear() {
+    std::vector<Entry>().swap(entries_);
+    std::vector<uint16_t>().swap(order_);
+    std::vector<char>().swap(names_);
+    more_ = wasted_ = 0;
+}
+
+bool FileList::before(const Entry& a, const Entry& b, FileSort by) const {
+    if (a.folder != b.folder) return a.folder;
+    if (!a.folder) {
+        if (by == FileSort::Date && a.modified != b.modified) return a.modified > b.modified;
+        if (by == FileSort::Size && a.size != b.size) return a.size > b.size;
+    }
+    return compareNames(names_.data() + a.name, names_.data() + b.name) < 0;
+}
+
+void FileList::add(const char* name, uint32_t size, uint32_t modified, bool folder) {
+    size_t len = std::strlen(name) + 1;
+    if (entries_.size() >= kMax) {
+        // Full: the new entry takes the place of the one that sorts last by name, if it sorts
+        // before it. The old name's bytes stay in the buffer until there's enough waste to pack.
+        more_++;
+        size_t last = 0;
+        for (size_t i = 1; i < entries_.size(); i++)
+            if (before(entries_[last], entries_[i], FileSort::Name)) last = i;
+        Entry candidate{static_cast<uint32_t>(names_.size()), size, modified, folder};
+        names_.insert(names_.end(), name, name + len);
+        if (!before(candidate, entries_[last], FileSort::Name)) {
+            names_.resize(names_.size() - len);
+            return;
+        }
+        wasted_ += std::strlen(names_.data() + entries_[last].name) + 1;
+        entries_[last] = candidate;
+        if (wasted_ > 2048) compact();
+        return;
+    }
+    if (entries_.empty()) {
+        entries_.reserve(32);
+        names_.reserve(512);
+    }
+    entries_.push_back({static_cast<uint32_t>(names_.size()), size, modified, folder});
+    names_.insert(names_.end(), name, name + len);
+    order_.push_back(static_cast<uint16_t>(order_.size()));
+}
+
+void FileList::compact() {
+    std::vector<char> packed;
+    packed.reserve(names_.size() - wasted_);
+    for (Entry& e : entries_) {
+        const char* n = names_.data() + e.name;
+        e.name = static_cast<uint32_t>(packed.size());
+        packed.insert(packed.end(), n, n + std::strlen(n) + 1);
+    }
+    names_.swap(packed);
+    wasted_ = 0;
+}
+
+void FileList::sort(FileSort by) {
+    if (wasted_) compact();
+    names_.shrink_to_fit();
+    entries_.shrink_to_fit();
+    order_.resize(entries_.size());
+    for (size_t i = 0; i < order_.size(); i++) order_[i] = static_cast<uint16_t>(i);
+    std::sort(order_.begin(), order_.end(), [&](uint16_t a, uint16_t b) { return before(entries_[a], entries_[b], by); });
+}
+
+int FileList::find(const std::string& name) const {
+    for (size_t i = 0; i < order_.size(); i++)
+        if (name == this->name(i)) return static_cast<int>(i);
+    return -1;
+}
+
+size_t FileList::bytes() const {
+    return entries_.capacity() * sizeof(Entry) + order_.capacity() * sizeof(uint16_t) + names_.capacity();
+}
+
+std::string formatStamp(uint32_t modified) {
+    if (modified < kYear2020) return "-";
+    time_t t = static_cast<time_t>(modified);
+    struct tm local;
+    localtime_r(&t, &local);
+    char s[20];
+    std::snprintf(s, sizeof s, "%04d-%02d-%02d %02d:%02d", local.tm_year + 1900, local.tm_mon + 1, local.tm_mday, local.tm_hour,
+                  local.tm_min);
+    return s;
+}
+
+std::string rowDetail(bool folder, uint32_t size, uint32_t modified) {
+    if (folder) return "folder";
+    std::string stamp = formatStamp(modified);
+    return sizeText(size) + "  " + (stamp == "-" ? stamp : stamp.substr(0, 10));
+}
+
+std::string fitName(const std::string& name, size_t maxChars) {
+    if (name.size() <= maxChars || maxChars < 8) return name.substr(0, maxChars);
+    size_t tail = std::min<size_t>(6, maxChars / 3), head = maxChars - tail - 2;
+    return name.substr(0, head) + ".." + name.substr(name.size() - tail);
+}
+
+}  // namespace roro::files

lib/files/src/file_list.h

@@ -0,0 +1,55 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace roro::files {
+
+enum class FileSort : uint8_t { Name, Date, Size };
+
+// A folder's entries for the Storage App (F1, Q129, Q136): 256 at most, the names packed into
+// one buffer, about 10 KB when full. A bigger folder keeps the first 256 by name, whatever order
+// the card lists them in, and counts the rest.
+class FileList {
+   public:
+    static constexpr size_t kMax = 256;
+
+    void clear();
+    void add(const char* name, uint32_t size, uint32_t modified, bool folder);
+    void sort(FileSort by);  // folders first, by name; then files by name, newest or biggest first
+
+    size_t count() const { return entries_.size(); }
+    size_t more() const { return more_; }  // entries that didn't fit
+    // By position after sort().
+    const char* name(size_t i) const { return names_.data() + entries_[order_[i]].name; }
+    uint32_t size(size_t i) const { return entries_[order_[i]].size; }
+    uint32_t modified(size_t i) const { return entries_[order_[i]].modified; }  // Unix time, 0 if unknown
+    bool folder(size_t i) const { return entries_[order_[i]].folder; }
+    int find(const std::string& name) const;  // position, or -1
+    size_t bytes() const;                     // memory held
+
+   private:
+    struct Entry {
+        uint32_t name;  // offset into names_
+        uint32_t size, modified;
+        bool folder;
+    };
+    bool before(const Entry& a, const Entry& b, FileSort by) const;
+    void compact();
+
+    std::vector<Entry> entries_;
+    std::vector<uint16_t> order_;
+    std::vector<char> names_;
+    size_t more_ = 0, wasted_ = 0;
+};
+
+// What a row shows on the right (Q129): "folder", or "1.2 KB  2026-10-05". A file dated before
+// 2020 was written before the clock was set: "-" (Q137). Local time.
+std::string rowDetail(bool folder, uint32_t size, uint32_t modified);
+std::string formatStamp(uint32_t modified);
+// A name cut to `maxChars` for a row, from the middle: the start and the extension stay readable.
+std::string fitName(const std::string& name, size_t maxChars);  // "2026-10-05 20:00", or "-"
+
+}  // namespace roro::files

lib/files/src/file_names.cpp

@@ -0,0 +1,99 @@
+#include "file_names.h"
+
+#include <cctype>
+
+namespace roro::files {
+
+const char* const kFirmwareFolders[] = {"/irc", "/wifi", "/updates", "/gnss", "/gemini", "/captures", "/notes"};
+const size_t kFirmwareFolderCount = sizeof kFirmwareFolders / sizeof kFirmwareFolders[0];
+
+std::string parentOf(const std::string& path) {
+    size_t slash = path.rfind('/');
+    return slash == std::string::npos || slash == 0 ? "/" : path.substr(0, slash);
+}
+
+std::string baseName(const std::string& path) {
+    size_t slash = path.rfind('/');
+    return slash == std::string::npos ? path : path.substr(slash + 1);
+}
+
+std::string joinPath(const std::string& folder, const std::string& name) {
+    return folder == "/" ? "/" + name : folder + "/" + name;
+}
+
+std::string extensionOf(const std::string& name) {
+    size_t dot = name.rfind('.');
+    if (dot == std::string::npos || dot == 0) return "";
+    std::string ext = name.substr(dot + 1);
+    for (char& c : ext) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+    return ext;
+}
+
+bool isInside(const std::string& path, const std::string& folder) {
+    if (folder == "/") return true;
+    if (path.compare(0, folder.size(), folder) != 0) return false;
+    return path.size() == folder.size() || path[folder.size()] == '/';
+}
+
+std::string checkName(const std::string& name) {
+    if (name.empty()) return "A name can't be empty";
+    if (name == "." || name == "..") return "\".\" and \"..\" aren't names";
+    if (name.size() > 64) return "A name can be 64 characters at most";
+    for (char c : name) {
+        if (static_cast<unsigned char>(c) < 0x20) return "A name can't contain control characters";
+        for (char bad : std::string("/\\:*?\"<>|"))
+            if (c == bad) return std::string("A name can't contain ") + c;
+    }
+    if (name.back() == '.' || name.back() == ' ') return "A name can't end with a dot or a space";
+    return "";
+}
+
+std::string whyReadOnly(const std::string& path, const std::vector<std::string>& inUse) {
+    if (path == "/" || path.empty()) return "That's the card itself";
+    if (isInside(path, kGeminiCache)) return std::string(kGeminiCache) + " is the Gemini App's working space";
+    for (const std::string& open : inUse) {
+        if (open == path) return "It's being written right now";
+        if (isInside(open, path)) return "It holds a file that's being written right now";
+    }
+    for (size_t i = 0; i < kFirmwareFolderCount; i++)
+        if (path == kFirmwareFolders[i]) return std::string("The firmware keeps its files in ") + path;
+    return "";
+}
+
+std::string whyNotInto(const std::string& source, const std::string& into) {
+    if (isInside(into, kGeminiCache)) return std::string(kGeminiCache) + " is the Gemini App's working space";
+    if (isInside(into, source)) return "A folder can't go inside itself";
+    if (parentOf(source) == into) return "It's already there";
+    return "";
+}
+
+std::string copyName(const std::string& name, int n) {
+    size_t dot = name.rfind('.');
+    std::string suffix = " (" + std::to_string(n) + ")";
+    if (dot == std::string::npos || dot == 0) return name + suffix;
+    return name.substr(0, dot) + suffix + name.substr(dot);
+}
+
+FileKind kindOf(const std::string& name) {
+    std::string ext = extensionOf(name);
+    if (ext == "gpx") return FileKind::Gpx;
+    if (ext == "pcap") return FileKind::Pcap;
+    if (ext == "ota") return FileKind::Ota;
+    for (const char* text : {"txt", "log", "gmi", "csv", "md", "json", "ini", "conf", "ir"})
+        if (ext == text) return FileKind::Text;
+    return FileKind::Unknown;
+}
+
+bool opensAtEnd(const std::string& name) { return extensionOf(name) == "log"; }
+
+bool looksLikeText(const uint8_t* data, size_t len) {
+    size_t odd = 0;
+    for (size_t i = 0; i < len; i++) {
+        uint8_t b = data[i];
+        if (b == 0) return false;
+        if (b < 0x20 && b != '\n' && b != '\r' && b != '\t') odd++;
+    }
+    return odd * 20 <= len;  // a stray control character or two is still text
+}
+
+}  // namespace roro::files

lib/files/src/file_names.h

@@ -0,0 +1,42 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace roro::files {
+
+// Paths on the SD card are absolute and use '/': "/gemini/saved/index.gmi".
+std::string parentOf(const std::string& path);    // "/" for a top-level entry and for "/"
+std::string baseName(const std::string& path);    // "" for "/"
+std::string joinPath(const std::string& folder, const std::string& name);
+std::string extensionOf(const std::string& name);  // lower case, without the dot; "" if none
+bool isInside(const std::string& path, const std::string& folder);  // a folder is inside itself
+
+// A name typed for rename or a new folder (F1, Q131): "" if FAT and this App can take it, or why not.
+std::string checkName(const std::string& name);
+
+// The top-level folders the firmware keeps its files in. They can't be renamed or deleted;
+// what's in them can (Q130).
+extern const char* const kFirmwareFolders[];
+extern const size_t kFirmwareFolderCount;
+constexpr const char* kGeminiCache = "/gemini/cache";
+
+// Why `path` can't be renamed, moved or deleted, or "" if it can (Q130). `inUse`: the files the
+// firmware has open right now.
+std::string whyReadOnly(const std::string& path, const std::vector<std::string>& inUse);
+
+// Why `source` can't be copied or moved into the folder `into`, or "" if it can.
+std::string whyNotInto(const std::string& source, const std::string& into);
+
+// "a (2).gmi": the name of a copy made next to its original.
+std::string copyName(const std::string& name, int n);
+
+// Which viewer opens a file (Q134), from its name. Unknown: look at the first bytes.
+enum class FileKind : uint8_t { Text, Gpx, Pcap, Ota, Unknown };
+FileKind kindOf(const std::string& name);
+bool opensAtEnd(const std::string& name);  // logs
+bool looksLikeText(const uint8_t* data, size_t len);
+
+}  // namespace roro::files

lib/files/src/file_views.cpp

@@ -0,0 +1,143 @@
+#include "file_views.h"
+
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+
+#include "file_list.h"
+#include "track.h"
+
+namespace roro::files {
+
+std::string hexRow(uint32_t offset, const uint8_t* data, size_t len) {
+    char head[8];
+    std::snprintf(head, sizeof head, "%05X", static_cast<unsigned>(offset));
+    std::string row = head, text;
+    for (size_t i = 0; i < 8; i++) {
+        if (i % 2 == 0) row += ' ';
+        char hex[3] = "  ";
+        if (i < len) {
+            std::snprintf(hex, sizeof hex, "%02x", data[i]);
+            text += data[i] >= 0x20 && data[i] < 0x7F ? static_cast<char>(data[i]) : '.';
+        }
+        row += hex;
+    }
+    return row + "  " + text;
+}
+
+namespace {
+// Days since 1970-01-01 (Howard Hinnant's days_from_civil): no timegm() everywhere.
+int64_t daysFromCivil(int y, int m, int d) {
+    y -= m <= 2;
+    int64_t era = (y >= 0 ? y : y - 399) / 400;
+    int yoe = static_cast<int>(y - era * 400);
+    int doy = (153 * (m + (m > 2 ? -3 : 9)) + 2) / 5 + d - 1;
+    int doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
+    return era * 146097 + doe - 719468;
+}
+
+bool attribute(const std::string& element, const char* name, double& out) {
+    size_t at = element.find(name);
+    if (at == std::string::npos) return false;
+    const char* from = element.c_str() + at + std::strlen(name);
+    char* end = nullptr;
+    out = std::strtod(from, &end);
+    return end != from;
+}
+}  // namespace
+
+void GpxSummary::point(const std::string& element) {
+    double lat, lon;
+    if (!attribute(element, "lat=\"", lat) || !attribute(element, "lon=\"", lon)) return;
+    if (points_ > 0) meters_ += gnss::distanceMeters(lat_, lon_, lat, lon);
+    lat_ = lat;
+    lon_ = lon;
+    points_++;
+    size_t at = element.find("<time>");
+    int y, mo, d, h, mi, s;
+    if (at != std::string::npos && std::sscanf(element.c_str() + at + 6, "%d-%d-%dT%d:%d:%d", &y, &mo, &d, &h, &mi, &s) == 6) {
+        int64_t t = daysFromCivil(y, mo, d) * 86400 + h * 3600 + mi * 60 + s;
+        if (first_ == 0) first_ = t;
+        last_ = t;
+    }
+}
+
+void GpxSummary::feed(const char* data, size_t len) {
+    carry_.append(data, len);
+    size_t done = 0;
+    for (;;) {
+        size_t open = carry_.find("<trkpt", done);
+        if (open == std::string::npos) {
+            // Nothing begun, except perhaps the first letters of a tag at the very end.
+            done = carry_.size() > 6 ? carry_.size() - 6 : done;
+            break;
+        }
+        size_t close = carry_.find("</trkpt>", open);
+        size_t next = carry_.find("<trkpt", open + 6);  // a point with nothing inside: <trkpt .../>
+        if (close == std::string::npos && next == std::string::npos) {
+            done = open;
+            break;
+        }
+        size_t end = close != std::string::npos && (next == std::string::npos || close < next) ? close + 8 : next;
+        point(carry_.substr(open, end - open));
+        done = end;
+    }
+    carry_.erase(0, done);
+    if (carry_.size() > 2048) carry_.erase(0, carry_.size() - 6);  // not a GPX point: don't keep it
+}
+
+std::string formatDuration(int64_t seconds) {
+    char s[24];
+    if (seconds < 60) std::snprintf(s, sizeof s, "%d s", static_cast<int>(seconds));
+    else if (seconds < 3600) std::snprintf(s, sizeof s, "%d min %02d s", static_cast<int>(seconds / 60), static_cast<int>(seconds % 60));
+    else std::snprintf(s, sizeof s, "%d h %02d min", static_cast<int>(seconds / 3600), static_cast<int>(seconds % 3600 / 60));
+    return s;
+}
+
+std::vector<std::string> GpxSummary::lines() const {
+    std::vector<std::string> out;
+    out.push_back(std::to_string(points_) + (points_ == 1 ? " point" : " points"));
+    if (first_ > 0) {
+        out.push_back("Started " + formatStamp(static_cast<uint32_t>(first_)));
+        out.push_back("Lasted " + formatDuration(last_ - first_));
+    }
+    char s[32];
+    if (meters_ < 1000) std::snprintf(s, sizeof s, "Distance %.0f m", meters_);
+    else std::snprintf(s, sizeof s, "Distance %.2f km", meters_ / 1000);
+    out.push_back(s);
+    return out;
+}
+
+namespace {
+uint32_t le32(const uint8_t* p) { return p[0] | p[1] << 8 | p[2] << 16 | static_cast<uint32_t>(p[3]) << 24; }
+}  // namespace
+
+PcapHeader parsePcapHeader(const uint8_t* data, size_t len) {
+    PcapHeader h;
+    if (len < kPcapHeaderSize || le32(data) != 0xA1B2C3D4) return h;  // little-endian, microseconds: what we write
+    h.ok = true;
+    h.linkType = le32(data + 20);
+    return h;
+}
+
+bool parsePcapRecord(const uint8_t* data, size_t len, PcapRecord& out) {
+    if (len < kPcapRecordSize) return false;
+    out.seconds = le32(data);
+    out.micros = le32(data + 4);
+    out.length = le32(data + 8);
+    return out.length <= 65535;
+}
+
+bool parseLoraTap(const uint8_t* d, size_t len, lora::RxInfo& out) {
+    if (len < lora::kLoraTapSize || d[0] != 0) return false;
+    out.frequencyHz = static_cast<uint32_t>(d[4]) << 24 | d[5] << 16 | d[6] << 8 | d[7];
+    out.bandwidthKHz = d[8] * 125.0f;
+    out.spreadingFactor = d[9];
+    out.rssi = d[10] - 139.0f;
+    out.noiseFloor = d[12] - 139.0f;
+    out.snr = static_cast<int8_t>(d[13]) / 4.0f;
+    out.syncWord = d[14];
+    return true;
+}
+
+}  // namespace roro::files

lib/files/src/file_views.h

@@ -0,0 +1,57 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "loratap.h"
+
+namespace roro::files {
+
+// What the Storage App's viewers show of the files the firmware writes (F1, Q134).
+
+// One row of a hex dump, eight bytes: "00010 4865 6c6c 6f2c 2077  Hello, w".
+std::string hexRow(uint32_t offset, const uint8_t* data, size_t len);
+
+// A Track (.gpx) read a piece at a time: its points, when it started and ended, how far it went.
+class GpxSummary {
+   public:
+    void feed(const char* data, size_t len);
+
+    uint32_t points() const { return points_; }
+    int64_t start() const { return first_; }  // UTC seconds, 0 if no point carried a time
+    int64_t end() const { return last_; }
+    double meters() const { return meters_; }
+    std::vector<std::string> lines() const;  // for the screen
+
+   private:
+    void point(const std::string& element);
+
+    std::string carry_;  // the part of a point cut by the end of a piece
+    uint32_t points_ = 0;
+    int64_t first_ = 0, last_ = 0;
+    double meters_ = 0, lat_ = 0, lon_ = 0;
+};
+
+// "1 h 02 min", "4 min 10 s", "12 s".
+std::string formatDuration(int64_t seconds);
+
+// A Capture (.pcap): the file's header, then one record after another.
+struct PcapHeader {
+    bool ok = false;
+    uint32_t linkType = 0;  // 270: LoRaTap, what the LoRa Scanner writes
+};
+constexpr size_t kPcapHeaderSize = 24, kPcapRecordSize = 16;
+constexpr uint32_t kLinkLoraTap = 270;
+PcapHeader parsePcapHeader(const uint8_t* data, size_t len);
+
+struct PcapRecord {
+    uint32_t seconds = 0, micros = 0, length = 0;  // length: the bytes that follow in the file
+};
+bool parsePcapRecord(const uint8_t* data, size_t len, PcapRecord& out);  // false: not a record, stop there
+
+// The LoRaTap header a packet starts with; false if `len` is too short for one.
+bool parseLoraTap(const uint8_t* data, size_t len, lora::RxInfo& out);
+
+}  // namespace roro::files

lib/files/src/text_pager.cpp

@@ -0,0 +1,121 @@
+#include "text_pager.h"
+
+#include <algorithm>
+
+namespace roro::files {
+
+TextPager::TextPager(ReadAt read, uint32_t size, int cols, int rows)
+    : read_(std::move(read)), size_(size), cols_(std::max(1, cols)), rows_(std::max(1, rows)) {}
+
+const uint8_t* TextPager::bytes(uint32_t at, size_t& len) {
+    len = 0;
+    if (at >= size_) return nullptr;
+    bool cached = at >= cacheAt_ && at < cacheAt_ + cache_.size();
+    // Wanted: a line's worth ahead, unless the cache already reaches the end of the file.
+    size_t ahead = cached ? cacheAt_ + cache_.size() - at : 0;
+    if (!cached || (ahead < kBlock / 4 && cacheAt_ + cache_.size() < size_)) {
+        cacheAt_ = at - std::min<uint32_t>(at, kBlock / 2);  // room behind too: scrolling back is common
+        cache_.resize(std::min<uint32_t>(kBlock, size_ - cacheAt_));
+        cache_.resize(read_(cacheAt_, cache_.data(), cache_.size()));
+        if (at >= cacheAt_ + cache_.size()) return nullptr;  // the file got shorter, or the card failed
+    }
+    len = cacheAt_ + cache_.size() - at;
+    return cache_.data() + (at - cacheAt_);
+}
+
+int TextPager::byteAt(uint32_t at) {
+    size_t len;
+    const uint8_t* p = bytes(at, len);
+    return p ? *p : -1;
+}
+
+uint32_t TextPager::nextLine(uint32_t at, std::string* text) {
+    size_t len;
+    const uint8_t* p = bytes(at, len);
+    if (text) text->clear();
+    if (!p) return size_;
+    size_t end = len, next = len;  // the line is [0, end); the one after starts at `next`
+    int count = 0;
+    size_t lastSpace = 0;
+    for (size_t i = 0; i < len; i++) {
+        uint8_t b = p[i];
+        if (b == '\n') {
+            end = i;
+            next = i + 1;
+            break;
+        }
+        if ((b & 0xC0) == 0x80) continue;  // inside a UTF-8 character
+        if (count == cols_) {              // one character too many: wrap
+            if (b == ' ') end = i, next = i + 1;
+            else if (lastSpace > 0) end = lastSpace, next = lastSpace + 1;
+            else end = next = i;
+            break;
+        }
+        count++;
+        if (b == ' ') lastSpace = i;
+    }
+    if (text) {
+        size_t n = end > 0 && p[end - 1] == '\r' ? end - 1 : end;
+        text->reserve(n);
+        for (size_t i = 0; i < n; i++) text->push_back(p[i] == '\t' ? ' ' : (p[i] < 0x20 || p[i] == 0x7F) ? '.' : static_cast<char>(p[i]));
+    }
+    return at + static_cast<uint32_t>(std::max<size_t>(next, 1));
+}
+
+uint32_t TextPager::lineBefore(uint32_t at) {
+    if (at == 0) return 0;
+    at = std::min(at, size_);
+    // The paragraph the line before `at` belongs to starts after the newline before it. The byte
+    // just before `at` may be that line's own newline.
+    uint32_t from = at - 1;
+    if (from > 0 && byteAt(from) == '\n') from--;
+    uint32_t limit = at > kLookBack ? at - kLookBack : 0, start = limit;
+    for (uint32_t i = from + 1; i-- > limit;) {
+        if (byteAt(i) == '\n' && i < at - 1) {
+            start = i + 1;
+            break;
+        }
+    }
+    // No newline that near: any character boundary will do as a place to wrap from.
+    while (start > 0 && start < at && (byteAt(start) & 0xC0) == 0x80) start++;
+    for (uint32_t a = start;;) {
+        uint32_t next = nextLine(a, nullptr);
+        if (next >= at) return a;
+        a = next;
+    }
+}
+
+bool TextPager::atEnd() {
+    uint32_t a = top_;
+    for (int i = 0; i < rows_; i++) {
+        a = nextLine(a, nullptr);
+        if (a >= size_) return true;
+    }
+    return false;
+}
+
+void TextPager::down(int n) {
+    for (; n > 0 && !atEnd(); n--) top_ = nextLine(top_, nullptr);
+}
+
+void TextPager::up(int n) {
+    for (; n > 0 && top_ > 0; n--) top_ = lineBefore(top_);
+}
+
+void TextPager::toEnd() {
+    top_ = size_;
+    up(rows_);
+}
+
+std::vector<std::string> TextPager::lines() {
+    std::vector<std::string> out;
+    uint32_t a = top_;
+    for (int i = 0; i < rows_ && a < size_; i++) {
+        std::string text;
+        a = nextLine(a, &text);
+        out.push_back(std::move(text));
+    }
+    return out;
+}
+
+}  // namespace roro::files

lib/files/src/text_pager.h

@@ -0,0 +1,50 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <string>
+#include <vector>
+
+namespace roro::files {
+
+// A text file of any size, shown a screen at a time (F1, Q134): only the part on screen is read,
+// through `read`, about a kilobyte at once. Lines wrap at spaces, `cols` characters wide. Going
+// back a line means finding where the paragraph before started and wrapping it again, so a file
+// reads the same whichever way it was scrolled.
+class TextPager {
+   public:
+    // Reads up to `len` bytes at `offset`; returns how many it got.
+    using ReadAt = std::function<size_t(uint32_t offset, uint8_t* into, size_t len)>;
+
+    TextPager(ReadAt read, uint32_t size, int cols, int rows);
+
+    void toStart() { top_ = 0; }
+    void toEnd();  // the last line at the bottom of the screen
+    void down(int lines = 1);
+    void up(int lines = 1);
+
+    std::vector<std::string> lines();  // what's on screen: tabs as spaces, control characters as dots
+    uint32_t top() const { return top_; }
+    uint32_t size() const { return size_; }
+    bool atEnd();  // the file's last line is on screen
+    int percent() const { return size_ ? static_cast<int>(static_cast<uint64_t>(top_) * 100 / size_) : 0; }
+
+   private:
+    static constexpr size_t kBlock = 1024;       // read at once
+    static constexpr uint32_t kLookBack = 1024;  // how far back a paragraph's start is looked for
+
+    const uint8_t* bytes(uint32_t at, size_t& len);  // what's cached from `at` on
+    int byteAt(uint32_t at);                         // -1 past the end
+    uint32_t nextLine(uint32_t at, std::string* text);  // where the line after the one at `at` starts
+    uint32_t lineBefore(uint32_t at);
+
+    ReadAt read_;
+    uint32_t size_;
+    int cols_, rows_;
+    uint32_t top_ = 0;
+    std::vector<uint8_t> cache_;
+    uint32_t cacheAt_ = 0;
+};
+
+}  // namespace roro::files

lib/notes/src/note_text.cpp

@@ -0,0 +1,329 @@
+#include "note_text.h"
+
+#include <algorithm>
+
+namespace roro::notes {
+
+namespace {
+bool continuation(char c) { return (static_cast<uint8_t>(c) & 0xC0) == 0x80; }
+}  // namespace
+
+NoteText::NoteText(int cols, int rows) : cols_(std::max(1, cols)), rows_(std::max(1, rows)) { text_.reserve(kMaxBytes); }
+
+NoteText::NoteText(int cols, int rows, std::string&& text) : cols_(std::max(1, cols)), rows_(std::max(1, rows)), text_(std::move(text)) {
+    dropCarriageReturns();
+    if (text_.size() > kMaxBytes) text_.resize(kMaxBytes);  // the caller checks sizes: not reached
+    text_.reserve(kMaxBytes);
+}
+
+void NoteText::dropCarriageReturns() {
+    size_t kept = 0;
+    for (size_t i = 0; i < text_.size(); i++)
+        if (!(text_[i] == '\r' && i + 1 < text_.size() && text_[i + 1] == '\n')) text_[kept++] = text_[i];
+    text_.resize(kept);
+}
+
+bool NoteText::setText(const std::string& text) {
+    size_t kept = text.size();
+    for (size_t i = 0; i + 1 < text.size(); i++)
+        if (text[i] == '\r' && text[i + 1] == '\n') kept--;
+    if (kept > kMaxBytes) return false;
+    text_.assign(text);
+    dropCarriageReturns();
+    cursor_ = top_ = 0;
+    goal_ = -1;
+    revision_++;
+    return true;
+}
+
+size_t NoteText::nextLine(size_t start) const {
+    size_t size = text_.size();
+    int count = 0;
+    size_t lastSpace = 0;
+    bool space = false;
+    for (size_t i = start; i < size; i++) {
+        char c = text_[i];
+        if (c == '\n') return i + 1;
+        if (continuation(c)) continue;
+        if (count == cols_) {  // one character too many: wrap
+            if (c == ' ') return i + 1;       // the space stays at the end of this line
+            if (space) return lastSpace + 1;  // after the last space that fits
+            return i;                         // a word longer than the screen is cut
+        }
+        count++;
+        if (c == ' ') {
+            lastSpace = i;
+            space = true;
+        }
+    }
+    return size;
+}
+
+size_t NoteText::lineOf(size_t pos) const {
+    size_t size = text_.size();
+    pos = std::min(pos, size);
+    size_t a = pos;  // the start of the paragraph: after the newline before `pos`
+    while (a > 0 && text_[a - 1] != '\n') a--;
+    while (a < size) {
+        size_t n = nextLine(a);
+        if (n > pos) return a;
+        // The end of the text is on the last line, unless that line ended with a newline: then
+        // it's on an empty line of its own.
+        if (n == size && pos == size && text_[size - 1] != '\n') return a;
+        a = n;
+    }
+    return a;
+}
+
+bool NoteText::hasLineAfter(size_t start) const {
+    size_t n = nextLine(start), size = text_.size();
+    if (n < size) return true;
+    return start < size && lineOf(size) != start;  // the empty line after a final newline
+}
+
+size_t NoteText::lastSpot(size_t start) const {
+    size_t n = nextLine(start), size = text_.size();
+    if (n == start) return start;  // the empty line at the end
+    if (n == size && lineOf(size) == start) return size;
+    size_t p = n - 1;  // before the newline, the space or the last character the line ends with
+    while (p > start && continuation(text_[p])) p--;
+    return p;
+}
+
+int NoteText::columnOf(size_t start, size_t pos) const {
+    int col = 0;
+    for (size_t i = start; i < pos && i < text_.size(); i++)
+        if (!continuation(text_[i])) col++;
+    return col;
+}
+
+size_t NoteText::atColumn(size_t start, int col) const {
+    size_t last = lastSpot(start), p = start;
+    while (p < last && col > 0) {
+        p++;
+        while (p < last && continuation(text_[p])) p++;
+        col--;
+    }
+    return p;
+}
+
+void NoteText::moved(bool keepGoal) {
+    if (!keepGoal) goal_ = -1;
+}
+
+bool NoteText::insertText(const std::string& s) {
+    if (text_.size() + s.size() > kMaxBytes) return false;
+    text_.insert(cursor_, s);
+    cursor_ += s.size();
+    revision_++;
+    moved();
+    return true;
+}
+
+bool NoteText::insert(uint32_t cp) {
+    std::string s;
+    if (cp < 0x80) s += static_cast<char>(cp);
+    else if (cp < 0x800) {
+        s += static_cast<char>(0xC0 | (cp >> 6));
+        s += static_cast<char>(0x80 | (cp & 0x3F));
+    } else if (cp < 0x10000) {
+        s += static_cast<char>(0xE0 | (cp >> 12));
+        s += static_cast<char>(0x80 | ((cp >> 6) & 0x3F));
+        s += static_cast<char>(0x80 | (cp & 0x3F));
+    } else {
+        s += static_cast<char>(0xF0 | (cp >> 18));
+        s += static_cast<char>(0x80 | ((cp >> 12) & 0x3F));
+        s += static_cast<char>(0x80 | ((cp >> 6) & 0x3F));
+        s += static_cast<char>(0x80 | (cp & 0x3F));
+    }
+    return insertText(s);
+}
+
+void NoteText::backspace() {
+    if (cursor_ == 0) return;
+    size_t from = cursor_ - 1;
+    while (from > 0 && continuation(text_[from])) from--;
+    text_.erase(from, cursor_ - from);
+    cursor_ = from;
+    revision_++;
+    moved();
+}
+
+void NoteText::left() {
+    if (cursor_ == 0) return;
+    cursor_--;
+    while (cursor_ > 0 && continuation(text_[cursor_])) cursor_--;
+    moved();
+}
+
+void NoteText::right() {
+    if (cursor_ >= text_.size()) return;
+    cursor_++;
+    while (cursor_ < text_.size() && continuation(text_[cursor_])) cursor_++;
+    moved();
+}
+
+void NoteText::up() {
+    size_t line = lineOf(cursor_);
+    if (goal_ < 0) goal_ = columnOf(line, cursor_);
+    if (line == 0) return;
+    cursor_ = atColumn(lineOf(line - 1), goal_);
+    moved(true);
+}
+
+void NoteText::down() {
+    size_t line = lineOf(cursor_);
+    if (goal_ < 0) goal_ = columnOf(line, cursor_);
+    if (!hasLineAfter(line)) return;
+    size_t next = nextLine(line);
+    cursor_ = next >= text_.size() ? text_.size() : atColumn(next, goal_);
+    moved(true);
+}
+
+void NoteText::pageUp() {
+    for (int i = 1; i < rows_; i++) up();
+}
+
+void NoteText::pageDown() {
+    for (int i = 1; i < rows_; i++) down();
+}
+
+void NoteText::lineStart() {
+    cursor_ = lineOf(cursor_);
+    moved();
+}
+
+void NoteText::lineEnd() {
+    cursor_ = lastSpot(lineOf(cursor_));
+    moved();
+}
+
+void NoteText::toStart() {
+    cursor_ = 0;
+    moved();
+}
+
+void NoteText::toEnd() {
+    cursor_ = text_.size();
+    moved();
+}
+
+void NoteText::follow() {
+    size_t line = lineOf(cursor_);
+    top_ = lineOf(std::min(top_, text_.size()));  // an edit above may have moved where lines start
+    if (line < top_) {
+        top_ = line;
+        return;
+    }
+    size_t a = top_;
+    for (int i = 0; i < rows_; i++) {
+        if (a == line) return;  // on screen
+        if (!hasLineAfter(a)) return;
+        a = nextLine(a);
+    }
+    // Below the screen: the cursor's line becomes the last row.
+    top_ = line;
+    for (int i = 1; i < rows_ && top_ > 0; i++) top_ = lineOf(top_ - 1);
+}
+
+std::vector<std::string> NoteText::rows() {
+    follow();
+    std::vector<std::string> out;
+    size_t a = top_, size = text_.size();
+    for (int i = 0; i < rows_; i++) {
+        size_t n = nextLine(a);
+        std::string row = text_.substr(a, n - a);
+        if (!row.empty() && row.back() == '\n') row.pop_back();
+        for (char& c : row)
+            if (c == '\t') c = ' ';
+        out.push_back(std::move(row));
+        if (!hasLineAfter(a)) break;
+        a = n >= size ? size : n;
+    }
+    return out;
+}
+
+int NoteText::cursorRow() {
+    follow();
+    size_t line = lineOf(cursor_), a = top_;
+    for (int i = 0; i < rows_; i++) {
+        if (a == line) return i;
+        a = nextLine(a);
+    }
+    return rows_ - 1;
+}
+
+int NoteText::cursorCol() { return columnOf(lineOf(cursor_), cursor_); }
+
+// At most a screen's worth of it: a note that is one line of 16 KB must not be copied whole.
+std::string NoteText::firstLine() const { return text_.substr(0, std::min<size_t>(text_.find('\n'), 160)); }
+
+namespace {
+// U+00C0 to U+00FF as the plain letters a file name gets; 0: left out.
+const char kPlain[64] = {
+    'a', 'a', 'a', 'a', 'a', 'a', 0,   'c', 'e', 'e', 'e', 'e', 'i', 'i', 'i', 'i',   // À..Ï
+    0,   'n', 'o', 'o', 'o', 'o', 'o', 0,   'o', 'u', 'u', 'u', 'u', 'y', 0,   's',   // Ð..ß
+    'a', 'a', 'a', 'a', 'a', 'a', 0,   'c', 'e', 'e', 'e', 'e', 'i', 'i', 'i', 'i',   // à..ï
+    0,   'n', 'o', 'o', 'o', 'o', 'o', 0,   'o', 'u', 'u', 'u', 'u', 'y', 0,   'y'};  // ð..ÿ
+
+// Drops a character the end of the string cuts in two.
+void dropPartial(std::string& s) {
+    size_t k = s.size();
+    while (k > 0 && continuation(s[k - 1]) && s.size() - k < 3) k--;
+    if (k == 0) return;
+    uint8_t lead = static_cast<uint8_t>(s[k - 1]);
+    size_t want = lead >= 0xF0 ? 4 : lead >= 0xE0 ? 3 : lead >= 0xC0 ? 2 : 1;
+    if (s.size() - (k - 1) < want) s.resize(k - 1);
+}
+}  // namespace
+
+std::string nameFromFirstLine(const std::string& firstLine, const std::string& stamp) {
+    std::string out;
+    bool dash = false;
+    for (size_t i = 0; i < firstLine.size() && out.size() < 32; i++) {
+        uint8_t c = static_cast<uint8_t>(firstLine[i]);
+        char letter = 0;
+        if (c < 0x80) {
+            if (c >= 'A' && c <= 'Z') letter = static_cast<char>(c + 32);
+            else if ((c >= 'a' && c <= 'z') || (c >= '0' && c <= '9')) letter = static_cast<char>(c);
+        } else if (c == 0xC3 && i + 1 < firstLine.size()) {  // U+00C0..U+00FF
+            letter = kPlain[static_cast<uint8_t>(firstLine[++i]) & 0x3F];
+        } else {
+            while (i + 1 < firstLine.size() && continuation(firstLine[i + 1])) i++;  // anything else is left out
+        }
+        if (letter) {
+            if (dash && !out.empty()) out += '-';
+            dash = false;
+            out += letter;
+        } else {
+            dash = true;
+        }
+    }
+    return out.empty() ? "note-" + stamp : out;
+}
+
+std::string titleFrom(const std::string& head, size_t maxChars) {
+    for (size_t at = 0; at < head.size();) {
+        size_t end = head.find('\n', at);
+        bool cut = end == std::string::npos;  // the line goes on past what was read
+        if (cut) end = head.size();
+        std::string line = head.substr(at, end - at);
+        if (cut) dropPartial(line);
+        while (!line.empty() && (line.back() == '\r' || line.back() == ' ' || line.back() == '\t')) line.pop_back();
+        size_t first = line.find_first_not_of(" \t");
+        if (first != std::string::npos) {
+            line.erase(0, first);
+            size_t bytes = 0;
+            for (size_t chars = 0; bytes < line.size() && chars < maxChars; chars++) {
+                bytes++;
+                while (bytes < line.size() && continuation(line[bytes])) bytes++;
+            }
+            line.resize(bytes);
+            return line;
+        }
+        at = end + 1;
+    }
+    return "";
+}
+
+}  // namespace roro::notes

lib/notes/src/note_text.h

@@ -0,0 +1,81 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace roro::notes {
+
+// The text of a note while it's edited (F1, Q144, Q145): UTF-8 held whole in memory, a cursor, and
+// the part of it on screen. Lines wrap at spaces, `cols` characters wide; a line owns the space or
+// the newline it ends with, so every byte of the text belongs to exactly one line. No index of
+// lines is kept (a note of newlines alone would need twice its size): where a line starts is
+// worked out from the start of its paragraph, which is never far.
+class NoteText {
+   public:
+    static constexpr size_t kMaxBytes = 16 * 1024;
+
+    // Room for a full note is reserved once, so typing never has to find a bigger block of memory:
+    // on the device a failed allocation is the end. The second form takes over a string the
+    // caller filled (and reserved): a note is never in memory twice.
+    NoteText(int cols, int rows);
+    NoteText(int cols, int rows, std::string&& text);
+
+    // Copied into the buffer already held. CRLF becomes LF (Q148). False, and nothing changes, if
+    // it's over kMaxBytes.
+    bool setText(const std::string& text);
+    const std::string& text() const { return text_; }
+    size_t cursor() const { return cursor_; }
+    uint32_t revision() const { return revision_; }  // changes with every edit: is it saved?
+
+    bool insert(uint32_t codePoint);         // false: the note is full
+    bool insertText(const std::string& s);   // all of it or nothing
+    void backspace();
+    void left();
+    void right();
+    void up();
+    void down();
+    void pageUp();
+    void pageDown();
+    void lineStart();
+    void lineEnd();
+    void toStart();
+    void toEnd();
+
+    // The screen, kept around the cursor: its rows (tabs as spaces, the ending newline left out),
+    // and where the cursor is on it, in rows and characters.
+    std::vector<std::string> rows();
+    int cursorRow();
+    int cursorCol();
+    int percent() const { return text_.empty() ? 0 : static_cast<int>(top_ * 100 / text_.size()); }
+
+    std::string firstLine() const;  // without its newline, for the title and the file's name
+
+   private:
+    size_t nextLine(size_t start) const;       // where the line after the one at `start` starts
+    size_t lineOf(size_t pos) const;           // the start of the line `pos` is on
+    size_t lastSpot(size_t start) const;       // the last place the cursor can be on that line
+    size_t atColumn(size_t start, int col) const;
+    int columnOf(size_t start, size_t pos) const;
+    bool hasLineAfter(size_t start) const;
+    void moved(bool keepGoal = false);
+    void follow();  // scrolls so the cursor is on screen
+    void dropCarriageReturns();
+
+    int cols_, rows_;
+    std::string text_;
+    size_t cursor_ = 0, top_ = 0;
+    int goal_ = -1;  // the column Up and Down aim for, across short lines
+    uint32_t revision_ = 0;
+};
+
+// The file a new note is saved as (Q142): from its first line, "Shopping list!" -> "shopping-list",
+// or "note-<stamp>" when that gives nothing. No extension, no folder.
+std::string nameFromFirstLine(const std::string& firstLine, const std::string& stamp);
+
+// A row's title in the Notes list, from the first bytes of a file: its first line that isn't
+// blank, cut to `maxChars`; "" if there's none.
+std::string titleFrom(const std::string& head, size_t maxChars);
+
+}  // namespace roro::notes

lib/release/src/http_head.cpp

@@ -0,0 +1,158 @@
+#include "http_head.h"
+
+#include <algorithm>
+#include <cctype>
+#include <cstdlib>
+
+namespace roro::release {
+
+namespace {
+std::string lower(std::string s) {
+    for (char& c : s) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+    return s;
+}
+}  // namespace
+
+size_t HttpHeadParser::feed(const char* data, size_t len) {
+    size_t used = 0;
+    while (used < len && !complete_ && !failed_) {
+        char c = data[used++];
+        total_++;
+        if (total_ > kMaxBytes) {
+            failed_ = true;
+            break;
+        }
+        if (c == '\n') {
+            if (!line_.empty() && line_.back() == '\r') line_.pop_back();
+            line();
+            line_.clear();
+        } else {
+            line_ += c;
+        }
+    }
+    return used;
+}
+
+void HttpHeadParser::line() {
+    if (first_) {  // "HTTP/1.1 200 OK"
+        first_ = false;
+        if (line_.compare(0, 5, "HTTP/") != 0) {
+            failed_ = true;
+            return;
+        }
+        size_t space = line_.find(' ');
+        head_.status = space == std::string::npos ? 0 : std::atoi(line_.c_str() + space + 1);
+        if (head_.status < 100 || head_.status > 599) failed_ = true;
+        return;
+    }
+    if (line_.empty()) {
+        complete_ = true;
+        return;
+    }
+    size_t colon = line_.find(':');
+    if (colon == std::string::npos) return;  // not a header: ignored
+    std::string name = lower(line_.substr(0, colon));
+    size_t from = line_.find_first_not_of(" \t", colon + 1);
+    std::string value = from == std::string::npos ? "" : line_.substr(from);
+    if (name == "content-length") head_.contentLength = std::atol(value.c_str());
+    else if (name == "transfer-encoding") head_.chunked = lower(value).find("chunked") != std::string::npos;
+    else if (name == "location") head_.location = value;
+    else if (name == "content-type") head_.contentType = value;
+}
+
+size_t ChunkedDecoder::decode(const uint8_t* in, size_t len, uint8_t* out) {
+    size_t written = 0;
+    for (size_t i = 0; i < len && !failed_ && state_ != State::Done; i++) {
+        uint8_t c = in[i];
+        switch (state_) {
+            case State::Size: {
+                int digit = c >= '0' && c <= '9' ? c - '0' : c >= 'a' && c <= 'f' ? c - 'a' + 10 : c >= 'A' && c <= 'F' ? c - 'A' + 10 : -1;
+                if (digit >= 0) {
+                    if (remaining_ > (SIZE_MAX >> 5)) failed_ = true;
+                    remaining_ = remaining_ * 16 + digit;
+                    anyDigit_ = true;
+                } else if (c == ';' && anyDigit_) {
+                    state_ = State::Extension;
+                } else if (c == '\r' && anyDigit_) {
+                    state_ = State::SizeLf;
+                } else {
+                    failed_ = true;
+                }
+                break;
+            }
+            case State::Extension:
+                if (c == '\r') state_ = State::SizeLf;
+                break;
+            case State::SizeLf:
+                if (c != '\n') {
+                    failed_ = true;
+                } else if (remaining_ == 0) {
+                    state_ = State::Trailer;
+                    trailerLine_ = 0;
+                } else {
+                    state_ = State::Data;
+                }
+                break;
+            case State::Data: {
+                size_t take = std::min(remaining_, len - i);
+                for (size_t k = 0; k < take; k++) out[written + k] = in[i + k];
+                written += take;
+                remaining_ -= take;
+                i += take - 1;
+                if (remaining_ == 0) state_ = State::DataCr;
+                break;
+            }
+            case State::DataCr:
+                if (c != '\r') failed_ = true;
+                else state_ = State::DataLf;
+                break;
+            case State::DataLf:
+                if (c != '\n') {
+                    failed_ = true;
+                } else {
+                    state_ = State::Size;
+                    anyDigit_ = false;
+                }
+                break;
+            case State::Trailer:  // header lines after the last chunk, until an empty one
+                if (c == '\n') {
+                    if (trailerLine_ == 0) state_ = State::Done;
+                    trailerLine_ = 0;
+                } else if (c != '\r') {
+                    trailerLine_++;
+                }
+                break;
+            case State::Done: break;
+        }
+    }
+    return written;
+}
+
+Url parseUrl(const std::string& url) {
+    Url u;
+    size_t scheme = url.find("://");
+    if (scheme == std::string::npos) return u;
+    std::string s = lower(url.substr(0, scheme));
+    if (s != "http" && s != "https") return u;
+    u.https = s == "https";
+    size_t hostStart = scheme + 3, pathStart = url.find('/', hostStart);
+    std::string authority = url.substr(hostStart, pathStart == std::string::npos ? std::string::npos : pathStart - hostStart);
+    u.path = pathStart == std::string::npos ? "/" : url.substr(pathStart);
+    if (authority.empty() || authority.find('@') != std::string::npos) return u;  // no credentials in a URL
+    size_t colon = authority.rfind(':');
+    u.port = u.https ? 443 : 80;
+    if (colon != std::string::npos) {
+        u.port = std::atoi(authority.c_str() + colon + 1);
+        authority.resize(colon);
+        if (u.port <= 0 || u.port > 65535) return u;
+    }
+    for (unsigned char c : authority)
+        if (!(std::isalnum(c) || c == '.' || c == '-')) return u;
+    for (unsigned char c : u.path)
+        if (c <= ' ' || c == 0x7F) return u;
+    u.host = lower(authority);
+    u.ok = !u.host.empty();
+    return u;
+}
+
+}  // namespace roro::release

lib/release/src/http_head.h

@@ -0,0 +1,62 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+
+namespace roro::release {
+
+// The status line and headers of an HTTP/1.1 response, read as bytes arrive.
+struct HttpHead {
+    int status = 0;
+    long contentLength = -1;  // -1: not given
+    bool chunked = false;
+    std::string location, contentType;
+};
+
+class HttpHeadParser {
+   public:
+    static constexpr size_t kMaxBytes = 4096;
+
+    // Takes bytes up to and including the blank line that ends the head; returns how many it used.
+    // What follows is the body.
+    size_t feed(const char* data, size_t len);
+    bool complete() const { return complete_; }
+    bool failed() const { return failed_; }
+    const HttpHead& head() const { return head_; }
+
+   private:
+    void line();
+
+    HttpHead head_;
+    std::string line_;
+    size_t total_ = 0;
+    bool first_ = true, complete_ = false, failed_ = false;
+};
+
+// Takes the chunks of "Transfer-Encoding: chunked" apart as they arrive.
+class ChunkedDecoder {
+   public:
+    // `out` has room for `len` bytes (the body is never longer than what carried it).
+    size_t decode(const uint8_t* in, size_t len, uint8_t* out);
+    bool done() const { return state_ == State::Done; }
+    bool failed() const { return failed_; }
+
+   private:
+    enum class State : uint8_t { Size, Extension, SizeLf, Data, DataCr, DataLf, Trailer, Done };
+    State state_ = State::Size;
+    size_t remaining_ = 0;
+    bool anyDigit_ = false, failed_ = false;
+    size_t trailerLine_ = 0;
+};
+
+// "https://git.twis.la/twisla/x/releases/download/v1/a.ota" taken apart. Only http and https.
+struct Url {
+    bool ok = false;
+    bool https = false;
+    std::string host, path;  // path from the first "/", with its query; "/" if none
+    int port = 0;
+};
+Url parseUrl(const std::string& url);
+
+}  // namespace roro::release

lib/release/src/json_scan.cpp

@@ -0,0 +1,202 @@
+#include "json_scan.h"
+
+namespace roro::release {
+
+namespace {
+bool space(char c) { return c == ' ' || c == '\t' || c == '\r' || c == '\n'; }
+bool continuation(char c) { return (static_cast<uint8_t>(c) & 0xC0) == 0x80; }
+}  // namespace
+
+void JsonScanner::feed(const char* data, size_t len) {
+    for (size_t i = 0; i < len && !failed_; i++) step(data[i]);
+}
+
+std::string JsonScanner::path() const {
+    std::string p;
+    for (const Frame& f : stack_) {
+        if (f.isObject) {
+            if (!p.empty()) p += '.';
+            p += f.key;
+        } else {
+            p += '[' + std::to_string(f.index) + ']';
+        }
+    }
+    return p;
+}
+
+void JsonScanner::append(const char* bytes, size_t n) {
+    if (text_.size() + n > max_) {
+        truncated_ = true;
+        return;
+    }
+    text_.append(bytes, n);
+}
+
+void JsonScanner::appendCodePoint(uint32_t cp) {
+    char b[4];
+    size_t n;
+    if (cp < 0x80) {
+        b[0] = static_cast<char>(cp);
+        n = 1;
+    } else if (cp < 0x800) {
+        b[0] = static_cast<char>(0xC0 | (cp >> 6));
+        b[1] = static_cast<char>(0x80 | (cp & 0x3F));
+        n = 2;
+    } else if (cp < 0x10000) {
+        b[0] = static_cast<char>(0xE0 | (cp >> 12));
+        b[1] = static_cast<char>(0x80 | ((cp >> 6) & 0x3F));
+        b[2] = static_cast<char>(0x80 | (cp & 0x3F));
+        n = 3;
+    } else {
+        b[0] = static_cast<char>(0xF0 | (cp >> 18));
+        b[1] = static_cast<char>(0x80 | ((cp >> 12) & 0x3F));
+        b[2] = static_cast<char>(0x80 | ((cp >> 6) & 0x3F));
+        b[3] = static_cast<char>(0x80 | (cp & 0x3F));
+        n = 4;
+    }
+    append(b, n);
+}
+
+void JsonScanner::startString(bool key) {
+    inString_ = true;
+    isKey_ = key;
+    escape_ = false;
+    unicodeLeft_ = 0;
+    highSurrogate_ = 0;
+    truncated_ = false;
+    text_.clear();
+}
+
+void JsonScanner::stringChar(char c) {
+    if (unicodeLeft_ > 0) {
+        int digit = c >= '0' && c <= '9' ? c - '0' : c >= 'a' && c <= 'f' ? c - 'a' + 10 : c >= 'A' && c <= 'F' ? c - 'A' + 10 : -1;
+        if (digit < 0) return fail();
+        unicode_ = unicode_ * 16 + digit;
+        if (--unicodeLeft_ == 0) {
+            if (unicode_ >= 0xD800 && unicode_ < 0xDC00) {
+                highSurrogate_ = unicode_;  // the low half comes next
+            } else if (unicode_ >= 0xDC00 && unicode_ < 0xE000 && highSurrogate_) {
+                appendCodePoint(0x10000 + ((highSurrogate_ - 0xD800) << 10) + (unicode_ - 0xDC00));
+                highSurrogate_ = 0;
+            } else {
+                appendCodePoint(unicode_);
+                highSurrogate_ = 0;
+            }
+        }
+        return;
+    }
+    if (escape_) {
+        escape_ = false;
+        switch (c) {
+            case 'n': append("\n", 1); break;
+            case 't': append("\t", 1); break;
+            case 'r': append("\r", 1); break;
+            case 'b': append("\b", 1); break;
+            case 'f': append("\f", 1); break;
+            case 'u': unicodeLeft_ = 4; unicode_ = 0; break;
+            default: append(&c, 1); break;  // \" \\ \/
+        }
+        return;
+    }
+    if (c == '\\') {
+        escape_ = true;
+    } else if (c == '"') {
+        endString();
+    } else {
+        append(&c, 1);
+    }
+}
+
+void JsonScanner::endString() {
+    inString_ = false;
+    // A cut can leave half a character at the end.
+    while (truncated_ && !text_.empty()) {
+        size_t k = text_.size();
+        while (k > 0 && continuation(text_[k - 1])) k--;
+        if (k == 0) break;
+        uint8_t lead = static_cast<uint8_t>(text_[k - 1]);
+        size_t want = lead >= 0xF0 ? 4 : lead >= 0xE0 ? 3 : lead >= 0xC0 ? 2 : 1;
+        if (text_.size() - (k - 1) < want) text_.resize(k - 1);
+        break;
+    }
+    if (isKey_) {
+        stack_.back().key = text_;
+        expect_ = Expect::Colon;
+        return;
+    }
+    sink_(path(), text_, true, truncated_);
+    valueDone();
+}
+
+void JsonScanner::endLiteral() {
+    inLiteral_ = false;
+    sink_(path(), text_, false, false);
+    valueDone();
+}
+
+void JsonScanner::valueDone() {
+    if (stack_.empty()) {
+        done_ = true;
+        return;
+    }
+    expect_ = Expect::CommaOrEnd;
+}
+
+void JsonScanner::step(char c) {
+    if (inString_) return stringChar(c);
+    if (inLiteral_) {
+        if (space(c) || c == ',' || c == '}' || c == ']') {
+            endLiteral();  // and the character that ended it is read again below
+        } else {
+            if (text_.size() < max_) text_ += c;
+            return;
+        }
+    }
+    if (space(c)) return;
+    switch (expect_) {
+        case Expect::Value:
+            if (c == '{') {
+                stack_.push_back({true, "", 0});
+                expect_ = Expect::KeyOrEnd;
+            } else if (c == '[') {
+                stack_.push_back({false, "", 0});
+                expect_ = Expect::Value;
+            } else if (c == ']' && !stack_.empty() && !stack_.back().isObject && stack_.back().index == 0) {
+                stack_.pop_back();  // an empty array
+                valueDone();
+            } else if (c == '"') {
+                startString(false);
+            } else if (c == '-' || (c >= '0' && c <= '9') || c == 't' || c == 'f' || c == 'n') {
+                inLiteral_ = true;
+                text_.assign(1, c);
+            } else {
+                fail();
+            }
+            return;
+        case Expect::KeyOrEnd:
+            if (c == '"') startString(true);
+            else if (c == '}') {
+                stack_.pop_back();
+                valueDone();
+            } else fail();
+            return;
+        case Expect::Colon:
+            if (c == ':') expect_ = Expect::Value;
+            else fail();
+            return;
+        case Expect::CommaOrEnd:
+            if (c == ',') {
+                if (stack_.back().isObject) expect_ = Expect::KeyOrEnd;
+                else {
+                    stack_.back().index++;
+                    expect_ = Expect::Value;
+                }
+            } else if ((c == '}' && stack_.back().isObject) || (c == ']' && !stack_.back().isObject)) {
+                stack_.pop_back();
+                valueDone();
+            } else fail();
+            return;
+    }
+}
+
+}  // namespace roro::release

lib/release/src/json_scan.h

@@ -0,0 +1,57 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <string>
+#include <vector>
+
+namespace roro::release {
+
+// Reads JSON as it arrives, a chunk at a time, and reports each plain value (a string, a number,
+// true, false, null) with where it was found: "tag_name", "assets[1].name", "[2].draft". Nothing
+// is kept but the path, so a 33 KB list of releases costs a few hundred bytes. A value longer than
+// `maxValueBytes` is cut (never in the middle of a character) and reported as truncated.
+// Meant for a server's answer, not for validating JSON: it only refuses what it can't follow.
+class JsonScanner {
+   public:
+    using Sink = std::function<void(const std::string& path, const std::string& value, bool isString, bool truncated)>;
+
+    explicit JsonScanner(Sink sink, size_t maxValueBytes = 300) : sink_(std::move(sink)), max_(maxValueBytes) {}
+
+    void feed(const char* data, size_t len);
+    bool failed() const { return failed_; }
+    bool done() const { return done_ && !failed_; }  // the top-level value is complete
+
+   private:
+    enum class Expect : uint8_t { Value, KeyOrEnd, Colon, CommaOrEnd };
+    struct Frame {
+        bool isObject;
+        std::string key;
+        int index;
+    };
+
+    void step(char c);
+    void startString(bool key);
+    void stringChar(char c);
+    void appendCodePoint(uint32_t cp);
+    void endString();
+    void endLiteral();
+    void valueDone();
+    void append(const char* bytes, size_t n);
+    std::string path() const;
+    void fail() { failed_ = true; }
+
+    Sink sink_;
+    size_t max_;
+    std::vector<Frame> stack_;
+    Expect expect_ = Expect::Value;
+    bool inString_ = false, isKey_ = false, escape_ = false, inLiteral_ = false;
+    int unicodeLeft_ = 0;
+    uint32_t unicode_ = 0, highSurrogate_ = 0;
+    bool truncated_ = false;
+    std::string text_;
+    bool failed_ = false, done_ = false;
+};
+
+}  // namespace roro::release

lib/release/src/release_info.cpp

@@ -0,0 +1,80 @@
+#include "release_info.h"
+
+#include <cstdlib>
+
+namespace roro::release {
+
+namespace {
+bool endsWith(const std::string& s, const char* tail) {
+    size_t n = std::char_traits<char>::length(tail);
+    return s.size() >= n && s.compare(s.size() - n, n, tail) == 0;
+}
+}  // namespace
+
+std::string firstParagraph(const std::string& text, bool truncated) {
+    size_t end = text.find("\n\n");
+    size_t crlf = text.find("\r\n\r\n");
+    if (crlf != std::string::npos && (end == std::string::npos || crlf < end)) end = crlf;
+    std::string p = text.substr(0, end);
+    size_t first = p.find_first_not_of(" \t\r\n");
+    if (first == std::string::npos) return "";
+    p.erase(0, first);
+    while (!p.empty() && (p.back() == ' ' || p.back() == '\t' || p.back() == '\r' || p.back() == '\n')) p.pop_back();
+    if (truncated && end == std::string::npos) p += "...";
+    return p;
+}
+
+ReleaseReader::ReleaseReader(size_t maxReleases)
+    : scanner_([this](const std::string& path, const std::string& text, bool isString, bool truncated) {
+          value(path, text, isString, truncated);
+      }),
+      max_(maxReleases) {}
+
+void ReleaseReader::end() { flushAsset(); }
+
+void ReleaseReader::flushAsset() {
+    if (assetRelease_ >= 0 && assetRelease_ < static_cast<int>(releases_.size()) && endsWith(assetName_, ".ota") && !assetUrl_.empty()) {
+        releases_[assetRelease_].otaUrl = assetUrl_;
+        releases_[assetRelease_].otaSize = assetSize_;
+    }
+    assetRelease_ = assetIndex_ = -1;
+    assetName_.clear();
+    assetUrl_.clear();
+    assetSize_ = 0;
+}
+
+void ReleaseReader::value(const std::string& path, const std::string& text, bool isString, bool truncated) {
+    size_t index = 0;
+    std::string rest = path;
+    if (!path.empty() && path[0] == '[') {  // a list: "[2].tag_name"
+        char* end;
+        index = static_cast<size_t>(std::strtol(path.c_str() + 1, &end, 10));
+        rest = *end == ']' ? std::string(end + 1) : "";
+        if (!rest.empty() && rest[0] == '.') rest.erase(0, 1);
+    }
+    if (index >= max_) return;
+    if (releases_.size() <= index) releases_.resize(index + 1);
+    Release& r = releases_[index];
+
+    if (rest == "tag_name") r.tag = text;
+    else if (rest == "published_at") r.published = text;
+    else if (rest == "body") r.notes = firstParagraph(text, truncated);
+    else if (rest == "draft") r.draft = text == "true";
+    else if (rest == "prerelease") r.prerelease = text == "true";
+    else if (rest.compare(0, 7, "assets[") == 0) {
+        char* end;
+        int j = static_cast<int>(std::strtol(rest.c_str() + 7, &end, 10));
+        if (static_cast<int>(index) != assetRelease_ || j != assetIndex_) {
+            flushAsset();
+            assetRelease_ = static_cast<int>(index);
+            assetIndex_ = j;
+        }
+        std::string field = *end == ']' && end[1] == '.' ? std::string(end + 2) : "";
+        if (field == "name") assetName_ = text;
+        else if (field == "size") assetSize_ = static_cast<uint32_t>(std::strtoul(text.c_str(), nullptr, 10));
+        else if (field == "browser_download_url") assetUrl_ = text;
+    }
+    (void)isString;
+}
+
+}  // namespace roro::release

lib/release/src/release_info.h

@@ -0,0 +1,52 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "json_scan.h"
+
+namespace roro::release {
+
+// What the device needs to know about one Gitea release (docs/milestones/R1.md, #6).
+struct Release {
+    std::string tag;        // "v0.10.0"
+    std::string published;  // "2026-10-06T08:11:31Z"
+    std::string notes;      // the first paragraph of the text: the tag's message
+    std::string otaUrl;     // where the signed Update File is
+    uint32_t otaSize = 0;
+    bool draft = false, prerelease = false;
+
+    // Something that can be installed and that the project meant to publish (drafts and
+    // pre-releases are left out for now: a release channel is #53).
+    bool usable() const { return !draft && !prerelease && !tag.empty() && !otaUrl.empty(); }
+    std::string date() const { return published.substr(0, 10); }  // "2026-10-06"
+};
+
+// Reads Gitea's answer as it arrives: `releases/latest` (one object) or `releases?limit=N` (a list).
+class ReleaseReader {
+   public:
+    explicit ReleaseReader(size_t maxReleases = 10);
+
+    void feed(const char* data, size_t len) { scanner_.feed(data, len); }
+    void end();  // after the last chunk
+    bool ok() const { return !scanner_.failed(); }
+    bool complete() const { return scanner_.done(); }
+    const std::vector<Release>& releases() const { return releases_; }
+
+   private:
+    void value(const std::string& path, const std::string& text, bool isString, bool truncated);
+    void flushAsset();
+
+    JsonScanner scanner_;
+    size_t max_;
+    std::vector<Release> releases_;
+    int assetRelease_ = -1, assetIndex_ = -1;
+    std::string assetName_, assetUrl_;
+    uint32_t assetSize_ = 0;
+};
+
+// The first paragraph of a release's text, trimmed; "..." if the text was cut before it ended.
+std::string firstParagraph(const std::string& text, bool truncated);
+
+}  // namespace roro::release

lib/release/src/update_check.cpp

@@ -0,0 +1,15 @@
+#include "update_check.h"
+
+#include "http_head.h"
+
+namespace roro::release {
+
+bool trustedAssetUrl(const std::string& url, const std::string& host, const std::string& repo) {
+    Url u = parseUrl(url);
+    if (!u.ok || !u.https || u.port != 443 || u.host != host) return false;
+    std::string prefix = "/" + repo + "/releases/download/";
+    return u.path.compare(0, prefix.size(), prefix) == 0 && u.path.find("..") == std::string::npos &&
+           u.path.find('?') == std::string::npos && u.path.find('#') == std::string::npos;
+}
+
+}  // namespace roro::release

lib/release/src/update_check.h

@@ -0,0 +1,38 @@
+#pragma once
+
+#include <string>
+
+#include "release_info.h"
+#include "version_compare.h"
+
+namespace roro::release {
+
+// Where the project's releases are (Q164). A fork changes these, and its own signing key.
+constexpr const char* kGiteaHost = "git.twis.la";
+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);
+}
+
+// Should the background check say so (Q166, Q168)? Not for a version that failed on this device
+// before (it rolled back), and not twice for the same one.
+inline bool shouldAnnounce(const Release& latest, const std::string& running, const std::string& failed, const std::string& announced) {
+    return isNewer(latest, running) && latest.tag != failed && latest.tag != announced;
+}
+
+// Is `url` a download this device takes from the project's server, for this repository? Whatever
+// the API says, the device only fetches from where it asked (a redirected or rewritten answer
+// can't send it elsewhere).
+bool trustedAssetUrl(const std::string& url, const std::string& host = kGiteaHost, const std::string& repo = kGiteaRepo);
+
+}  // namespace roro::release

lib/services/src/power_policy.cpp

@@ -10,7 +10,10 @@ bool PowerPolicy::activity(uint32_t nowMs) {
 }
 
 ScreenState PowerPolicy::update(uint32_t nowMs) {
-    uint32_t idle = nowMs - lastActivityMs_;
+    // Activity stamped from a clock read after this pass's nowMs (the Debug Console's `key`) is in
+    // the future, not 49 days ago: unsigned, the screen went off for a tick and ate the next key.
+    int32_t since = static_cast<int32_t>(nowMs - lastActivityMs_);
+    uint32_t idle = since < 0 ? 0 : static_cast<uint32_t>(since);
     state_ = idle >= offMs_ ? ScreenState::Off : idle >= dimMs_ ? ScreenState::Dimmed : ScreenState::On;
     if (notifying_) {
         if (static_cast<int32_t>(nowMs - notifyUntilMs_) >= 0)

lib/services/src/settings.cpp

@@ -39,6 +39,8 @@ const Definition kDefinitions[] = {
     {"dns_always", Kind::Bool, 0, nullptr, 0, 1},
     {"ntp1", Kind::String, 0, "pool.ntp.org", 1, 63},
     {"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)
 };
 static_assert(sizeof(kDefinitions) / sizeof(kDefinitions[0]) == static_cast<size_t>(Setting::Count),
               "every Setting needs a definition");

lib/services/src/settings.h

@@ -29,6 +29,8 @@ enum class Setting : uint8_t {
     DnsAlways,        // bool: use them on Automatic (DHCP) networks too, instead of DHCP's
     Ntp1,             // string: the first NTP server, a host name or an IPv4 address (S1, Q110)
     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)
     Count
 };
 

lib/services/src/storage_monitor.cpp

@@ -24,7 +24,7 @@ void StorageMonitor::update(bool present, uint64_t totalBytes, uint64_t usedByte
 
     if (next.present && next.level >= 80 && !warned_) {
         warned_ = true;
-        bus_.publish(Event::withText(EventType::Notification, "SD card over 80% full",
+        bus_.publish(Event::withText(EventType::Notification, "SD card over 80% full: see Storage",
                                      static_cast<int32_t>(NotificationLevel::Warning)));
     }
 }

platformio.ini

@@ -46,3 +46,14 @@ build_flags =
 platform = native
 lib_ldf_mode = deep+
 build_flags = -std=gnu++17
+
+; The same tests, built to count which lines of lib/ they run (scripts/coverage.sh).
+[env:native-coverage]
+extends = env:native
+build_flags =
+    ${env:native.build_flags}
+    --coverage
+    -O0
+extra_scripts =
+    ${env.extra_scripts}
+    pre:scripts/coverage_link.py

scripts/_docker.sh

@@ -1,8 +1,10 @@
 # Shared helper: run a command inside the roro9stack build container.
+# With RORO_NO_DOCKER set, the caller is in such a container already (a CI job): the command runs
+# right here, in the checkout.
 IMAGE=roro9stack-build
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 
-docker build -q -t "$IMAGE" "$ROOT/docker" >/dev/null
+[ -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.
 DEBUG_TOKEN_FILE="$HOME/.config/roro9stack/debug-token"
@@ -12,6 +14,10 @@ if [ ! -s "$DEBUG_TOKEN_FILE" ]; then
 fi
 
 run_in_container() {
+    if [ -n "${RORO_NO_DOCKER:-}" ]; then
+        (cd "$ROOT" && RORO_DEBUG_TOKEN="$(cat "$DEBUG_TOKEN_FILE")" "$@")
+        return
+    fi
     docker run --rm \
         -u "$(id -u):$(id -g)" -e HOME=/tmp \
         -e RORO_DEBUG_TOKEN="$(cat "$DEBUG_TOKEN_FILE")" \

scripts/ci.sh

@@ -1,7 +1,14 @@
 #!/usr/bin/env bash
 # Local CI: run host unit tests, then build the firmware.
+# Usage: scripts/ci.sh [tests|builds]   one half only; both by default
 set -euo pipefail
 source "$(dirname "$0")/_docker.sh"
 DOCKER_EXTRA=()
 
-run_in_container bash -c 'git config --global --add safe.directory /work && pio test -e native && pio run -e cardputer-adv -e cardputer-adv-debug'
+case "${1:-all}" in
+    tests) STEPS='pio test -e native' ;;
+    builds) STEPS='pio run -e cardputer-adv -e cardputer-adv-debug' ;;
+    all) STEPS='pio test -e native && pio run -e cardputer-adv -e cardputer-adv-debug' ;;
+    *) 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/coverage.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Runs the host tests and says how much of lib/ they run: they're built with coverage counters.
+# Usage: scripts/coverage.sh [out folder, default .pio/coverage]
+# Out: summary.json (gcovr), coverage.svg (the README's badge), index.html (line by line).
+# What it measures: the lines of lib/ that compile on a PC. Not lib/SD (the card's driver) and not
+# src/ (the Apps, the Services, everything that needs the device): those have no host tests.
+set -euo pipefail
+source "$(dirname "$0")/_docker.sh"
+DOCKER_EXTRA=()
+OUT="${1:-.pio/coverage}"
+
+run_in_container bash -c '
+    set -eo pipefail  # a failing test fails this script, tail or not
+    git config --global --add safe.directory "$PWD"
+    rm -rf .pio/build/native-coverage "'"$OUT"'"
+    mkdir -p "'"$OUT"'"
+    pio test -e native-coverage | tail -1
+    gcovr -r . --filter "lib/" --object-directory .pio/build/native-coverage \
+        --json-summary "'"$OUT"'/summary.json" --html-details "'"$OUT"'/index.html" --print-summary | tail -4
+    python3 scripts/coverage_badge.py "'"$OUT"'/summary.json" "'"$OUT"'/coverage.svg"
+'

scripts/coverage_badge.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""Draws the README's coverage badge from gcovr's summary.
+
+Usage: scripts/coverage_badge.py <summary.json> <out.svg>
+       scripts/coverage_badge.py --plain <label> <value> <out.svg>   any other badge, in blue
+Also prints one line, and appends a short table to $GITHUB_STEP_SUMMARY when CI sets it.
+"""
+import json
+import os
+import sys
+
+
+def badge(label, value, color, title):
+    left, right = 6 * len(label) + 12, 7 * len(value) + 12
+    return f'''<svg xmlns="http://www.w3.org/2000/svg" width="{left + right}" height="20" role="img" aria-label="{label}: {value}">
+<title>{title}</title>
+<linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient>
+<clipPath id="r"><rect width="{left + right}" height="20" rx="3" fill="#fff"/></clipPath>
+<g clip-path="url(#r)"><rect width="{left}" height="20" fill="#555"/><rect x="{left}" width="{right}" height="20" fill="{color}"/><rect width="{left + right}" height="20" fill="url(#s)"/></g>
+<g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
+<text x="{left / 2}" y="14">{label}</text><text x="{left + right / 2}" y="14">{value}</text></g></svg>
+'''
+
+
+def main():
+    if sys.argv[1] == "--plain":  # any other badge: --plain <label> <value> <out.svg>
+        label, value, out = sys.argv[2:5]
+        open(out, "w").write(badge(label, value, "#007ec6", f"{label}: {value}"))
+        return
+    summary = json.load(open(sys.argv[1]))
+    lines, branches = summary["line_percent"], summary["branch_percent"]
+    label, value = "lib coverage", f"{lines:.0f}%"
+    color = "#4c1" if lines >= 90 else "#a4a61d" if lines >= 75 else "#dfb317" if lines >= 60 else "#e05d44"
+    svg = badge(label, value, color, f"{label}: {value} of the lines of lib/ are run by the host tests")
+    open(sys.argv[2], "w").write(svg)
+    print(f"coverage of lib/: {lines:.1f}% of {summary['line_total']} lines, {branches:.1f}% of branches, {len(summary['files'])} files")
+    step = os.environ.get("GITHUB_STEP_SUMMARY")
+    if step:
+        worst = sorted((f["line_percent"], f["filename"]) for f in summary["files"] if f["line_total"] >= 10)[:5]
+        with open(step, "a") as out:
+            out.write(f"### Coverage of `lib/` by the host tests\n\n**{lines:.1f}%** of {summary['line_total']} lines, {branches:.1f}% of branches.\n\n")
+            out.write("| Least covered | Lines |\n|---|---|\n" + "".join(f"| `{name}` | {pct:.0f}% |\n" for pct, name in worst))
+
+
+if __name__ == "__main__":
+    main()

scripts/coverage_link.py

@@ -0,0 +1,4 @@
+# The coverage build must also link with --coverage (build_flags only reaches the compiler).
+Import("env")  # noqa: F821  (provided by PlatformIO)
+
+env.Append(LINKFLAGS=["--coverage"])  # noqa: F821

scripts/ota_verify.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""Checks an Update File (.ota) the way the device does, on a PC: header, signature, image hash.
+
+Usage: scripts/ota_verify.py <file.ota> [public key, default keys/ota-public.pem]
+Exits 0 and prints the version if a device would accept the file.
+"""
+import hashlib
+import os
+import struct
+import subprocess
+import sys
+import tempfile
+
+HEADER_SIZE = 160
+SIGNED_BYTES = 80
+
+
+def main():
+    if len(sys.argv) < 2:
+        sys.exit(__doc__)
+    root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    key = sys.argv[2] if len(sys.argv) > 2 else os.path.join(root, "keys", "ota-public.pem")
+    data = open(sys.argv[1], "rb").read()
+    if len(data) < HEADER_SIZE or data[:8] != b"RORO-OTA":
+        sys.exit("not an update file")
+    fmt, header_size, image_size = struct.unpack("<HHI", data[8:16])
+    if fmt != 1 or header_size != HEADER_SIZE:
+        sys.exit("unsupported update format")
+    image = data[HEADER_SIZE:]
+    if len(image) != image_size:
+        sys.exit(f"the header announces {image_size} bytes of image, the file has {len(image)}")
+    if hashlib.sha256(image).digest() != data[16:48]:
+        sys.exit("image corrupted (hash mismatch)")
+    version = data[48:80].split(b"\0")[0].decode()
+    (sig_len,) = struct.unpack("<H", data[80:82])
+    with tempfile.NamedTemporaryFile() as signed, tempfile.NamedTemporaryFile() as sig:
+        signed.write(data[:SIGNED_BYTES])
+        signed.flush()
+        sig.write(data[82:82 + sig_len])
+        sig.flush()
+        ok = subprocess.run(["openssl", "dgst", "-sha256", "-verify", key, "-signature", sig.name, signed.name],
+                            capture_output=True).returncode == 0
+    if not ok:
+        sys.exit("bad signature (wrong key)")
+    print(f"{sys.argv[1]}: {version}, {image_size} bytes, signature good")
+
+
+if __name__ == "__main__":
+    main()

scripts/rdbg.py

@@ -224,10 +224,15 @@ def interactive(sock):
             sys.stdout.write(data.decode(errors="replace"))
             sys.stdout.flush()
         if sys.stdin in ready:
-            line = sys.stdin.readline()
-            if not line:
+            # Straight from the descriptor: readline() takes every waiting line into Python's own
+            # buffer and hands over one, and select() then sees nothing more to read. Piped input
+            # written while we were still connecting got stuck until the next line came.
+            data = os.read(sys.stdin.fileno(), 4096)
+            if not data:
                 return
-            sock.sendall(line.encode())
+            sock.setblocking(True)
+            sock.sendall(data)
+            sock.setblocking(False)
 
 
 def main():

scripts/release_build.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# Builds what a release publishes, from a checkout of the repository at a tag (docs/milestones/R1.md).
+# Usage: scripts/release_build.sh <checkout> <out folder>
+#   <checkout>   a clone with its tags, at the commit to release: its own sources are built, with
+#                this copy's build image and signing tools, so an old tag can be released today.
+# The signing key is read from $RORO_OTA_KEY (a file), as scripts/make_ota.py does.
+# Out: roro9stack-<version>.ota (signed, checked), -factory.bin (USB), .elf.gz (to decode crashes),
+#      SHA256SUMS, and notes.md for the release's text.
+set -euo pipefail
+SRC="$(cd "$1" && pwd)"
+mkdir -p "$2"
+OUT="$(cd "$2" && pwd)"
+TOOLS="$(cd "$(dirname "$0")" && pwd)"
+
+VERSION="$(git -C "$SRC" describe --tags --always --dirty)"
+case "$VERSION" in
+    *-dirty) echo "release: $SRC has uncommitted changes ($VERSION)" >&2; exit 1 ;;
+esac
+git -C "$SRC" describe --tags --exact-match >/dev/null 2>&1 || { echo "release: $VERSION is not a tag" >&2; exit 1; }
+
+source "$TOOLS/_docker.sh"
+ROOT="$SRC"  # _docker.sh mounts $ROOT as /work: the checkout to build, not necessarily this copy
+DOCKER_EXTRA=()
+# A tag from before the framework was rebuilt with our settings (ADR 0006) can't link against a
+# rebuilt one left in the toolchain cache: it gets the framework's libraries as they come.
+if ! grep -q custom_sdkconfig "$SRC/platformio.ini"; then
+    run_in_container bash -c 'rm -rf "${PLATFORMIO_CORE_DIR:-/pio}/packages/framework-arduinoespressif32-libs"'
+fi
+run_in_container bash -c 'git config --global --add safe.directory "$PWD" && pio run -e cardputer-adv'
+
+BUILD="$SRC/.pio/build/cardputer-adv"
+NAME="roro9stack-$VERSION"
+"$TOOLS/make_ota.py" "$BUILD/firmware.bin" "$VERSION" "$OUT/$NAME.ota"
+# A wrong key must stop the release here, not on a device: checked against the public key the
+# sources being built carry (the tags from before Firmware Updates have none: today's, then).
+PUBLIC="$SRC/keys/ota-public.pem"
+[ -e "$PUBLIC" ] || PUBLIC="$TOOLS/../keys/ota-public.pem"
+"$TOOLS/ota_verify.py" "$OUT/$NAME.ota" "$PUBLIC"
+cp "$BUILD/firmware.factory.bin" "$OUT/$NAME-factory.bin"
+gzip -9 -c "$BUILD/firmware.elf" > "$OUT/$NAME.elf.gz"
+(cd "$OUT" && sha256sum "$NAME.ota" "$NAME-factory.bin" "$NAME.elf.gz" > SHA256SUMS)
+
+# The release's text: what the tag says, then what went in since the tag before.
+PREVIOUS="$(git -C "$SRC" describe --tags --abbrev=0 "$VERSION^" 2>/dev/null || true)"
+{
+    git -C "$SRC" tag -l --format='%(contents)' "$VERSION" | sed -e '/^-----BEGIN PGP/,$d'
+    echo
+    echo "## Files"
+    echo
+    echo "- \`$NAME.ota\`: the signed Update File. Copy it to \`/updates\` on the SD card and install it from Settings > Firmware or the Storage App, or push it over Wi-Fi with \`scripts/ota_push.py\`."
+    echo "- \`$NAME-factory.bin\`: the whole flash image, for a first install over USB at offset 0."
+    echo "- \`$NAME.elf.gz\`: the symbols, to decode a crash report from this build."
+    echo "- \`SHA256SUMS\`: checksums of the three."
+    if [ -n "$PREVIOUS" ]; then
+        echo
+        echo "## Changes since $PREVIOUS"
+        echo
+        git -C "$SRC" log --no-merges --format='- %s' "$PREVIOUS..$VERSION"
+    fi
+} > "$OUT/notes.md"
+echo "$VERSION" > "$OUT/version"
+ls -l "$OUT"

scripts/release_publish.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""Creates or completes a Gitea release from what scripts/release_build.sh made.
+
+Usage: scripts/release_publish.py <folder>
+Environment: GITEA_API (https://host/api/v1), GITEA_REPO (owner/name), GITEA_TOKEN.
+Run again for the same version, it replaces the files and the text instead of failing.
+"""
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+API = os.environ.get("GITEA_API", "").rstrip("/")
+REPO = os.environ.get("GITEA_REPO", "")
+TOKEN = os.environ.get("GITEA_TOKEN", "")
+
+
+def call(method, path, body=None, raw=None, content_type="application/json"):
+    data = raw if raw is not None else (json.dumps(body).encode() if body is not None else None)
+    request = urllib.request.Request(f"{API}/repos/{REPO}{path}", data=data, method=method)
+    request.add_header("Authorization", f"token {TOKEN}")
+    if data is not None:
+        request.add_header("Content-Type", content_type)
+    try:
+        with urllib.request.urlopen(request, timeout=300) as response:
+            text = response.read()
+            return response.status, json.loads(text) if text else None
+    except urllib.error.HTTPError as e:
+        return e.code, e.read().decode(errors="replace")[:300]
+
+
+def main():
+    if len(sys.argv) != 2 or not (API and REPO and TOKEN):
+        sys.exit(__doc__)
+    folder = sys.argv[1]
+    version = open(os.path.join(folder, "version")).read().strip()
+    notes = open(os.path.join(folder, "notes.md")).read()
+    files = sorted(f for f in os.listdir(folder) if f not in ("version", "notes.md"))
+
+    status, release = call("GET", f"/releases/tags/{urllib.parse.quote(version)}")
+    fields = {"tag_name": version, "name": f"roro9stack {version}", "body": notes, "draft": False, "prerelease": False}
+    if status == 200:
+        status, release = call("PATCH", f"/releases/{release['id']}", fields)
+    else:
+        status, release = call("POST", "/releases", fields)
+    if status not in (200, 201):
+        sys.exit(f"release: Gitea answered {status}: {release}")
+
+    for asset in release.get("assets") or []:  # a second run replaces what the first uploaded
+        if asset["name"] in files:
+            call("DELETE", f"/releases/{release['id']}/assets/{asset['id']}")
+    for name in files:
+        with open(os.path.join(folder, name), "rb") as f:
+            status, answer = call("POST", f"/releases/{release['id']}/assets?name={urllib.parse.quote(name)}", raw=f.read(),
+                                  content_type="application/octet-stream")
+        if status != 201:
+            sys.exit(f"release: uploading {name}: Gitea answered {status}: {answer}")
+        print(f"uploaded {name} ({answer['size']} bytes)")
+    print(f"published {release['html_url']}")
+
+
+if __name__ == "__main__":
+    main()

site/README.md

@@ -0,0 +1,45 @@
+# The roro9stack site
+
+Source of https://roro9stack.net (docs/milestones/W1.md): a [Zola](https://www.getzola.org/) site. The home page, an Install page with a browser flasher, and the list of releases so far; the user guide, how-tos, FAQ and developer docs come next.
+
+```
+config.toml           base_url, the repository and API addresses
+content/              the pages (Markdown, with their template named in the front matter)
+templates/            base, home, install, downloads, 404; illustrations/ is generated
+data/                 the App cards and the screenshots' captions
+static/               css, js, fonts (self-hosted), img, screens (real screenshots), vendor/esp-web-tools
+tools/                make_illustrations.py, check_site.py
+```
+
+## Build and look
+
+```sh
+docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/repo" -w /repo/site ghcr.io/getzola/zola:v0.22.0 build   # writes ./public
+docker run --rm -u "$(id -u):$(id -g)" -p 1111:1111 -v "$PWD:/repo" -w /repo/site ghcr.io/getzola/zola:v0.22.0 serve --interface 0.0.0.0
+python3 site/tools/check_site.py public    # what the pages promise, kept
+```
+
+Or `zola build` with a Zola of your own, in `site/` (or `zola --root site build` from the root). **The output goes to `public/` at the root of the repository,** not into `site/`: `output_dir` in `config.toml`, and git ignores that directory. The build reads the latest release and the list of releases from the Gitea API (`load_data`); if the server can't be reached, the pages say so instead of failing.
+
+## Publishing
+
+The web server pulls `main` and runs `zola build`, as for the blog. CI (`.gitea/workflows/site.yml`) builds the site and runs the checks when `site/`, `docs/`, `README.md` or `CONTEXT.md` change; the firmware workflow skips a change that touches only those.
+
+## Things to know
+
+- **The Install page needs Caddy's help.** Gitea's release downloads carry no CORS header, so the page asks the API from the browser only if Caddy, in front of Gitea, allows this origin:
+
+  ```caddy
+  @releases {
+      method GET HEAD
+      path /twisla/roro9stack/releases/download/* /api/v1/repos/twisla/roro9stack/releases*
+  }
+  header @releases Access-Control-Allow-Origin "https://roro9stack.net"
+  header @releases Vary Origin
+  ```
+
+  Without it the page says it can't reach the release server and points to the esptool steps.
+- **No third-party requests.** Fonts and the flasher library are served from here; `tools/check_site.py` fails the build if a page loads anything from another origin.
+- **Illustrations.** `templates/illustrations/*.html` are generated by `tools/make_illustrations.py`; run it again rather than editing them.
+- **Updating the flasher library:** see `static/vendor/esp-web-tools/README.txt`.
+- **Fonts** are DM Mono and Hanken Grotesk, under the SIL Open Font License (the licences are in `static/fonts/`).

site/config.toml

@@ -0,0 +1,28 @@
+# roro9stack.net (docs/milestones/W1.md). Build with `zola build`; the web server pulls main and does this.
+base_url = "https://roro9stack.net"
+title = "roro9stack"
+description = "Open firmware for the M5Stack Cardputer ADV with the Cap LoRa-1262: a LoRa scanner, GNSS, a Gemini browser, IRC, Wi-Fi tools, notes and more."
+default_language = "en"
+compile_sass = false
+build_search_index = false
+generate_feeds = false  # the devlog turns its own on (content/devlog/_index.md)
+feed_filenames = ["atom.xml"]
+# The built site goes to public/ at the root of the repository (git ignores it), whether Zola is run
+# from site/ or from the root with `--root site`.
+output_dir = "../public"
+
+[markdown]
+smart_punctuation = false
+
+[markdown.highlighting]
+# Classes instead of inline colours; Zola 0.22 still wants a theme and writes giallo.css, which the
+# templates don't link.
+style = "class"
+theme = "nord"
+
+[extra]
+author = "twisla"
+repo = "https://git.twis.la/twisla/roro9stack"
+api = "https://git.twis.la/api/v1/repos/twisla/roro9stack"
+blog = "https://experiments.twis.la"
+contact = "contact@roro9stack.net"

site/content/_index.md

@@ -0,0 +1,4 @@
++++
+title = "roro9stack"
+template = "index.html"
++++

site/content/devlog/_index.md

@@ -0,0 +1,12 @@
++++
+title = "The devlog"
+description = "How roro9stack gets built, written up as it happens: what worked, what broke, and what the firmware taught me on the way."
+sort_by = "date"
+page_template = "devlog-post.html"
+template = "devlog-index.html"
+generate_feeds = true
++++
+
+One post for each stretch of work, newest first. They are written after the fact, from the commits, the decisions and the logs, and they keep the bad parts in: every post has at least one thing that turned out not to be what I thought. For what the firmware does *today*, read the [user guide](/guide/); this is how it got there.
+
+My other write-ups (a vinyl remote, a ZFS rescue) are on [twisla's experiments](https://experiments.twis.la/), where these posts were first published.

site/content/devlog/roro9stack-f1-r1/index.md

@@ -0,0 +1,263 @@
++++
+title = '''836 bytes'''
+description = '''roro9stack learns to browse its SD card and keep notes that save themselves, CI starts building and signing every release, and the device installs the project's releases on its own, which nearly took all of its memory while IRC was connected.'''
+date = 2026-10-06T17:15:00+02:00
+
+[extra]
+topics = '''ESP32-S3 · CI · Memory'''
+read_label = '''Read where the memory went →'''
+uid = '''<b>notification:</b> v0.11.0 is out: see Settings > Firmware'''
+dek = "Two more milestones for [roro9stack](/devlog/roro9stack/), my firmware for the M5Stack Cardputer: a Storage App and Notes, then releases that build and sign themselves on a CI runner, and a device that fetches them from my Gitea. Each of the three ran into the same wall, which is how much RAM is left once IRC is connected. The last time it was a download that left **836 bytes**."
+byline = '''designed by interrogation, rounds eight to eleven: 47 questions, and a runner label registered three times'''
+
+[extra.sign]
+label = "Lowest free heap during a download, IRC connected"
+note = "Before IRC was asked to step aside. Afterwards: 38,316."
+count = "836"
+tone = "red"
+
+[[extra.cast]]
+name = "IRC's connection"
+role = "one TLS session, always on"
+text = "Holds about 41 KB of the 107 KB the chip has free after boot, just by being connected. Perfectly well behaved. Doesn't know anyone else wants to talk."
+
+[[extra.cast]]
+name = "The largest free block"
+role = "31.7 KB, with IRC connected"
+text = "The number that decides things, not the total. Out of memory on this chip isn't an error to handle: it's an abort."
+
+[[extra.cast]]
+name = "The runner"
+role = "runner0, Ubuntu 26.04, 4 cores, 7 GB"
+text = "Mine, on my network, running whatever a workflow tells it to. Spent its first hours running jobs on its own host because of how its label had been written."
+
+[[extra.cast]]
+name = "The signing key"
+role = "ECDSA P-256, now in two places"
+text = "Used to live on one machine. Now also in a repository secret, on purpose, so that a tag is a release without anyone at a keyboard."
+
+[[extra.cast]]
+name = "The server's certificate"
+role = "Let's Encrypt, replaced every few months"
+text = "Next expiry: 2026-12-14. Too short-lived to pin, which is why the device carries the roots it chains to instead."
++++
+
+## TL;DR
+
+- **The Storage App** (v0.9.0) browses the SD card: sizes, dates, copy, move, rename, delete, new folder, with a viewer for each kind of file the firmware writes. A copy runs in slices so the Logs keep being written, and says what it's about to delete before it does.
+- **Notes** (v0.10.0): plain text files in `/notes`, no save key. The note is written five seconds after the last key, on Back, and when the screen turns off. A power cut costs a few seconds, never the note.
+- **CI** on my own Gitea runner: the host tests on every push to `main`, both firmwares on every pull request, and every tag `v*` becomes a signed release. All fourteen tags from v0.1.0 to v0.11.0 now have one, each downloaded again and checked.
+- **The device installs releases itself,** from Settings, with no PC and no card. That's **v0.11.0**, the first release that can look for the next one. Getting there turned up the number in the title.
+- Three bugs with one shape: a subtraction of unsigned times that goes wrong when a stamp comes from the future.
+- 456 host tests, 60 more than last time. The code is [on my Gitea](https://git.twis.la/twisla/roro9stack/src/branch/main), and the plans with every measurement are [F1](https://git.twis.la/twisla/roro9stack/src/branch/main/docs/milestones/F1.md) and [R1](https://git.twis.la/twisla/roro9stack/src/branch/main/docs/milestones/R1.md).
+
+## Two milestones, and one wall
+
+After the [housekeeping milestone](/devlog/roro9stack-s1/) the backlog still said two things. The card holds everything the firmware writes, and the only way to look at it was a debug console command. And every release had been built and signed on my laptop and pushed to one device, with nothing published anywhere.
+
+So **F1** is files and notes, and **R1** is releases. Neither is glamorous. Both are the sort of thing a device needs before it's something other than mine.
+
+What I didn't plan for is that the story of both is memory. The Cardputer's ESP32-S3 has no external RAM: about 107 KB free after boot, and IRC's TLS session takes 41 of it the moment it connects. Every feature below was fine until I tested it with IRC up.
+
+## The cast
+
+{{ cast() }}
+
+## A card you can look at
+
+The Storage App is a file browser, with the decisions I'd normally take for granted made out loud in a design round:
+
+- **One item at a time, with a clipboard.** `c` copies, `x` cuts, `v` pastes, `r` renames, `d` deletes, `n` makes a folder, `i` says what it is. Back goes up a level. No multiple selection: that's [an issue](https://git.twis.la/twisla/roro9stack/issues/41) of its own.
+- **Folders first, then by name**, with `s` to sort by date or size. A folder holds at most 256 entries on screen and says "first 256 of 329" when it's bigger.
+- **Settings > Storage is gone.** Its usage figures, Clean-up and "Erase SD card" are the last row at the top of the card, behind a warning that they delete things for good.
+
+{{ figure(src="storage.png", alt="Four Cardputer screens at 2x in a grid. Top left: the Storage App at the top level of the card: captures (selected), gemini, gnss, irc, updates and wifi, each marked folder, then Maintenance, with 7.3 GB free in the corner and the key hints c x v:paste r:rename d:del n:new i s:sort. Top right: a box reading Copying f1test (2) with a progress bar at 1.8 MB of 8.0 MB and Back: cancel. Bottom left: the same list with an orange line at the bottom reading The firmware keeps its files in /captures. Bottom right: a box reading Delete f1test and its 300 files (2.5 KB)? It can't be undone, with Cancel selected beside Delete", width=976, height=556, landscape=true, full=true, caption=`The top of the card, an 8 MB folder being copied, a refusal with its reason, and the question before a delete. The folders named f1test are my scratch space for the checks.`) }}
+
+### Copying without starving the Logs
+
+Everything that touches the card runs on one task, because the SD driver isn't safe across tasks. The IRC Logs, a Track being recorded and a LoRa Capture write through that same task. A copy that holds it for twenty seconds makes all three wait.
+
+So an operation works in slices of about 150 milliseconds and puts itself back at the end of the queue, and the Logs get their turn in between. I checked it the obvious way: queued two Log lines in the middle of an 8.4 MB folder copy, which took 19.4 seconds (435 KB/s), and both were on the card afterwards. Cancelling a copy at 1.8 MB deletes what it had written and says "nothing was copied". Afterwards every file's size is compared with the original; not its contents, since the driver has earned back that much trust since [last time](/devlog/roro9stack-s1/).
+
+### The listing that took two seconds
+
+My first version listed a folder by asking the Arduino `File` object for each entry, then its size, then its date. Each of those looks the entry up by name again. A folder of 329 files took over two seconds to appear. The listing now reads the folder from FatFs in one pass, and it's on screen before the display has redrawn.
+
+### What can't be deleted
+
+Nothing is hidden, and almost nothing is protected. The exceptions are the six folders the firmware keeps its files in (what's in them is yours), `/gemini/cache`, and any file the firmware has open for writing right now: today's IRC Log, a Track, a Capture. I tried each from the console: `rm /irc`, `rm` on a Capture while it was recording, a folder into itself. Each came back refused with a reason. A Capture being recorded could still be *copied*, which is the point of having separate rules for "change" and "read".
+
+### Looking inside
+
+Enter on a file opens it by what it is.
+
+{{ figure(src="viewers.png", alt="Four Cardputer screens at 2x in a grid. Top left: big.log, 1.0 MB, opened at its end, the last line reading 20:59:59 <end> THE LAST LINE, with the hint Tab: hex t: top b: end. Top right: the same file as a hex dump, rows of eight bytes with their offsets and the text beside them, starting 00000 3230 3a30 303a 3030 20:00:00. Bottom left: a file called readme with no extension, 102 B, shown as text: A file without an extension. It looks like text, so it opens as text, and a line with accents, été, ça. Bottom right: test1.ota, 1.6 MB: Version v0.2.1-13-g14ff13f-dirty+debug, Running v0.8.1-2-g7ab8f04-dirty+debug, Signed with the project's key, intact, Older than what's running, and the hint Enter: install, Tab: hex", width=976, height=556, landscape=true, full=true, caption=`A megabyte of log, open at its last line; the same file as bytes; a file with no extension that looks like text; and an Update File.`) }}
+
+**Text** is read from the card as you scroll, a kilobyte around the screen at a time, so a 1 MB log opens at once, at its end. Scrolling back wraps the paragraph before again, so a file reads the same in both directions; that's a [small class](https://git.twis.la/twisla/roro9stack/src/tag/v0.10.0/lib/files/src/text_pager.h) with its own tests. **Hex** is what anything else gets. A **`.pcap`** shows the packets the way the LoRa Scanner lists them, a **`.gpx`** its point count, start, duration and distance, and an **`.ota`** is checked the way an install would check it: the same parser, with a sink that writes nothing. "Signed with the project's key, intact" is that parser's answer.
+
+### Two things I found on the way
+
+**The Storage Warning had never opened anything.** The project's own glossary said "selecting it opens Storage Clean-up". It had only ever been a Toast, and a Toast can't be selected. It now says "see Storage" and promises nothing more.
+
+**The Clock now sets the system time**, whatever its source. Files used to be dated only after NTP. I pointed NTP at an address that doesn't answer, restarted, and made a folder: it was dated 08:39, from the GNSS fix. A Track written before the clock was set still shows "-" for its date, which is honest.
+
+And a confession: a key script I ran against the device was one step off and renamed `/gemini/saved` to `saved2`, then copied it to the top of the card. I noticed within a minute and put it back (same 7 files, 53,798 bytes). The rule I took from it is to look at a screenshot before any key that renames, moves or deletes.
+
+## Notes that save themselves
+
+{{ figure(src="notes.png", alt="Four Cardputer screens at 2x in a grid. Top left: the Notes list for /notes, 6 notes, each under its first line with the date 2026-10-06: The note as it was saved (selected), Only the temporary file is, This is line 0000 of a not twice, Ideas and abcdefghijklmnopqrstuvwxyz. Top right: the editor on shopping-list.txt, 66 B, saved: Shopping list, milk, and bread ad a longer line that wraps on the screen, with the cursor at the end. Bottom left: a box titled Unsaved copy reading A save of this note was cut short. Its copy has 79 B, the note 26 B, with the buttons Keep the note (selected) and Use the copy. Bottom right: full.txt, 16 KB, saved, lines reading This is line 0000 of a note made to be exactly as big as a note may be, and an orange line at the bottom reading This note is full: 16 KB", width=976, height=556, landscape=true, full=true, caption=`The list, under each note's first line; the editor; a note whose last save was cut short; and a note at its 16 KB limit.`) }}
+
+Notes are plain text files in `/notes`, listed by their first line. There is no save key, which was a decision, not an omission: **five seconds after the last key, on Back, on leaving the App, when the screen turns off, and before the device powers off.** A new note has no file until something is typed, and then it takes its name from its first line: `shopping-list.txt`.
+
+### Never half a note
+
+A save writes `shopping-list.txt.tmp`, checks its size, and puts it in the note's place. FAT can't rename one file onto another, so between the delete and the rename there's a moment when only the temporary file exists. If the power goes then, the next time the Notes list opens it finds the lone `.tmp` and puts it back under its name. If the note and a `.tmp` both exist, the save was cut short earlier, and opening the note offers the copy back (third screen above).
+
+I tried the power cut, as well as a device can fake one: typed, waited past the five seconds, typed more, and restarted it at once. The note had what had been saved, whole, and not the last few keys. The first runs looked as if the editor were dropping keys. It wasn't. The tool I use to send keys held lines back until the next one arrived, a bug in the tool, now fixed.
+
+### The 16 KB buffer
+
+A note is held in memory while it's edited, up to 16 KB, and a bigger text file opens read-only in the Storage App. I'd have liked to say "any size". Editing in place needs a structure that keeps the changes apart from a file you can't load, and I'm not starting that inside a first version. It's [issue #47](https://git.twis.la/twisla/roro9stack/issues/47), it's marked high, and the plan says it has to come in a later release.
+
+The first version of the 16 KB limit did something that looks harmless. It read the file into one string and copied it into the editor's buffer. Opening a full note with IRC connected **restarted the device.** The backtrace ended in `operator new`: with IRC up, the largest free block is 31.7 KB, two 16 KB blocks weren't going to fit in it, and on this chip a failed allocation isn't an error to handle. It's an abort.
+
+Now the buffer is reserved once when the note is opened, the file is read straight into it, and nothing typed afterwards ever makes it grow. The editor also refuses to open without a free block of 24 KB, and says so. With IRC connected and a full note open there are 55 KB free.
+
+## The same bug, three times
+
+In one day, the same mistake found me three times, and I'd like you to be spared it.
+
+**1. A panic nine seconds after boot.** The first boot of a new build crashed with `Operating mode must not be set while SNTP client is running`. The device was on Probation, so it rolled back to the previous build by itself, which is the safety net from [the OTA post](/devlog/roro9stack-ota/) catching a real bug. The cause: when Wi-Fi joins, the code stamps the time it last set up DNS and NTP, from `millis()`, and a few lines later compares *now* with that stamp, where "now" was read earlier in the same pass. The stamp is a few milliseconds in the future, an unsigned subtraction wraps to forty-nine days, and the setup ran twice. Starting SNTP is only queued for the network task, so about once in a dozen boots the second request landed before the first had run. It had been there since v0.7.0. [Issue #46](https://git.twis.la/twisla/roro9stack/issues/46).
+
+**2. Keys that went missing.** About one key in twenty-five sent through the Debug Console never arrived. The `key` command stamps the screen's idle timer from `millis()`; the power tick compares with its own, older time; the screen "turned off" for one tick, and the next key was swallowed as a wake-up. Keys from the real keyboard pass the loop's own time, so they were never affected. This also explains some "lost" keys from earlier sessions I'd put down to the screen waking.
+
+**3. A message that never showed.** In the Storage App, a footer message set by a key press in a pass looked 49 days old to the code that decides when to hide it.
+
+Same shape each time, and each fixed by comparing signed. A test now covers the one in the power policy. I haven't hunted down the rest of the pattern; there are more comparisons like it in the code, and the ones in the Apps only cost an extra redraw.
+
+## Releases that build themselves
+
+Until now a release was a tag on my laptop and an `.ota` pushed to one device. [Issue #5](https://git.twis.la/twisla/roro9stack/issues/5) asked for the real thing: push a tag, get a signed release on Gitea.
+
+I'd registered a runner on my own server, so the first question was what a job on it can do. A probe workflow answered: Ubuntu 26.04, Docker, git, no Node, no compiler. That ruled out the usual JavaScript actions, so the checkout is four git commands and the build is the same `scripts/ci.sh` that runs on a laptop.
+
+### The label that took three tries
+
+The runner's label was registered as `ubuntu://docker:ubuntu:resolute`, and Gitea took the whole string for the label's *name*. The runner wasn't running jobs in containers at all: it ran them on its own host, as a user in the Docker group. My first workflow, and the release of v0.10.0, were written for that.
+
+I wanted containers. The label became `ubuntu::docker://…`, which was also wrong, and then `ubuntu` with the image given properly. With a container per job and a named volume for the toolchains, the workflow installs PlatformIO into a plain Python image and mounts the volume as the cache. The first full run, on an empty cache, took 11.4 minutes: the framework is rebuilt with smaller TLS buffers. A pull request run now takes about 8.7 minutes, a release build alone 5.5.
+
+Gitea 1.27's API can't cancel a run that isn't finished. Twelve release runs, queued for the old label, stayed queued until I cancelled them in the web UI.
+
+### Putting the key in a secret
+
+CI has to sign, or a tag isn't a release. I decided to automate it: the signing key is now a repository secret, written to a file for the length of one step and removed after. [ADR 0008](https://git.twis.la/twisla/roro9stack/src/branch/main/docs/adr/0008-ci-signs-releases.md) is the part where I wrote down what that costs: **anyone who can run a workflow here can sign firmware every device accepts**, and the runner executes jobs on its own host's Docker. What limits it: the release step checks the signed file against the public key in the sources before publishing, so a wrong or swapped secret stops the release instead of producing one nobody can install. And a device only installs what it's told to, keeps it on Probation, and rolls back what doesn't hold.
+
+### The old tags
+
+Releases for the thirteen tags that existed went through the same workflow, each built from its own sources. The first attempt, on the old label, failed on v0.1.0: it predates the rebuilt framework and wouldn't link against the rebuilt one the cache held. The release script now restores the stock libraries for tags from before that, and the whole backfill passed on its second go. Then I downloaded all thirteen `.ota` files from the published releases and checked each checksum and signature from here: all good.
+
+Two things I measured and left alone. A CI build isn't byte-identical to one on my laptop for the same tag: same size, different bytes. Signing no longer depends on it. And the Debug Build is built by CI to prove it compiles but never published, because each one carries its builder's console token.
+
+### What runs when
+
+My first workflow rebuilt both firmwares on every push, and I said so: that's overkill. A push now runs only the host tests, about 45 seconds of them. A pull request adds both firmware builds, and the repository only merges a pull request one way, as "rebase, then a merge commit", so the commits in a branch keep their messages. And then a branch with an open pull request ran twice per push, once for the push and once for the pull request, so branch pushes now run nothing and the pull request is what runs.
+
+The README has badges now: the workflow's status, the latest release, and a coverage figure. **94.6%** is the share of `lib/` the host tests run, 3,193 lines. It leaves out `lib/SD` and all of `src/`, about 10,000 lines of Apps and Services that need the device and have no host tests. The badge says "lib coverage", and the README says what it doesn't cover, because a bare percentage there would be a small lie.
+
+## 836 bytes
+
+With releases published, [issue #6](https://git.twis.la/twisla/roro9stack/issues/6) was unblocked: **the device checks Gitea for a newer release and installs it.**
+
+It's in Settings > Firmware. *Latest release* checks the server and shows `v0.11.0 (new)` or `(current)`; Enter opens the release, with its version, date, size and the tag's message, and an Install button when it's newer. *Older releases* lists the last ten, and going back asks a different question. A setting, *Check for updates*, looks once a day, with Wi-Fi up and the clock set, and says `v0.11.0 is out: see Settings > Firmware`. It installs nothing by itself.
+
+{{ figure(src="updates.png", alt="Four Cardputer screens at 2x in a grid. Top left: Settings, Firmware: Version, Status confirmed, Push to 10.39.39.12:3232, Latest release v0.10.0 (new) selected, Older releases, then On the SD card with two .ota files. Top right: the release page, v0.10.0, Published 2026-10-06, 1.8 MB, then the start of the tag's message about the Notes App, with the hint Enter: install, c: check again. Bottom left: a box titled Install update? reading v0.10.0 replaces v0.9.0. The device restarts once it's written, with Cancel selected beside Install. Bottom right: the full-screen progress: Firmware update, Receiving v0.10.0, a bar at 28 percent", width=976, height=556, landscape=true, full=true, caption=`The page, a release, the question, and the download. The device was pretending to run v0.9.0, so that the release of v0.10.0 counted as an update.`) }}
+
+### What's trusted
+
+The server's certificate is a Let's Encrypt chain, all ECDSA, and it changes every few months. Pinning it, as the Gemini App does for capsules, would ask a question at every renewal. The framework's bundle of well over a hundred authorities would let any of them vouch for my server. So the firmware carries the two roots the chain ends in, ISRG Root X1 and X2, 2.7 KB, and checks the chain and the name against them ([ADR 0009](https://git.twis.la/twisla/roro9stack/src/branch/main/docs/adr/0009-the-device-trusts-the-isrg-roots.md)). If the server ever moves to another authority, the next firmware has to come from the PC.
+
+That's the transport. What decides whether a download installs is still the Update File's own signature, checked after the first 160 bytes, before a byte is written to the slot. I tried the refusals against the real server rather than trusting that: a download cut at 800,000 bytes ("update file too short"), a byte flipped in the signature ("bad signature"), a byte flipped in the image, which downloads in full and is refused at the end ("image corrupted"). Each time the running firmware was untouched. And connections to github.com, example.com and four deliberately broken badssl.com hosts (expired, self-signed, wrong host, untrusted root) were refused.
+
+### The install
+
+The real thing, twice: once from the console and once from the screen. The device downloaded v0.10.0 from `git.twis.la`, restarted into it, and confirmed itself on Probation. Then I pushed my Debug Build back from the PC. The slot table afterwards read `v0.10.0, valid`. No card, no PC in the install. The full download took 46 seconds, about 40 KB/s, over a guest Wi-Fi at −65 dBm. I haven't looked into why it isn't faster.
+
+### Where the memory went
+
+Then I did what I'd done with every feature that day, and connected IRC first.
+
+{{ diagram(src="memory.svg", min_width=620, caption=`The lowest the free heap got, from a fresh boot each time, with Gemini's 20 KB floor marked. IRC's connection holds 41 KB of the 107 KB; a TLS connection to this server needs about 52 on top.`) }}
+
+A TLS connection to the server peaks at about **52 KB** of heap. I wondered if checking the certificate was the expensive part, and tried three modes: both roots, only the small ECDSA one, no verification at all. The lowest free heap was 56.3, 55.0 and 56.0 KB. Skipping the check would have saved nothing. The cost is the connection: record buffers and the handshake.
+
+With no IRC that leaves a comfortable margin. With IRC connected, 66 KB free, a plain check bottomed out at **3 KB**, and a list at 2.9 KB. And a full download, twice: the lowest free heap was 6,140 bytes the first time and **836 bytes** the second. The device didn't crash. It was entirely luck. My start floor was 55 KB, which IRC leaves you at 66 and passes; the floor was measuring the wrong thing.
+
+### Making room
+
+IRC steps aside. A check, a list or an install you asked for makes IRC say QUIT, free its TLS session, and reconnect when the Update Service is done. A TLS connection now needs 80 KB free to start, the 52 plus the 20 KB spare the Gemini milestone settled on, with some margin. The same worst case, IRC connected and a full download, now bottoms out at **38,316 bytes**, and IRC comes back afterwards: its byte counters kept growing.
+
+The daily check never does that. It's not worth taking IRC down for a look nobody asked for. So with IRC connected it waits for a moment when it isn't. I tried both: with IRC connected, 68 KB free, the daily check didn't run. Without it, the check ran by itself and announced the update. Its first message was `Update v0.10.0 available: see Settings > Firmware`, and the console printed it cut off at "Firmwa", because a notification holds 48 bytes. It reads `v0.10.0 is out: see Settings > Firmware` now.
+
+That's a real limit, and I'd rather state it than hide it: **with IRC connected for days, the daily check doesn't run.** Opening *Latest release* still does it. And a Debug Build shows the latest release but won't install it, since releases carry no debug console and installing one would take mine away.
+
+### The first release it could see
+
+v0.11.0 is the release that carries all this, tagged on `main` after the merge. CI took 14.1 minutes (the tests, both firmwares, then the signed release build and the upload) and published the usual four files. I downloaded the `.ota` again and checked the checksum and the signature from here: both good.
+
+The device was still on a v0.10.0-based build, so this was the first time it could see a release newer than itself without my pretending. I ran the daily check, with none of the knobs, and it announced `v0.11.0 is out: see Settings > Firmware` by itself. Settings > Firmware says `v0.11.0 (new)`. The release page, on this Debug Build, says it won't install it. Then I pushed the tagged Debug Build from the PC, and the same check now says the latest release isn't newer.
+
+{{ figure(src="release.png", alt="Two Cardputer screens at 2x side by side. Left: Settings, Firmware: Version v0.10.0-19-g4ef4134-dirty+debug, Status confirmed, Push to 10.39.39.12:3232, Latest release v0.11.0 (new) selected, Older releases, then On the SD card with two .ota files. Right: the release page, v0.11.0, Published 2026-10-06, 1.8 MB, then the start of the tag's message, v0.11.0: updates from Gitea (Settings > Firmware checks the project's server, lists the last ten releases and installs one straight into the inactive slot; a daily check announces, and at the bottom, cut off at the screen's edge, A Debug Build keeps its console: update it from", width=976, height=270, landscape=true, full=true, caption=`The real thing: a build older than v0.11.0 sees it as new, and a Debug Build says it won't install it. The sentence at the bottom is cut off by the screen, which is a bug.`) }}
+
+Two flaws showed up. That message overruns the screen's edge, and it needs to be shorter. And the README's release badge still said v0.10.0 afterwards: CI draws it when `main` is pushed, not when a tag is, so it catches up at the next push. Neither is fixed yet.
+
+### What I didn't verify
+
+- **The certificate's name, on its own.** I tried connecting by IP address, hoping for a valid chain with the wrong name. The server ended the handshake before showing its certificate, so that proved nothing. The library does check the name it connects to, and OpenSSL on the PC refused the wrong name against the same chain, but I haven't seen the device do it.
+- **A failed daily check retrying**, and **not announcing a version that already failed here**. Both have host tests. Neither was on the device.
+
+## By the numbers
+
+{% table() %}
+| | |
+| --- | --- |
+| Releases cut | 3 (v0.9.0, v0.10.0, v0.11.0), and 14 published on Gitea, v0.1.0 to v0.11.0 |
+| Design questions | 47 (Q128 to Q174) |
+| Host tests | 456, 60 of them new |
+| Lines of `lib/` the tests run | 94.6% of 3,193 |
+| The signed image | 1.92 MB, against 1.80 for v0.8.0 |
+| Releases whose `.ota` I downloaded again and verified | 14 of 14 |
+| CI: tests only (a push to `main`), a pull request, a tag with its release | 1.1, 8.7 and 14.1 min |
+| Times the runner's label was registered | 3 |
+| Queued runs the API wouldn't cancel | 12 |
+| Times the same unsigned subtraction found me | 3 |
+| A full 1.9 MB download | 46 s |
+| Lowest free heap during it, IRC connected: before, after | 836 B, 38,316 B |
+| Bytes a notification holds | 48 |
+{% 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: the Storage App and Notes.~~ v0.9.0 and v0.10.0, this post.
+
+8. R1, so far: CI and signed releases, and updates from Gitea. v0.11.0, this post. Next in R1 is an Issues App, to list and file issues from the device.
+
+9. Still waiting: the card as a USB drive, notes of any size, and M4, the mesh, which wants a second node I still haven't got.
+{% end %}
+
+{% signoff() %}
+Out of memory on this chip isn't a message, it's an abort, and my check against it was a number I'd chosen without measuring. The measuring took one afternoon and a device that, twice, survived on luck.
+{% end %}

site/content/devlog/roro9stack-f1-r1/memory.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 298" role="img" aria-label="Lowest free heap during an operation, in kilobytes, from a fresh boot each time. With no IRC: a check 56.3 KB, a download 54.0 KB. With IRC connected: a check 3.1 KB and a download 0.8 KB, both far below the 20 KB floor. With IRC stepping aside for the download: 38.3 KB.">
+  <g font-family="JetBrains Mono, ui-monospace, monospace" fill="currentColor" font-size="10">
+    <text x="16" y="22" font-size="12" font-weight="600">The lowest the free heap got</text>
+    <text x="16" y="36" class="mem-dim">107 KB free after boot; IRC's connection holds 41 of them</text>
+    <line class="mem-grid" x1="190.0" y1="44" x2="190.0" y2="232"/><text x="190.0" y="246" text-anchor="middle" class="mem-dim">0</text><line class="mem-grid" x1="282.7" y1="44" x2="282.7" y2="232"/><text x="282.7" y="246" text-anchor="middle" class="mem-dim">20</text><line class="mem-grid" x1="375.5" y1="44" x2="375.5" y2="232"/><text x="375.5" y="246" text-anchor="middle" class="mem-dim">40</text><line class="mem-grid" x1="468.2" y1="44" x2="468.2" y2="232"/><text x="468.2" y="246" text-anchor="middle" class="mem-dim">60</text><line class="mem-grid" x1="560.9" y1="44" x2="560.9" y2="232"/><text x="560.9" y="246" text-anchor="middle" class="mem-dim">80</text><line class="mem-grid" x1="653.6" y1="44" x2="653.6" y2="232"/><text x="653.6" y="246" text-anchor="middle" class="mem-dim">100</text>
+    <text x="16" y="73">No IRC: a check</text><rect class="mem-ok" x="190" y="58" width="261.0" height="22" rx="2"/><text x="459.0" y="73" class="mem-val ">56.3 KB</text><text x="16" y="109">No IRC: a download</text><rect class="mem-ok" x="190" y="94" width="250.4" height="22" rx="2"/><text x="448.4" y="109" class="mem-val ">54.0 KB</text><text x="16" y="145">IRC connected: a check</text><rect class="mem-bad" x="190" y="130" width="14.4" height="22" rx="2"/><text x="212.4" y="145" class="mem-val mem-redtext">3.1 KB</text><text x="16" y="181">IRC connected: a download</text><rect class="mem-bad" x="190" y="166" width="3.7" height="22" rx="2"/><text x="201.7" y="181" class="mem-val mem-redtext">0.8 KB</text><text x="16" y="217">IRC steps aside: a download</text><rect class="mem-fixed" x="190" y="202" width="177.6" height="22" rx="2"/><text x="375.6" y="217" class="mem-val ">38.3 KB</text>
+    <line class="mem-floor" x1="282.7" y1="44" x2="282.7" y2="232"/>
+    <text class="f-red" x="288.7" y="266">20 KB: the floor the Gemini App was built around</text>
+    <text x="16" y="284" class="mem-dim">Each bar: a fresh boot, then the operation. KB of heap; the chip has no PSRAM.</text>
+  </g>
+</svg>

site/content/devlog/roro9stack-gemini/fetch.svg

@@ -0,0 +1,59 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 330" role="img" aria-label="The path of one Gemini fetch. The Gemini App asks for a URL and goes on drawing. A short-lived Gemini task opens a TLS connection to port 1965 with verification off, reads the server's certificate fingerprint and compares it with the one pinned for that host: the first time it pins it, if it changed it stops and the App asks. It sends the URL, reads the status line, and streams the body to a cache file on the SD card in 1 KB pieces, each written by the storage task. The connection closes and its memory comes back. Then the page is loaded into memory from the card, as far as the 40 KB floor allows; a bigger page is windowed and read as you scroll. The App gets the page.">
+  <defs>
+    <marker id="gx-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="gx-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="gx-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="gx-panel" x="16" y="20" width="150" height="70" rx="8"/>
+    <text x="28" y="44" font-size="12" font-weight="600">Gemini App</text>
+    <text x="28" y="64" font-size="11" class="gx-dim">asks, then keeps</text>
+    <text x="28" y="80" font-size="11" class="gx-dim">drawing</text>
+
+    <rect class="gx-hot" x="210" y="20" width="534" height="200" rx="8"/>
+    <text x="224" y="42" font-size="12" font-weight="600">Gemini task (one job at a time, gone when idle)</text>
+
+    <rect class="gx-box" x="224" y="56" width="150" height="66" rx="6"/>
+    <text x="236" y="76" font-size="11" font-weight="600">1 TLS, port 1965</text>
+    <text x="236" y="94" font-size="10" class="gx-dim">fingerprint vs</text>
+    <text x="236" y="108" font-size="10" class="gx-dim">the pinned one</text>
+
+    <rect class="gx-box" x="392" y="56" width="150" height="66" rx="6"/>
+    <text x="404" y="76" font-size="11" font-weight="600">2 URL, status</text>
+    <text x="404" y="94" font-size="10" class="gx-dim">"20 text/gemini"</text>
+    <text x="404" y="108" font-size="10" class="gx-dim">or 1x 3x 4x 5x</text>
+
+    <rect class="gx-box" x="560" y="56" width="170" height="66" rx="6"/>
+    <text x="572" y="76" font-size="11" font-weight="600">3 body to the card</text>
+    <text x="572" y="94" font-size="10" class="gx-dim">1 KB pieces, by the</text>
+    <text x="572" y="108" font-size="10" class="gx-dim">storage task</text>
+
+    <rect class="gx-box" x="392" y="142" width="150" height="62" rx="6"/>
+    <text x="404" y="162" font-size="11" font-weight="600">4 connection</text>
+    <text x="404" y="178" font-size="11" font-weight="600">  closed</text>
+    <text x="404" y="194" font-size="10" class="gx-dim">~45 KB back</text>
+
+    <rect class="gx-box" x="560" y="142" width="170" height="62" rx="6"/>
+    <text x="572" y="162" font-size="11" font-weight="600">5 into memory</text>
+    <text x="572" y="178" font-size="10" class="gx-dim">as far as 40 KB allows;</text>
+    <text x="572" y="194" font-size="10" class="gx-dim">bigger: windowed</text>
+
+    <path class="gx-line" d="M374 89 H388" marker-end="url(#gx-arrow)"/>
+    <path class="gx-line" d="M542 89 H556" marker-end="url(#gx-arrow)"/>
+    <path class="gx-line" d="M645 122 V128 H467 V138" marker-end="url(#gx-arrow)"/>
+    <path class="gx-line" d="M542 173 H556" marker-end="url(#gx-arrow)"/>
+
+    <path class="gx-line-hot" d="M166 55 H206" marker-end="url(#gx-arrow-hot)"/>
+    <text class="f-accent" x="172" y="48" font-size="10">URL</text>
+    <path class="gx-line-hot" d="M645 204 V260 H91 V94" marker-end="url(#gx-arrow-hot)"/>
+    <text class="f-accent" x="300" y="254" font-size="10">the page, or a window of it</text>
+
+    <rect class="gx-warn" x="224" y="142" width="150" height="62" rx="6"/>
+    <text class="f-red" x="236" y="162" font-size="11" font-weight="600">changed?</text>
+    <text x="236" y="178" font-size="10" class="gx-dim">stop; the App shows</text>
+    <text x="236" y="194" font-size="10" class="gx-dim">both, and asks</text>
+    <path class="gx-line-bad" d="M299 122 V138" marker-end="url(#gx-arrow-bad)"/>
+
+    <text x="16" y="300" font-size="11" class="gx-dim">No card: steps 3 and 5 happen in memory instead, under the same two floors.</text>
+  </g>
+</svg>

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

@@ -0,0 +1,169 @@
++++
+title = '''A browser in the RAM IRC left over'''
+description = '''roro9stack gets a Gemini client: pages over TLS with trust on first use, links, search prompts, bookmarks, and pages saved to the SD card to read offline. On a device where IRC already holds most of the memory, every page goes through the card, and the big ones are read from it as you scroll.'''
+date = 2026-10-05T02:10:00+02:00
+
+[extra]
+topics = '''ESP32-S3 · Gemini · TLS'''
+read_label = '''Read it, offline if you like →'''
+uid = '''<b>gemini:</b> 20 text/gemini, 1184 bytes'''
+dek = "Gemini is a small internet: text pages, links, one request per TLS connection, no cookies, no scripts, no ads. It's the obvious thing to browse from a [keyboard computer](/devlog/roro9stack/) with a 240×135 screen. It took one night to write. Most of that night went into a question Gemini itself never asks: where do you put a 31 KB page when the largest free block of memory is 31 KB, and IRC wants it too?"
+byline = '''designed by interrogation, then by two decisions I hadn't planned to make, and one I had to take back'''
+
+[extra.sign]
+label = "Times the heap fell to 436 bytes"
+note = "It got up again. Most of us did."
+count = "1"
+tone = "red"
+
+[[extra.cast]]
+name = "Gemini"
+role = "port 1965, TLS, text/gemini"
+text = "A protocol from 2019 that fits in a page: send a URL and CRLF, get a status line and a body. Its page format, gemtext, has six kinds of line, which is exactly as many as a 40-column screen needs."
+
+[[extra.cast]]
+name = "The capsules"
+role = "geminiprotocol.net, Kennedy, Cosmos, Bubble"
+text = "Gemini's sites are called capsules. These four were the test bench: the project's own, a search engine, an aggregator that redirects, and a bulletin board full of emoji my fonts can't draw."
+
+[[extra.cast]]
+name = "The heap"
+role = "about 68 KB free with IRC connected"
+text = "What's left once Wi-Fi, IRC over TLS, the screen and the debug tools have taken theirs. A second TLS connection needs about 45 KB of it, for a while."
+
+[[extra.cast]]
+name = "The SD card"
+role = "7.3 GB, mostly empty"
+text = "Where the memory problem went to be solved. Pages stream through it, and Saved Pages live on it."
++++
+
+## TL;DR
+
+- **A Gemini App** on the Cardputer: gemtext rendered for a 40-column screen, Tab between links, Enter to follow, Back to where you were, `g` for an address.
+- **Trust on first use**, as Gemini expects: each capsule's certificate is pinned the first time; if it changes, the page stops and a dialog shows both fingerprints.
+- **Redirects, input prompts (searching works) and server errors** handled; links to the web are refused politely.
+- **Bookmarks** with `b`, and **Saved Pages** with `s`, or `S` for a page and everything it links to on the same capsule. They're listed on the start page and **read offline**.
+- **Every page streams through the SD card**, so it arrives whole even with IRC connected, and **pages bigger than memory are read from the card as you scroll**.
+- Two memory floors, measured on the device, and one dip I decided to accept.
+- Tagged **v0.5.0**; the code is [on my Gitea](https://git.twis.la/twisla/roro9stack/src/tag/v0.5.0).
+
+## Why Gemini
+
+The Cardputer already talks IRC and walks the Wi-Fi spectrum. A browser was the natural next app, and the web, with its megabyte pages and its JavaScript, is not something an ESP32-S3 with 340 KB of RAM should be asked to render. Gemini is. A page is a text file. A request is one line. The format is so small that the [whole specification](https://geminiprotocol.net/docs/protocol-specification.gmi) reads in a coffee break, and the community writes for exactly this kind of screen: gemlogs, link lists, bulletin boards, search engines, all in plain text.
+
+It also wasn't on the plan. Milestone three, the LoRa radio, was next, so this became a side milestone, **G1**, with the same routine as the others: questions first, tests first, measured on the device.
+
+## The cast
+
+{{ cast() }}
+
+## Designed by interrogation, round four
+
+Sixteen questions this time, Q70 to Q85: trust on first use, which responses to handle, how big a page can be, how gemtext should look on 240 pixels, which keys do what, what the start page shows. Then a late request of my own: **save pages to the card to read later, offline**. That added four more questions (Q82 to Q85) and a word to the glossary. A *Saved Page* is kept until you delete it, and Storage Clean-up never offers it by age, the same rule as Notes: you chose to keep it.
+
+Two more questions came up only once the device had answered some of mine, and one of those I answered twice. They're the memory story below.
+
+## The parsers, tested first
+
+Before any network code, three small parsers, host-tested like everything else in this project:
+
+- **URLs.** A gemtext link is usually relative (`docs/faq.gmi`, `../`, `?q`), so the client has to resolve it the way RFC 3986 says, dot segments and all. The [resolver](https://git.twis.la/twisla/roro9stack/src/tag/v0.5.0/lib/gemini/src/gemini_url.cpp#L61) passes the RFC's own 32 reference examples, normal and abnormal, with `gemini://` in place of `http://`. `../../../g` from three levels deep is `gemini://a/g`, in case you were wondering. Nobody ever is, until a link breaks.
+- **The response header:** two digits, a space, up to 1024 bytes of meta. `20 text/gemini; charset=utf-8` is a page, `31 gemini://…` a redirect, `10 Enter search query` a prompt.
+- **Gemtext**, line by line: three heading levels, lists, quotes, links, and preformatted blocks between ` ``` ` lines, where nothing is interpreted.
+
+Then a fourth piece I hadn't planned, for the fonts. They're Latin-1: accents fine, emoji and CJK not. So text goes through a filter that keeps everything up to U+00FF and turns the rest into `?`. Bubble, the bulletin board, labels its links with emoji, and on the Cardputer they read `? Subspaces` and `? Help`. Honest, if not pretty.
+
+## A fetch, and whose certificate it is
+
+{{ diagram(src="fetch.svg", min_width=580, caption="One fetch, start to finish. The App never waits: a TLS handshake takes a second or two, and the main loop's watchdog bites after five.") }}
+
+Each fetch runs on a short-lived task of its own. A TLS handshake can take two seconds, and the main loop has a watchdog since the last milestone. Also, an idle browser should cost nothing, not a 6 KB stack sitting around waiting.
+
+Gemini capsules mostly use self-signed certificates, so checking them against a certificate authority would reject half of Geminispace. The convention is **trust on first use**: the first time the Cardputer meets a capsule, it [pins the certificate's SHA-256](https://git.twis.la/twisla/roro9stack/src/tag/v0.5.0/src/services/gemini_service.cpp#L100) in NVS. If the certificate is ever different, the page doesn't load; a dialog shows the old and new fingerprints and asks. The IRC client already did exactly this for self-signed IRC servers, so it was a matter of doing it again, per host and port, under a key short enough for NVS's 15-character limit (two letters and 12 hex digits of a hash).
+
+{{ figure(src="gemini-browse.png", alt="Four Cardputer screens at 2x in a grid. Top left: the Gemini start page, with a help line, Bookmarks, and a bookmarked Project Gemini link. Top right: Project Gemini's home page, the title in blue, Gemini in 100 words in bold, and wrapped text. Bottom left: further down the page, a link highlighted: Or, if you'd prefer, here's a video overview. Bottom right: the same screen after pressing Enter on it, with Not Gemini: https://www.youtube.com/watch?v=DoE in orange where the URL was", width=976, height=556, landscape=true, full=true, caption=`The start page, Project Gemini, a selected link, and what happens when that link is to YouTube. Captured over Wi-Fi with the Debug Console's screenshot command.`) }}
+
+## Where to put a page
+
+This is where the night went.
+
+The first version read the body into one `std::string`. Then Cosmos, an aggregator, came back cut short at 8.7 KB with 107 KB free. Two reasons. Growing a string copies it into a block twice its size, and my check, rightly, refused to let that happen near the floor. Worse: with IRC connected, the largest free block of memory is about **31 KB**. A 64 KB page in one piece was never going to happen, however much memory was free in total.
+
+So a page became a [`TextBuffer`](https://git.twis.la/twisla/roro9stack/src/tag/v0.5.0/lib/gemini/src/text_buffer.h#L13): lines packed into 4 KB chunks, with an index of 6 bytes per line. No big block, no doubling copies. Storing each line as its own string would have cost about 40 bytes a line in overhead; on a 400-line page, that's a page.
+
+Then the next wall. While the TLS connection is open it holds about 45 KB, so a single "stay above 40 KB" check during the download left room for barely 20 KB of page, and with IRC connected, none. Cosmos stopped at **4.6 KB**. But the connection's memory comes back the moment it closes. So, first decision: **two floors**. Above 40 KB once the page is in; above 20 KB while the connection is open. And no fetch starts below 55 KB free.
+
+Without IRC, Cosmos now arrived whole: 31.6 KB, 419 lines. With IRC, it still stopped at 4.6 KB, because during the transfer the heap sits right at the 20 KB line. Second decision: **every page streams to the card**. While the connection is open, the body goes to a cache file on the SD card in 1 KB pieces, each written by the storage task, which owns every card access. Only once the connection has closed and given its 45 KB back is the page loaded into memory, as much of it as the steady floor allows. Cosmos with IRC connected: the whole page on the card, 20 KB of it on screen.
+
+And the rest of it? That was "Cut short: only part of it fits in memory", until I asked for the obvious.
+
+## Reading from the card as you scroll
+
+{{ diagram(src="window.svg", min_width=580, caption="A page bigger than memory: indexed once, read a window at a time. Cosmos with IRC connected: 226 of its 419 lines in memory, then lines 192 to 419, then back to 64 and 0 as I scrolled up again.") }}
+
+Opening a page that doesn't fit, [one pass over its file](https://git.twis.la/twisla/roro9stack/src/tag/v0.5.0/src/services/gemini_service.cpp#L705) counts the lines and notes where every 64th one starts, plus whether it's inside a preformatted block, so a window starting there knows how to draw it. That's 4 bytes per 64 lines: about 1 KB for a 1 MB page. The same pass loads the first window. Scroll near the end of it and the next window is read in the background, starting at the index entry just before the line on top of the screen, so what you're reading doesn't move. The scrollbar follows your place in the whole page, not the window. Tab, at the last link in memory, pages down instead of wrapping to the top.
+
+The first window read while scrolling held 20 lines. Its budget was computed with the old window still in memory, so it got what was left beside it. Now the request says how much the old window will give back. The next window was 227 lines: the whole rest of the page.
+
+Pages for the screen alternate between two cache files, so the page you're reading is never overwritten by the next fetch. Background jobs, like saving a capsule's linked pages, use a third.
+
+{{ figure(src="cosmos.png", alt="Cosmos on the Cardputer at 2x, deep into the page: a line ending situación de calle [Crónica], then links including Ploum.net ? Ah ouais, quand même, on en est là?! and Ploum.net ? Les mécanismes de compensation carbone expliqués à mon hamster, with a scrollbar on the right about two thirds down", width=480, height=270, caption=`Two thirds of the way down Cosmos, read from the card with IRC connected. Accents fine, emoji as question marks, hamsters explained.`) }}
+
+## The dip I accepted
+
+{{ diagram(src="memory.svg", min_width=580, caption="Free heap around one fetch with IRC connected. Before, during the handshake, while the body streams to the card, and once the connection has closed and the page is loaded.") }}
+
+With IRC's TLS connection open and a Gemini one alongside, the lowest free heap during a fetch came out at 24 KB the first time I measured it, then 19.5, 15.5 and **13 KB**. Same page, same code. The receive buffers grow with the size of the records the server sends, so the dip depends on the other end. My own code keeps its allocations above 20 KB; the TLS stack doesn't ask.
+
+The options were: refuse to fetch below 70 KB, which with IRC connected would refuse almost every fetch; close IRC's connection for every page; or accept a dip to about 12 KB for a second or two. I took the third. It's written down with the numbers, in the plan's own words, as a decision and not an accident.
+
+## Saved Pages
+
+{{ figure(src="gemini-tools.png", alt="Four Cardputer screens at 2x in a grid. Top left: an input prompt over a page, Enter search query, with an empty input box. Top right: Kennedy search results, 'cardputer' - ? Kennedy Search, 2 matches on ? Image Search, Showing 1 - 15 of 87 results, 1. M5Stack Cardputer. Bottom left: a Saved Page, the URL bar reading saved 2026-10-05 01:13, a quote line Saved from gemini://geminiprotocol.net/docs/faq.gmi on 2026-10-05 01:13, then Project Gemini FAQ. Bottom right: a dialog, Certificate changed, geminiprotocol.net now shows a different certificate, with Cancel and Trust it buttons", width=976, height=556, landscape=true, full=true, caption=`Kennedy's search prompt and its 87 results for "cardputer"; a Saved Page, which says where and when it came from; and the dialog for a changed certificate, which I faked by pinning a wrong fingerprint on purpose.`) }}
+
+`s` copies the page from the cache file to `/gemini/saved/<capsule>/<path>.gmi`, with one line added at the top: `> Saved from <url> on <date>`. It shows as a quote, so you know what you're reading, and it gives relative links their base. `S` saves the page and everything it links to on the same capsule, up to 30 pages, in the background with progress Toasts: Project Gemini and its five linked pages, six of six, in about twenty seconds.
+
+The start page lists them by capsule, newest first. Inside a Saved Page, a link to another saved page opens the saved copy, and anything else goes online if it can, or says "Not saved, and offline" if it can't. `r` refreshes a Saved Page from the network, `d` deletes it after asking.
+
+## Where it hurt
+
+- **The bug from [the first post](/devlog/roro9stack/), again.** A status message ("Not Gemini: https://…") was cleared before it was ever drawn. It was timestamped with `millis()` after the main loop had read the clock, and in unsigned arithmetic, three milliseconds in the future is 49 days ago. That's exactly the bug that made toasts expire before they appeared in [the first post](/devlog/roro9stack/). Same fix: a signed comparison. Same feeling.
+- **A space where none was.** Wrapped link and list lines are indented, which meant re-wrapping their continuation rows. I rebuilt that text by joining the rows with spaces, so a long URL the first wrap had cut mid-word came out as `faq.gm i`. Now it re-wraps the exact rest of the line.
+- **436 bytes.** The refresh job needed to know where a Saved Page came from, so it opened the page, all of it, next to the App's copy of the same page and a fresh TLS connection. The heap's lowest point since boot: 436 bytes. Nothing crashed, which is less reassuring than it sounds. Now it reads one line, and the 55 KB start floor guards every fetch, not just the ones the App asks for. Lowest afterwards: 53.8 KB.
+- **The same trap, twice in one milestone.** A forward declaration of `NetworkClientSecure` inside the project's namespace declares a different class that doesn't exist. I'd made that mistake in the Debug Console two milestones ago. I made it again, in the same way, and the compiler explained it again, at the same length.
+- **Antenna is down.** The aggregator I meant as a default bookmark doesn't answer, from the Cardputer or from my PC. Cosmos took its place, and its redirect became the test case for redirects.
+
+## By the numbers
+
+{% table() %}
+| | |
+| --- | --- |
+| Commits from v0.4.0 to v0.5.0 | 9 |
+| Lines added | about 2,400, 223 of them tests |
+| Tests | 338, 14 of them new |
+| Release firmware | 1.71 MB of 3.3 MB, 127 KB more than v0.4.0 |
+| A fetch, from Enter to page | 0.7 to 2.2 s, mostly the TLS handshake |
+| Cosmos with IRC connected | 31.6 KB on the card, 226 of 419 lines in memory at first |
+| Index for a windowed page | 4 bytes per 64 lines |
+| Search results for "cardputer" | 87 |
+| Lowest free heap during a fetch with IRC | 13 KB, accepted |
+| Lowest free heap, ever, this milestone | 436 bytes, fixed |
+{% 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, with Saved Pages to read offline.~~ v0.5.0, this post.
+
+5. Next, M3: the LoRa radio. The first thing this device will ever transmit.
+{% end %}
+
+{% signoff() %}
+The Cardputer now carries a small library on its SD card: capsules saved on the train, read on the plane, refreshed when Wi-Fi comes back. All of it in the memory IRC wasn't using.
+{% end %}

site/content/devlog/roro9stack-gemini/memory.svg

@@ -0,0 +1,33 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 290" role="img" aria-label="Free heap around one Gemini fetch of Cosmos with IRC connected over TLS. About 68 KB before the fetch, above the 55 KB start floor. During the TLS handshake it dips to between 24 KB in the best run and 13 KB in the worst, under the 20 KB the firmware keeps for its own allocations: that dip, from the TLS receive buffers, is accepted. While the body streams to the card, about 21 KB. After the connection closes and part of the page is loaded, 43 KB, above the 40 KB steady floor.">
+  <g font-family="JetBrains Mono, ui-monospace, monospace" fill="currentColor">
+    <line class="gm-grid" x1="70" y1="230" x2="740" y2="230"/>
+    <g font-size="10" class="gm-dim" text-anchor="end">
+      <text x="62" y="233">0</text><text x="62" y="173">20</text><text x="62" y="113">40</text><text x="62" y="53">60 KB</text>
+    </g>
+    <!-- y = 230 - 3 * KB -->
+    <line class="gm-floor s-muted" x1="70" y1="65" x2="740" y2="65"/>
+    <text x="736" y="60" font-size="10" text-anchor="end" class="gm-dim">55 KB: no fetch starts below</text>
+    <line class="gm-floor s-yellow" x1="70" y1="110" x2="740" y2="110"/>
+    <text class="f-yellow" x="736" y="123" font-size="10" text-anchor="end">40 KB: left once the page is in</text>
+    <line class="gm-floor s-green" x1="70" y1="170" x2="740" y2="170"/>
+    <text class="f-green" x="736" y="165" font-size="10" text-anchor="end">20 KB: the firmware's own allocations</text>
+
+    <path class="gm-step" d="M80 26 H230 V158 H260 V167 H480 V101 H730"/>
+    <path class="gm-worst" d="M230 26 V191 H260"/>
+
+    <g font-size="11" text-anchor="middle">
+      <text x="155" y="20">68 KB</text>
+      <text class="f-accent" x="245" y="152">24</text>
+      <text class="f-red" x="245" y="208">13</text>
+      <text x="370" y="161">~21 KB</text>
+      <text x="605" y="95">43 KB, page loaded</text>
+    </g>
+    <g font-size="11" text-anchor="middle" class="gm-dim">
+      <text x="155" y="252">before</text>
+      <text x="245" y="252">handshake</text>
+      <text x="370" y="252">body to the card</text>
+      <text x="605" y="252">closed, loaded</text>
+    </g>
+    <text x="70" y="280" font-size="10" class="gm-dim">Measured on the device, Debug Build, IRC on TLS. Dashed red: the worst handshake seen. Accepted.</text>
+  </g>
+</svg>

site/content/devlog/roro9stack-gemini/window.svg

@@ -0,0 +1,37 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 260" role="img" aria-label="Reading a page bigger than memory. On the card, the page's file of 419 lines. Opening it, one pass records where every 64th line starts, and whether it's inside a preformatted block: 7 entries, 4 bytes each. In memory, a window of about 226 lines, of which the screen shows 8 rows. Scrolling near the end of the window asks for the next window, starting at the index entry before the line on top, so what's on screen stays; near the top, the previous one.">
+  <defs>
+    <marker id="gw-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>
+  </defs>
+  <g font-family="JetBrains Mono, ui-monospace, monospace" fill="currentColor">
+    <text x="16" y="24" font-size="12" font-weight="600">on the card: the page, 419 lines</text>
+    <rect class="gw-box" x="16" y="36" width="728" height="34" rx="4"/>
+    <!-- 419 lines over 728 px: 1.737 px a line; ticks every 64 lines (111 px) -->
+    <g>
+      <line class="gw-tick" x1="16" y1="70" x2="16" y2="80"/><line class="gw-tick" x1="127" y1="70" x2="127" y2="80"/>
+      <line class="gw-tick" x1="238" y1="70" x2="238" y2="80"/><line class="gw-tick" x1="349" y1="70" x2="349" y2="80"/>
+      <line class="gw-tick" x1="461" y1="70" x2="461" y2="80"/><line class="gw-tick" x1="572" y1="70" x2="572" y2="80"/>
+      <line class="gw-tick" x1="683" y1="70" x2="683" y2="80"/>
+    </g>
+    <g font-size="10" class="gw-dim" text-anchor="middle">
+      <text x="16" y="92">0</text><text x="127" y="92">64</text><text x="238" y="92">128</text><text x="349" y="92">192</text>
+      <text x="461" y="92">256</text><text x="572" y="92">320</text><text x="683" y="92">384</text>
+    </g>
+    <text x="16" y="112" font-size="11" class="gw-dim">index: where every 64th line starts (and if it's in a ``` block): 7 x 4 bytes</text>
+
+    <rect class="gw-hot" x="349" y="38" width="393" height="30" rx="3"/>
+    <rect class="gw-screen" x="420" y="40" width="14" height="26"/>
+    <text x="356" y="58" font-size="10">in memory: lines 192 to 419</text>
+
+    <text x="16" y="150" font-size="12" font-weight="600">in memory: one window</text>
+    <rect class="gw-hot" x="16" y="160" width="460" height="40" rx="6"/>
+    <rect class="gw-screen" x="96" y="164" width="70" height="32" rx="3"/>
+    <text x="104" y="184" font-size="10">screen</text>
+    <text x="180" y="185" font-size="11">~226 lines, as text in 4 KB chunks</text>
+
+    <path class="gw-line" d="M476 180 H520" marker-end="url(#gw-arrow)"/>
+    <text x="528" y="176" font-size="11">near the end: the next window,</text>
+    <text x="528" y="192" font-size="11" class="gw-dim">from the index entry before the</text>
+    <text x="528" y="208" font-size="11" class="gw-dim">line on top, so the screen stays</text>
+    <text x="16" y="236" font-size="11" class="gw-dim">Near the top: the previous one. The scrollbar follows the line, over the whole page.</text>
+  </g>
+</svg>

site/content/devlog/roro9stack-gnss/gnss-flow.svg

@@ -0,0 +1,53 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 330" role="img" aria-label="The GNSS data path. The receiver on the Cap, an ATGM336H on the AT6668 chip, tracks GPS, GLONASS, Galileo, BeiDou and QZSS and sends NMEA once a second, about 450 bytes a second, over a UART at 115200 baud into GPIO 15. Commands go back on GPIO 13: PCAS12 for standby, PCAS10 to wake. The GNSS Service reads the UART on the main loop's tick every 50 milliseconds and feeds the NMEA parser, which checks checksums and handles RMC, GGA, GSA and GSV across constellations. The result is one GNSS state: the Fix, the position, UTC time and the satellites. Four things use it: the GNSS App with its Position and Sky views, the Status Bar mark, the clock, where GNSS outranks NTP, and Tracks, written as GPX to the SD card.">
+  <defs>
+    <marker id="gf-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="gf-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="gf-panel" x="16" y="100" width="180" height="130" rx="8"/>
+    <text x="30" y="124" font-size="12" font-weight="600">the receiver</text>
+    <text x="30" y="144" font-size="11">ATGM336H, AT6668</text>
+    <text x="30" y="162" font-size="11" class="gf-dim">GPS GLONASS Galileo</text>
+    <text x="30" y="178" font-size="11" class="gf-dim">BeiDou QZSS</text>
+    <text x="30" y="200" font-size="11">NMEA, 1 Hz</text>
+    <text x="30" y="216" font-size="11" class="gf-dim">about 450 B/s</text>
+
+    <rect class="gf-hot" x="250" y="40" width="240" height="250" rx="8"/>
+    <text x="264" y="64" font-size="12" font-weight="600">GNSS Service</text>
+    <text x="264" y="84" font-size="11" class="gf-dim">read every 50 ms tick</text>
+    <rect class="gf-box" x="264" y="98" width="212" height="74" rx="6"/>
+    <text x="276" y="120" font-size="12" font-weight="600">NMEA parser</text>
+    <text x="276" y="140" font-size="11">RMC GGA GSA GSV</text>
+    <text x="276" y="158" font-size="11" class="gf-dim">checksums, constellations</text>
+    <path class="gf-line" d="M370 172 V194" marker-end="url(#gf-arrow)"/>
+    <rect class="gf-box" x="264" y="198" width="212" height="78" rx="6"/>
+    <text x="276" y="220" font-size="12" font-weight="600">GNSS state</text>
+    <text x="276" y="240" font-size="11">Fix, position, UTC,</text>
+    <text x="276" y="258" font-size="11">satellites (merged)</text>
+
+    <path class="gf-line-hot" d="M196 140 H246" marker-end="url(#gf-arrow-hot)"/>
+    <text class="f-accent" x="200" y="132" font-size="10">RX 15</text>
+    <path class="gf-line" d="M246 196 H200" marker-end="url(#gf-arrow)"/>
+    <text x="200" y="214" font-size="10" class="gf-dim">TX 13</text>
+    <text x="30" y="252" font-size="10" class="gf-dim">commands on TX 13:</text>
+    <text x="30" y="266" font-size="10" class="gf-dim">$PCAS12 sleep, $PCAS10 wake</text>
+
+    <rect class="gf-box" x="540" y="24" width="204" height="56" rx="6"/>
+    <text x="552" y="46" font-size="12" font-weight="600">GNSS App</text>
+    <text x="552" y="66" font-size="11" class="gf-dim">Position, Sky</text>
+    <rect class="gf-box" x="540" y="96" width="204" height="56" rx="6"/>
+    <text x="552" y="118" font-size="12" font-weight="600">Status Bar</text>
+    <text x="552" y="138" font-size="11" class="gf-dim">G17, REC</text>
+    <rect class="gf-box" x="540" y="168" width="204" height="56" rx="6"/>
+    <text x="552" y="190" font-size="12" font-weight="600">Clock</text>
+    <text x="552" y="210" font-size="11" class="gf-dim">GNSS outranks NTP</text>
+    <rect class="gf-box" x="540" y="240" width="204" height="56" rx="6"/>
+    <text x="552" y="262" font-size="12" font-weight="600">Tracks</text>
+    <text x="552" y="282" font-size="11" class="gf-dim">GPX on the SD card</text>
+
+    <path class="gf-line" d="M476 236 H510 V52 H536" marker-end="url(#gf-arrow)"/>
+    <path class="gf-line" d="M510 124 H536" marker-end="url(#gf-arrow)"/>
+    <path class="gf-line" d="M510 196 H536" marker-end="url(#gf-arrow)"/>
+    <path class="gf-line" d="M510 236 V268 H536" marker-end="url(#gf-arrow)"/>
+  </g>
+</svg>

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

@@ -0,0 +1,242 @@
++++
+title = '''Seventeen satellites, and 47 KB down the back of the sofa'''
+description = '''roro9stack learns where it is: a GNSS receiver read in the background, a sky view of every satellite overhead, the clock set from space, and Tracks recorded to the SD card. Then a memory hunt that found 47 KB the firmware didn't know it was wasting.'''
+date = 2026-10-04T23:55:00+02:00
+
+[extra]
+topics = '''ESP32-S3 · GNSS · Memory'''
+read_label = '''Read where it went →'''
+uid = '''<b>gnss:</b> Fix 3D, 17 satellites used'''
+dek = "Milestone two for [roro9stack](/devlog/roro9stack/), my firmware for the M5Stack Cardputer: the GNSS receiver on its LoRa cap. It now knows where it is, what time it is without a network, and which of the satellites overhead it's listening to, and it records where it's been. Along the way the documentation got the pins wrong, a test silenced the receiver until I pulled the plug, and the debug tools from [the last post](/devlog/roro9stack-ota/) turned out to be eating the memory they were supposed to watch."
+byline = '''designed by interrogation again: 12 questions, and one answer the code from milestone zero knew better'''
+
+[extra.sign]
+label = "Bugs fixed by turning it off and on again"
+note = "Only one. It still counts."
+count = "1"
+tone = "red"
+
+[[extra.cast]]
+name = "The receiver"
+role = "ATGM336H-6N, AT6668"
+text = "On the Cap LoRa-1262, next to the radio: a multi-constellation GNSS receiver with a ceramic antenna, talking NMEA over a UART at 115200 baud. It also listens, to commands nobody documents where I looked."
+
+[[extra.cast]]
+name = "The satellites"
+role = "GPS, GLONASS, Galileo, BeiDou, QZSS"
+text = "Up to 23 in view from my desk, and 18 of them in one Fix. Four constellations at once, colour-coded, because a sky view in one colour is just a scatter plot."
+
+[[extra.cast]]
+name = "The heap"
+role = "about 340 KB, no PSRAM"
+text = "Shared by Wi-Fi, TLS, the screen buffer, eight tasks and a receiver. The real antagonist of this post."
+
+[[extra.cast]]
+name = "The window"
+role = "the only antenna upgrade I own"
+text = "Indoors the receiver saw one satellite. Moved to the windowsill, it saw seventeen."
++++
+
+## TL;DR
+
+- The Cap's **GNSS receiver** is read in the background by a new GNSS Service, through my own NMEA parser (17 tests, fed with lines captured from the device).
+- A **GNSS App** shows the position (decimal degrees or degrees-minutes-seconds, plus the Maidenhead locator) and a **sky view**: every satellite by direction and elevation, coloured by constellation.
+- The **clock is set from satellites** once there's a Fix, Wi-Fi or not. The **Status Bar** says `G17` with a 3D Fix of 17 satellites.
+- **Tracks** record to GPX on the SD card in the background, and survive a power cut.
+- **Off means off:** Settings → GNSS puts the receiver in real standby, with commands found by experiment.
+- From cold, a 3D Fix by the window takes **73 s**.
+- Then the **memory hunt**: with IRC on TLS, the lowest free heap was 12.6 KB, against a 40 KB floor. Measured stacks, no more mDNS and rebuilt TLS buffers bring it to **59 KB**. Free memory went from 31 KB to 78 KB.
+- Tagged **v0.4.0**; the code is [on my Gitea](https://git.twis.la/twisla/roro9stack/src/tag/v0.4.0).
+
+## Why GNSS, and why now
+
+A mesh messenger wants to know where its nodes are, and a device with no battery-backed clock wants the time from somewhere other than Wi-Fi. Both come from the same little receiver on the back of the Cap. It's also the smallest of the hardware milestones: no transmitting, no regulations, just listening to satellites, which are famously patient.
+
+The plan also promised a "radar view". In M2 that means the sky: where the satellites are. The other kind of radar, other people's nodes by distance and direction, needs the mesh, so it waits for M4.
+
+## The cast
+
+{{ cast() }}
+
+## Designed by interrogation, round three
+
+Twelve questions this time, Q58 to Q69, each with a recommendation to accept or overrule. GNSS on by default, with a Settings switch. Two views, switched with Tab. Tracks started by hand, written as GPX, a point every 5 s once you've moved 5 m. Coordinates in decimal degrees with the Maidenhead locator alongside, because once you've owned a radio you never stop wanting to know your grid square. And the position never leaves the device, at least until the mesh exists and we decide how precisely to share it.
+
+One answer didn't survive contact with the code. Q62 said GNSS would set the clock only when NTP hadn't. But the clock model, written back in milestone zero, already ranks its sources by trust, Mesh below NTP below GNSS. A source can only replace the time if it's at least as trusted as the one that set it, which is right: GNSS time comes from atomic clocks in orbit. The plan now admits the code from three days earlier knew better.
+
+## Finding the receiver
+
+M5Stack's page for the Cap says the GNSS UART is on GPIO 8 and 9. Meshtastic, which already supports this exact hardware, says 15 and 13. On the Cardputer ADV, GPIO 8 and 9 are the internal I2C bus the keyboard controller sits on, so the page is wrong, and opening a UART there would have unplugged the keyboard in software.
+
+So, measure. A temporary `gnss probe` command listened on the candidate pins at two baud rates:
+
+```
+gnss probe: rx 15 tx 13 at 115200: 537 bytes, 16 NMEA lines
+  $GNRMC,200231.00,V,,,,,,,041026,,,N,V*1A
+  $GNGGA,200231.00,,,,,0,00,25.5,,,,,,*48
+  $GNGSA,A,1,,,,,,,,,,,,,25.5,25.5,25.5,1*01
+  $GPGSV,1,1,01,25,41,108,17,1*58
+  $GLGSV,1,1,00,1*78
+gnss probe: rx 13 tx 15 at 115200: 0 bytes, 0 NMEA lines
+```
+
+Receive on 15, transmit on 13, 115200 baud. Indoors, one GPS satellite, no Fix. Good enough to start.
+
+The probe had a flaw I didn't see: to be thorough, it also tried the pins the other way round. For a second, the ESP32 drove the receiver's *output* line. An hour later, the GNSS Service I'd written read zero bytes. I suspected my code first, naturally, then ran the original probe again: zero bytes there too, on code that had worked. Hot start, cold start: nothing. An ESP32 restart doesn't cut power to the Cap, so the receiver had stayed in whatever sulk it was in since the probe.
+
+Fix: unplug USB, switch off, wait ten seconds, switch on. The receiver came back, and the Service, which had been running all along, read 31,618 bytes and 1,008 sentences without a single bad checksum. Have you tried turning it off and on again: one point to the helpdesk. The milestone plan now says it in so many words: never drive GPIO 15.
+
+## NMEA, as this receiver speaks it
+
+{{ diagram(src="gnss-flow.svg", min_width=580, caption="The receiver talks; the GNSS Service listens from the main loop, every 50 ms, which a 512-byte UART buffer covers with room to spare at 450 bytes a second. Commands go back the other way for standby and wake.") }}
+
+NMEA is a text protocol from the 1980s: one comma-separated sentence per line, ending in a checksum. The receiver sends a burst once a second: where it is (RMC, GGA), which satellites it uses (GSA) and which it can see (GSV). TinyGPSPlus, the library the first decision record named, handles the position fine but doesn't keep the satellite list across constellations, and the sky view is made of exactly that. So [the parser](https://git.twis.la/twisla/roro9stack/src/tag/v0.4.0/lib/gnss/src/nmea_parser.cpp) is my own, about 230 lines, written test-first, and it learned three things from this receiver:
+
+- **One GSA per constellation.** The receiver sends a GSA sentence for each system, with a system ID in its last field: 1 for GPS, 2 GLONASS, 3 Galileo, 4 BeiDou, 5 QZSS. That ID matters, because satellite numbers aren't unique across systems: GPS 5 and BeiDou 5 are different satellites in different orbits.
+- **One satellite, two bands.** The AT6668 is multi-frequency, so a GPS satellite can be listed once for its L1 signal and again for L5. The parser keeps each GSV sequence per constellation and band, then [merges them](https://git.twis.la/twisla/roro9stack/src/tag/v0.4.0/lib/gnss/src/nmea_parser.cpp#L193-L233), keeping the stronger signal.
+- **Time without a Fix.** RMC carries a date and time even when its status says `V`, not valid: the receiver's own clock, of unknown quality. The parser only trusts it with a Fix.
+
+{{ diagram(src="satellites.svg", min_width=580, caption="Satellites are merged by constellation and number across bands, then marked as used from the GSA of their own system.") }}
+
+## Off, by experiment
+
+Q58 said Settings → GNSS Off should really switch the receiver off, if it accepted a command for it. It speaks CASIC's `$PCAS` commands, but the search for its standby command found mostly military aircraft. So: experiment, with a safety net. If `$PCAS12,<seconds>` meant "standby for that long", a 5-second value would make the receiver come back by itself even if nothing else worked. Bytes received each second:
+
+```
+t= 1.1 s  +216 bytes
+t= 2.3 s  +0
+t= 3.3 s  +0
+t= 4.4 s  +0
+t= 5.5 s  +120
+t= 6.7 s  +743
+t= 7.8 s  +470
+```
+
+Standby, then back on its own after 5 s. A second test showed any command wakes it within a second, and that 65,535 seconds is accepted. So [Off](https://git.twis.la/twisla/roro9stack/src/tag/v0.4.0/src/services/gnss_service.cpp#L42-L58) sends `$PCAS12,65535` (about 18 hours, renewed every hour just in case), and On sends a hot start, `$PCAS10,0`, which wakes it and keeps everything it knew. Switched back on, it has a Fix again within seconds.
+
+## The GNSS App
+
+{{ figure(src="gnss-app.png", alt="Four Cardputer screens at 2x in a grid. Top left: the GNSS App's Position view, reading 3D Fix, 18 of 21 satellites, then Lat 50.86928 degrees N, Lon 4.25353 degrees E, Locator JO20du, Altitude 52 m, Speed 0.1 km/h, HDOP 0.9, Time 21:45:07 UTC, with r: record a Track and Tab: sky at the bottom; the Status Bar shows G18. Top right: the Sky view, a circle with N, E, S and W, rings for 30 and 60 degrees of elevation, and coloured dots for satellites, filled when used, hollow when not; the legend reads GPS 7/10, GLONASS 5/5, Galileo 1/1, BeiDou 4/5, and 3D Fix. Bottom left: the Position view while recording, REC in orange in the Status Bar and REC 1 point, 13 s, r: stop at the bottom. Bottom right: Settings, with GNSS On and Coordinates Decimal near the end of the list", width=976, height=556, landscape=true, full=true, caption=`The Position view, the Sky view, a Track recording, and the two new settings. All captured over Wi-Fi with the Debug Console's screenshot command, and yes, that's my desk.`) }}
+
+**Position** is the receiver's state in a form a human can use: the Fix and how many satellites it uses out of how many it sees, then latitude and longitude, the Maidenhead locator, altitude, speed (and heading once you're moving faster than 1 km/h, below which it's noise), HDOP and UTC. HDOP is the receiver's own estimate of how good the satellite geometry is: under 1 is excellent, which is what four constellations at once buy you. The formatting, the locator and the sky projection are host-tested, with the locator checked against known squares (FN31pr for the ARRL station W1AW, JN58td for Munich).
+
+**Sky** is the radar: the zenith in the middle, the horizon on the circle, north up. Each satellite is a dot in its constellation's colour, filled if the Fix uses it, hollow if the receiver sees it but doesn't (yet). The legend counts used and in view per constellation. It's the most useless and most satisfying screen in the firmware: nothing on it changes what you do, and you'll watch it anyway.
+
+With GNSS off, the App says so and where to turn it back on, and the Status Bar mark disappears.
+
+{{ figure(src="m2-off.png", alt="The GNSS App with GNSS off: GNSS is off, and under it, Settings > GNSS turns it on. The Status Bar has no G mark", width=480, height=270, caption=`Off is off: no G in the Status Bar, and the receiver asleep.`) }}
+
+## The clock, and a first Fix after zero seconds
+
+The clock had been set by NTP since milestone one. Now the GNSS Service sets it with a Fix and refreshes it every 10 minutes, so the Cardputer knows the time in a field with no Wi-Fi, and logs get the right date.
+
+The first time I checked the time to first Fix, the console said:
+
+```
+gnss: first Fix after 0 s
+gnss: clock set
+```
+
+Very impressive, and meaningless: the ESP32 had restarted for an update, but the receiver, still powered by the Cap, had kept its Fix the whole time. A real cold start (`$PCAS10,2`, forget everything) by the window: **73 seconds** to a 3D Fix. Normal for a cold start, and it only happens once per power-up.
+
+## Tracks
+
+Press `r` in the GNSS App and a **Track** starts: GPX on the SD card, a point every 5 seconds once you've moved 5 metres (haversine, tested), so standing still doesn't fill the card. It keeps recording with the App closed, says `REC` in the Status Bar, and announces start and stop with a Toast. Tracks are treated like Captures: something you start, so they keep writing past the 90 % card usage where Logs pause.
+
+GPX is XML, and XML has a footer. A Track cut short by a dead battery or a crash would lack its closing tags, and every GPX reader would refuse the whole file. So at boot, the GNSS Service [looks for unfinished Tracks](https://git.twis.la/twisla/roro9stack/src/tag/v0.4.0/src/services/gnss_service.cpp#L139) and closes them. Tested the honest way: start a Track, then restart the device mid-recording.
+
+```
+gnss: Track /gnss/tracks/20261004-204450.gpx started
+debug: restarting now
+gnss: closed 1 unfinished Track(s)
+```
+
+The file opened as valid GPX 1.1 on the PC, points and all.
+
+## The memory hunt
+
+With everything working, the last "done when" item was memory: free heap above 40 KB with GNSS, Wi-Fi, IRC on TLS and the UI all running. In v0.2.1, before any of the update and debug work, the lowest point had been 79 KB. Now:
+
+```
+irc: status 4, unread 0, heap 33092 min 12632
+```
+
+33 KB free, 12.6 KB at the lowest. GNSS was innocent: it costs a 512-byte buffer and a parser. The culprits were the [last post](/devlog/roro9stack-ota/)'s own features: a task for updates, a task and a log ring for the Debug Console, a bigger stack for checking signatures on the SD card, bigger serial buffers, mDNS, two TCP servers. The tools for watching the device had been eating its memory. Every sysadmin has met a monitoring agent like that.
+
+{{ diagram(src="memory.svg", min_width=580, caption="Free heap with IRC connected over TLS, and the lowest point since boot, in a Debug Build. The lowest point finally clears the floor once the TLS buffers shrink.") }}
+
+**Stacks, measured.** Every task gets a fixed stack when it's created, and most were sized by guessing generously. FreeRTOS records each task's lowest free stack, so I pushed each through its worst case first: an ECDSA-checked install over Wi-Fi and one from the SD card (a tampered file, so the full check runs but nothing restarts), file transfers, a core dump fetch, an IRC TLS handshake. Then I read the marks:
+
+{% table() %}
+| Task | Stack | Peak used | Now |
+| --- | --- | --- | --- |
+| main loop | 8 KB | 3.0 KB | 6 KB |
+| update | 8 KB | 3.4 KB | 5 KB |
+| storage | 10 KB | 3.9 KB | 6 KB |
+| irc | 8 KB | 4.0 KB | 6 KB |
+{% end %}
+
+Then the same worst cases again on the smaller stacks: every task kept at least 1.6 KB free. With the log ring and two serial buffers trimmed too, that bought 15 KB, which wasn't enough: the lowest point was still 18 KB.
+
+**mDNS, gone.** The device announced itself as `roro9stack-2fa4.local`, a name that never once worked from my dev box, because the VM reaches the Cardputer through a routed network that mDNS doesn't cross. 7.5 KB back, and pushes go to the IP the Firmware page shows, as they always had.
+
+**TLS, rebuilt.** The big one. Arduino-ESP32 ships its ESP-IDF libraries prebuilt, with one configuration for every board, and that configuration gives each TLS connection a 16 KB receive buffer *and* a 16 KB send buffer, for life. A TLS record can be 16 KB, so receiving needs it. Sending IRC lines doesn't. Those sizes are compiled into the libraries, so changing them means rebuilding the framework. pioarduino calls that a hybrid compile: list the settings in `platformio.ini`, and the build regenerates the libraries from ESP-IDF first ([ADR 0006](https://git.twis.la/twisla/roro9stack/src/tag/v0.4.0/docs/adr/0006-framework-rebuilt-for-smaller-tls-buffers.md)):
+
+{% code(caption="[platformio.ini](https://git.twis.la/twisla/roro9stack/src/tag/v0.4.0/platformio.ini#L23-L32): receive stays 16 KB, send drops to 4 KB, and buffers come and go as needed.") %}
+```ini
+custom_sdkconfig =
+    CONFIG_MBEDTLS_ASYMMETRIC_CONTENT_LEN=y
+    CONFIG_MBEDTLS_SSL_IN_CONTENT_LEN=16384
+    CONFIG_MBEDTLS_SSL_OUT_CONTENT_LEN=4096
+    CONFIG_MBEDTLS_DYNAMIC_BUFFER=y
+    CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA=y
+    CONFIG_MBEDTLS_DYNAMIC_FREE_CA_CERT=y
+```
+{% end %}
+
+The first attempt downloaded ESP-IDF, installed 31 Python packages, configured everything, and died on `Missing partition table file /work/default_8MB.csv`: in this mode the project must own its partition table. It's now in the repository, checked byte for byte against the one in the device's flash, because moving the app slots under a firmware that updates itself would be a creative way to brick it. The second attempt took 3 minutes 56 seconds, and later builds are back under a minute.
+
+A rebuilt framework is a lot of change underneath, so before trusting it I checked the regenerated configuration still had everything the firmware leans on: rollback, core dumps to flash, the 5-second task watchdog, task statistics, the certificate bundle. All there, plus a surprise: the rebuild follows the board definition, so support for PSRAM the Cardputer doesn't have is off too. Then the whole stress set again. Result: **78 KB free with IRC connected, 59 KB at the lowest**, and 46 KB under the heaviest pile-up I could manage all at once.
+
+**And IRC can stop now.** Testing all this, I noticed IRC could only really be stopped while connected: `/quit` did nothing while it was retrying or waiting for Wi-Fi, and opening the App reconnected anyway. Now `/quit` and a new `irc stop` work in any state, a stopped IRC stays stopped until you type a line, and stopping it gives its 40-odd KB back.
+
+## Smaller bruises
+
+- **A UI driven blind.** My screenshots come from the frame the UI composes off-screen, and the UI doesn't redraw while the display is off. So a screenshot taken a minute after the last key press shows whatever the screen showed a minute ago, and the first key after that only wakes the screen. For a while I thought my key presses were going to the wrong app. They were going nowhere.
+- **The wrong firmware said "confirmed".** My test loop waited until the device reported its update confirmed, then measured. Once, the new build had failed to compile, so the old firmware, never replaced, happily said "confirmed", and I took careful screenshots of an App that didn't exist yet. The loop now waits for the version it pushed.
+- **One wrong include.** The GNSS App's first build failed with dozens of identical errors about an incomplete type. One missing header. Compilers have never learned to say it once.
+
+## By the numbers
+
+{% table() %}
+| | |
+| --- | --- |
+| Commits from v0.3.0 to v0.4.0 | 12 |
+| Lines added | about 1,650 |
+| Tests | 324, 31 of them new |
+| Release firmware | 1.58 MB of 3.3 MB (47 %) |
+| NMEA from the receiver | about 450 bytes a second, one Fix a second |
+| Cold start to a 3D Fix, by the window | 73 s |
+| Most satellites in one Fix | 18 of 21, HDOP 0.9 |
+| Free heap with IRC on TLS | 31 → 78 KB |
+| Lowest free heap | 12.6 → 59 KB |
+| First build with the rebuilt framework | 3 min 56 s |
+{% end %}
+
+## Where it stands
+
+{% steps() %}
+1. ~~M0: the skeleton, and M1: Wi-Fi, IRC and 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, with Position and Sky views, the clock from satellites, Tracks, and the memory to run it all with IRC.~~ v0.4.0, this post.
+
+4. Next, M3: the LoRa radio on the same Cap, with a scanner, plus notes and a file browser. The first time anything on this device transmits, so the Region setting from milestone zero finally gets to say no to something.
+
+5. Then M4 and M5, the mesh, and with it the other radar: nodes by distance and direction.
+{% end %}
+
+{% signoff() %}
+The Cardputer knows where it is, what time it is, and which satellites are listening, and it has its memory back. Next, it learns to talk.
+{% end %}

site/content/devlog/roro9stack-gnss/memory.svg

@@ -0,0 +1,41 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 300" role="img" aria-label="Free heap with IRC connected over TLS, Debug Build, at four stages, against a 40 KB floor. When M2 began: 31 KB free, 12.6 KB at the lowest. After trimming stacks and buffers by measurement: 46 KB free, 18.4 KB lowest. After removing mDNS: 54 KB free, 33.8 KB lowest. After shrinking the TLS buffers: 77.7 KB free, 59.1 KB lowest, the first time the lowest point clears the floor.">
+  <g font-family="JetBrains Mono, ui-monospace, monospace" fill="currentColor">
+    <line class="mm-grid" x1="70" y1="240" x2="740" y2="240"/>
+    <line class="mm-grid" x1="70" y1="190" x2="740" y2="190"/>
+    <line class="mm-grid" x1="70" y1="90" x2="740" y2="90"/>
+    <line class="mm-grid" x1="70" y1="40" x2="740" y2="40"/>
+    <g font-size="10" class="mm-dim" text-anchor="end">
+      <text x="62" y="243">0</text><text x="62" y="193">20</text><text x="62" y="143">40 KB</text>
+      <text x="62" y="93">60</text><text x="62" y="43">80</text>
+    </g>
+    <line class="mm-floor" x1="70" y1="140" x2="740" y2="140"/>
+    <text class="f-yellow" x="736" y="133" font-size="10" text-anchor="end">floor</text>
+
+    <rect class="mm-free" x="106" y="162.5" width="44" height="77.5" rx="2"/>
+    <rect class="mm-low-bad" x="158" y="208.5" width="44" height="31.5" rx="2"/>
+    <rect class="mm-free" x="273" y="125" width="44" height="115" rx="2"/>
+    <rect class="mm-low-bad" x="325" y="194" width="44" height="46" rx="2"/>
+    <rect class="mm-free" x="441" y="105" width="44" height="135" rx="2"/>
+    <rect class="mm-low-bad" x="493" y="155.5" width="44" height="84.5" rx="2"/>
+    <rect class="mm-free" x="608" y="45.75" width="44" height="194.25" rx="2"/>
+    <rect class="mm-low-ok" x="660" y="92.25" width="44" height="147.75" rx="2"/>
+
+    <g font-size="11" text-anchor="middle">
+      <text x="128" y="156">31</text><text x="180" y="202">12.6</text>
+      <text x="295" y="119">46</text><text x="347" y="188">18.4</text>
+      <text x="463" y="99">54</text><text x="515" y="153">33.8</text>
+      <text x="630" y="40">77.7</text><text x="682" y="86">59.1</text>
+    </g>
+    <g font-size="11" text-anchor="middle">
+      <text x="154" y="260">M2 begins</text>
+      <text x="321" y="260">stacks trimmed</text>
+      <text x="489" y="260">mDNS removed</text>
+      <text x="656" y="260">TLS buffers</text>
+    </g>
+    <rect class="mm-free" x="232" y="278" width="12" height="12" rx="2"/>
+    <text x="250" y="288" font-size="11">free, IRC connected</text>
+    <rect class="mm-low-bad" x="420" y="278" width="12" height="12" rx="2"/>
+    <rect class="mm-low-ok" x="434" y="278" width="12" height="12" rx="2"/>
+    <text x="452" y="288" font-size="11">lowest since boot</text>
+  </g>
+</svg>

site/content/devlog/roro9stack-gnss/satellites.svg

@@ -0,0 +1,49 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 270" role="img" aria-label="How the satellite list is built. GSV sequences arrive per constellation and per signal band: GPS on L1 lists satellites 5, 13 and 15; GPS on L5 lists 5 and 13 again; GLONASS lists 70. The parser keeps each sequence until its last message, then merges them by constellation and satellite number, keeping the stronger signal: GPS 5 at 42 dB-Hz rather than 30, GPS 13, GPS 15, GLONASS 70. Then the GSA sentences, one per constellation with a system ID in their last field, mark which satellites the Fix uses: system 1, GPS, uses 5 and 13. GPS 5 and BeiDou 5 are different satellites, which is why the system ID matters.">
+  <defs>
+    <marker id="sv-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>
+  </defs>
+  <g font-family="JetBrains Mono, ui-monospace, monospace" fill="currentColor">
+    <text x="16" y="22" font-size="12" font-weight="600">GSV, per constellation and band</text>
+    <rect class="sv-box" x="16" y="36" width="270" height="44" rx="6"/>
+    <text x="28" y="54" font-size="11">$GPGSV … signal 1 (L1)</text>
+    <text x="28" y="70" font-size="11" class="sv-dim">5 (30)  13 (35)  15 (30)</text>
+    <rect class="sv-box" x="16" y="92" width="270" height="44" rx="6"/>
+    <text x="28" y="110" font-size="11">$GPGSV … signal 8 (L5)</text>
+    <text x="28" y="126" font-size="11" class="sv-dim">5 (42)  13 (33)</text>
+    <rect class="sv-box" x="16" y="148" width="270" height="44" rx="6"/>
+    <text x="28" y="166" font-size="11">$GLGSV … signal 1</text>
+    <text x="28" y="182" font-size="11" class="sv-dim">70 (33)</text>
+
+    <text x="16" y="222" font-size="12" font-weight="600">GSA, one per system ID</text>
+    <rect class="sv-box" x="16" y="232" width="270" height="30" rx="6"/>
+    <text x="28" y="252" font-size="11">$GNGSA,A,3,05,13,…,1 → GPS</text>
+
+    <path class="sv-line" d="M286 58 H330 V112 H356" />
+    <path class="sv-line" d="M286 114 H356" marker-end="url(#sv-arrow)"/>
+    <path class="sv-line" d="M286 170 H330 V116" />
+    <text x="300" y="98" font-size="10" class="sv-dim">merge</text>
+
+    <rect class="sv-hot" x="360" y="36" width="230" height="156" rx="8"/>
+    <text x="374" y="60" font-size="12" font-weight="600">satellites in view</text>
+    <circle class="sv-used" cx="382" cy="83" r="4"/>
+    <text x="394" y="87" font-size="11">GPS 5     42 dB-Hz</text>
+    <circle class="sv-used" cx="382" cy="107" r="4"/>
+    <text x="394" y="111" font-size="11">GPS 13    35 dB-Hz</text>
+    <circle cx="382" cy="131" r="4" fill="none" stroke="currentColor" stroke-opacity=".6"/>
+    <text x="394" y="135" font-size="11">GPS 15    30 dB-Hz</text>
+    <circle cx="382" cy="155" r="4" fill="none" stroke="currentColor" stroke-opacity=".6"/>
+    <text x="394" y="159" font-size="11">GLONASS 70  33 dB-Hz</text>
+    <text x="374" y="182" font-size="10" class="sv-dim">filled: in the Fix</text>
+
+    <path class="sv-line" d="M286 247 H475 V196" marker-end="url(#sv-arrow)"/>
+    <text x="300" y="240" font-size="10" class="sv-dim">marks used</text>
+
+    <text x="610" y="70" font-size="11" class="sv-dim">One satellite on</text>
+    <text x="610" y="86" font-size="11" class="sv-dim">two bands counts</text>
+    <text x="610" y="102" font-size="11" class="sv-dim">once, with its</text>
+    <text x="610" y="118" font-size="11" class="sv-dim">stronger signal.</text>
+    <text x="610" y="150" font-size="11" class="sv-dim">GPS 5 and BeiDou 5</text>
+    <text x="610" y="166" font-size="11" class="sv-dim">are different</text>
+    <text x="610" y="182" font-size="11" class="sv-dim">satellites.</text>
+  </g>
+</svg>

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

@@ -0,0 +1,218 @@
++++
+title = '''The loudest thing it hears is itself'''
+description = '''roro9stack switches on its LoRa radio, receive only: a Radio Service that shares the SD card's bus, a Scanner that decodes Meshtastic headers and records Wireshark captures, and a Sweep of the whole band. It works, and in an hour outside it heard exactly nothing, mostly over the noise of its own electronics.'''
+date = 2026-10-05T21:00:00+02:00
+
+[extra]
+topics = '''ESP32-S3 · LoRa · Meshtastic'''
+read_label = '''Read what it's listening to →'''
+uid = '''<b>radio:</b> 0 packets, 0 bad CRC, 0 radio errors'''
+dek = "Milestone three for [roro9stack](/devlog/roro9stack/), my firmware for the M5Stack Cardputer: the LoRa radio on its Cap, the one this whole project was bought for. This milestone only listens; the mesh comes after. The radio works, the Scanner works, the captures open in Wireshark. What it has heard, after an hour outside, is the noise of the Cardputer's own electronics, which turns out to be louder than anything else in Brussels."
+byline = '''designed by interrogation, round five: 16 questions, and a milestone I cut in half before writing a line'''
+
+[extra.sign]
+label = "Packets received from another device"
+note = "After an hour outside. Still zero."
+count = "0"
+tone = "red"
+
+[[extra.cast]]
+name = "The radio"
+role = "Semtech SX1262 on the Cap LoRa-1262"
+text = "868 to 923 MHz, a 1.8 V temperature-compensated crystal, an RP-SMA antenna. It identifies itself as an SX1261, which every SX1262 does. Nobody knows why; everybody's code checks for it anyway."
+
+[[extra.cast]]
+name = "The expander"
+role = "PI4IOE5V6408 at I2C 0x43"
+text = "A tiny I/O chip on the Cap with one job that matters: its pin P0 connects the antenna. At power-on it doesn't. The project that supports this exact hardware never mentions it."
+
+[[extra.cast]]
+name = "The neighbours"
+role = "6 Meshtastic nodes within 30 km"
+text = "According to meshmap.net, with positions blurred by a few kilometres on purpose. Two within 10 km, the nearest about 5 km east. None of them has been heard from yet."
+
+[[extra.cast]]
+name = "The noise"
+role = "about 15 dB of it, home-made"
+text = "Broadband, flat across the band, with a comb of steady spikes on top. It followed the Cardputer outside, onto the battery, and mostly stayed when Wi-Fi went off."
++++
+
+## TL;DR
+
+- **The radio works, receive only.** A Radio Service owns the SX1262 on its own task and shares the SPI bus with the SD card. Nothing in the firmware can transmit: the function doesn't exist.
+- **The antenna needs switching on.** P0 of an I/O expander on the Cap connects it. Without that the receiver is deaf, reading a flat -112 dBm. Meshtastic's board file for this hardware doesn't mention it; M5Stack's page does.
+- **A LoRa Scanner App:**
+  - The **Sniffer** lists packets and decodes the Meshtastic header, which is never encrypted.
+  - **Captures** are pcap files with LoRaTap headers, and Wireshark reads them field by field.
+  - **Sweep** draws the whole 863–870 MHz band as bars and a waterfall.
+- **Testing found two older bugs, both fixed:**
+  - The Debug Console's file upload could silently write 3 KB of zeros to the card.
+  - The Gemini client left less memory than it promised on big pages.
+- **It heard nothing.** Twenty minutes at the desk on Meshtastic's channel and three LoRaWAN frequencies, then an hour outside on battery: zero packets and zero headers. The noise floor is about 15 dB above what the chip hears on its own, and Sweep says most of that is the Cardputer itself.
+- Tagged **v0.6.0**; the code is [on my Gitea](https://git.twis.la/twisla/roro9stack/src/tag/v0.6.0), and the plan with every measurement is [docs/milestones/M3.md](https://git.twis.la/twisla/roro9stack/src/tag/v0.6.0/docs/milestones/M3.md).
+
+## Why it only listens
+
+The plan from [the first post](/devlog/roro9stack/) put the mesh last: receiving in M4, transmitting in M5, and before that, a second Meshtastic device to test against. M3 is the radio coming up: drivers, the shared bus, a scanner. It needs nothing to talk to, which is lucky, because I have nothing to talk to.
+
+I checked anyway. meshmap.net publishes the nodes that report to the internet. I downloaded the whole list and filtered it on my own machine, so my position stayed home. Within 10 km of my desk there are two nodes; within 30 km, six, all seen that day. The map blurs positions by a few kilometres, and it only shows nodes that report online, so there are probably more. Whether any of them reaches a small antenna in a city is another question. Spoiler: no.
+
+## The cast
+
+{{ cast() }}
+
+## Designed by interrogation, round five
+
+Sixteen questions, Q89 to Q104. The first one cut the milestone in half. The original M3 also had Notes and a file browser. Since then, the file browser had grown into a proper design of its own, in the project's issue tracker. So M3 became the radio only, and the other two moved out to issues #3 and #19 for later. The radio is the risky part, and nothing else in the milestone needed it.
+
+The rest settled how it would work:
+
+- a Radio Service that owns the chip;
+- Meshtastic's LongFast settings by default (869.525 MHz, 250 kHz, spreading factor 11);
+- the Meshtastic header decoded, but not the encrypted payload;
+- captures in a format Wireshark reads;
+- a Sweep that pauses the Sniffer while it runs.
+
+One decision mattered more than the others. **The Radio Service has no transmit function.** It isn't unused: it doesn't exist. Nothing in M3 can put this device on the air by accident, because there's no code for it to do so with. Safety by absence, the only kind that survives a tired developer at 1 am.
+
+## The antenna that wasn't
+
+Step one is always a probe: a console command that asks the hardware what it is before any real code trusts it. `lora probe` found the chip on the pins Meshtastic uses. The chip identified itself as `SX1261 V2D 2D02`, which is what every SX1262 says. Its 1.8 V crystal worked on the first try, and it was ready in 38 ms.
+
+Then it measured how much noise it could hear, and that was suspiciously little: a flat -111.9 dBm. That's the sound of a receiver listening to itself.
+
+The two sources disagreed:
+
+- **Meshtastic's board file** says the radio drives its own antenna switch through its DIO2 pin, and that's all.
+- **M5Stack's page** says the switch is enabled by pin P0 of an I/O expander on the Cap's I2C bus. It gives no address for the expander.
+
+The probe scanned the bus and found the expander at 0x43, its pin P0 configured as an input, so not driving anything. With P0 set high, the noise jumped to -87 to -94 dBm: the antenna, finally hearing the room. DIO2 made no difference to reception either way; it most likely picks transmit or receive inside the switch.
+
+So the Radio Service [sets P0 high at boot](https://git.twis.la/twisla/roro9stack/src/tag/v0.6.0/src/services/radio_service.cpp#L25). Without it, this radio would have listened politely to its own thoughts forever, and I'd have blamed the neighbours.
+
+## One task to own it
+
+{{ diagram(src="radio.svg", min_width=600, caption="Who touches what. The radio task is the only code that talks to the chip; the main loop only asks. The card and the radio share one SPI bus and one lock. The expander sits on the I2C bus with the keyboard, so only the main loop touches it.") }}
+
+The radio is shared, slow to talk to, and interrupt-driven, all at once. So it gets one owner. The radio task does every SPI transfer to the chip, under the same bus lock the SD card uses. The radio's interrupt line (DIO1) only wakes that task; nothing happens in the interrupt itself. The main loop posts requests ("listen", "use this preset", "sweep") and reads the packets the task leaves in a ring of 32.
+
+That ring takes 9.8 KB, and only while something is listening. When nobody is, the radio sleeps and the memory goes back. RadioLib and all of this cost 24 KB of flash.
+
+The I/O expander is on the I2C bus that the keyboard also uses. Rather than share a bus between tasks, everything on it stays on the main loop. One owner per bus. I learned that rule the hard way in M2 and didn't fancy learning it twice.
+
+## The bus test that caught someone else
+
+The risk of sharing a bus is that two users corrupt each other's traffic. So the test was a 1.7 MB file uploaded to the card over Wi-Fi while the radio listened, then read back and compared.
+
+It differed. Bytes 188,416 to 191,487, exactly six 512-byte sectors, had come back as zeros.
+
+Blaming the radio would have been easy. But the same test with the radio asleep failed too, in a different place. And the console's log had the answer: `put: write failed at 191488, retry 1`.
+
+Here's what happened:
+
+1. The card occasionally refuses a write.
+2. The upload code's retry closed the file, which threw away the last 3 KB still sitting in the write buffer.
+3. It then *truncated the file up* to the length it thought it had written. Truncating a file to a larger size fills the gap with zeros.
+4. The SHA-256 check covered the bytes received over the network, not what landed on the card, so it passed.
+
+The checksum was checking the postman, not the letterbox. This bug came from the OTA milestone and had been waiting for someone to look.
+
+Now the upload [reads the file back from the card and hashes it](https://git.twis.la/twisla/roro9stack/src/tag/v0.6.0/src/services/debug_console.cpp#L268), and a retry that finds lost data gives up instead of papering over it. The card still refuses a write about once in five 1.7 MB uploads, with the radio listening or asleep. With the radio listening, four uploads in a row came back intact.
+
+The same test also caught the Gemini client leaving 1.5 to 3 KB less memory than its 40 KB promise on large pages, radio or no radio. Its budget counted the page text and forgot the App's own tables. That's fixed too.
+
+## Nothing to hear
+
+With the radio up and the bus proven, I listened for twenty minutes:
+
+- On LongFast.
+- On the three frequencies LoRaWAN sensors use (868.1, 868.3 and 868.5 MHz), at spreading factors 7, 9 and 12. Brussels is full of those sensors, and I hoped one would at least wave.
+
+**Zero packets. Zero headers, valid or broken.**
+
+The radio also flags "preamble detected" when something looks like the start of a packet. It flagged 25 in two minutes on LongFast, which looked hopeful. So I ran a control on 869.0 MHz, where nobody transmits LoRa: 97 detections in two minutes. False alarms, then. Noise that happens to look like a preamble.
+
+## Proving the ears work without a voice
+
+Zero is a suspicious number. If the interrupt never reached the task, the result would look exactly like this.
+
+The chip can prove its own interrupt without any transmitter: [start a receive with a 100 ms timeout](https://git.twis.la/twisla/roro9stack/src/tag/v0.6.0/src/services/radio_service.cpp#L434), route the timeout to DIO1, and see whether the task wakes. It woke after 105 ms. So the antenna, the radio, the interrupt and the task are all fine, and the silence is real.
+
+To test everything after the radio, Debug Builds got `lora inject`. It puts a made-up packet into the ring as if it had been received, and nothing goes on the air. That made the App and the captures testable.
+
+A capture made on the device opens in TShark with every field right: time, frequency, spreading factor, RSSI, SNR and payload. One detail took a second look. The LoRaTap spec says packet RSSI below 0 dB SNR is stored in quarter dB, a formula from older chips. Wireshark ignores that rule and reads plain dBm. I went with Wireshark, since that's who reads the files.
+
+## The Scanner
+
+{{ figure(src="scanner.png", alt="Four Cardputer screens at 2x in a grid. Top left: the LoRa Scanner listening on LongFast 869.525 MHz, noise -97, with No packets yet and Meshtastic nodes in range show here. Top right: three test packets injected from the console, newest first, with time, RSSI and SNR, the first a 3-byte packet, the second d3c4>0b0a 1/3 and the third 5678>all 0/3, CAP 3 at the top right and CAP in the Status Bar. Bottom left: the details of the second packet: 20:14:39, 20 bytes, -117 dBm, SNR -9.2 dB, noise -85, 869.5250 MHz, then From !a1b2d3c4 to !0d0c0b0a, Packet 04030201, wants an ack, Hops 1 of 3, limit 2 left, Channel 0x08 (LongFast, default key), Relayed by ..aa, and the first line of the hex dump. Bottom right: Sweep at the desk, bars across 863 to 870 MHz with peak-hold dots and a dotted line at 869.525 MHz, a mostly blue waterfall with a brighter column near 863.2 MHz, and floor -100, 863.2 MHz at -89 dBm", width=976, height=556, landscape=true, full=true, caption=`The Scanner: listening, a list (of packets I injected from the console, since the real world hasn't sent any), one packet's details with its Meshtastic header, and Sweep at the desk.`) }}
+
+The Sniffer lists packets newest first:
+
+- time, RSSI and SNR on every row;
+- for Meshtastic packets, also who sent it to whom, by the last four hex digits Meshtastic uses as a default name, and how many hops it took.
+
+Enter shows [the details](https://git.twis.la/twisla/roro9stack/src/tag/v0.6.0/lib/lora/src/packet_view.cpp#L51): the full node numbers, the packet ID, whether it wants an acknowledgement, the hops, the channel (hash 0x08 is LongFast with the public default key), the node that relayed it, and a hex dump. `p` picks one of the seven Meshtastic presets allowed in Europe. `c` starts a capture, which keeps recording after you leave the App.
+
+## Sweep, and the loudest thing in the room
+
+[Sweep](https://git.twis.la/twisla/roro9stack/src/tag/v0.6.0/src/services/radio_service.cpp#L256) steps across 863–870 MHz in 100 kHz steps and reads the signal strength at each, a full pass every 0.6 seconds. At the desk, the band came back flat at -100 to -102 dBm, with a steady carrier at 863.2 MHz. Flat noise across the band is the signature of digital electronics nearby, not of a transmitter. My desk has plenty of candidates, so I asked for the Cardputer to be taken outside, on battery.
+
+{{ diagram(src="sweep-outside.svg", min_width=600, caption="One Sweep pass outside, on battery. The same spikes come back on every pass, several of them 400 kHz apart. The one at 869.4 MHz sits right on the lower edge of LongFast's channel.") }}
+
+Outside wasn't quieter. It was slightly *louder*, and the spikes were still there, in the same places, pass after pass. A noise source that follows the device outside and onto its battery is in the device.
+
+Then Wi-Fi went off for a minute, read from the screen since my connection went with it: -99 to -100 dBm, against -97 with it on. Two or three decibels, no more.
+
+{{ diagram(src="noise.svg", min_width=600, caption="What the radio hears with nothing transmitting, all at 125 kHz. The antenna-off figure was measured at 250 kHz and scaled.") }}
+
+So about 15 dB of the noise floor is the Cardputer's own: the processor, the display, the SD card, its power supply, all within a few centimetres of the antenna. One suspect is the radio itself: the spike at 864.0 MHz is exactly the 27th harmonic of its own 32 MHz crystal. A suspect, not a verdict.
+
+What 15 dB costs: LoRa at spreading factor 11 decodes down to about 17 dB below the noise floor. On this Cardputer that's roughly -114 dBm, against about -130 for a quiet receiver. In a city that divides the range by something like three to five. A node across the street will get through; one 5 km away, through Brussels, probably won't.
+
+## The hour outside
+
+From 20:33 to 21:34 the Cardputer sat outside on its battery, listening on LongFast with a capture running, while I checked on it every five minutes over Wi-Fi.
+
+Zero packets. Zero headers. Zero radio errors. The noise stayed at -85 to -87 dBm for the whole hour, the preamble detector cried wolf 860 times, and the capture file ended at 24 bytes: a pcap header, and nothing to put after it. The firmware, at least, didn't blink: no restart, 93 KB free.
+
+The design round had a rule for this (Q104): if the hour hears nothing, M3 closes anyway, and a Meshtastic node of my own becomes a requirement for the next milestone. So that's what happens. One item on the checklist stays half done, and I'd rather say so than tick it: Sweep was never pointed at a *known* transmitter, like a car key. It shows the floor and the Cardputer's own spikes; nobody has keyed a real signal in front of it yet.
+
+## Where it stands
+
+{% steps() %}
+1. ~~Step 1: the probe, and the antenna that needed switching on.~~
+
+2. ~~Step 2: the Meshtastic header, presets and captures, tested on the PC against Meshtastic's own source and TShark.~~
+
+3. ~~Step 3: the Radio Service, and the bus test that found the upload bug.~~
+
+4. ~~Step 4: the Scanner App, with captures that outlive it.~~
+
+5. ~~Step 5: Sweep, and finding out who's making all that noise.~~
+
+6. ~~Step 6: an hour of listening, outside. It heard nothing.~~ v0.6.0.
+
+7. Next, M4: receiving the mesh. It needs a Meshtastic node of my own, sitting a metre away, where even this receiver can't miss it. The self-noise has an issue of its own (#20): switch things off one at a time, Sweep, and find out which part of the Cardputer is shouting.
+{% end %}
+
+## By the numbers
+
+{% table() %}
+| | |
+| --- | --- |
+| Design questions | 16 (Q89 to Q104) |
+| Tests | 365, 27 of them new |
+| Flash cost of the radio, Scanner and Sweep | about 52 KB (1.72 MB of 3.3 MB) |
+| RAM while listening | 9.8 KB (the packet ring), nothing when idle |
+| Radio task stack, peak | 2.0 KB |
+| A Sweep pass, 863–870 MHz | 71 steps, 0.6 s |
+| Noise floor at 125 kHz: chip alone / desk / outside | about -115 / -101 / -97 dBm |
+| Zeros the upload bug wrote | 3,072 bytes, now none |
+| Free memory with the radio listening and IRC connected | 52.6 KB, above the 40 KB floor |
+| The listening hour | 61 minutes, 860 false alarms |
+| Packets from another device | 0 |
+{% end %}
+
+{% signoff() %}
+The radio is up, it listens, it records, it draws the band in colour. All it needs now is someone to say something, louder than it talks to itself.
+{% end %}

site/content/devlog/roro9stack-lora/noise.svg

@@ -0,0 +1,37 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 250" role="img" aria-label="The noise floor at 125 kHz with nothing transmitting. With the antenna switched off, the chip hears only itself: -112 dBm at 250 kHz, about -115 at 125 kHz. At the desk, on USB with Wi-Fi on, the band sits at -101 dBm. Outside on battery with Wi-Fi off, -99.5; with Wi-Fi on, -97. Moving away from the desk didn't help and Wi-Fi accounts for 2 or 3 dB: most of the 15 dB above the chip's own floor comes from the Cardputer itself.">
+  <g font-family="JetBrains Mono, ui-monospace, monospace" fill="currentColor">
+    <line class="nf-grid" x1="250.0" y1="24" x2="250.0" y2="200"/>
+    <text x="250.0" y="216" font-size="10" class="nf-dim" text-anchor="middle">-120</text>
+    <line class="nf-grid" x1="330.0" y1="24" x2="330.0" y2="200"/>
+    <text x="330.0" y="216" font-size="10" class="nf-dim" text-anchor="middle">-115</text>
+    <line class="nf-grid" x1="410.0" y1="24" x2="410.0" y2="200"/>
+    <text x="410.0" y="216" font-size="10" class="nf-dim" text-anchor="middle">-110</text>
+    <line class="nf-grid" x1="490.0" y1="24" x2="490.0" y2="200"/>
+    <text x="490.0" y="216" font-size="10" class="nf-dim" text-anchor="middle">-105</text>
+    <line class="nf-grid" x1="570.0" y1="24" x2="570.0" y2="200"/>
+    <text x="570.0" y="216" font-size="10" class="nf-dim" text-anchor="middle">-100</text>
+    <line class="nf-grid" x1="650.0" y1="24" x2="650.0" y2="200"/>
+    <text x="650.0" y="216" font-size="10" class="nf-dim" text-anchor="middle">-95</text>
+    <line class="nf-grid" x1="730.0" y1="24" x2="730.0" y2="200"/>
+    <text x="730.0" y="216" font-size="10" class="nf-dim" text-anchor="middle">-90</text>
+    <text x="730" y="232" font-size="10" class="nf-dim" text-anchor="end">dBm at 125 kHz: longer is louder</text>
+    <text x="240" y="44" font-size="11" font-weight="600" text-anchor="end">Antenna switched off</text>
+    <text x="240" y="58" font-size="9" class="nf-dim" text-anchor="end">the chip alone: -112 at 250 kHz</text>
+    <rect class="f-green75" x="250" y="34" width="80.0" height="22" rx="3"/>
+    <text x="336.0" y="49" font-size="11">-115</text>
+    <text x="240" y="86" font-size="11" font-weight="600" text-anchor="end">Desk, USB, Wi-Fi on</text>
+    <text x="240" y="100" font-size="9" class="nf-dim" text-anchor="end">Sweep median, 863-870 MHz</text>
+    <rect class="f-accent75" x="250" y="76" width="304.0" height="22" rx="3"/>
+    <text x="560.0" y="91" font-size="11">-101</text>
+    <text x="240" y="128" font-size="11" font-weight="600" text-anchor="end">Outside, battery, Wi-Fi off</text>
+    <text x="240" y="142" font-size="9" class="nf-dim" text-anchor="end">read on the screen</text>
+    <rect class="f-accent75" x="250" y="118" width="328.0" height="22" rx="3"/>
+    <text x="584.0" y="133" font-size="11">-99.5</text>
+    <text x="240" y="170" font-size="11" font-weight="600" text-anchor="end">Outside, battery, Wi-Fi on</text>
+    <text x="240" y="184" font-size="9" class="nf-dim" text-anchor="end">Sweep median</text>
+    <rect class="f-accent75" x="250" y="160" width="368.0" height="22" rx="3"/>
+    <text x="624.0" y="175" font-size="11">-97</text>
+    <path class="s-red15" d="M330.0,196 L554.0,196" marker-end="none"/>
+    <text class="f-red" x="442.0" y="192" font-size="10" text-anchor="middle">about 15 dB of its own</text>
+  </g>
+</svg>

site/content/devlog/roro9stack-lora/radio.svg

@@ -0,0 +1,68 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 300" role="img" aria-label="Who touches the radio. The main loop runs the keys, the App and the Status Bar; it only posts requests to the radio task: listen, preset, sweep, probe. The radio task owns the SX1262 on the Cap and is the only code that talks to it, over SPI under the same bus lock the SD card uses. The radio's DIO1 interrupt only wakes the radio task. Received packets go into a ring of 32, under a lock, which the main loop reads to draw them and to append them to a Capture. The Cap's I/O expander at I2C address 0x43 is touched only by the main loop, which owns the I2C bus with the keyboard: its pin P0 connects the antenna, and without it the receiver is deaf at -112 dBm. The storage task writes the Capture to the SD card, on the same SPI bus as the radio.">
+  <defs>
+    <marker id="rx-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="rx-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="rx-panel" x="16" y="20" width="200" height="100" rx="8"/>
+    <text x="28" y="44" font-size="12" font-weight="600">Main loop</text>
+    <text x="28" y="64" font-size="10" class="rx-dim">keys, the App,</text>
+    <text x="28" y="78" font-size="10" class="rx-dim">the Status Bar;</text>
+    <text x="28" y="92" font-size="10" class="rx-dim">Capture: ring to pcap</text>
+    <text x="28" y="106" font-size="10" class="rx-dim">never touches the radio</text>
+
+    <rect class="rx-hot" x="290" y="20" width="230" height="100" rx="8"/>
+    <text x="302" y="44" font-size="12" font-weight="600">Radio task</text>
+    <text x="302" y="64" font-size="10" class="rx-dim">the only code that talks</text>
+    <text x="302" y="78" font-size="10" class="rx-dim">to the SX1262; packets to a</text>
+    <text x="302" y="92" font-size="10" class="rx-dim">ring of 32, noise every 0.5 s</text>
+    <text class="f-red" x="302" y="106" font-size="10">no transmit function</text>
+
+    <rect class="rx-box" x="590" y="20" width="154" height="100" rx="8"/>
+    <text x="602" y="44" font-size="12" font-weight="600">SX1262</text>
+    <text x="602" y="64" font-size="10" class="rx-dim">on the Cap,</text>
+    <text x="602" y="78" font-size="10" class="rx-dim">869.525 MHz,</text>
+    <text x="602" y="92" font-size="10" class="rx-dim">TCXO 1.8 V</text>
+
+    <!-- main loop <-> radio task -->
+    <path class="rx-line" d="M216,52 L286,52" marker-end="url(#rx-arrow)"/>
+    <text x="222" y="46" font-size="9" class="rx-dim">requests</text>
+    <path class="rx-line" d="M288,92 L218,92" marker-end="url(#rx-arrow)"/>
+    <text x="226" y="106" font-size="9" class="rx-dim">packets</text>
+
+    <!-- radio task <-> SX1262 -->
+    <path class="rx-line-hot" d="M520,52 L586,52" marker-start="url(#rx-arrow-hot)" marker-end="url(#rx-arrow-hot)"/>
+    <text class="f-accent" x="536" y="46" font-size="9">SPI</text>
+    <path class="rx-line" d="M588,96 L524,96" marker-end="url(#rx-arrow)"/>
+    <text x="530" y="110" font-size="9" class="rx-dim">DIO1:</text>
+    <text x="530" y="121" font-size="9" class="rx-dim">wake up</text>
+
+    <!-- the expander, I2C, main loop only -->
+    <rect class="rx-box" x="16" y="190" width="200" height="90" rx="8"/>
+    <text x="28" y="212" font-size="11" font-weight="600">Cap I/O expander</text>
+    <text x="28" y="230" font-size="10" class="rx-dim">PI4IOE5V6408 at 0x43</text>
+    <text class="f-green" x="28" y="246" font-size="10">P0 high: antenna on</text>
+    <text class="f-red" x="28" y="262" font-size="10">P0 low: deaf, -112 dBm</text>
+    <path class="rx-line" d="M116,122 L116,186" marker-end="url(#rx-arrow)"/>
+    <text x="124" y="152" font-size="9" class="rx-dim">I2C, shared with</text>
+    <text x="124" y="164" font-size="9" class="rx-dim">the keyboard</text>
+
+    <!-- storage task and the card -->
+    <rect class="rx-box" x="290" y="190" width="230" height="90" rx="8"/>
+    <text x="302" y="212" font-size="11" font-weight="600">Storage task</text>
+    <text x="302" y="230" font-size="10" class="rx-dim">every card access,</text>
+    <text x="302" y="246" font-size="10" class="rx-dim">Captures as pcap</text>
+    <path class="rx-line" d="M200,122 L300,186" marker-end="url(#rx-arrow)"/>
+    <text x="232" y="174" font-size="9" class="rx-dim">records</text>
+
+    <rect class="rx-box" x="590" y="190" width="154" height="90" rx="8"/>
+    <text x="602" y="212" font-size="11" font-weight="600">SD card</text>
+    <path class="rx-line" d="M520,236 L586,236" marker-start="url(#rx-arrow)" marker-end="url(#rx-arrow)"/>
+    <text x="536" y="230" font-size="9" class="rx-dim">SPI</text>
+
+    <!-- one bus, one lock -->
+    <path class="rx-bus" d="M578,56 L578,232"/>
+    <text class="f-yellow" x="584" y="156" font-size="10">one SPI bus,</text>
+    <text class="f-yellow" x="584" y="170" font-size="10">one lock</text>
+  </g>
+</svg>

site/content/devlog/roro9stack-lora/sweep-outside.svg

@@ -0,0 +1,47 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 290" role="img" aria-label="One Sweep pass outside, on battery, 863 to 870 MHz in 100 kHz steps. The floor sits at about -97 dBm, with narrow peaks that come back at the same frequencies on every pass: 863.2 MHz at -89 dBm, 863.6, 864.4 and 864.8 MHz at -90 to -91, 865.9 at -89, 866.3 at -88, 867.8 at -91, 869.0 at -89 and 869.4 at -88 dBm, right at the lower edge of the LongFast channel, 869.4 to 869.65 MHz. Several of them are 400 kHz apart.">
+  <g font-family="JetBrains Mono, ui-monospace, monospace" fill="currentColor">
+    <rect class="sw-ch" x="682.6" y="40" width="23.9" height="198.0"/>
+    <text class="f-green" x="702.5" y="52" font-size="10" text-anchor="end">LongFast</text>
+    <line class="sw-grid" x1="70" y1="49.0" x2="740" y2="49.0"/>
+    <text x="62" y="52.0" font-size="10" class="sw-dim" text-anchor="end">-85</text>
+    <line class="sw-grid" x1="70" y1="94.0" x2="740" y2="94.0"/>
+    <text x="62" y="97.0" font-size="10" class="sw-dim" text-anchor="end">-90</text>
+    <line class="sw-grid" x1="70" y1="139.0" x2="740" y2="139.0"/>
+    <text x="62" y="142.0" font-size="10" class="sw-dim" text-anchor="end">-95</text>
+    <line class="sw-grid" x1="70" y1="184.0" x2="740" y2="184.0"/>
+    <text x="62" y="187.0" font-size="10" class="sw-dim" text-anchor="end">-100</text>
+    <line class="sw-grid" x1="70" y1="229.0" x2="740" y2="229.0"/>
+    <text x="62" y="232.0" font-size="10" class="sw-dim" text-anchor="end">-105</text>
+    <text x="62" y="28" font-size="10" class="sw-dim" text-anchor="end">dBm</text>
+    <line class="sw-floor" x1="70" y1="157.0" x2="740" y2="157.0"/>
+    <polyline class="sw-line" points="70.0,184.0 79.6,175.0 89.1,85.0 98.7,94.0 108.3,148.0 117.9,157.0 127.4,103.0 137.0,157.0 146.6,175.0 156.1,148.0 165.7,121.0 175.3,157.0 184.9,166.0 194.4,166.0 204.0,103.0 213.6,94.0 223.1,166.0 232.7,130.0 242.3,94.0 251.9,166.0 261.4,193.0 271.0,157.0 280.6,139.0 290.1,166.0 299.7,175.0 309.3,166.0 318.9,148.0 328.4,175.0 338.0,175.0 347.6,85.0 357.1,121.0 366.7,166.0 376.3,175.0 385.9,76.0 395.4,166.0 405.0,175.0 414.6,166.0 424.1,139.0 433.7,166.0 443.3,175.0 452.9,166.0 462.4,157.0 472.0,175.0 481.6,175.0 491.1,148.0 500.7,148.0 510.3,175.0 519.9,148.0 529.4,103.0 539.0,112.0 548.6,166.0 558.1,157.0 567.7,121.0 577.3,157.0 586.9,166.0 596.4,157.0 606.0,103.0 615.6,130.0 625.1,139.0 634.7,148.0 644.3,85.0 653.9,157.0 663.4,166.0 673.0,130.0 682.6,76.0 692.1,157.0 701.7,175.0 711.3,157.0 720.9,139.0 730.4,157.0 740.0,166.0"/>
+    <circle class="f-red" cx="89.1" cy="85.0" r="3"/>
+    <text class="f-red" x="89.1" y="77.0" font-size="9" text-anchor="middle">863.2</text>
+    <circle class="f-red" cx="127.4" cy="103.0" r="3"/>
+    <text class="f-red" x="127.4" y="95.0" font-size="9" text-anchor="middle">863.6</text>
+    <circle class="f-red" cx="204.0" cy="103.0" r="3"/>
+    <text class="f-red" x="204.0" y="95.0" font-size="9" text-anchor="middle">864.4</text>
+    <circle class="f-red" cx="242.3" cy="94.0" r="3"/>
+    <text class="f-red" x="242.3" y="86.0" font-size="9" text-anchor="middle">864.8</text>
+    <circle class="f-red" cx="347.6" cy="85.0" r="3"/>
+    <text class="f-red" x="347.6" y="77.0" font-size="9" text-anchor="middle">865.9</text>
+    <circle class="f-red" cx="385.9" cy="76.0" r="3"/>
+    <text class="f-red" x="385.9" y="68.0" font-size="9" text-anchor="middle">866.3</text>
+    <circle class="f-red" cx="529.4" cy="103.0" r="3"/>
+    <text class="f-red" x="529.4" y="95.0" font-size="9" text-anchor="middle">867.8</text>
+    <circle class="f-red" cx="644.3" cy="85.0" r="3"/>
+    <text class="f-red" x="644.3" y="77.0" font-size="9" text-anchor="middle">869.0</text>
+    <circle class="f-red" cx="682.6" cy="76.0" r="3"/>
+    <text class="f-red" x="682.6" y="68.0" font-size="9" text-anchor="middle">869.4</text>
+    <text x="70.0" y="254.0" font-size="10" class="sw-dim" text-anchor="middle">863</text>
+    <text x="165.7" y="254.0" font-size="10" class="sw-dim" text-anchor="middle">864</text>
+    <text x="261.4" y="254.0" font-size="10" class="sw-dim" text-anchor="middle">865</text>
+    <text x="357.1" y="254.0" font-size="10" class="sw-dim" text-anchor="middle">866</text>
+    <text x="452.9" y="254.0" font-size="10" class="sw-dim" text-anchor="middle">867</text>
+    <text x="548.6" y="254.0" font-size="10" class="sw-dim" text-anchor="middle">868</text>
+    <text x="644.3" y="254.0" font-size="10" class="sw-dim" text-anchor="middle">869</text>
+    <text x="740.0" y="254.0" font-size="10" class="sw-dim" text-anchor="middle">870</text>
+    <text x="740" y="268.0" font-size="10" class="sw-dim" text-anchor="end">MHz, 100 kHz steps, measured at 125 kHz</text>
+    <text x="70" y="268.0" font-size="10" class="sw-dim">dashed: the floor, -97 dBm (median)</text>
+  </g>
+</svg>

site/content/devlog/roro9stack-ota/boot.svg

@@ -0,0 +1,48 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 452" role="img" aria-label="Every start, in order. Power on or restart. The bootloader boots the other slot if a new image already had its chance. Then setup runs bootGuard and the crash record: which version ran, which one crashed, and how many starts in a row ended in a crash. Three in a row: Safe Mode, with only the clock, Wi-Fi, the Update Service and the Debug Console, no Apps, no IRC, no SD card; fix it by pushing an update, or reboot. Otherwise a normal start with everything, the main loop on the task watchdog, and the crash count reset after 60 seconds up. A panic, or a main loop stuck for 5 seconds, leaves a core dump and restarts, back to the top.">
+  <defs>
+    <marker id="bt-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="bt-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="bt-box" x="200" y="16" width="360" height="44" rx="6"/>
+    <text x="380" y="43" font-size="12" text-anchor="middle" font-weight="600">power on, or restart</text>
+
+    <rect class="bt-box" x="200" y="84" width="360" height="56" rx="6"/>
+    <text x="214" y="106" font-size="12" font-weight="600">bootloader</text>
+    <text x="214" y="126" font-size="11" class="bt-dim">new image had its chance? other slot</text>
+
+    <rect class="bt-box" x="200" y="164" width="360" height="56" rx="6"/>
+    <text x="214" y="186" font-size="12" font-weight="600">setup(): bootGuard + crash record</text>
+    <text x="214" y="206" font-size="11" class="bt-dim">who ran, who crashed, how many in a row</text>
+
+    <rect class="bt-hot" x="200" y="244" width="360" height="44" rx="6"/>
+    <text x="380" y="271" font-size="12" text-anchor="middle" font-weight="600">3 crash starts in a row?</text>
+
+    <rect class="bt-safe" x="16" y="320" width="300" height="100" rx="8"/>
+    <text x="30" y="344" font-size="12" font-weight="600">Safe Mode</text>
+    <text x="30" y="366" font-size="11">clock, Wi-Fi, Update Service,</text>
+    <text x="30" y="384" font-size="11">Debug Console. Nothing else:</text>
+    <text x="30" y="402" font-size="11" class="bt-dim">no Apps, no IRC, no SD card</text>
+    <text x="166" y="442" font-size="11" text-anchor="middle" class="bt-dim">fix: push an update, or reboot</text>
+
+    <rect class="bt-ok" x="444" y="320" width="300" height="100" rx="8"/>
+    <text x="458" y="344" font-size="12" font-weight="600">normal start</text>
+    <text x="458" y="366" font-size="11">everything: Services, Apps</text>
+    <text x="458" y="384" font-size="11">loop on the watchdog (5 s)</text>
+    <text x="458" y="402" font-size="11" class="bt-dim">60 s up: crash count reset</text>
+
+    <path class="bt-line" d="M380 60 V80" marker-end="url(#bt-arrow)"/>
+    <path class="bt-line" d="M380 140 V160" marker-end="url(#bt-arrow)"/>
+    <path class="bt-line" d="M380 220 V240" marker-end="url(#bt-arrow)"/>
+    <path class="bt-line" d="M290 288 V302 H166 V316" marker-end="url(#bt-arrow)"/>
+    <text x="174" y="314" font-size="11" class="bt-dim">yes</text>
+    <path class="bt-line" d="M470 288 V302 H594 V316" marker-end="url(#bt-arrow)"/>
+    <text x="602" y="314" font-size="11" class="bt-dim">no</text>
+
+    <path class="bt-line-bad" d="M744 370 H752 V38 H564" marker-end="url(#bt-arrow-bad)"/>
+    <text x="742" y="190" font-size="11" text-anchor="end" class="bt-red">panic, or the</text>
+    <text x="742" y="206" font-size="11" text-anchor="end" class="bt-red">loop stuck 5 s:</text>
+    <text x="742" y="222" font-size="11" text-anchor="end" class="bt-red">core dump,</text>
+    <text x="742" y="238" font-size="11" text-anchor="end" class="bt-red">restart</text>
+  </g>
+</svg>

site/content/devlog/roro9stack-ota/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 6 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">6 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/devlog/roro9stack-ota/index.md

@@ -0,0 +1,283 @@
++++
+title = '''Look, no cables'''
+description = '''My Cardputer firmware now updates itself over Wi-Fi or from its SD card, refuses anything I didn't sign, rolls back an update that crashes, opens a debug console over the network, and sulks in Safe Mode when all else fails. How it works, and the three times it lied to me along the way.'''
+date = 2026-10-04T19:30:00+02:00
+
+[extra]
+topics = '''ESP32-S3 · OTA · Debugging'''
+read_label = '''Read the flight log →'''
+uid = '''<b>device:</b> OK v0.3.0+debug'''
+dek = "Until this weekend, every change to [roro9stack](/devlog/roro9stack/) went through a USB cable, a VM's USB passthrough, and an `Errno 71` whenever the passthrough got bored. Now the Cardputer takes signed firmware over Wi-Fi, puts itself back when an update goes bad, lets me read its logs and core dumps from the sofa, and keeps a lifeboat for the day it can't even do that. Here's how it all fits together, and the three times it lied to me."
+byline = '''then crashed on purpose, repeatedly, and once by accident 29 times in a row'''
+
+[extra.sign]
+label = "USB cables needed since v0.3.0"
+note = "The VM's USB passthrough is taking it personally."
+count = "0"
+
+[[extra.cast]]
+name = "The Cardputer ADV"
+role = "ESP32-S3, 8 MB flash"
+text = "Two 3.3 MB app slots, so one can run while the other gets overwritten, and a 64 KB core dump partition, which turned out to be the most useful 64 KB on the chip."
+
+[[extra.cast]]
+name = "The bootloader"
+role = "ESP-IDF 5.5.5, prebuilt"
+text = "Rolls back an update that crashes before it's confirmed. I spent a day convinced it didn't. It was never asked."
+
+[[extra.cast]]
+name = "The key pair"
+role = "ECDSA P-256"
+text = "The public half is compiled into the firmware. The private half lives in `~/.config/roro9stack/` and has never been within a mile of git."
+
+[[extra.cast]]
+name = "The dev box"
+role = "a VM with Docker"
+text = "Builds everything in a container and reaches the Cardputer over a routed network, so mDNS doesn't make it across and everything is addressed by IP. Its USB passthrough is the reason this post exists."
++++
+
+## TL;DR
+
+- **Firmware Updates without a cable.** `scripts/flash.sh --ota <ip>` builds, signs and pushes a new firmware over Wi-Fi. Dropping the file on the SD card works too, and so do two more ways that don't need anyone to touch the device.
+- **Only my firmware gets in.** Every Update File carries an ECDSA P-256 signature over its header, which includes the image's SHA-256. Bad signatures are refused before a single byte is written; corrupted images when their hash doesn't match.
+- **A bad update undoes itself.** New firmware runs on Probation until it has been up 30 s, drawn the screen and reconnected Wi-Fi. If it crashes before that, the bootloader boots the previous one, which says so.
+- **Debug Builds** add a **Debug Console** over Wi-Fi: live logs, every serial command, files on the SD card, screenshots, crash reports with decoded backtraces, and full core dumps. Release builds compile none of it.
+- **Safe Mode** for firmware that was confirmed and crashes anyway: after 3 crash restarts in a row, only Wi-Fi and updates start, so a fix can still get in.
+- On the way, the device lied to me three times: about rolling back, about which firmware had failed, and about its watchdog. Details below.
+- The code is [public on my Gitea](https://git.twis.la/twisla/roro9stack/src/tag/v0.3.0), tagged **v0.3.0**.
+
+## Why bother
+
+The [previous post](/devlog/roro9stack/) ended with the Cardputer on Wi-Fi and IRC, and every change still flashed over USB. My dev box is a VM, and its USB passthrough has a hobby: every so often, flashing fails with `OSError: [Errno 71] Protocol error`, retrying never helps, and only unplugging the Cardputer does. Moving the device to put it into download mode also moves the serial port to a new name, and sometimes out of the VM altogether.
+
+So the goal was not just "update over the air". It was **manage it over the air**: install, recover, and find out what went wrong, all from the sofa. A device that can take an update but can't tell you why the last one crashed is only half-managed.
+
+## The cast
+
+{{ cast() }}
+
+## An Update File, and who's allowed to write one
+
+The ESP32 has hardware Secure Boot. It's enforced by the chip and burns eFuses, one way: a mistake bricks the device, and it can never run unsigned code again. On a single development board, I'd like my mistakes to stay reversible, so the firmware checks signatures itself ([ADR 0003](https://git.twis.la/twisla/roro9stack/src/tag/v0.3.0/docs/adr/0003-own-signature-check-not-secure-boot.md)). Someone holding the device can still flash anything over USB; someone on the network can't.
+
+An Update File (`.ota`) is a 160-byte header and the firmware image:
+
+{{ diagram(src="update-file.svg", min_width=580, caption="The first 80 bytes are signed, and they include the image's SHA-256. So a forged file is refused before anything is written, and a corrupted image when its hash comes out wrong at the end. [update_parser.h](https://git.twis.la/twisla/roro9stack/src/tag/v0.3.0/lib/ota/src/update_parser.h) has the layout, [make_ota.py](https://git.twis.la/twisla/roro9stack/src/tag/v0.3.0/scripts/make_ota.py) the PC side.") }}
+
+The device never holds the whole file. A streaming parser takes the header, checks the signature with mbedTLS against the public key compiled in, then writes the image into the app slot that isn't running, hashing it on the way. Only if the hash matches does it make that slot the next boot. Downgrades are allowed, and labelled as such, because sometimes the old version is the one that worked.
+
+Like everything else in this project, the parser was written test-first and runs on the PC. Something that isn't an Update File, a bad signature, a tampered version, a corrupted image, a truncated file, trailing bytes, an image too big for the slot: each has a test that expects a refusal. The forged and oversized ones are refused before anything is written; the damaged ones are aborted, and their slot is never made bootable.
+
+## Four ways in
+
+{{ diagram(src="ways-in.svg", min_width=580, caption="Every path ends at the same Update Service and the same signature check. The SD card paths go through the storage task, which owns every card access.") }}
+
+**Over Wi-Fi.** The device listens on TCP 3232 whenever Wi-Fi is up, and announces itself as `roro9stack-2fa4.local` (the suffix comes from its MAC address). mDNS doesn't make it across my VM's routed network, so in practice it's the IP. The push script streams the file and waits for an answer: the device replies `OK v0.3.0` as soon as the image size announced in the header has arrived, and hangs up mid-transfer on a refused header, which the script reports instead of printing a Python traceback. After a successful install the device restarts, but waits up to 60 s if you're typing. Nobody likes an IRC message eaten by a firmware update.
+
+**From the SD card.** Settings → Firmware lists the `.ota` files in `/updates` and installs one after a confirmation:
+
+{{ figure(src="firmware.png", alt="The Cardputer's Settings, Firmware page, at 2x: Version v0.3.0+debug, Status confirmed, Push to 10.39.39.12:3232, Name roro9stack-2fa4.local, then On the SD card: roro9stack-tampered.ota and test1.ota, each with install on the right", width=480, height=270, caption=`Settings → Firmware, captured over Wi-Fi with the screenshot command described below. Yes, there's a file called tampered.ota on that card. It's refused every time, which is its whole job.`) }}
+
+**Over USB serial, card in.** For when Wi-Fi isn't set up yet: `scripts/sd_put.sh file.ota` copies the file into `/updates` through the serial console. The ESP32-S3's USB serial driver drops bytes when its receive buffer is full, so the protocol is stop-and-wait: 1 KB chunks, each acknowledged once it's on the card, and a SHA-256 check before the `.part` file is renamed into place. That's 55 KB/s, or 30 s for 1.6 MB. Slow, but it beats walking to the device.
+
+**Over the Debug Console.** In a Debug Build, `rdbg.py put` sends the file over Wi-Fi at about 300 KB/s and `rdbg.py install /updates/…` starts Update from SD remotely. It's the SD card path, without anyone touching the SD card.
+
+## Probation, and the rollback that never was
+
+A firmware that installs fine can still fail to boot. So new firmware runs on **Probation**: it's confirmed only once it has been up 30 s, drawn a frame, and reconnected to Wi-Fi if Wi-Fi is configured (it gets 3 minutes for that). Fail any of it, or crash first, and it goes back to the previous firmware, which is still in the other slot.
+
+{{ diagram(src="probation.svg", min_width=580, caption="The bootloader does the rolling back. The firmware only has to not confirm itself too early, which is harder than it sounds: see the trap on the left.") }}
+
+Testing this needs a firmware that crashes on purpose. A build flag adds `if (millis() > 5000) abort();` to the main loop, the build gets signed and pushed, and the device should come back on the old firmware with a Toast saying so.
+
+It didn't. It crashed every 5.5 seconds, forever, until I put it in download mode by hand and reflashed it over USB, cable, VM, `Errno 71` and all. The conclusion seemed obvious: the bootloader PlatformIO flashes doesn't support rollback, even though the app's configuration enables it. So I wrote a second line of defence in the firmware, `bootGuard()`, which counts unconfirmed starts in NVS and rolls back on the second one. I also wrote an architecture decision record explaining that the bootloader can't roll back. With the confidence of a man who hasn't checked.
+
+It crash-looped again. So this time I read the OTA state straight out of flash:
+
+```
+otadata 0  seq 0x1  state 0xffffffff
+otadata 1  seq 0x2  state 0x2
+```
+
+Lie number one. State `0x2` is `ESP_OTA_IMG_VALID`. The crashing image, which had never once lived 30 seconds, was marked **valid**. Neither the bootloader nor `bootGuard()` had anything to roll back: as far as they could tell, the update had been a success.
+
+The culprit is Arduino-ESP32's start-up code. Before `setup()` even runs, `initArduino()` checks for a freshly installed image and marks it valid on the spot, unless the sketch overrides a weak function called `verifyRollbackLater()` to return true. The bootloader had been doing its job all along. It just never got a chance: by the time my code ran, the evidence had been signed off.
+
+The fix is one line. My first attempt didn't work either:
+
+```
+$ xtensa-esp32s3-elf-nm -C firmware.elf | grep verifyRollbackLater
+420383a4 t _GLOBAL__sub_I__Z19verifyRollbackLaterv
+42104d5c W verifyRollbackLater
+```
+
+That `W` is Arduino's weak default, still the one linked. Mine had compiled as a C++ function, `_Z19verifyRollbackLaterv`, a different name entirely, so nothing replaced anything. No Arduino header declares it, so nothing told the compiler it should be C. Two words fixed that:
+
+{% code(caption="[main.cpp](https://git.twis.la/twisla/roro9stack/src/tag/v0.3.0/src/main.cpp#L106-L108). The comment is longer than the code, which is correct.") %}
+```cpp
+// Arduino-ESP32 marks a new image valid before setup() unless this returns true. Probation
+// (UpdateService::tick) decides instead, and an unconfirmed image stays PENDING_VERIFY.
+extern "C" bool verifyRollbackLater() { return true; }  // C linkage, or the weak default wins
+```
+{% end %}
+
+Now `nm` shows a capital `T`, and the next test reported a failed update, which sounds right until you notice who said it. Lie number two: the crashing image had been built with the same version string as the good one, the Update File carried a different one, and at boot the firmware reports a Rollback when the version it was told to expect isn't its own. So the crashing firmware, alive for its 5 seconds, announced its own failure. Every test build now gets a version of its own. And then, finally:
+
+```
+  6.2 abort() was called at PC 0x4203849e on core 1
+  7.2 roro9stack v0.2.1-9-g7afe6b7 ready
+  7.2 notification: Update to v0.2.1-9-g7afe6b7-dirty failed, back on v0.2.1-9-g7afe6b7
+```
+
+One crash, and the very next boot is the previous firmware, saying so. `bootGuard()` stays, demoted to second line, and the decision record now says the opposite of what it said that morning.
+
+## A console with a network cable it doesn't have
+
+Updates were only half the goal. The other half was being able to look inside a device that's on a shelf across the room. That's what a **Debug Build** is for: `scripts/flash.sh --debug` builds the same firmware with `-DRORO_DEBUG`, a `+debug` suffix on its version, and a **Debug Console** on TCP 2323 ([ADR 0004](https://git.twis.la/twisla/roro9stack/src/tag/v0.3.0/docs/adr/0004-debug-console-in-debug-builds.md)).
+
+Release builds don't have a disabled console. They have no console at all: the code isn't compiled in. Something that injects keys and reboots the device over the network is a remote control, and a remote control in a release build is just a vulnerability with good documentation.
+
+{{ diagram(src="debug-console.svg", min_width=580, caption="Commands from the network run on the main loop, like serial ones, because that's the only task allowed to touch Apps and Services. Binary transfers don't wait for it: the console task answers them itself, which keeps them working when the main loop is stuck.") }}
+
+A client must send a token as its first line: 128 random bits, made by the first build, kept in `~/.config/roro9stack/` with the signing key, passed into the build container and never committed. A Debug Build refuses to compile without one, rather than fall back on a default. Then the client gets the last 6 KB of console output (so boot messages aren't lost just because nobody was connected), every new line live, ESP-IDF's own log lines included, and the same commands as the serial port. One client at a time keeps the memory cost flat: 6 KB for the ring, 6 KB of task stack.
+
+The PC side is [`scripts/rdbg.py`](https://git.twis.la/twisla/roro9stack/src/tag/v0.3.0/scripts/rdbg.py):
+
+```
+$ scripts/rdbg.py info
+firmware: roro9stack v0.3.0+debug
+uptime: 0h00m36s, last start: restart
+heap: 90148 free, 67388 lowest, 42996 largest block
+chip: ESP32-S3 rev 2, 240 MHz, 40.3 C
+wifi: knbg-guests, ip 10.39.39.12, rssi -53 | sd: present
+update: confirmed
+slot app0: v0.3.0+debug, running, boots next, valid
+slot app1: v0.2.1-14-g388e847+debug, valid
+```
+
+Those slot versions come from NVS, not from the images: the prebuilt framework stamps its own version on every image, so the firmware writes down which version went into which slot, at boot and at every install.
+
+{% details(summary="Every command") %}
+| Command | Does |
+|---|---|
+| `info` | Firmware, uptime, last restart reason, memory, Wi-Fi, both app slots |
+| `tasks` | Every FreeRTOS task: state, priority, lowest free stack, CPU share |
+| `crash` | The last crash: which firmware, why, task, PC, backtrace |
+| `reboot`, `boot other` | Restart, or restart into the other slot (a manual Rollback) |
+| `log level <0-5>` | ESP-IDF's log level, at runtime |
+| `ls`, `rm`, `install <path>` | Files on the SD card, and Update from SD |
+| `key <name>` | Presses a key: drives the UI from the PC |
+| `wifi status`, `irc dump`, … | Everything the serial console already had |
+| `get`, `put` | Files to and from the SD card, about 300 KB/s (console task) |
+| `screenshot` | The screen, as a PNG on the PC (console task) |
+| `coredump get` | The raw core dump, decoded on the PC (console task) |
+| `reset` | Restart at once, even with the main loop stuck (console task) |
+| `crash abort`, `crash wdt` | Crash on purpose, or hang the main loop (Debug Builds only, obviously) |
+{% end %}
+
+`screenshot` is my favourite, for a petty reason: the UI already composes every frame in a 32 KB off-screen buffer (8-bit colour, to save RAM), so the console task just sends that buffer as it stands. No extra memory, and `rdbg.py` turns it into a PNG without a single image library, because PNG is zlib plus four CRCs and I was feeling stubborn. Every screen in this post came from it, the Firmware page above included, after `key down` × 13 to get there.
+
+{{ figure(src="launcher.png", alt="The Cardputer's Launcher at 2x: a dark status bar reading roro9stack, with Wi-Fi bars, SD, 97 percent battery and 03:12; then IRC highlighted, Wi-Fi Tools and Settings", width=480, height=270, caption=`The Launcher at 3:12 in the morning, captured over Wi-Fi. The timestamp is there to make you feel sorry for me.`) }}
+
+### A console that waited for nobody
+
+The first remote `tasks` command printed its header, then one line every few seconds, interleaved with other tasks' messages. The main loop was crawling. The Cardputer was plugged into the VM, which wasn't reading the serial port, and when a USB host is attached but not reading, Arduino's USB serial driver retries each write 20 times with a 100 ms timeout. That's up to 2 seconds per line, on the main loop. A device that freezes because nobody is reading its debug output is the opposite of a debugging aid.
+
+So the console now writes to USB only when the transmit buffer has room for the whole line ([console.cpp](https://git.twis.la/twisla/roro9stack/src/tag/v0.3.0/src/platform/console.cpp#L80-L83)), and never waits. The ring keeps everything anyway.
+
+## When it crashes anyway
+
+ESP-IDF already writes a core dump to its flash partition when the firmware panics. Nobody was reading it. Now, first thing at every boot, the firmware writes down which version is running. After a crash restart, that record says which firmware crashed, even if a Rollback has switched slots in between. The firmware prints the core dump's summary and raises a Notification. And every build keeps its ELF in `.pio/elves/`, named by version and by the first digits of its SHA-256, the same digest the core dump records for the firmware that crashed. So the PC can decode a crash from any build, even one that's been rebuilt since:
+
+```
+$ scripts/rdbg.py crash
+crash: last one in v0.3.0+debug (panic)
+crash: task loopTask, pc 0x4037e231, cause 0, address 0x00000000
+crash: reason: abort() was called at PC 0x4203a486 on core 1
+crash: backtrace 0x4037e231 0x4037e1f9 0x40385691 0x4203a486 0x4203b389 0x4203b78b 0x4205269c 0x4037f211
+crash: elf sha256 422a68a36
+
+using .pio/elves/v0.3.0+debug.422a68a36fb990f3.elf
+0x4037e231: panic_abort at esp-idf/esp_system/panic.c:477
+0x4037e1f9: esp_system_abort at esp-idf/esp_system/port/esp_system_chip.c:87
+0x40385691: abort at esp-idf/newlib/src/abort.c:38
+0x4203a486: runCommand(String) at /work/src/main.cpp:390
+0x4203b389: remoteCommands() at /work/src/main.cpp:494
+0x4203b78b: loop() at /work/src/main.cpp:541
+0x4205269c: loopTask(void*) at framework-arduinoespressif32/cores/esp32/main.cpp:82
+```
+
+That one was me typing `crash abort`, and `main.cpp:390` is exactly the line that called `abort()`. For the cases where a backtrace isn't enough, `rdbg.py coredump` fetches the whole dump over Wi-Fi and runs `esp-coredump` with GDB against the same ELF: registers, every task's stack, the lot. The toolchain container already had both. It just needed someone to ask.
+
+## Safe Mode
+
+Rollback protects against new firmware. It does nothing for firmware that was confirmed and crashes later: a corrupt setting, an IRC server sending something unexpected, a bug that takes an hour to show. Without a cable, that device restarts forever. So every build, release included, has a lifeboat ([ADR 0005](https://git.twis.la/twisla/roro9stack/src/tag/v0.3.0/docs/adr/0005-safe-mode-crash-reports-watchdog.md)):
+
+{{ diagram(src="boot.svg", min_width=580, caption="The crash record is written before anything that could crash. Three starts in a row that follow a panic or a watchdog, and the firmware only starts what it takes to be fixed over the air.") }}
+
+{{ figure(src="safemode.png", alt="The Cardputer screen at 2x, black, with Safe Mode in blue in the middle and, under it, Updates: 10.39.39.12:3232", width=480, height=270, caption=`Safe Mode, after three deliberate crashes in a row. It says where to send the fix, which is more than most error screens manage.`) }}
+
+The first proper test of it went better than planned, and worse. My test script crashed the device three times, then kept asking for `info` to see whether it was back. In Safe Mode, `info` asks the Storage Service how the SD card is doing, and Safe Mode never starts the Storage Service, whose lock was only created by `start()`. Null mutex, assert, panic, Safe Mode again, `info` again. The script was patient. When I looked:
+
+```
+roro9stack v0.2.1-12-g0fb7f4e-dirty+debug in SAFE MODE: 29 crash restarts in a row.
+crash: reason: assert failed: xQueueSemaphoreTake queue.c:1709 (( pxQueue ))
+```
+
+The bright side: between crashes, Safe Mode served the Debug Console every time, the crash report pointed straight at `StorageService::state()`, and the fix (create the lock in the constructor) went in **over Wi-Fi, into the device in Safe Mode**. It installed, restarted into normal mode, and confirmed on Probation. That's the whole feature, tested by accident, in the worst case available. Twenty-nine crashes, zero cables.
+
+## The loop nobody watched
+
+To test the watchdog, `crash wdt` spins the main loop forever. The device should panic within 5 s and restart. It didn't come back. Four minutes later it still hadn't, and the Debug Console accepted connections but ran nothing, because every command is queued for a main loop that was busy doing `for (;;) {}`.
+
+Lie number three: the task watchdog was on, but Arduino-ESP32 only watches the idle task on core 0. The main loop runs on core 1, unwatched. A stuck main loop was a frozen device, permanently, with a screen showing whatever it showed last. That one fix is now in every build:
+
+- `enableLoopWDT()` at the end of setup: a main loop stuck for 5 s panics, leaves a core dump and counts towards Safe Mode. Retested: back on Wi-Fi in 15 s, with a backtrace pointing into `runCommand()`, at the command that was spinning.
+- An installed update no longer depends on the main loop to restart into it: the Update Service does it by itself after 90 s.
+- `reset` is answered by the console task, not queued, so it works when nothing else does.
+
+## Smaller bruises
+
+- **220 KB for one line.** `FileReceiver`, the logic behind `sd put`, parsed its arguments with `std::istringstream`. That pulled libstdc++'s iostreams and locales into the firmware: 220 KB of flash, to split a string on spaces. A ten-line loop does it now, and the feature costs 7 KB.
+- **Binary read as commands.** When a `put` failed halfway, the rest of the file kept arriving and the console read it as command lines. Random bytes can spell `reboot`. A failed `put` now hangs up.
+- **A card that fails one write.** One upload failed at 1.3 MB with a zero-byte write, the next four went through. FATFS keeps a file in error after one failed write, so `put` now closes the file, cuts it back to the last good byte, reopens it and retries, up to three times. The retry hasn't fired since, which is either good news or a test I haven't managed to run.
+- **A race in the waiting room.** A card job queued from the console task waits for the storage task, and gives up after 5 s if there's no card. If the job started at the exact moment the wait gave up, it would have written into a stack frame that no longer existed. One compare-and-swap now decides which side wins.
+
+## By the numbers
+
+{% table() %}
+| | |
+| --- | --- |
+| Commits from v0.2.1 to v0.3.0 | 14, over about a day |
+| Lines added | about 3,600, 530 of them tests |
+| Tests | 293, all on the PC |
+| Release firmware | 1.62 MB of a 3.3 MB slot |
+| Debug Build | 1.63 MB, and about 12 KB more RAM |
+| SD card over USB serial / over Wi-Fi | 55 KB/s / 270–380 KB/s |
+| From a hung main loop back to Wi-Fi | 15 s |
+| Crash restarts in a row, record | 29 |
+{% end %}
+
+## What it doesn't do
+
+- **Safe Mode can't save a firmware whose Wi-Fi is what crashes.** Then it's USB again.
+- **The Debug Console is plain text.** Fine on my network, not something to expose to the internet. The token keeps neighbours out, not eavesdroppers.
+- **Two paths haven't been seen working:** the card write retry, and the Update Service restarting by itself after 90 s. Both are written; neither has fired since.
+- **Once, the USB serial console went silent** in both directions after an upload, with Wi-Fi still fine. I couldn't make it happen again. If it does, the Debug Console will be watching.
+- **No pulling updates from Gitea releases yet.** The device is pushed to, never pulls.
+
+## Where it stands
+
+{% steps() %}
+1. ~~Signed Update Files, push over Wi-Fi, Update from SD, Probation and Rollback.~~ Done, and the Rollback finally rolls back.
+
+2. ~~Debug Builds and the Debug Console: logs, commands, files, screenshots, crash reports and core dumps over Wi-Fi.~~ Done.
+
+3. ~~Safe Mode, crash records, and a watched main loop, in every build.~~ Done, and tested harder than intended.
+
+4. Next for roro9stack: GNSS, then the LoRa radio. With a cable plugged in only for charging.
+{% end %}
+
+{% signoff() %}
+The Cardputer now sits on a shelf across the room. It gets its updates over the air, and when something breaks, it tells me what and where. The USB cable is in a drawer, which is where it belongs.
+{% end %}

site/content/devlog/roro9stack-ota/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/devlog/roro9stack-ota/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/devlog/roro9stack-ota/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 Build, 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/devlog/roro9stack-s1/index.md

@@ -0,0 +1,217 @@
++++
+title = '''One byte too early'''
+description = '''roro9stack's housekeeping milestone: the SD card that "refused" writes turns out to be a driver asking one byte too soon, fixed and reported upstream; networks without DHCP get fixed addresses, DNS and NTP; and a System App shows tasks, memory and network use live, starting with a main loop that eats a whole core.'''
+date = 2026-10-06T02:30:00+02:00
+
+[extra]
+topics = '''ESP32-S3 · SD card · FreeRTOS'''
+read_label = '''Read who was really at fault →'''
+uid = '''<b>sd:</b> present, 0 write faults'''
+dek = "A side milestone for [roro9stack](/devlog/roro9stack/), my firmware for the M5Stack Cardputer, between the radio and the mesh: make what exists solid. Three jobs on the list. The SD card that [refused a write now and then](/devlog/roro9stack-lora/) took four wrong guesses and one missing byte. Fixed IP addresses took an evening and a safety net. And the system monitor's first act was to report that the firmware had been burning an entire CPU core doing nothing, which I'd have preferred to hear from someone else."
+byline = '''designed by interrogation, rounds six and seven: 23 questions, and a bug report with my name on it'''
+
+[extra.sign]
+label = "Wrong guesses before the right one"
+note = "The radio, a timeout, the bus speed, a CRC bug. None of them."
+count = "4"
+tone = "red"
+
+[[extra.cast]]
+name = "The card"
+role = "Samsung microSDHC, 8 GB, June 2013"
+text = "Thirteen years old, product name \"00000\", which is the most honest thing a memory card has ever said about itself. Accused for two days of refusing writes. Innocent."
+
+[[extra.cast]]
+name = "The driver"
+role = "sd_diskio.cpp, 891 lines, from the Arduino framework"
+text = "Talks to the card over SPI. Gives up on a write without saying why, and tests for \"ready\" one byte before the card has had time to say \"busy\"."
+
+[[extra.cast]]
+name = "The network"
+role = "10.39.39.0/24, gateway at .1"
+text = "The only one I have to test on, with exactly one device on it. Which makes 10.39.39.13 the safest free address in Brussels."
+
+[[extra.cast]]
+name = "The main loop"
+role = "100% of core 1, at rest"
+text = "Polls the keyboard, ticks the services, redraws when needed, and comes straight back for more. Has never once considered sitting down."
++++
+
+## TL;DR
+
+- **The SD card was never refusing writes.** The framework's driver asked the card for its status one byte too early, got garbage, and reported an error. Two dummy bytes fixed it: 30 uploads of 1.7 MB in a row with no failure, against 3 in 10 before. Reported upstream as [arduino-esp32#12970](https://github.com/espressif/arduino-esp32/issues/12970).
+- **Fixed IPv4 addresses**, per network, for networks with no DHCP, plus DNS and NTP servers in Settings with public defaults.
+- **A System App:** tasks, memory, network traffic per service and system state, live, in any build.
+- **What the System App found first:** the main loop uses a whole CPU core at rest. Not fixed yet; it has an issue of its own.
+- Three releases: **v0.6.1**, **v0.7.0** and **v0.8.0**. The code is [on my Gitea](https://git.twis.la/twisla/roro9stack/src/tag/v0.8.0), and the plan with every measurement is [docs/milestones/S1.md](https://git.twis.la/twisla/roro9stack/src/tag/v0.8.0/docs/milestones/S1.md).
+
+## Why a housekeeping milestone
+
+The [radio milestone](/devlog/roro9stack-lora/) ended waiting for hardware: the mesh needs a second node, and I don't have one yet. It also left a card that failed about one upload in five, and a backlog of some twenty ideas I'd dictated into the issue tracker in one sitting.
+
+So the backlog got sorted into milestones, and the first one is the boring kind: **S1, system basics**. The card can be trusted. The device works on any network. You can see what the system is doing. Nothing glamorous, all of it wanted before a radio starts writing to that card around the clock.
+
+## The cast
+
+{{ cast() }}
+
+## The card that never said no
+
+[The last post](/devlog/roro9stack-lora/) left it here: about once in five uploads, a write to the card failed, the retry code papered over the hole with zeros, and I'd fixed the papering but not the failing. The card "refuses a write now and then", I wrote, like it was weather.
+
+### Four wrong guesses
+
+**The radio.** It shares the card's SPI bus, so it was the obvious suspect. Cleared in [the last post](/devlog/roro9stack-lora/): the failures came with the radio asleep too.
+
+**A timeout.** The driver waits at most 500 ms for a busy card and then gives up, silently. Cards do pause for housekeeping. So I timed every write. Good ones took up to 107 ms. The failing one came back after **4 ms**. Nothing waits 500 ms in 4 ms.
+
+**The bus speed.** 20 MHz over wires that also run up into the radio's cap: maybe bits were getting flipped. At 10 MHz the uploads were 15% slower and one in ten still failed, after 7 ms this time. A failure that takes twice as long at half the speed is an exchange being rejected, not a signal problem.
+
+**A CRC bug.** Reading the driver, I found something that looked like the answer. After each data block the card replies with one of three values: `0x05` accepted, `0x0B` CRC error, `0x0D` write error. The driver masks the reply so its lowest bit is always 1, then checks whether it equals `0x0A` to decide to resend. It can never equal `0x0A`. So a block the card rejects is never resent. A real bug, sitting in the framework for anyone to trip over. I was sure.
+
+It wasn't that either.
+
+### Asking the driver
+
+The driver fails without logging anything, so the only way to know was to make it talk. That meant owning it.
+
+You can't just drop a file with the same name into the project: PlatformIO links the framework library's objects directly, and the linker complained about every function twice. What works is a project library with the same name, which takes the framework's place. So `lib/SD` is now [my copy of the framework's SD library](https://git.twis.la/twisla/roro9stack/src/tag/v0.8.0/docs/adr/0007-own-copy-of-the-sd-driver.md): committed once exactly as it ships, then with my changes on top, so the difference stays one readable commit.
+
+It took three tries to build. I forgot the library's sixth file, the one with the CRC routines. Then my new code landed inside an `extern "C"` block and got the wrong name. The compiler was patient about it, in the way compilers are.
+
+With a record of where each write gave up, twelve uploads produced four failures, **all at the same step**: every data block accepted, the write properly ended, and then the status check came back as `0xFF` three times and `0x1F` once. Those aren't status values. They're what a wire looks like when nobody's driving it.
+
+### One byte
+
+{{ diagram(src="sd-ready.svg", min_width=620, caption=`The end of a multi-block write. The driver's test for "ready" landed in the one byte before the card says "busy".`) }}
+
+After the token that ends a multi-block write, a card takes about one byte of clock before it signals busy. The driver deselects the card, selects it again, and reads a single byte to see if it's ready. Usually, by then, the card has raised busy and the driver waits. About once in 1,500 writes it hasn't yet: the byte reads `0xFF`, "ready", and the driver asks for the card's status while the card is still writing. The reply is garbage, the driver calls it an error, and the filesystem is told the write failed.
+
+It hadn't. **The data was on the card every time.** The check was wrong, not the write.
+
+The reference SD driver that everyone copies from sends one dummy byte after selecting the card, with a comment saying why. The Arduino one doesn't. [Two dummy bytes](https://git.twis.la/twisla/roro9stack/commit/3f2650c), one after the end-of-write token and one after selecting, and:
+
+- 30 uploads of 1.7 MB in a row, each read back and checked by SHA-256: **no failure**.
+- Ten of those with the radio listening on the same bus.
+- Before: 3 failures in 10.
+
+The CRC bug is still there, by the way. It's real, nothing here triggers it, and I don't fix code paths I can't test. It's written down, and it's in the report.
+
+### Telling upstream
+
+A bug in a framework that thousands of projects use deserves a report, and a report deserves the card's make. Which I didn't know: the card is anonymous on the outside, and I had no other device to read it with.
+
+The card knows, though. Every SD card carries an identity register: maker, product name, revision, serial number, date. So the firmware got an `sd card` command that asks, through the driver I now own:
+
+```
+sd card: SDHC/SDXC, 7.9 GB, Samsung (0x1B) "SM" "00000" rev 1.0, serial …, made 2013-06
+```
+
+A Samsung from 2013 whose product name is five zeros. It went into the report with the measurements, the two-line fix and the second bug: [arduino-esp32#12970](https://github.com/espressif/arduino-esp32/issues/12970). No reply yet. Until a fixed release exists, my copy has to be kept in step with the framework by hand, which is the price of the fix and has [an issue to keep me honest](https://git.twis.la/twisla/roro9stack/issues/39).
+
+## Networks that don't hand out addresses
+
+Not every network has a DHCP server: a lab bench, a direct cable to a router, a network where someone assigns addresses from a spreadsheet. Until now the Cardputer couldn't join any of them. Twelve questions settled how:
+
+- **Per network.** Each saved network is Automatic or Fixed. The right address at home is the wrong one at work.
+- **A prefix, not a mask.** Typing `24` beats typing `255.255.255.0` on this keyboard, and it can't be malformed.
+- **The gateway is optional.** A bench network with no way out is a legitimate network.
+- **DNS and NTP are global**, with public defaults: 9.9.9.9 then 1.1.1.1 for names, `pool.ntp.org` then `time.cloudflare.com` for time. A switch, "Always use my DNS", covers networks whose resolver you'd rather not trust.
+- **IPv4 only.** IPv6 was offered as a "later"; I said not even that.
+
+{{ figure(src="wifi.png", alt="Four Cardputer screens at 2x in a grid. Top left: Settings, Wi-Fi: Wi-Fi On, Status knbg-guests (-48 dBm), DNS and NTP, Add a network, Add a hidden network, then the saved networks knbg-guests (selected) and Longcat. Top right: the page of knbg-guests: IP address Fixed, Address 10.39.39.12, Prefix 24 (255.255.255.0), Gateway 10.39.39.1, Forget this network. Bottom left: DNS and NTP: DNS 1 9.9.9.9, DNS 2 1.1.1.1, Always use my DNS Off, NTP 1 pool.ntp.org, NTP 2 time.cloudflare.com. Bottom right: connection details: knbg-guests, -47 dBm, Address 10.39.39.12/24 (DHCP), Mask 255.255.255.0, Gateway 10.39.39.1, DNS 10.39.39.1 (DHCP), NTP pool.ntp.org, answered, NTP time.cloudflare.com", width=976, height=556, landscape=true, full=true, caption=`Settings > Wi-Fi, a network's own page, the DNS and NTP servers, and the connection's details with where each value came from.`) }}
+
+Enter on a saved network used to ask "Forget network?", which was a rude thing to ask first. Now it opens the network's page. Switch it to Fixed and the page fills in the address, prefix and gateway the network is giving you right now, since the commonest reason to want a fixed address is to keep the one you have. Nothing is applied until you leave the page, so a half-typed address is never used.
+
+What's typed gets checked, [in code tested on the PC](https://git.twis.la/twisla/roro9stack/src/tag/v0.8.0/lib/net/src/ipv4.cpp#L37), with a reason for every refusal: "10.39.39.0 is the network's own address", "The gateway 10.39.40.1 isn't in 10.39.39.0/24".
+
+### A safety net for remote hands
+
+There's a catch in testing this over Wi-Fi: a wrong address cuts the branch you're sitting on. The Debug Console and updates both come over that connection.
+
+So Debug Builds got a trial: `wifi ip … try 60` applies a setting and goes back to the previous one after 60 seconds unless confirmed. Then I gave it a deliberately wrong gateway. The device went silent, and a minute later it was back, unassisted. Without the trial, someone would have had to pick the device up and fix it on its own keyboard.
+
+Two things the network stack does behind your back, found by reading and avoided by checking every 30 seconds:
+
+- A DHCP renewal quietly puts DHCP's DNS servers back.
+- It also clears every NTP slot it didn't fill itself.
+
+And one I caught before it ran: my first version treated "just connected" like "the settings changed", and would have rejoined the network forever to fetch DNS servers it already had.
+
+Tested on the only network I have: fixed at 10.39.39.12, then 10.39.39.13 (the device is alone there, so the neighbouring address was free by definition), internet working through the configured DNS both times, back to DHCP, and both NTP servers answering. Not tested, and written down as such: NTP servers offered by DHCP, because mine offers none.
+
+## What the system is doing
+
+Every milestone so far ran on measurements that needed a Debug Build and a laptop: memory floors, stack sizes, TLS dips. The System App puts them on the device.
+
+{{ figure(src="system.png", alt="Four Cardputer screens at 2x in a grid. Top left: the Overview: Core 0 at 47%, Core 1 at 64%, Memory 49 KB free, lowest 14, Network 33 B/s in, 4.1 KB/s out, Battery 97%, 4.17 V, Uptime 28 min 32 s, 43 C, and a graph of both cores over two minutes. Top right: Tasks sorted by stack left: IDLE0 with 232 bytes, spk_task with 264 and IDLE1 with 336, all three in orange, then ipc1, ipc0, irc and radio. Bottom left: Memory: 53.0 KB free, lowest 14.1, largest free block 31.0 KB, with a graph that runs near 75 KB then drops to about 50 KB, above dotted lines at 55, 40 and 20 KB. Bottom right: Network: knbg-guests, -49 dBm, 10.39.39.12/24 DHCP, gateway 10.39.39.1, then IRC 19 KB in and 1.1 KB out, Gemini 162 KB in and 72 B out, Debug Console 3.3 KB in and 750 KB out, Updates 0", width=976, height=556, landscape=true, full=true, caption=`The System App: the overview, tasks sorted by how little stack they have left, memory while IRC connects over TLS, and traffic per service.`) }}
+
+Five views, Tab between them. It samples once a second, keeps two minutes of history, and keeps nothing at all while it's closed.
+
+**Memory** draws free heap against the three floors from the Gemini milestone. The screenshot shows IRC connecting over TLS: 25 KB gone in a second. The graph only bottoms out near 50 KB, but "lowest 14.1" says the handshake went far deeper between two samples. Right after that I asked for a Gemini page, and the firmware refused: "Not enough memory (44 KB free): stop IRC or retry". That's the start floor from two milestones ago doing its job, and the first time I've seen the cause on the device's own screen while it happened.
+
+**Network** counts bytes per service. That took one small [wrapper class](https://git.twis.la/twisla/roro9stack/src/tag/v0.8.0/src/platform/counted_client.h#L14) around each service's connection instead of a dozen edits. It counts in the two calls everything else goes through. The counts are exact: fetching a 164,970-byte Gemini page counted 164,986 bytes in, which is the page plus its 16-byte header line, and 42 out, which is a 40-character URL and a line ending.
+
+**Tasks** flags anything with under 512 bytes of stack left. Three tasks qualify today, all the framework's own, one of them with 232 bytes. I've chosen to find that reassuring.
+
+### The loop that read 2%
+
+The Tasks view shows each task's share of a core over the last second. On its first honest run it showed the main loop at 2%, core 1's idle task at 0%, and core 1 at 100% load. Ninety-eight percent of a core, belonging to nobody.
+
+{{ diagram(src="runtime.svg", min_width=620, caption="FreeRTOS adds to a task's run time when the task is switched out. A task that's never switched out never gets its time added.") }}
+
+FreeRTOS adds to a task's run-time counter at the moment the task is switched out. The main loop is the task taking the sample. When nothing else wants its core, it's never switched out, so its counter stands still while it runs flat out. The fix is arithmetic: the task doing the sampling [gets whatever is left of its core](https://git.twis.la/twisla/roro9stack/src/tag/v0.8.0/lib/system/src/task_stats.cpp#L32) once everything else is counted.
+
+The console's `tasks` command had its own version of this. My first rewrite took two samples a quarter of a second apart, inside the command, and reported the loop at 1%. Of course it did: the loop was asleep, waiting for the command to finish measuring it. It now takes one sample, lets the loop run for a second, and prints after the second.
+
+With both fixed, the figure is plain:
+
+```
+task             st   pri  stack   cpu% core
+loopTask         R      1   2872  100.0 1
+IDLE1            r      0    352    0.0 1
+load: core 0 2 %, core 1 100 %
+```
+
+**The main loop uses a whole core at rest.** It polls, ticks, redraws and comes straight back, forever. An hour earlier I'd measured it at 81%, which was an average since boot, hobbled by the same counter. It's a battery cost, a heat cost, and a suspect for the [radio noise](/devlog/roro9stack-lora/) from the last post. It's also not fixed: letting the loop sleep touches key response, redraw timing and every service's tick, so it gets [its own issue](https://git.twis.la/twisla/roro9stack/issues/40) and its own measurements. The monitor's job was to make it impossible to ignore, and it did that in its first minute.
+
+## By the numbers
+
+{% table() %}
+| | |
+| --- | --- |
+| Releases | 3: v0.6.1, v0.7.0, v0.8.0 |
+| Design questions | 23 (Q105 to Q127) |
+| Tests | 396, 31 of them new |
+| Firmware | 1.74 MB of 3.3 MB, 35 KB more than v0.6.0 |
+| Wrong guesses about the card | 4 |
+| Bytes missing from the driver | 2 |
+| Uploads without a failure since | 30 of 30 (it was 7 of 10) |
+| A failed write, before | every 1,500 or so |
+| Free address used for testing | 10.39.39.13 |
+| Seconds cut off by a wrong gateway, on purpose | 60 |
+| Bytes miscounted in a 164,970-byte fetch | 0 |
+| Share of a core the main loop uses at rest | 100% |
+{% 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.0, this post.
+
+7. Next: the main loop learns to rest, and the radio noise gets hunted with the tools that now exist. M4, the mesh, still waits for a second node.
+{% end %}
+
+{% signoff() %}
+The card was innocent, the network was simple, and the monitor's first finding was about its own author. A good milestone for humility, and for a 13-year-old memory card with no name.
+{% end %}

site/content/devlog/roro9stack-s1/runtime.svg

@@ -0,0 +1,32 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 300" role="img" aria-label="One second on core 1, twice. In the first, the main loop shares the core with another task: it is switched out several times, and each time FreeRTOS adds the time it ran to its counter, so the counter keeps up and reads 60 percent. In the second, the main loop has the core to itself: it runs for the whole second and is never switched out, so its counter hardly moves and reads 2 percent, while the idle task's counter reads 0 percent. Two percent plus zero percent leaves 98 percent of the core unaccounted for: it belongs to the task that is still running, the one taking the sample.">
+  <g font-family="JetBrains Mono, ui-monospace, monospace" fill="currentColor" font-size="10">
+    <!-- shared core -->
+    <text x="16" y="22" font-size="12" font-weight="600">The loop shares core 1</text>
+    <text x="16" y="48" class="rt-dim">running</text>
+    <rect class="rt-run" x="110" y="36" width="110" height="16"/>
+    <rect class="rt-other" x="220" y="36" width="60" height="16"/>
+    <rect class="rt-run" x="280" y="36" width="130" height="16"/>
+    <rect class="rt-other" x="410" y="36" width="90" height="16"/>
+    <rect class="rt-run" x="500" y="36" width="120" height="16"/>
+    <rect class="rt-other" x="620" y="36" width="100" height="16"/>
+    <text x="16" y="88" class="rt-dim">its counter</text>
+    <line class="rt-axis" x1="110" y1="110" x2="720" y2="110"/>
+    <polyline class="rt-count" points="110,110 220,110 220,96 410,96 410,80 620,80 620,66 720,66"/>
+    <line class="rt-tick" x1="220" y1="54" x2="220" y2="110"/>
+    <line class="rt-tick" x1="410" y1="54" x2="410" y2="110"/>
+    <line class="rt-tick" x1="620" y1="54" x2="620" y2="110"/>
+    <text x="226" y="124" class="rt-dim">added when it's switched out</text>
+    <text class="f-green" x="728" y="70">60%</text>
+
+    <!-- alone -->
+    <text x="16" y="166" font-size="12" font-weight="600">The loop has core 1 to itself</text>
+    <text x="16" y="192" class="rt-dim">running</text>
+    <rect class="rt-run" x="110" y="180" width="610" height="16"/>
+    <text x="16" y="232" class="rt-dim">its counter</text>
+    <line class="rt-axis" x1="110" y1="250" x2="720" y2="250"/>
+    <polyline class="rt-count-bad" points="110,250 126,250 126,247 720,247"/>
+    <text class="f-red" x="728" y="250">2%</text>
+    <text x="134" y="238" class="rt-dim">never switched out, so nothing is added: idle 0% + loop 2% = 2% of a core that's 100% busy</text>
+    <text x="16" y="284" class="rt-dim">The missing 98% belongs to the task still running: the one taking the sample.</text>
+  </g>
+</svg>

site/content/devlog/roro9stack-s1/sd-ready.svg

@@ -0,0 +1,41 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 330" role="img" aria-label="The end of a multi-block write to an SD card, as a timeline. The card accepts the last block, receives the Stop Tran token, takes about one byte of clock before it signals busy, stays busy while it programs, then is ready. The original driver sends Stop Tran, deselects and selects the card, and reads one byte to test for ready: that byte arrives before the card has signalled busy, reads 0xFF, and is taken as ready. The driver then sends the status command CMD13 while the card is still programming, gets 0xFF or 0x1F back, and reports a write error. The fixed driver sends a dummy byte after Stop Tran and another after selecting the card, so its ready test sees busy, waits, and sends CMD13 once the card is ready: status 0x00, the write succeeded.">
+  <g font-family="JetBrains Mono, ui-monospace, monospace" fill="currentColor" font-size="10">
+    <text x="16" y="24" font-size="12" font-weight="600">The card</text>
+    <rect class="sd-box" x="16" y="34" width="150" height="40" rx="5"/>
+    <text x="24" y="50">last block</text><text x="24" y="64" class="sd-dim">answers 0x05: accepted</text>
+    <rect class="sd-box" x="170" y="34" width="96" height="40" rx="5"/>
+    <text x="178" y="50">Stop Tran</text><text x="178" y="64" class="sd-dim">0xFD</text>
+    <rect class="sd-bad" x="270" y="34" width="88" height="40" rx="5"/>
+    <text x="278" y="50">not busy yet</text><text x="278" y="64" class="sd-dim">reads 0xFF</text>
+    <rect class="sd-busy" x="362" y="34" width="240" height="40" rx="5"/>
+    <text x="370" y="50">busy: programming the blocks</text><text x="370" y="64" class="sd-dim">reads 0x00</text>
+    <rect class="sd-box" x="606" y="34" width="138" height="40" rx="5"/>
+    <text x="614" y="50">ready</text><text x="614" y="64" class="sd-dim">reads 0xFF</text>
+
+    <line class="sd-guide" x1="314" y1="76" x2="314" y2="262"/>
+    <line class="sd-guide" x1="606" y1="76" x2="606" y2="262"/>
+
+    <text x="16" y="112" font-size="12" font-weight="600">The driver, as shipped</text>
+    <rect class="sd-box" x="170" y="122" width="96" height="40" rx="5"/>
+    <text x="178" y="138">Stop Tran,</text><text x="178" y="152" class="sd-dim">then reselect</text>
+    <rect class="sd-bad" x="270" y="122" width="88" height="40" rx="5"/>
+    <text x="278" y="138">ready?</text><text class="f-red" x="278" y="152">0xFF: yes</text>
+    <rect class="sd-bad" x="362" y="122" width="150" height="40" rx="5"/>
+    <text x="370" y="138">CMD13: status?</text><text class="f-red" x="370" y="152">0xFF or 0x1F: "error"</text>
+    <text class="f-red" x="522" y="138">the write "failed"</text>
+    <text class="f-red" x="522" y="152">(it hadn't)</text>
+
+    <text x="16" y="200" font-size="12" font-weight="600">With two dummy bytes</text>
+    <rect class="sd-box" x="170" y="210" width="96" height="40" rx="5"/>
+    <text x="178" y="226">Stop Tran</text>
+    <rect class="sd-new" x="270" y="210" width="88" height="40" rx="5"/>
+    <text x="278" y="226">dummy,</text><text x="278" y="240">dummy</text>
+    <rect class="sd-busy" x="362" y="210" width="240" height="40" rx="5"/>
+    <text x="370" y="226">ready? 0x00: no. Waits.</text><text x="370" y="240" class="sd-dim">up to 500 ms; it took at most 107</text>
+    <rect class="sd-good" x="606" y="210" width="138" height="40" rx="5"/>
+    <text x="614" y="226">CMD13: status?</text><text class="f-green" x="614" y="240">0x00: written</text>
+
+    <text x="16" y="290" class="sd-dim">About once in 1,500 writes, the first byte after reselecting came before the card had raised busy.</text>
+    <text x="16" y="306" class="sd-dim">Time runs left to right; not to scale.</text>
+  </g>
+</svg>

site/content/devlog/roro9stack/architecture.svg

@@ -0,0 +1,61 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 452" role="img" aria-label="Four layers. Apps, one on screen at a time: Launcher, IRC, Settings, and a hidden widget demo. Below them the main loop, which sends keys to the App and events to toasts and the status bar. Below that the Services, which keep running whatever is on screen: Power, Battery, Clock, Wi-Fi, and Storage and IRC on their own tasks. At the bottom the hardware. Events go up from the Services through a queue to the main loop; Apps send requests down to the Services.">
+    <defs>
+      <marker id="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="arrow-hot" 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="#81A1C1"/>
+      </marker>
+    </defs>
+    <g font-family="JetBrains Mono, ui-monospace, monospace" fill="currentColor">
+      <!-- Apps -->
+      <rect x="16" y="16" width="728" height="92" rx="8" fill="currentColor" fill-opacity="0.05" stroke="currentColor" stroke-opacity="0.55"/>
+      <text x="32" y="40" font-size="13" font-weight="600">Apps · one on screen at a time</text>
+      <rect x="32" y="56" width="160" height="36" rx="6" fill="none" stroke="currentColor" stroke-opacity="0.4"/>
+      <text x="112" y="78" text-anchor="middle" font-size="12">Launcher</text>
+      <rect x="208" y="56" width="160" height="36" rx="6" fill="none" stroke="currentColor" stroke-opacity="0.4"/>
+      <text x="288" y="78" text-anchor="middle" font-size="12">IRC</text>
+      <rect x="384" y="56" width="160" height="36" rx="6" fill="none" stroke="currentColor" stroke-opacity="0.4"/>
+      <text x="464" y="78" text-anchor="middle" font-size="12">Settings</text>
+      <rect x="560" y="56" width="168" height="36" rx="6" fill="none" stroke="currentColor" stroke-opacity="0.4" stroke-dasharray="4 3"/>
+      <text x="644" y="78" text-anchor="middle" font-size="12" fill-opacity="0.7">widget demo, hidden</text>
+
+      <!-- Main loop -->
+      <rect x="16" y="148" width="580" height="60" rx="8" fill="#81A1C1" fill-opacity="0.12" stroke="#81A1C1"/>
+      <text x="32" y="172" font-size="13" font-weight="600">Main loop</text>
+      <text x="32" y="192" font-size="11" fill-opacity="0.7">keys to the App · events to toasts and status bar · a frame per change</text>
+
+      <!-- Services -->
+      <rect x="16" y="248" width="728" height="100" rx="8" fill="currentColor" fill-opacity="0.05" stroke="currentColor" stroke-opacity="0.55"/>
+      <text x="32" y="272" font-size="13" font-weight="600">Services · keep running whatever is on screen</text>
+      <rect x="32" y="288" width="104" height="44" rx="6" fill="none" stroke="currentColor" stroke-opacity="0.4"/>
+      <text x="84" y="315" text-anchor="middle" font-size="12">Power</text>
+      <rect x="148" y="288" width="104" height="44" rx="6" fill="none" stroke="currentColor" stroke-opacity="0.4"/>
+      <text x="200" y="315" text-anchor="middle" font-size="12">Battery</text>
+      <rect x="264" y="288" width="104" height="44" rx="6" fill="none" stroke="currentColor" stroke-opacity="0.4"/>
+      <text x="316" y="315" text-anchor="middle" font-size="12">Clock</text>
+      <rect x="380" y="288" width="104" height="44" rx="6" fill="none" stroke="currentColor" stroke-opacity="0.4"/>
+      <text x="432" y="315" text-anchor="middle" font-size="12">Wi-Fi</text>
+      <rect x="496" y="288" width="104" height="44" rx="6" fill="none" stroke="currentColor" stroke-opacity="0.4"/>
+      <text x="548" y="307" text-anchor="middle" font-size="12">Storage</text>
+      <text x="548" y="323" text-anchor="middle" font-size="10" fill-opacity="0.7">own task</text>
+      <rect x="612" y="288" width="116" height="44" rx="6" fill="none" stroke="currentColor" stroke-opacity="0.4"/>
+      <text x="670" y="307" text-anchor="middle" font-size="12">IRC</text>
+      <text x="670" y="323" text-anchor="middle" font-size="10" fill-opacity="0.7">own task</text>
+
+      <!-- Hardware -->
+      <rect x="16" y="380" width="728" height="56" rx="8" fill="none" stroke="currentColor" stroke-opacity="0.35" stroke-dasharray="4 3"/>
+      <text x="32" y="403" font-size="13" font-weight="600">Hardware</text>
+      <text x="32" y="422" font-size="11" fill-opacity="0.7">screen, keyboard, SD card, Wi-Fi today · LoRa radio and GNSS from M2 and M3</text>
+
+      <!-- Connectors -->
+      <path d="M180 248 V212" fill="none" stroke="#81A1C1" stroke-width="1.5" marker-end="url(#arrow-hot)"/>
+      <text x="192" y="234" font-size="11" fill="#81A1C1">events, queued</text>
+      <path d="M180 148 V112" fill="none" stroke="#81A1C1" stroke-width="1.5" marker-end="url(#arrow-hot)"/>
+      <text x="192" y="134" font-size="11" fill="#81A1C1">keys, redraws</text>
+      <path d="M670 108 V244" fill="none" stroke="currentColor" stroke-opacity="0.6" stroke-width="1.25" marker-end="url(#arrow)"/>
+      <text x="658" y="182" text-anchor="end" font-size="11" fill-opacity="0.7">requests</text>
+      <path d="M380 348 V376" fill="none" stroke="currentColor" stroke-opacity="0.6" stroke-width="1.25" marker-end="url(#arrow)"/>
+      <text x="392" y="366" font-size="11" fill-opacity="0.7">drivers</text>
+    </g>
+</svg>

site/content/devlog/roro9stack/index.md

@@ -0,0 +1,182 @@
++++
+title = '''roro9stack'''
+description = '''A pocket computer with a keyboard and a LoRa radio, and my first firmware written from scratch. In three days it learned to join Wi-Fi by itself, stay on IRC in the background, keep its logs on an SD card, map the Wi-Fi channels around it and find an access point by ear. The mesh messenger it's meant to become comes later.'''
+date = 2026-10-03T21:30:00+02:00
+
+[extra]
+topics = '''ESP32-S3 · LoRa · IRC'''
+read_label = '''Read how I built it →'''
+uid = '''<b>roro_2fa4</b> JOIN #roro9stack-test'''
+dek = "An M5Stack Cardputer ADV with a LoRa cap is a tiny keyboard computer with a mesh radio on its back. Meshtastic already runs on it. I wanted my own: a small multi-app firmware, a messenger first, with Wi-Fi tools and IRC beside it. This post covers the first three days, from an empty repository to v0.2.1: the skeleton, Wi-Fi, IRC and Wi-Fi Tools, dead ends included."
+byline = '''designed by interrogation again: a bot asked me about 50 questions, then wrote 260 tests before the Cardputer ran any of it'''
+
+[[extra.cast]]
+name = "The Cardputer ADV"
+role = "ESP32-S3, 8 MB flash, no PSRAM"
+text = "A 240×135 screen, a 56-key keyboard read by a TCA8418 chip, a speaker, an RGB LED, a microSD slot and a 1750 mAh battery. About 340 KB of RAM to share between everything, which turned out to be the real design constraint."
+
+[[extra.cast]]
+name = "The Cap LoRa-1262"
+role = "SX1262 + GNSS"
+text = "Clips onto the back: a LoRa radio for the 868 MHz band and a GNSS receiver. It shares its SPI bus with the SD card, so its chip-select is held high until the radio gets its own milestone."
+
+[[extra.cast]]
+name = "The dev box"
+role = "a VM with Docker"
+text = "Nothing but Docker is installed. PlatformIO, the ESP32 compiler and every library live in a container, which builds, runs the tests and flashes over USB passthrough. Mostly."
+
+[[extra.cast]]
+name = "Libera.Chat"
+role = "irc.libera.chat:6697"
+text = "The first server the Cardputer ever talked to over TLS, in an empty channel made for the occasion."
++++
+
+## TL;DR
+
+- **roro9stack** is my own firmware for the Cardputer ADV: apps on a launcher, services running underneath, and a Meshtastic-compatible messenger as its first real job.
+- Before any code, about **50 design questions**, a glossary and two decision records. The big one: write my own firmware that speaks Meshtastic, instead of forking Meshtastic.
+- **Docker is the only tool installed.** Every piece of logic is tested on the PC first: 260 tests by the end of this post.
+- **M0** (v0.1.0): launcher, status bar, settings, a first-boot wizard, toasts with beep and LED, accented letters on a US keyboard, and SD card handling.
+- **M1** (v0.2.0): the Cardputer joins Wi-Fi by itself, sets its clock over NTP, writes daily logs to the SD card, and stays on IRC over TLS in the background, with notifications when someone mentions me.
+- **Wi-Fi Tools**, finished in v0.2.1: a sortable, filterable list of the networks nearby that can log every scan to CSV, a chart of how crowded each 2.4 GHz channel is, and a tracker that follows one access point with clicks that speed up as you get closer.
+- Memory decided one thing: with IRC on TLS, the lowest free RAM fell to 51 KB, so the screen buffer went from 16-bit to 8-bit colour. That bought 28 KB back.
+- What came next, updating and debugging it all without a cable, has [its own post](/devlog/roro9stack-ota/).
+
+## What it is
+
+The Cardputer ADV is a credit-card-sized computer with a real keyboard. With the LoRa cap, it's also the obvious shape for an off-grid messenger. Meshtastic already supports this exact combination, and M5Stack even sells it as a kit.
+
+What I wanted is different: a small operating environment where the messenger is one app among several, with my own interface. Wi-Fi diagnostics, an IRC client, GNSS, a LoRa scanner, notes. The radio keeps relaying for the mesh whatever app is on screen.
+
+It's also my first embedded project. I'd never used PlatformIO, ESP-IDF or Arduino before. The bot writes the code; I decide what it should do, test it on the device, and say when something feels wrong.
+
+## The cast
+
+{{ cast() }}
+
+## Designed by interrogation
+
+Like my Music Remote, this started with questions, not code. Rounds of numbered questions, each with a recommended answer to accept or overrule: is the mesh a background service or an app? Where do messages live when there's no SD card? What happens when the card is 90 % full? About 50 decisions later, two things went into the repository.
+
+A **glossary**, so every word means one thing. A *Service* runs in the background; an *App* is what's on screen. A *Log* is recorded on its own; a *Capture* is something you start. "Channel" turned out to have three meanings (mesh, IRC, Wi-Fi), so the glossary now says which one is meant when.
+
+And **two decision records**, for the choices that are expensive to undo:
+
+- **My own firmware that speaks Meshtastic, not a fork.** A fork gives full compatibility on day one, but Meshtastic is built to be a single-purpose node, and a multi-app design would fight it everywhere. The price: re-implementing the protocol, and only partial compatibility at first.
+- **A small widget kit of my own, not LVGL.** With no PSRAM, the 40 to 60 KB LVGL would cost is memory the Wi-Fi and radio stacks need. The screens are mostly lists and text anyway.
+
+## Docker, and tests first
+
+Two scripts do everything. `scripts/ci.sh` runs the tests on the PC, then builds the firmware. `scripts/flash.sh` uploads it and opens the serial console. Versions are pinned (Arduino-ESP32 3.3 on ESP-IDF 5.5, M5Cardputer 1.1.1), so a build next year should still produce the same firmware.
+
+The rule that paid off most: **all logic lives in libraries that don't know about the hardware.** Settings validation, the battery curve, the Wi-Fi state machine, the IRC protocol, the channel arithmetic: each one has tests written before the code, and runs on the PC in seconds. The Cardputer only ever runs logic that has already passed.
+
+The last piece is a handful of serial commands. `burst` fires five notifications at once, `key select` presses a key, `irc dump` prints every IRC buffer. With those, the bot can drive the device and read its state without me touching the keyboard, which mattered more than I expected (see below).
+
+## M0: a skeleton you can hold
+
+The first milestone, tagged v0.1.0, proves the architecture every later feature plugs into:
+
+{{ diagram(src="architecture.svg", min_width=580, caption="Services keep running underneath; one App has the screen. Events come up through a single queue, so drawing never happens on two tasks at once. Storage and IRC run on their own tasks, because an SD mount or a TLS handshake can block for seconds.") }}
+
+On top of that:
+
+- **A widget kit:** list, text view, line editor, dialog, status bar and toast. Each frame is drawn off-screen and sent to the display in one transfer, about 15 ms.
+- **A keyboard layer.** Outside text fields, `; . , /` are arrows on their own; while typing, they need Fn. The `opt` key is a dead key: `opt` `'` `e` types é, which matters when you live in Belgium.
+- **Notifications** as toasts, with a beep and an LED flash. If the screen is off, it lights up dimmed while the toast shows, so you can see what beeped.
+- **Settings, an About page and a first-boot wizard** that asks for your names and your radio region. The radio isn't allowed to transmit until the region is confirmed.
+- **SD card rules:** a warning at 80 %, logs paused at 90 % to keep room for captures, and a format feature. It turned an old Raspberry Pi card, seen as 512 MB, back into 8 GB of FAT32.
+
+{{ figure(src="apps.png", alt="Four screens of the Cardputer at 2x, in a grid. Top left: the Launcher, with IRC highlighted, Wi-Fi Tools and Settings, and a blue toast reading Burst 1 at the bottom; the status bar shows roro9stack, a W with Wi-Fi bars, SD, 97 percent battery and the time. Top right: the IRC App on the buffer #roro9stack-test 2/2, with the line 21:20 Joined #roro9stack-test and an empty input box at the bottom. Bottom left: Settings, with Long name roro9stack proto, Short name roro, Region EU868, Timezone Brussels, Brightness 100 percent, Dim after 30 s, Screen off after 1 min, Sound and LED On. Bottom right: the SD card page, with SD card 7.3 GB 0 percent used, Logs recording, Captures allowed, Clean up and Erase SD card", width=976, height=556, landscape=true, full=true, caption=`The Launcher with a toast from burst, the IRC App, the first page of Settings, and the SD card page. These were captured later, over Wi-Fi, with a tool from [the next post](/devlog/roro9stack-ota/); the screens themselves are the ones from this one.`) }}
+
+## M1: Wi-Fi and IRC
+
+The Cardputer now stays online and on IRC in the background.
+
+- **Wi-Fi** keeps up to 8 saved networks and joins the strongest one in range. It backs off when none is around and turns the radio off when nothing is saved. Once connected, it sets the clock over NTP.
+- **Logs** go to daily files such as `/irc/irc.libera.chat/#roro9stack-test/2026-10-02.log`. Settings has a clean-up screen that shows how much each age cutoff ("older than 3 months") would free before deleting anything.
+- **IRC** runs as a service, connected over TLS with the server's certificate checked against the ESP-IDF bundle. It logs in with SASL or NickServ, rejoins after a drop, and raises a notification when someone mentions me or sends a private message, wherever I am. Its server settings are edited as a draft and applied in one go, under the service's lock, so the connection never sees a half-edited configuration.
+- **The IRC App** shows one buffer at a time: Tab switches between the server, channels and private chats, and each one counts its unread lines.
+
+v0.2.1 polished the IRC side after a day of use:
+
+- **Registered channels.** It falls back to NickServ when SASL fails, waits for the login to be confirmed before joining channels that only accept registered users, takes channel keys (`#private key`) in the auto-join list, and takes its nick back from a stale session.
+- **The input line** behaves like a shell: Up and Down recall what I sent, Alt with the arrow keys scrolls back through the buffer, and `/j` works as `/join`, because nobody types `/join`.
+
+Memory decided one design change. The first thing M1 did was measure: Wi-Fi costs about 60 KB of RAM, and one TLS connection another 46 KB. With IRC actually running, the lowest free memory fell to 51 KB, too close to the 40 KB floor I'd set. The fallback picked during the design round was to halve the screen buffer:
+
+{% table() %}
+| Screen buffer | Free RAM, IRC online | Lowest seen |
+| --- | --- | --- |
+| 16-bit colour, 64 KB | 61 KB | 51 KB |
+| 8-bit colour, 32 KB | 93 KB | 79 KB |
+{% end %}
+
+## Wi-Fi Tools
+
+Three tools on one menu, all built from ordinary scans. They ask the Wi-Fi Service for scans of their own: active scans of every channel, hidden networks included, which the ESP32 runs without dropping its connection. So IRC stays online while you look around. If a scan is already running for the Wi-Fi Service, its results serve both. With Wi-Fi switched off in Settings, the radio comes on for the scans and goes off again when you leave.
+
+{{ figure(src="wifi-tools.png", alt="Four screens of Wi-Fi Tools at 2x, in a grid. Top left: the menu, with Networks nearby highlighted, Channel occupancy and Signal tracker. Top right: the networks list, sorted by channel, with LOG 6 in orange at the top right; rows read knbg-guests ch1 -48 WPA2, a blacked-out name ch1 -48 WPA2, (hidden) ch1 -49 WPA2, a blacked-out name ch6 -68 WPA2, knbg-guests ch6 -68 WPA2, (hidden) ch6 -68 WPA2. Bottom left: channel occupancy, reading 6 networks, quietest of 1/6/11: 11, with bars over channels 1 to 13: tall on 1, medium on 2 and 6, small on 3, 4, 5, 7 and 8, nothing from 9 to 13, and the 11 label in green. Bottom right: the signal tracker on knbg-guests, with its BSSID, ch1 and m: clicks on, a large -48 dBm, a green bar about three quarters full, and a flat block of history bars", width=976, height=556, landscape=true, full=true, caption=`The menu, Networks nearby sorted by channel while logging, Channel occupancy, and the Signal tracker. The neighbours' network names are blacked out; mine stays. The tracker's history is flat because the Cardputer was sitting on a shelf, which is exactly when a signal tracker is least interesting.`) }}
+
+**Networks nearby** lists every access point the last scan saw, with its channel, signal and security, and rescans every 4 seconds. A few letters change what's shown:
+
+{% table() %}
+| Key | Does |
+| --- | --- |
+| `s` | Cycles the sort: by signal, by channel, by name |
+| `o` | Only open networks |
+| `h` | Hides hidden networks |
+| `w` | Only strong ones, −75 dBm or better |
+| `l` | Logs every scan to the SD card |
+| Enter | Opens the Signal tracker on that network |
+{% end %}
+
+The line above the list says which sort and filters are on, and `LOG 6` in the corner counts the rows written so far. A log is a CSV file per day, `/wifi/scans/2026-10-03.csv`: a header, then one row per access point per logged scan, with the time, BSSID, channel, RSSI, security and SSID, quoted when a field contains a comma or a quote. It logs at most every 30 seconds, only while Wi-Fi Tools is on screen, and only once the clock is set, because a row without a time is useless. Storage Clean-up has a "Wi-Fi scan logs" category to delete old ones by age. The CSV format, the throttle, and the sorting and filtering are all host-tested, down to an SSID with a comma in it.
+
+**Channel occupancy** shows how crowded each 2.4 GHz channel from 1 to 13 is. A 20 MHz network doesn't stay on its channel: it spills onto the channels up to two away, less the further it goes. So each network adds to five bars, and a strong signal counts more than a faint one. Channels 1, 6 and 11, the only three that don't overlap, are drawn in blue, and the quietest of those three gets a green label: that's where to put your own access point. Here it's 11, which nobody nearby uses at all.
+
+**Signal tracker** follows one access point, picked from the list. It rescans only that network's channel, every 0.4 seconds, and shows the signal in dBm, as a bar, and as a graph of the last 110 readings, about 45 seconds. It also clicks, like a Geiger counter: once every 1.2 seconds at −95 dBm, speeding up to every 60 ms at −35 dBm. Walk around with it and listen; the clicks get frantic near the access point. `m` mutes them, and after 5 seconds without a sighting the readout says "lost".
+
+Everything here comes from ordinary scans. Tools that would need more than that were on the plan, and are on hold.
+
+## Where it hurt
+
+**The toast that expired before it appeared.** Toasts showed late, and a burst of five showed only some of them. The main loop read the clock once per pass, but each toast was stamped a few milliseconds later. In unsigned arithmetic, "3 ms in the future" is "49 days ago", so the toast was already expired when it arrived. A failing test reproduced it; a signed comparison fixed it.
+
+**The bug that wasn't.** After that fix, I still saw only "Burst 3" and "Burst 5". Instead of fixing it a second time, the bot added logs, then fired the burst itself over serial: all five drawn, exactly 3 s apart. The real culprit was an earlier test key that had saved a 10-second screen timeout, so the screen went dark mid-burst. Measure before fixing twice.
+
+**The SD card that froze everything.** With no card inserted, each mount attempt blocked for 2.5 seconds, every 15 seconds. All card access moved to its own task, which later also became the only writer of logs, since the SD driver doesn't like two tasks at once.
+
+**Errno 71.** My dev box is a VM with USB passthrough. Every so often, flashing fails with `OSError: [Errno 71] Protocol error`, and retrying never helps; resetting the Cardputer does. Separately, stopping a background serial logger didn't stop its Docker container, which kept the port busy and made flashes fail quietly. The logger now runs in a named container that the flash script removes first. This one eventually got a whole post of its own: [Look, no cables](/devlog/roro9stack-ota/).
+
+**The channel that wouldn't let me in.** My registered IRC channel refused every join. The obvious fix was a delay: join only after NickServ confirms the login. It still failed, so the bot dumped the whole server buffer instead of guessing again. Three problems were stacked. SASL had failed, and because SASL was configured, NickServ was never tried. Then the device's previous connection, cut short by a reflash, still held my nick, so it logged in as `roro9_` and identified the wrong name. Now SASL falls back to NickServ, the identify names the account explicitly, and the device takes its nick back from a stale session. The last layer was the password I'd typed, which is mine to fix. Still. The screenshot above is in a channel that doesn't ask.
+
+## By the numbers
+
+{% table() %}
+| | |
+| --- | --- |
+| Commits from the first, on 1 October, to v0.2.1 | 30 |
+| Firmware code, without font data | about 7,000 lines of C++ |
+| Tests | 260, in 28 suites, about 3,400 lines |
+| Flash used by the app | 1.49 MB of 3.3 MB (45 %) |
+| Lowest free RAM, Wi-Fi and IRC on TLS | about 80 KB |
+{% end %}
+
+## Where it ended up
+
+{% steps() %}
+1. ~~M0: launcher, status bar, settings, first-boot wizard, toasts, Compose key, SD card rules.~~ Done, tagged v0.1.0.
+
+2. ~~M1: memory baseline, Wi-Fi service, logs and clean-up, IRC service, IRC app, Wi-Fi Tools.~~ Done, tagged v0.2.0.
+
+3. ~~IRC polish, and Wi-Fi Tools' sorting, filters and scan logs.~~ Done, tagged v0.2.1.
+
+4. ~~Firmware updates without a cable, and remote debugging.~~ Not on the original plan, and done since, in v0.3.0: [Look, no cables](/devlog/roro9stack-ota/).
+
+5. Next: M2, GNSS, with position, fix status and a radar view. Then M3, the LoRa radio, with a scanner, plus notes and a file browser. Then M4 and M5, the mesh: receiving and decoding Meshtastic packets first, then sending, direct messages, relaying and EU868 duty-cycle limits. That part waits for a second Meshtastic node to test against.
+{% end %}
+
+{% signoff() %}
+Three days, one skeleton, two networks to talk on, and a device that clicks when you walk towards your router. The next part cut the USB cable.
+{% end %}

site/content/downloads/index.md

@@ -0,0 +1,5 @@
++++
+title = "Downloads"
+description = "Every release of roro9stack: the signed update file, the factory image for USB, and what changed."
+template = "downloads.html"
++++

site/content/guide/_index.md

@@ -0,0 +1,13 @@
++++
+title = "User guide"
+description = "How to use each App on the Cardputer: the keys, what the screens show, and what is written to the SD card."
+template = "guide-index.html"
+sort_by = "weight"
+page_template = "guide-page.html"
++++
+
+This guide says what the firmware does **today** and nothing else. Start with the basics (the keys, the Launcher, the first start), then read the page of any App. It describes the latest release; the numbers and key names come from the firmware's own source.
+
+**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.
+
+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

@@ -0,0 +1,63 @@
++++
+title = "The basics"
+description = "The keys, the Launcher, the Status Bar and what happens the first time you switch the device on."
+weight = 1
+[extra]
+tag = "Start here"
++++
+
+## The keys
+
+The Cardputer's keyboard has no arrow keys and no Escape, so the firmware gives a few keys a second job:
+
+| Key | Does |
+|---|---|
+| <kbd>Enter</kbd> | Opens or confirms the selected item |
+| <kbd>`</kbd> | **Back**: one step out of a screen, and out of an App |
+| <kbd>Fn</kbd> + <kbd>`</kbd> | **Home**: back to the Launcher |
+| <kbd>Fn</kbd> + <kbd>;</kbd> <kbd>.</kbd> <kbd>,</kbd> <kbd>/</kbd> | The arrows: up, down, left, right |
+| <kbd>;</kbd> <kbd>.</kbd> <kbd>,</kbd> <kbd>/</kbd> alone | The same arrows, as long as you are **not** typing text |
+| <kbd>Tab</kbd> | Switches view in an App that has more than one |
+| <kbd>Del</kbd> | Deletes backwards when you type |
+| <kbd>opt</kbd> then an accent, then a letter | Types an accented letter: <kbd>opt</kbd> <kbd>'</kbd> <kbd>e</kbd> gives é |
+
+While you type text (a note, an IRC line, a setting), `;` `.` `,` `/` type their own characters and you need <kbd>Fn</kbd> for the arrows. The bottom of the screen shows `opt` while a compose is waiting for its letter.
+
+## The Launcher
+
+The home screen lists the Apps. Move with the arrows, open one with <kbd>Enter</kbd>. Back inside an App returns here.
+
+## The Status Bar
+
+A strip at the top of every screen: the name of the App on the left, and on the right, from the edge inwards:
+
+| Shows | Means |
+|---|---|
+| the time | The clock, once Wi-Fi or a GNSS fix has set it |
+| `[3]` | Unread IRC messages that mention you, or private ones |
+| `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 |
+| `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 |
+| `G` or `G12` | The GNSS receiver is searching (`G`, dim), has a 2D fix (`G`), or has a 3D fix with that many satellites (`G12`) |
+
+## Toasts
+
+News from a background service (an IRC mention, a Storage warning, an update that is out) shows as a short message over whatever App is open, and can beep and flash the LED. **Sound & LED** in Settings turns that off.
+
+## The first start
+
+On a new device a short Setup asks four things, then never appears again:
+
+1. **Long name**, up to 39 bytes.
+2. **Short name**, up to 4 characters.
+3. **Radio region.** Nothing will transmit until you confirm yours. EU868 is the supported region.
+4. **Timezone.**
+
+## The SD card
+
+Put a microSD card in the Cardputer. Without one the radio, GNSS, Wi-Fi and IRC still work, but nothing can be saved: no notes, IRC logs, Wi-Fi scan logs, GPX tracks, LoRa captures or saved Gemini pages. The [Storage App](/guide/storage/) shows what is on the card.
+
+The firmware keeps its own folders at the top of the card (`captures`, `gemini`, `gnss`, `irc`, `updates`, `wifi`, plus `notes`). You can use the card in a computer too, but those names are the firmware's.

site/content/guide/gemini.md

@@ -0,0 +1,42 @@
++++
+title = "Gemini"
+description = "Browse Geminispace: follow links, go back, bookmark pages and keep them on the SD card to read offline."
+weight = 4
+[extra]
+tag = "Gemini"
+screens = ["gemini.png"]
++++
+
+[Gemini](https://geminiprotocol.net/) is a small, text-first protocol: pages are plain **gemtext**, served over an encrypted connection, from **capsules** instead of sites. It needs Wi-Fi.
+
+## Reading
+
+| Key | Does |
+|---|---|
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Picks the next or previous link |
+| <kbd>Enter</kbd> | Follows the link |
+| <kbd>`</kbd> (Back) | Returns to the previous page, at the place where you scrolled to |
+| Up and down | Scroll a line |
+| <kbd>Space</kbd> | Pages down |
+| <kbd>g</kbd> | Types an address |
+| <kbd>b</kbd> | Bookmarks the page |
+| <kbd>s</kbd> | Saves the page to the card |
+| <kbd>S</kbd> | Saves it with the pages it links to |
+
+Headings, lists, quotes and preformatted blocks are drawn as gemtext intends, wrapped to the screen. Links to other protocols show their address and are not followed. A page that asks for input (a search, say) shows a prompt, and a password prompt hides what you type. Characters outside the Latin fonts show as `?`. The history keeps the last 20 pages.
+
+## The start page
+
+It lists your **bookmarks**, then your **Saved Pages**, then a few starting points: geminiprotocol.net, a search engine and an aggregator. Without a card it shows only the built-in starting points.
+
+## Certificates: trust on first use
+
+Most capsules sign their own certificate. The first certificate seen for a host is **remembered**; if it later changes, the page is not shown and you are asked whether to trust the new one, with both fingerprints on screen. Expired or self-signed certificates are fine: only a *change* counts. Client certificates are not supported.
+
+## Saved Pages
+
+<kbd>s</kbd> keeps the page on the card, with the address it came from and when it was saved, and you can read it with no network. <kbd>S</kbd> also saves the pages it links to on the **same capsule**, as text only, up to 30, in the background. On the start page, Saved Pages are listed by capsule, newest first. Inside one, <kbd>r</kbd> **refreshes** it and <kbd>d</kbd> **deletes** it. A link to another saved page opens the saved copy; any other link fetches online if Wi-Fi is up, or says it is not saved. A file that is not text (a picture, say) is saved to `/gemini/downloads/` instead of being shown. The Storage clean-up never offers Saved Pages for deletion.
+
+## Big pages and memory
+
+With a card, every page streams to the card first, so a page larger than the device's memory still arrives whole and is read from the card as you scroll. Without a card, a page is limited to what fits in memory. If there is not enough free memory to open a secure connection, the fetch says so instead of failing silently; stopping IRC frees the most.

site/content/guide/gnss.md

@@ -0,0 +1,30 @@
++++
+title = "GNSS"
+description = "Where you are and which satellites you can see, from the Cap's receiver, with Tracks saved to the SD card as GPX."
+weight = 3
+[extra]
+tag = "GNSS"
+screens = ["sky.png"]
++++
+
+GNSS needs the **Cap LoRa-1262**, an antenna with a view of the sky, and **Settings → GNSS** switched **On**. Otherwise the App says `GNSS is off` (or `paused`, when "Pause GNSS for LoRa" has put the receiver on standby while the radio listens). A first fix outdoors can take a while: the App says how long it has been searching.
+
+## Position
+
+The first view shows the fix (`No Fix`, `2D Fix` or `3D Fix`, and how many satellites it uses), then:
+
+- **Lat** and **Lon**, in decimal degrees or degrees, minutes and seconds (**Settings → Coordinates**);
+- the **Locator**, the Maidenhead grid square;
+- **Altitude**, **Speed** and the direction you are moving;
+- **HDOP**, the horizontal precision: a smaller number is better;
+- the **Time**, in UTC.
+
+Once there is a fix, the device's clock follows it.
+
+## Sky
+
+<kbd>Tab</kbd> switches between Position and **Sky**: a circle with N, E, S and W, where each satellite is a dot, coloured by constellation, and filled when the receiver uses it. A legend counts, for each constellation (GPS, GLONASS, Galileo, BeiDou), the satellites used and in view.
+
+## Tracks
+
+<kbd>r</kbd> starts recording a **Track**: the route is saved as a **GPX** file on the SD card, in `/gnss/tracks` (named by date and time), and the Status Bar shows `REC`. Press <kbd>r</kbd> again to stop. A Track keeps recording with the App closed. It needs a card and a clock (a fix or Wi-Fi sets it); if it cannot start, the App says why: `GNSS is off`, `No SD card` or `Waiting for the time`. The [Storage App](/guide/storage/) opens a `.gpx` file and shows its points, start, duration and distance.

site/content/guide/irc.md

@@ -0,0 +1,51 @@
++++
+title = "IRC"
+description = "Chat on an IRC server from the keyboard, with a connection that outlives the App and daily logs on the SD card."
+weight = 5
+[extra]
+tag = "IRC"
++++
+
+## Connecting
+
+The first time, type `/settings` and press <kbd>Enter</kbd>. The settings page has:
+
+- **Server** and **Port**, and **TLS** (on or off).
+- **Self-signed:** for a server whose certificate no authority signed. It is *pinned on first use*: the first certificate it sees is remembered, and a different one later is refused.
+- **Nick**, **SASL user** and **SASL password**, **NickServ password**: passwords show only as `(set)`.
+- **Auto-join:** the channels to join after connecting.
+- **Save & reconnect.**
+
+Opening the IRC App connects, if Wi-Fi is up. The connection belongs to a **background service**: leaving the App does not disconnect, and new messages keep arriving and being logged. It reconnects by itself after a drop, and does not start by itself after a restart.
+
+## Chatting
+
+You type at the bottom; <kbd>Enter</kbd> sends. A line starting with `/` is a command:
+
+| Command | Does |
+|---|---|
+| `/join #channel [key]` (or `/j`) | Joins; the `#` is optional |
+| `/part [#channel] [message]` | Leaves |
+| `/msg nick text` (or `/query`) | Opens a private chat, sending the text if there is any |
+| `/me text` | An action line |
+| `/nick newnick` | Changes your nick |
+| `/topic [text]` | Shows or sets the channel topic |
+| `/names [#channel]` | Lists who is there |
+| `/quit [message]` | Disconnects and **stays disconnected** until you type something again |
+| `/raw …` (or `/quote`) | Sends a line to the server as it is |
+| `/settings` | The settings page |
+
+Each server, channel and private chat is a **buffer**. <kbd>Tab</kbd> moves to the next one, each shows how many messages are unread, and your own lines are in the accent colour. Scroll back with <kbd>Alt</kbd> + <kbd>;</kbd> (older) and <kbd>Alt</kbd> + <kbd>.</kbd> (newer). The up and down arrows (<kbd>Fn</kbd> + <kbd>;</kbd> and <kbd>.</kbd>) recall lines you sent.
+
+## Mentions and the unread count
+
+A message with your nick in it, or any private message, is a **mention**: it shows a Toast over whatever App is open, and counts in the Status Bar's `[n]`. Other traffic only adds to the buffer's unread count.
+
+## Logs
+
+Every buffer is logged to the SD card, one file per day, under `/irc`. Logs stop when the card passes 90% full, to keep the rest for captures; nothing is deleted without your asking, in the [Storage App](/guide/storage/)'s Maintenance.
+
+## Good to know
+
+- IRC **pauses** while Wi-Fi is monitoring (the Status Bar shows `MON`) and while the device **installs an update**. It reconnects and rejoins its channels afterwards; the App says `paused` in the meantime.
+- A secure connection costs memory: IRC's takes about 40 KB of the 107 KB the device has, and an update's download needs about 52 KB more. That is why IRC steps aside for an update, and why the daily update check waits for IRC to be disconnected (see [Updates](/guide/updates/)).

site/content/guide/lora-scanner.md

@@ -0,0 +1,35 @@
++++
+title = "LoRa Scanner"
+description = "Listen to the radio: every packet it hears, a survey of signal strength from 863 to 870 MHz, and captures for Wireshark. It only listens."
+weight = 2
+[extra]
+tag = "LoRa Scanner"
+screens = ["sniffer.png", "sweep.png"]
++++
+
+The Scanner uses the **Cap LoRa-1262**. It **never transmits**: it listens and shows.
+
+## Sniffer
+
+The first view lists what the radio hears, newest first: the time, the RSSI (signal strength, in dBm) and the SNR (signal over noise, in dB). For a **Meshtastic** packet it also shows the sender and the receiver (the last four hex digits of their numbers) and the number of hops.
+
+| Key | Does |
+|---|---|
+| <kbd>Enter</kbd> | The details of a packet: the Meshtastic header, which is never encrypted, and a hex dump |
+| <kbd>p</kbd> | Picks one of the 7 Meshtastic presets allowed in EU868 (LongFast by default) |
+| <kbd>c</kbd> | Starts or stops a **capture** |
+| <kbd>Tab</kbd> | Switches to the Sweep |
+
+The Scanner shows the header and the bytes; it does not decrypt the message itself, which Meshtastic encrypts with the channel's key.
+
+## Capture
+
+A capture records packets into a **pcap** file with LoRaTap headers in `/captures/lora/` on the SD card, to open in Wireshark. It keeps recording with the App closed (the Status Bar shows `CAP`); the radio sleeps when the App is not open and no capture is running. Captures are never deleted unless you ask, in the [Storage App](/guide/storage/), which can also show a pcap's packets on the device.
+
+## Sweep
+
+<kbd>Tab</kbd> switches to the Sweep: the signal strength across **863 to 870 MHz** in 100 kHz steps, drawn as bars with a mark at each peak, and a waterfall under them. The frequency the Sniffer listens on is marked. The Sniffer is paused during a Sweep and picks up where it was. The Status Bar shows `SW`.
+
+## The GNSS receiver raises the noise
+
+The GNSS receiver on the same Cap makes the radio's noise floor about **8 dB** worse while it runs. **Settings → Pause GNSS for LoRa** (off by default) puts the receiver on standby while the radio listens, except while a Track is being recorded.