twislaandClaude Opus 5.5
1874a1b586
The framework's server begin() fails without a word: the console's task now asks whether it listens, says so, and tries again. `debug off <seconds>` closes the console and reopens it after the pause, which is the only way to test its closing and reopening from afar. Checked on the device: 25 closings and reopenings, each back a second after the pause. Free heap dips about 270 bytes for each connection the device closes and is all back two minutes later (TCP keeps a closed connection that long): not a leak. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT
4.5 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 (the question opens on Cancel: move to Switch on), and makes a token if there is none |
| Connect to | The address and port: 10.39.39.12:2323 |
| New token | Makes another one. The old one stops working, and whoever is connected is cut off |
| Type a token | One of your own, of 16 to 64 characters |
Under the rows, the token, in large type on two lines, in groups of four: K7QF-3M2X-9WBD-HT4P-6RNC. This page is the only place it is ever shown. The Status Bar shows DBG while the console listens, and brighter while someone is connected.
The setting stays across restarts and updates, and in Safe Mode.
The token
- The device makes it, from its hardware random generator, the first time the console is switched on: 100 bits, written as 20 characters without the letters that get misread (no I, L, O or U).
- Dashes and case do not count, and an
O,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 off 30 # ...for 30 seconds: it comes back by itself
debug on and debug token work over USB serial only: the console cannot be used to open itself wider. debug status and debug off work from anywhere, and a screenshot taken over the console while this page is open shows the token, to someone who already had it. Your token file is made by the first build (scripts/_docker.sh), 32 hex digits, and is never committed.
Since the setting survives updates, this is needed once for a device, not at each flash. Later builds go over Wi-Fi with scripts/flash.sh --ota.
Should it be on?
On your own network, on a device you are working on: yes, that is what it is for. Remember what it gives to whoever has the token and is on the same network: the console, the keys, the files on the SD card, a restart. It does not give them the firmware: an update still has to be signed.
On a network you share with strangers, switch it off, or at least know that what the console prints is not encrypted. The token is safe there; the conversation is not.