Public Access
twislaandClaude Opus 5.5
db265fb757
Peak stack use was measured through each task's worst case (an ECDSA-checked install over Wi-Fi and from SD, get/put, a core dump fetch, an IRC TLS handshake); stacks are now peak plus about 2 KB: loop 8 -> 6 KB, update 8 -> 5, storage 10 -> 6, irc 8 -> 6. The Debug Build's console ring goes 6 -> 4 KB, serial TX 2 -> 1 KB, the GNSS UART buffer 1 KB -> 512 B. On the device, with IRC on TLS: 46 KB free (was 31), an 18 KB low (was 9.4). The re-run of every worst case left at least 1.6 KB of stack free in each task. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT
24 lines
2.9 KiB
Markdown
24 lines
2.9 KiB
Markdown
# A Debug Console over Wi-Fi, in Debug Builds only
|
|
|
|
The goal of Firmware Updates is to manage the device without a cable, and that includes finding out what went wrong. So a **Debug Build** (`cardputer-adv-debug`, `-DRORO_DEBUG`, version suffix `+debug`) adds a **Debug Console** on TCP 2323: the serial console, over Wi-Fi. A client sends a token as its first line, then gets the last 4 KB of console output (boot messages included), every new line live, and runs the same commands as the serial port, plus a few that only make sense remotely. ESP-IDF's own log lines are teed into it.
|
|
|
|
It's compiled out of release builds entirely, rather than switched off by a setting. A console that runs commands is a remote control: in a release build, nothing listens.
|
|
|
|
## How it fits
|
|
|
|
- **Console, not Serial.** All human-readable output goes through `console`, which writes to the USB port and, in a Debug Build, to a ring buffer the Debug Console drains. Writes never wait for USB: a host that's attached but not reading used to stall the main loop for up to 2 s per line.
|
|
- **Commands run on the main loop.** The socket lives on the Debug Console's own task, which only queues command lines. The main loop runs them, as it does serial commands, so they touch Apps and Services from the one task allowed to.
|
|
- **The token** is 128 random bits in `~/.config/roro9stack/debug-token`, made by the first build and passed into the container. It's never committed; a Debug Build refuses to compile without one. Like the OTA key, it guards against the network, not against someone holding the device.
|
|
- **One client at a time**, to keep memory flat (4 KB for the ring since M2, 6 KB of task stack).
|
|
- **Binary commands are answered on the console's own task**, not queued: `get`/`put` (SD card files, run as one Storage Service job each so card access stays on the storage task, with TCP doing the flow control), `screenshot` (the 32 KB RGB332 frame the UI composes into, read as it stands, so it may tear), `coredump get` and `reset`. These keep working when the main loop is stuck. A failed `put` closes the connection, so the rest of the file is never read as commands.
|
|
|
|
## Keep a Debug Build in the fallback slot
|
|
|
|
Rollback returns to the previous firmware, whatever it is. As long as development goes through Debug Builds, the firmware a crash falls back to has the Debug Console, so a bad update never costs remote access. A release build pushed over a Debug Build leaves the Debug Build in the other slot until the next update overwrites it.
|
|
|
|
## Consequences
|
|
|
|
- Anyone on the same network with the token can read the console, inject keys and reboot the device. The console never prints stored secrets (Wi-Fi and IRC passwords), but the IRC traffic it shows is readable.
|
|
- The TCP stream is plain text: fine on a home network, not across the internet.
|
|
- `+debug` versions compare equal to their release counterparts, so moving between the two is never refused as a downgrade.
|