The Debug Console · Reference

Command reference

Every command the firmware understands, over USB serial or the Debug Console: what `help` prints, then what each one does.

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; a Meshtastic preset (LongFast...) or MeshCore
mesh status | mesh nodes | mesh channels | mesh rx on|off | mesh on|off   the MeshCore mesh, receive only
mesh channel add #name | mesh channel add <name><TAB><32 hex digits> | mesh channel remove <name>
mesh send on|off    Settings > Mesh: Sending (the region confirmed), or Listening
mesh advert [flood]   this device's advert: zero-hop (direct neighbours), or flood (every repeater passes it on)
mesh send <channel number> <text> | mesh dm <key's start or name> <text> | mesh dms   messages, sent and kept
mesh login <key's start or name> [password]   a room (the password kept when none is given)
mesh key | mesh key export | mesh key import <hex>   the device's MeshCore key (export and import: USB only)
ble status | ble on|off | ble forget   Bluetooth and the MeshCore app: the link, the phone, the frames; forget the bonded phone
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)
imu                 what the motion sensor reads: g on its three axes, then degrees a second
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 | theme [0-6] [light|dark] | short | normal
Irc | Wifi | Gnss | Gemini | Lora | Storage | Notes | Shell | System | Settings   open that App: a capital letter is an App, not a command
ping <host> [count] [size] | nslookup <name> [server] | port <host> <port> | traceroute <host> | cancel   is it there, does its name resolve, is its port open, which way; one at a time
tls <host> [port] | ntp [server]   a TLS handshake: who the certificate is for, by whom, until when, and whether this device trusts it; a time server's clock against this one
ifconfig | arp | netstat   the interfaces (Wi-Fi and the VPN), their addresses, the default route and the DNS servers; the neighbours heard; what listens and what is connected
uname   the firmware, its version and the chip it is built for
scp [-f] [-P port] <file on the card> user@host:path | scp [-f] [-P port] user@host:path <file on the card>   one file over SSH, with this device's key or, in the Shell, a password, to a server the SSH App already trusts; -f replaces a file on the card; `cancel` stops it
ssh user@host[:port] | ssh status | ssh stop   a terminal on another machine, in the SSH App; the password is asked there, never here
vpn status | vpn up [seconds] | vpn down | vpn import [path] | vpn forget | vpn auto on|off   the WireGuard tunnel (Settings > Network > 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 > System > 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)
lora tx <hex>       sends a packet on the mesh, as it is: Mesh Sending, MeshCore's setting, within the hour's airtime
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, uname, 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.

CommandEffect
burstPublishes 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 offToggles the Sound setting (beep + LED)
theme / theme <0-6> [light|dark]Lists the colour themes, or picks one and its side
short / normalScreen 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 cardWhat the SD card says it is: type, size, and its identity register (maker, name, revision, serial, date)
sd listLists 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 startStarts the IRC Service (normally done by opening the IRC App)
irc stopStops 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 dumpPrints IRC status, memory, and the last lines of each Buffer
wifi statusPrints Wi-Fi state, network, signal, clock and free heap, then the address, gateway, DNS and NTP servers in use and where each came from
infoFirmware, 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, SettingsOpens that App: a capital letter is an App, not a command
tasksFreeRTOS 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
netBytes each network service has read and written since boot
reboot / boot otherRestart, 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> / cancelWhat 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 → System → 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 dailyPretend to run another version (so a release counts as an update), see whether a server's certificate is accepted, break each connection of the next download after n bytes (it is carried on, issue #54) or damage one byte of it, run the daily check again
lora probeFinds the radio: chip, oscillator, antenna switch, DIO1 interrupt, noise floor
lora statusRadio settings, who's listening, packet and error counters, noise floor, task stack
lora rx on / lora rx offListens and prints each packet on the console
mesh statusThe mesh (M4): listening or paused, packets, adverts verified, forged and replayed, channel messages read and not, nodes in RAM, where the history goes
mesh nodesThe nodes heard, most recent first: key, kind, when, RSSI, SNR, hops, position, name
mesh channels / mesh channel add #name / mesh channel add <name><TAB><32 hex digits> / mesh channel remove <name>The channels followed besides Public: hashtag ones by name, private ones with their secret
mesh rx on / mesh rx offEach node and message on the console as it is heard
mesh on / mesh offSettings > Mesh: the Mesh Service listens in the background (on by default)
lora preset <name> / lora custom <MHz> <BW kHz> <SF> <CR> <sync hex> [preamble]Receive settings: a Meshtastic preset or MeshCore, or anything else (lora custom 868.1 125 7 5 34 8 for LoRaWAN)
lora capture start / lora capture stopA LoRa Capture, as c in the App
lora sweep on [from MHz] [to MHz] [step kHz] / lora sweep off / lora sweep dumpSweep 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 offThe "Pause GNSS for LoRa" setting
imuWhat the motion sensor reads: g on its three axes, then degrees a second (the Compass, issue #16)
gnss status / gnss restartThe receiver's state, and a restart of it
gnss track start / gnss track stopA Track, as r in the GNSS App (the reason is printed if it can't start)
gnss nmea on / gnss nmea offPrints 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 reportSweep 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)
crashThe last crash: which firmware, why, task, PC and backtrace (from the core dump in flash)
coredump eraseForgets the core dump
loop spin on / loop spin offMake the main loop spin without resting, to compare load and radio noise
crash abort / crash wdtCrash on purpose, or hang the main loop until the watchdog fires
ping <host> [count] [size] / nslookup <name> [server] / port <host> <port> / traceroute <host> / cancelNetwork troubleshooting (issue #90): does a host answer and how fast; a name's addresses, from which DNS server and in how long; is a TCP port open, refused or silent; the routers on the way. Each runs on a task of its own and prints as it goes, one at a time; cancel stops it
tls <host> [port] / ntp [server]A TLS handshake that checks nothing, then the certificate said in words: who it is for, who signed it, until when, its SHA-256, and whether this device's roots and the name asked for accept it (about 52 KB of heap while it runs; refused under 70 KB free, and for the few hosts whose handshake would restart the device: ADR 0006). A time server's clock against the device's, with the round trip
ifconfig / arp / netstatThe interfaces (Wi-Fi and the VPN) with their addresses, MTU, which is the default route, and the DNS servers; the neighbours heard on the Wi-Fi; what listens and what is connected
ssh user@host[:port] / ssh status / ssh stopOpens the SSH App and connects (the password is asked there, never on a console); the session's state and this device's public key; end the session
scp [-f] [-P port] <file> user@host:path / scp [-f] [-P port] user@host:path <file>One file between the card and a server, with the device's key, or a password asked (masked) in the Shell, to a server the SSH App already trusts; -f replaces a file on the card; cancel stops it
unameThe firmware, its version and the chip it is built for (IRC has /uname)
vpn status / vpn up [seconds] / vpn down / vpn import [path] / vpn forget / vpn auto on|offThe 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 newUSB 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
helpLists the commands

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

This page is generated from src/main.cpp and README.md in the repository. To change it, change that file and run site/tools/gen_dev_docs.py.