twislaandClaude Opus 5.5
c68741cc46
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
4.4 KiB
+++ 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 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,IorLis taken for the0or1it 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 says how).
- It guards against the network, not against someone who holds the device: anyone with USB access can flash anything anyway (ADR 0003).
Give rdbg.py the token
scripts/rdbg.py looks for it in this order:
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:
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.