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. These work in every build, over USB serial:

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 <path> | cp [-f] <from> <to> | mv [-f] <from> <to> | cancel   the SD card, with the Storage App's rules
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 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, or one character
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 | list | status | install <tag>   the project's releases on Gitea
sd card | sd list | cat <path> | log <text> | burst | sound on|off | short | normal

A Debug Build adds these (the last ones, marked Debug Console only, exist only over Wi-Fi, where rdbg.py speaks them):

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
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. 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, or key <char>	Injects a key press
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. Debug Builds: 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>	Debug Builds: 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, and both app slots with their versions and OTA states
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
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
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 (not on a Debug Build)
update pretend <version> / update probe <host> / update damage cut|flip <n> / update daily	Debug Builds: 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	Debug Builds: 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]	Debug Builds: 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	Debug Builds: make the main loop spin without resting, to compare load and radio noise
crash abort / crash wdt	Debug Builds: crash on purpose, or hang the main loop until the watchdog fires
help	Lists the commands

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