Debug shell: a local shell on the device with every debug command #67

New Issue

2026-10-06T19:30:11Z

twisla commented

2026-10-06 19:30:11 +00:00

The serial and Debug Console commands (info, tasks, ls, key, update …, lora …, crash, …) can only be typed on a PC. Idea: an App with a shell on the Cardputer's own screen and keyboard, running the same commands, so the device can be inspected and driven with no PC and no Wi-Fi: in the field, on a dead network, or with a Debug Build in a bag.

Why it fits: the commands already run through one dispatcher (runCommand in src/main.cpp), the same for USB serial and the Debug Console. A shell is a third place to type into it, and the IRC App already has the pieces: a line editor with history, a scrolling buffer, and Alt+;/. to scroll.

Questions for a design round (Qnn):

Which builds? In a Debug Build, obviously all the commands. In a release build, the serial commands already exist over USB, so a shell exposes nothing a person holding the device with a cable cannot do. But key, rm, install and reset-like commands on the device's own screen are easy to hit by accident. A shell only in Debug Builds, behind an explicit Settings switch, or in all builds with a smaller command set?
Output: the console's ring is 4 KB and Debug-only today; a release build prints to USB only. Where does a shell's output come from, and what does it cost in heap (see concern/memory)? A fixed 2 to 4 KB scrollback?
Screen and keys: 240×135 px with the small font is about 40 columns × 10 lines. Tab completion for command names and card paths? Fn+arrows for history and cursor, which the line editor already does.
Long-running commands (tasks takes a second, lora sweep, update install): run on the main loop as now, and show a spinner? Cancel with Back?
Safe Mode: the shell should be one of the things that still starts there, with the same short list of commands.
Binary commands (get, put, screenshot, coredump get, reset) have no meaning on the device itself and stay Debug Console only.
Sharing with the console: one command dispatcher, one output path with several sinks (USB, Debug Console ring, shell)? That is also a chance to stop commands writing to console directly.

Done when (to be refined): an App listed in the Launcher where help works and a handful of read-only commands (info, ls /, net, tasks) show their output; destructive commands ask first; documented in the developer docs.

The serial and Debug Console commands (`info`, `tasks`, `ls`, `key`, `update …`, `lora …`, `crash`, …) can only be typed on a PC. Idea: an **App with a shell on the Cardputer's own screen and keyboard**, running the same commands, so the device can be inspected and driven with no PC and no Wi-Fi: in the field, on a dead network, or with a Debug Build in a bag. **Why it fits:** the commands already run through one dispatcher (`runCommand` in `src/main.cpp`), the same for USB serial and the Debug Console. A shell is a third place to type into it, and the IRC App already has the pieces: a line editor with history, a scrolling buffer, and Alt+`;`/`.` to scroll. **Questions for a design round (Qnn):** - **Which builds?** In a Debug Build, obviously all the commands. In a release build, the serial commands already exist over USB, so a shell exposes nothing a person holding the device with a cable cannot do. But `key`, `rm`, `install` and `reset`-like commands on the device's own screen are easy to hit by accident. A shell only in Debug Builds, behind an explicit Settings switch, or in all builds with a smaller command set? - **Output:** the console's ring is 4 KB and Debug-only today; a release build prints to USB only. Where does a shell's output come from, and what does it cost in heap (see `concern/memory`)? A fixed 2 to 4 KB scrollback? - **Screen and keys:** 240×135 px with the small font is about 40 columns × 10 lines. Tab completion for command names and card paths? Fn+arrows for history and cursor, which the line editor already does. - **Long-running commands** (`tasks` takes a second, `lora sweep`, `update install`): run on the main loop as now, and show a spinner? Cancel with Back? - **Safe Mode:** the shell should be one of the things that still starts there, with the same short list of commands. - **Binary commands** (`get`, `put`, `screenshot`, `coredump get`, `reset`) have no meaning on the device itself and stay Debug Console only. - **Sharing with the console:** one command dispatcher, one output path with several sinks (USB, Debug Console ring, shell)? That is also a chance to stop commands writing to `console` directly. **Done when (to be refined):** an App listed in the Launcher where `help` works and a handful of read-only commands (`info`, `ls /`, `net`, `tasks`) show their output; destructive commands ask first; documented in the developer docs.

twisla added this to the S1 System basics milestone 2026-10-06 19:30:11 +00:00

twisla added the

kind

feature

area/apps area/ui area/ota-debug

labels 2026-10-06 19:30:11 +00:00

twisla referenced this issue

2026-10-06 22:26:41 +00:00