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