One firmware: the Debug Console in every build, off until switched on, with the device's own token

There is no Debug Build any more (ADR 0010, issue #68, Q188 to Q195). The
console and the test commands are compiled into every firmware. It listens
only while Settings > Debug Console is on, which isn't the default; off,
neither its task nor its 4 KB ring exists. The token is made by the device
and shown on that page; a client proves it knows it by answering a challenge
with an HMAC, so it never crosses the network, and five wrong answers close
the console for a minute. DBG in the Status Bar while it listens.

Over USB serial only: debug on, debug token <value>, debug token new.
scripts/flash.sh --debug uses them to set a device up with the developer's
token. scripts/rdbg.py takes the token from -t, $RORO_DEBUG_TOKEN or the
file, answers the challenge, and fetches a release's ELF to decode a crash.

Gone: the cardputer-adv-debug environment, RORO_DEBUG, the +debug version,
scripts/debug_flags.py, update install ... force, and the rule that a Debug
Build doesn't install releases. Old clients and old firmwares don't talk to
each other.

Against the builds it replaces: 30 KB more flash and 88 bytes more static
RAM than the release, 4 KB less RAM than the Debug Build. 468 host tests.
Checked on the device: off by default, login, the pause after wrong tokens,
Safe Mode with the console, the setting surviving an update, debug off.

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

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

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