Switch the console on

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:

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 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.