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