roro9stack/site/content/dev/debug/commands.md

+++ title = "Command reference" description = "Every command the firmware understands, over USB serial or the Debug Console: what help prints, then what each one does." weight = 30

[extra] docs = true source = "src/main.cpp and README.md" tag = "Reference" +++

What help prints

The firmware's own list, read from src/main.cpp. Every firmware has all of them, over USB serial and over the Debug Console. The ones marked Debug Console only exist only over Wi-Fi, where rdbg.py speaks them, and the ones marked USB serial only only over the cable:

info              firmware, uptime, memory, Wi-Fi, app slots
tasks             FreeRTOS tasks over the next second: state, priority, free stack, CPU share
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 [-r] [-f] <path> | cp [-f] <from> <to> | mv [-f] <from> <to> | cancel   the SD card, with the Storage App's rules (rm -r for a folder; -f: the Shell doesn't ask; * and ? in a name: /notes/*.txt)
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] | 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>
crash             the last crash: firmware, reason, task, backtrace
coredump erase    forget the core dump in flash
key <name|char>   press a key: up down left right select back home del tab space help shot, or one character; ctrl- alt- shift- before it (key ctrl-down)
wifi status | wifi add <ssid><TAB><password>
wifi ip <ssid> dhcp | wifi ip <ssid> <address>/<prefix> [gateway]   a Saved Network's IP setting
wifi dns <a> [b] | wifi dns always on|off | wifi ntp <a> [b]   DNS and NTP servers
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 | 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
Irc | Wifi | Gnss | Gemini | Lora | Storage | Notes | Shell | System | Settings   open that App: a capital letter is an App, not a command
vpn status | vpn up [seconds] | vpn down | vpn import [path] | vpn forget | vpn auto on|off   the WireGuard tunnel (Settings > VPN); import reads /vpn/wg0.conf; with seconds, it goes down by itself
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
crash abort|wdt   crash on purpose (to test crash reports and Safe Mode)
wifi ip ... try <seconds> | wifi ip keep   a trial IP setting: back to the previous one unless kept
loop spin on|off  make the main loop spin without resting, to compare load and radio noise
lora noise test [gnss|quiet] | lora noise report   Sweep under one changed condition at a time (Wi-Fi goes off for a moment)
lora inject <hex> [rssi] [snr]   a packet into the LoRa Scanner as if received (nothing is sent)
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: there, a bare `screenshot` sends the screen instead of saving it
quit              close the Debug Console connection

In Safe Mode (see Crashes and Safe Mode) only a few run: help, info, tasks, net, reboot, boot other, wifi status, and anything starting with log level, crash, coredump, wifi add, debug. Anything else answers not available in Safe Mode.

What they do

scripts/serial_log.sh [seconds] [command…] records the serial output, and can send commands to the firmware first. For example, scripts/serial_log.sh 30 short sleep:12 burst sets short screen timeouts, waits 12 s, then sends a burst of Toasts.

Command	Effect
burst	Publishes 5 Notifications at once
key up|down|left|right|select|back|home|del|tab|space|help|shot, or key <char>	Injects a key press (help is Fn+h: the keys of the screen that is showing; shot is Fn+p: a screenshot). ctrl-, alt- and shift- before it hold that key: key ctrl-down, key alt-up, key ctrl-b
sound on / sound off	Toggles the Sound setting (beep + LED)
short / normal	Screen timeouts 5 s / 10 s, or 30 s / 60 s
wifi add <ssid><TAB><password>	Adds a Saved Network (so credentials stay out of the repo)
wifi ip <ssid> dhcp / wifi ip <ssid> <address>/<prefix> [gateway]	A Saved Network's IP setting: Automatic, or Fixed. Add try <seconds> to go back to the previous setting unless wifi ip keep follows
wifi dns <a> [b] / wifi dns always on|off / wifi ntp <a> [b]	DNS servers (used on Fixed networks, or always), and NTP servers
log <text>	Appends a line to a test IRC Log (/irc/dev/#test/<date>.log)
sd card	What the SD card says it is: type, size, and its identity register (maker, name, revision, serial, date)
sd list	Lists the files of each Storage Clean-up category
sd fill <folder> <count>	Makes that many small files in a folder, to test a crowded one
cat <path>	Prints the first ~1.2 KB of a file on the SD card
irc start	Starts the IRC Service (normally done by opening the IRC App)
irc stop	Stops it, as /quit does: QUIT if connected, no more retries, and the App stays disconnected until you type
gemini get <url>	Fetches a Gemini page and prints its header, size, certificate fingerprint and heap use
gemini trust <host> <port> <sha256>	Pins a certificate by hand (the Gemini App asks when one changes)
irc say <buffer> <text>	Types into a Buffer, commands included (irc say 0 /join #test)
irc dump	Prints IRC status, memory, and the last lines of each Buffer
wifi status	Prints Wi-Fi state, network, signal, clock and free heap, then the address, gateway, DNS and NTP servers in use and where each came from
info	Firmware, uptime, last start reason, memory, Wi-Fi, the SD card and its write faults since boot, which App is in front, and both app slots with their versions and OTA states
Notes, Irc, Wifi, Gnss, Gemini, Lora, Storage, Shell, System, Settings	Opens that App: a capital letter is an App, not a command
tasks	FreeRTOS tasks over the next second: state, priority, lowest free stack, share of a core, each core's load, and how many passes the main loop made
net	Bytes each network service has read and written since boot
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
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 [-r] [-f] <path> / mkdir <path> / cancel	What the Storage App does, with its rules: copy (folders too), move or rename, delete (rm -r for a folder and what's in it, as Unix has it), new folder. -f replaces a file that's in the way; * and ? in the last part of a path (ls, du, rm, cp, mv) run the command for each name matched, 64 at most; 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
lora probe	Finds the radio: chip, oscillator, antenna switch, DIO1 interrupt, noise floor
lora status	Radio settings, who's listening, packet and error counters, noise floor, task stack
lora rx on / lora rx off	Listens and prints each packet on the console
lora preset <name> / lora custom <MHz> <BW kHz> <SF> <CR> <sync hex> [preamble]	Receive settings: a Meshtastic preset, or anything else (lora custom 868.1 125 7 5 34 8 for LoRaWAN)
lora capture start / lora capture stop	A LoRa Capture, as c in the App
lora sweep on [from MHz] [to MHz] [step kHz] / lora sweep off / lora sweep dump	Sweep a band (863 870 100 by default), with a summary every 2 s (floor, strongest, peaks), or print the latest pass
gnss quiet on / gnss quiet off	The "Pause GNSS for LoRa" setting
gnss status / gnss restart	The receiver's state, and a restart of it
gnss track start / gnss track stop	A Track, as r in the GNSS App (the reason is printed if it can't start)
gnss nmea on / gnss nmea off	Prints each NMEA sentence the receiver sends, as nmea: …
gnss send <sentence>	Sends a sentence to the receiver, without the $ and the checksum (it adds them)
lora noise test [gnss|quiet] / lora noise report	Sweep under one changed condition at a time to find what raises the noise floor (Wi-Fi goes off for a few seconds); then the result
lora inject <hex> [rssi] [snr]	A packet into the Scanner as if received (nothing is sent)
crash	The last crash: which firmware, why, task, PC and backtrace (from the core dump in flash)
coredump erase	Forgets the core dump
loop spin on / loop spin off	Make the main loop spin without resting, to compare load and radio noise
crash abort / crash wdt	Crash on purpose, or hang the main loop until the watchdog fires
vpn status / vpn up [seconds] / vpn down / vpn import [path] / vpn forget / vpn auto on|off	The WireGuard tunnel: its state, on (for that many seconds, then off by itself: for trying a configuration from afar), off, read a .conf from the card (/vpn/wg0.conf), erase it, start with Wi-Fi. No key is ever printed
debug status / debug off [seconds]	The Debug Console: whether it's on, has a token and a client; switch it off. With a number of seconds, it comes back by itself after that long
debug on / debug token <value> / debug token new	USB serial only: switch it on (making a token if there's none), give it a token of 16 to 64 characters, or make a new one. The token is never printed
help	Lists the commands

scripts/flash.sh stops a running serial log first, since it would hold the port.