[DOC] CLI Reference
CLI Console – (from CommonCLI.cpp)
All commands below are directly parsed by the firmware, available over USB‑CDC, serial UART, or BLE console. Commands are case‑sensitive. For remote‑originated CLI packets (OTA from another node) the firmware prepends a two‑byte timestamp; behaviour is identical unless noted.
Maintenance Commands
| Command | Arguments | Node Type |
|---|
ver
–
All
No
Print firmware version and build date.
Confirm code revision before reporting bugs.
reboot
–
All
No
Soft‑restarts MCU. Clock usually retained.
Apply radio settings, recover from faults.
erase
–
All
Yes
Formats the on‑board file‑system. Requires physical console (ignored remotely).
Start clean after corrupted storage.
advert
–
All
No
Transmit a 400 ms flood advert packet.
Force discovery by other nodes.
neighbors
–
Repeater
No
Dump current neighbour table with RSSI & airtime stats.
Assess link health and connectivity.
clear stats
–
All
No
Reset airtime/packet counters in all link records.
Benchmark after network tweaks.
start ota
–
All
No
Kick off OTA firmware update (Bluetooth for nRF52840-based nodes, Wi-Fi for ESP32-based). Nodes that do not have the Bluetooth radio enabled (Room Server, Repeater) will activate the radio and await a connection. nRF52840-based nodes will continue running MeshCore application until the DFU app connects and reboots the node into DFU mode.
Push a compiled image from the Nordic Semiconductor DFU app (nRF52840 only) or a web browser (ESP32 only).
clock
–
All
No
Show current UTC time from the real‑time clock.
Quick sanity check after power loss.
clock sync
–
All
No
Accepts sender’s timestamp and sets local RTC if newer.
Resync clock from the currently logged in companion node after a cold boot/power loss.
time <epoch>
Unix‑epoch seconds
All
Yes
Manually set RTC (value must be in the future).
Manually set time when no external source (e.g. companion node) present.
Logging
| Command | Node Type |
|---|
log start
All
No
Enable runtime logging to on‑device file.
Investigating intermittent issues.
log stop
All
No
Disable logging (frees flash wear and airtime).
Normal low‑power operation.
log erase
All
No
Delete the stored log file.
Clear space or privacy/rotation.
log
All
Yes
Stream the log file to console. Requires physical console (ignored remotely).Download logs for post‑mortem.
Reading Configuration
Syntax: get <key> → returns value prefixed with >.
| Key | Node Type |
|---|
af
All
No
Airtime factor (0 – 9, float). Higher = longer RX windows (slower network).
Trade throughput for range/robustness.
radio
All
No
freq,bw,sf,cr current tuple.
One‑shot snapshot of radio stack.
freq
All
No
Centre frequency in MHz.
Verify channel plan (e.g., 915.8).
tx
All
No
TX power dBm.
Ensure legal limit / link budget.
lat
All
No
Fixed position - Latitude.Map display in apps, manual routing hints.
lon
All
No
Fixed position - Longitude.
Map display in apps, manual routing hints.
rxdelay
All
No
Base RX delay in seconds.Align receive window in dense nets.
txdelay
All
No
TX delay factor in seconds.
Randomise channel access in collisions.
direct.txdelay
All
No
Direct path TX delay factor.
Delay for nodes within single hop.
int.thresh
All
No
Interference threshold RSSI (0‑255).
Ignore very weak/strong garbage signals.
agc.reset.interval
All
No
Seconds between AGC resets (multiple of 4).
Improve front‑end recovery in RF‑noisy sites.
allow.read.only
on / off. If set to on, users can log in without a password and view messages but not post.Permit guest (read‑only) CLI users.
advert.interval
All
No
Minutes between local adverts (0 = off). Min 60.
Zero-hop advertisement of the node ID.
flood.advert.interval
All
No
Hours between flood adverts (0 = off). Min 3.
Flood advertisement of the node ID (Long‑range periodic beaconing).
flood.max
All
No
Maximum simultaneous flood forwards of messages (0‑64).
Limit the number of repeats for a message to prevent broadcast storms.
name
All
No
Node’s name label in the contact list.
Advert payload, UI display.
guest.passwordAll No Retrieve guest password. Credential check.
repeat
on if packet forwarding enabled, else off.
Confirm node acting as repeater.
public.key
All
No
Hex of node ECC public key (64 B).
Out‑of‑band key exchange.
role
All
No
Current node role (repeater, room server).Identify which role firmware is installed and presented to other nodes.
multi.acks
All
No
Sending of two ACK packets instead of one.
Useful on unreliable links where remote side doesn't always receive delivery confirmation from packets sent to this node.
bridge.type
Repeater
No
Identify if repeater is acting as a bridge and what type.
Identify if repeater is acting as a RS232/ESPNOW bridge.
bridge.enabled
Repeater
No
Check if bridge feature is enabled.
bridge.delay
Repeater
No
Delay time (seconds) before bridge will re-transmit packets.
bridge.source
Repeater
No
Choose whether bridge will re-transmit received or transmitted packets
bridge.baud
Repeater
No
(RS232 bridge only) set baud rate of serial bridge port
bridge.secret
Repeater
No
(ESPNOW only) set shared secret for bridge
bridge.channel
Repeater
No
(ESPNOW only) channel number for ESPNow bridge
adc.multiplier
All
No
Custom value to use as ADC multiplier to determine battery voltage
Writing Configuration
Syntax: set <key> <value> → immediately persisted to /com_prefs.
| Key & Value | Valid Range / Format | Default | Inter‑operability impact | Notes |
radio <f> <bw> <sf> <cr> |
f = 300‑2500 MHz, bw = 7‑500 kHz, sf = 7‑12, cr = 5‑8 | 869.525, 250, 11, 5 | Breaks comms if any one of f/bw/sf/cr differs between nodes. | Reboot required. Change during a maintenance window; push to every node then reboot. |
freq <MHz> |
300‑2500 | 869.525 | Same as above (freq only). | Reboot required. |
tx <dBm> |
1‑30 | 22 | None (all nodes still RX) but raising too high can desensitise neighbours; lowering may drop links. | Balance per‑link budget; stay legal. |
af <n> |
0–9 (float) | 1 | Mismatched extremes (0 vs 9) can shorten RX window on fast nodes so they miss slow packets. | 0 = fast, 9 = long‑range. Changes RX-window length and internal timing. Large differences (e.g., 0 vs 9) can cause short-window nodes to miss beacons from slow ones. Aim to keep all nodes within ±2 steps. Raise in marginal links. |
rxdelay <s> |
≥ 0 | 0.0 | Slight |
Tune if in a dense network. |
txdelay < |
≥ 0 | 0.5 | None on demodulation; affects collision rate. | Increase on congested |
direct.txdelay < |
≥ 0 | 0. |
None | Increase for chatty one‑hop setups. |
int.thresh <N> |
0‑255 RSSI | 0 | Ignore packets below RSSI <n>. Helps in urban RF noise. | Survey links and keep threshold 6 dB below weakest steady RSSI. |
flood.advert.interval <H> |
3‑48 hours, 0=off | 12 | None | Longer beacon range; use sparingly. |
advert.interval <M> |
60‑240 min, 0=off | 0 (after first manual cfg) | None | Local presence beacon; switch off on busy nets. |
flood.max <N> |
0‑64 | 64 |
None on RX path; high value increases airtime. | Consider reducing on battery nodes or in high density areas. |
repeat on/off |
on / off |
Repeater firmware: on Room server firmware: off |
Turning off may isolate parts of mesh. | Ensure alternate paths exist before disabling. |
allow.read.only on/off |
on / off |
off | None | Grants passwordless CLI read‑only access and read-only message board access (room server). Useful for public info kiosks. |
agc.reset.interval <S> |
0‑1020 s (÷4) | 0 |
None | Front‑end gain recalibration period (<S>econds divided by 4 internally). Shorten when nearby strong interferers. |
lat <deg> |
geo coords | 0 | None | Static install coordinates. Enables map overlays. |
lon <deg> |
geo coords | 0 |
None | Static install coordinates. Enables map overlays. |
name <text> |
≤ 32 chars | First 8 characters of public key |
None | Appears in adverts and contact list. |
guest.password <password> |
≤ 14 chars |
Repeater: <blank> Room server: hello |
None | Read‑only users (repeater) and post permission (room server). |
password <password> |
≤ 14 chars | "admin" | None | Change immediately. |
multi.acks
on/off
off
None
Sends two ACK packets instead of one. Use sparingly; usually not required.
bridge.enabled
on/off
None
Enable RS232/ESPNOW bridge
bridge.delay
None
Delay time (seconds) before bridge will re-transmit packets.
bridge.source
rx/tx
rx
Choose whether bridge will re-transmit received or transmitted packets
bridge.baud
9600 - 115200
(RS232 bridge only) set baud rate of serial bridge port
bridge.secret
All bridge members must use the same shared key
(ESPNOW only) set shared secret for bridge members
bridge.channel
0 - 14
Bridge members must use the same channel number (ESPNOW only) channel number for ESPNow bridge
adc.multiplier
None Custom value to use as ADC multiplier to determine battery voltage
No
saveneeded – everysetwrites straight to/com_prefs.