Shell: the console's commands on the device's own screen and keyboard (#67)

An App in the Launcher that runs the same commands as USB serial and the
Debug Console, trusted like the first. It shows what the console prints
while it is open, through a second ring of the console's that exists only
meanwhile; Ctrl+b keeps only what follows your own commands. Tab completes
a command's name from the firmware's help text, Fn with up and down recalls
earlier lines, Alt with up and down scrolls back. `rm` asks first in the
Shell, `rm -f` doesn't. Nothing is kept once the App is left.

`screenshot [seconds]` saves the screen as a PNG in /screenshots on the
card, now or after a pause: written a row at a time, indexed colour with
RGB332 as the palette, in one stored deflate block.

487 host tests (11 new: the PNG writer, the Shell's log filter, Tab).
Checked on the device over the Debug Console: commands, Tab, history, a
screenshot fetched and decoded on the PC, rm with and without the question,
a delayed screenshot of another screen. 12 KB of flash; 7 KB of heap while
open. Decisions Q204 to Q212 in docs/milestones/S1.md. Safe Mode: #77.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT

site/content/dev/debug/commands.md

@@ -19,10 +19,11 @@ net               bytes each network service has read and written since boot
 reboot            restart
 boot other        restart into the other app slot (manual Rollback)
 log level <0-5>   ESP-IDF log level (0 none ... 5 verbose)
-ls [folder] | du <path> | mkdir <path> | rm <path> | cp [-f] <from> <to> | mv [-f] <from> <to> | cancel   the SD card, with the Storage App's rules
+ls [folder] | du <path> | mkdir <path> | rm [-f] <path> | cp [-f] <from> <to> | mv [-f] <from> <to> | cancel   the SD card, with the Storage App's rules
+screenshot [seconds]   the screen as a PNG in /screenshots on the card, now or after a pause
 lora probe | lora status | lora rx on|off | lora preset <name>   the LoRa radio, receive only
 lora capture start|stop   a LoRa Capture to /captures/lora (pcap, LoRaTap)
-lora sweep on [from MHz] [to MHz] [step kHz] | off | dump   RSSI across a band (863 870 100)
+lora sweep on [from MHz] [to MHz] [step kHz] | lora sweep off | lora sweep dump   RSSI across a band (863 870 100)
 lora custom <MHz> <BW kHz> <SF> <CR 5-8> <sync hex> [preamble]   e.g. 868.1 125 7 5 34 8 (LoRaWAN)
 gnss quiet on|off   pause the GNSS receiver while the LoRa radio listens (it costs the radio 8 dB)
 gnss status | gnss restart | gnss track start|stop | gnss nmea on|off | gnss send <sentence without $ and checksum>
@@ -35,7 +36,7 @@ wifi dns <a> [b] | wifi dns always on|off | wifi ntp <a> [b]   DNS and NTP serve
 gemini get <url>  fetch a Gemini page and report header, size, certificate, heap
 irc start | irc stop | irc dump | irc say <buffer> <text>
 install <path.ota>   Update from SD
-update check | list | status | install <tag>   the project's releases on Gitea
+update check | update list | update status | update install <tag>   the project's releases on Gitea
 sd card | sd list | cat <path> | log <text> | burst | sound on|off | short | normal
 debug status | debug off [seconds]   the Debug Console over Wi-Fi (Settings > Debug Console); with seconds, it comes back
 debug on | debug token <16 to 64 characters> | debug token new   (USB serial only) switch it on, set its token
@@ -47,7 +48,7 @@ lora inject <hex> [rssi] [snr]   a packet into the LoRa Scanner as if received (
 sd fill <folder> <count>   makes that many small files there, to test a crowded folder
 coredump get      (Debug Console only) send the raw core dump: use scripts/rdbg.py coredump
 reset             (Debug Console only) restart at once, even if the main loop is stuck
-get <path> | put <path> <size> <sha256> | screenshot   (Debug Console only) binary, see rdbg.py
+get <path> | put <path> <size> <sha256> | screenshot   (Debug Console only) binary, see rdbg.py: there, a bare `screenshot` sends the screen instead of saving it
 quit              close the Debug Console connection
 ```
 
@@ -84,7 +85,8 @@ In **Safe Mode** (see [Crashes and Safe Mode](/dev/debug/crashes/)) only a few r
 | `reboot` / `boot other` | Restart, or restart into the other app slot (a manual Rollback) |
 | `log level <0-5>` | ESP-IDF log level |
 | `ls [folder]` / `du <path>` | Lists a folder of the SD card with sizes and dates, or counts the files and bytes under a path |
-| `cp [-f] <from> <to>` / `mv [-f] <from> <to>` / `rm <path>` / `mkdir <path>` / `cancel` | What the Storage App does, with its rules: copy (folders too), move or rename, delete (a folder with what's in it), new folder. `-f` replaces a file that's in the way; a tab separates paths that hold spaces; `cancel` stops a copy or a delete |
+| `screenshot [seconds]` | The screen as a PNG in `/screenshots` on the card, now or after a pause to get to the screen you want (240 x 135, about 33 KB). Over the Debug Console a bare `screenshot` sends the screen to the PC instead |
+| `cp [-f] <from> <to>` / `mv [-f] <from> <to>` / `rm [-f] <path>` / `mkdir <path>` / `cancel` | What the Storage App does, with its rules: copy (folders too), move or rename, delete (a folder with what's in it), new folder. `-f` replaces a file that's in the way; a tab separates paths that hold spaces; `cancel` stops a copy or a delete |
 | `install <path>` | Update from SD with that `.ota` file, as Settings → Firmware does |
 | `update check` / `update list` / `update status` / `update install <tag>` | The project's releases on Gitea: look at the latest, list the last ten, say what's known, or download and install one |
 | `update pretend <version>` / `update probe <host>` / `update damage cut\|flip <n>` / `update daily` | Pretend to run another version (so a release counts as an update), see whether a server's certificate is accepted, cut or damage the next download, run the daily check again |

site/content/dev/debug/files-and-screens.md

@@ -45,6 +45,7 @@ The device sends `screenshot: rgb332 <width> <height>` and then **one byte per p
 
 - It is read **as it stands**, while the UI may be drawing, so it can **tear**. It is for looking at, not for pixel-exact comparison.
 - It is the real thing: the screenshots on this site, in the [user guide](/guide/) and the [devlog](/devlog/), were taken this way.
+- **With a number, it saves to the card instead:** `screenshot 5` (or `screenshot 0`) writes a PNG to `/screenshots` on the SD card after that many seconds, as the [Shell](/guide/shell/) does. A bare `screenshot` over the console is the binary one above.
 - Its main use is in a loop: send a key, wait a moment, take a screenshot, look. See [Drive the UI](/dev/debug/drive-the-ui/).
 
 ## `coredump get`: the crash dump