[DOC] CLI Reference
CLI Console
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 | Serial only | Description |
|---|---|---|---|---|
ver |
– | All | No | Print firmware version and build date. |
board |
- | All | No | Print the make and model of the board. |
reboot |
– | All | No | Soft‑restarts MCU. Clock usually retained. |
clkreboot |
- | All | No | Reset clock and soft-restart MCU. |
poweroff or shutdown |
- | All | No | Powers down board. Note: you will need to physically reset the board to restore it again. |
erase |
– | All | Yes | Formats the on‑board file‑system. |
advert |
– | All | No | Transmit a flood advert packet. |
advert.zerohop |
- | All | No | Transmit a zero-hop (non-repeated) advert packet. |
neighbors |
– | Repeater | No | Dump current neighbour table with RSSI & airtime stats. |
neighbor.remove |
<Public Key> | Repeater | No | Remove a neighbour from the node's neighbour list. |
clear stats |
– | All | No | Reset airtime/packet counters in all link records. |
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. |
clock |
– | All | No | Show current UTC time from the real‑time clock. |
clock sync |
– | All | No | Accepts sender’s timestamp and sets local RTC if newer. |
time <epoch> |
Unix‑epoch seconds |
All | Yes | Manually set RTC (value must be in the future). |
public.key |
- |
All |
No | Returns the public key of the node. |
role |
- |
All |
No | Returns the node's role (repeater, room server). |
Logging
| Command | Node Type | Serial Only | Effect | When to use |
|---|---|---|---|---|
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. |
Node Configuration
Syntax: set/get <key> <value> . Immediately persisted to board configuration file.
| Command & Value | Prefix | Valid Range / Format | Default | Description | Inter‑operability impact |
tempradio <f> <bw> <sf> <cr> <timeout> |
N/A |
f = 150‑2500 MHz bw = 7‑500 kHz sf = 5‑12 cr = 5‑8 timeout=<n> mins |
N/A | Temporarily assign alternate radio settings for a number of minutes for testing purposes. After the timeout, node reverts to configured settings. | Node will only be reachable from the temporary settings during the timeout window. |
gps |
N/A |
N/A |
N/A |
Returns current GPS state. Data returned (in order): Enabled=on/off Active=active/deactivated Fix=fix/no fix Satellites=<n> sats |
None |
gps on/off |
N/A |
N/A |
off |
Enable/disable GPS location services. Requires GPS module fitted to node. |
None |
gps sync |
N/A |
N/A |
N/A |
Sync clock from GPS. |
None |
gps setloc |
N/A |
N/A |
N/A |
Set current node location from GPS coordinates. |
None |
gps advert |
N/A |
N/A |
N/A |
Retrieves current GPS position advert permissions ("None", "Prefs", "Share") |
None |
gps advert <none/prefs/share> |
N/A |
none/prefs/share |
N/A |
Sets current GPS position advert permissions. none=do not share position in adverts prefs=share configured position from node preferences share=share live GPS position |
None |
radio <f> <bw> <sf> <cr> |
|
f = 150‑2500 MHz bw = 7‑500 kHz sf = 5‑12 cr = 5‑8 |
869.525, 250, 11, 5 | Sets radio parameters. Reboot required. Change during a maintenance window and be mindful of critical paths to other nodes that will break. | Breaks comms if any one of f/bw/sf/cr differs between nodes. |
freq <MHz> |
|
150‑2500 | 869.525 | Sets LoRa radio centre frequency in MHz. Reboot required. | Same as above (freq only). |
tx <dBm> |
|
1‑30 | 22 | Sets LoRa radio transmit power in dBm. Balance per‑link budget; stay legal. | None (all nodes still RX) but raising too high can desensitise neighbours; lowering may drop links. |
af <n> |
|
0–9 (float) | 1 | Airtime Factor. 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. | Mismatched extremes (0 vs 9) can shorten RX window on fast nodes so they miss slow packets. |
rxdelay <n> |
|
>= 0.0 | 0.0 |
Controls a per-hop hold time before a flood packet is processed/forwarded. Only applies to flood-mode receive/forward paths. Direct/path-routed traffic bypasses this delay.
This is informed by SNR, as opposed to TX delay which is a set factor that adds random jitter to each transmitted packet. The configured value is a dimensionless base (not seconds). Actual delay is calculated:
Practical ranges depend on SF and BW. Examples:
|
Each hop adds delay; with 16–20 hops, large bases can accumulate into second-scale latency and may trigger app timeouts. Very large values can make low-SNR packets wait near the 4s CAD busy ceiling before forwarding. Leaving the value at 0 can increase risk of collisions. |
txdelay <s> |
|
≥ 0 | 0.5 | Increase on congested channels or when multiple repeaters are reachable but this one is less preferred. | None on demodulation; affects collision rate. |
direct.txdelay <s> |
|
≥ 0 | 0.3 | Increase for chatty one‑hop setups. | None |
int.thresh <N> |
|
0‑255 RSSI | 0 |
Interference Threshold. This can help prevent collisions by checking if the frequency is busy before transmitting. With thresh=0 (default) the busy check is skipped; the node will transmit whenever its own duty-cycle timer allows.
With thresh>0 the node does an RSSI-based "listen‑before‑talk". The effective busy trigger is "noise floor + thresh" in dB, so the number you set is the margin above the current floor.
If the channel is busy send is deferred by ~200 ms, retrying until the channel clears or 4s elapse. After 4s it sends anyway but logs a CAD timeout.
For most sites on SF7, 6-8 is a good range to test with.
For higher spread factors, noisy RF sites, or more marginal links, lean higher (8-10) to avoid the channel appearing forever busy. |
None, however TX performance can be impacted.
When set to 0, collision risk is increased.
When set too low, threshold can be too sensitive and may result in all packets being delayed.
When set too high, the hold-off to TX may never trigger and behave similarly to a disabled (set to 0) state. |
flood.advert.interval <H> |
|
3‑48 hours, 0=off | 12 | Longer beacon range; use sparingly. Most nodes in busy meshes use 24-36. | None, however too frequent will cause high airtime in busy meshes due to the volume and frequency of flood adverts. |
advert.interval <M> |
|
60‑240 min, 0=off | 0 (after first manual cfg) | Local presence beacon; switch off on busy nets. | None |
flood.max <N> |
|
0‑64 | 64 |
Maximum number of hops for flood messages. Consider reducing on battery nodes or in high density areas. The maximum hop count is reduced if path byte count is increased. | None on RX path; high value increases airtime. |
repeat on/off |
|
on / off |
Repeater firmware: on Room server firmware: off |
Enable or disable repeats (repeater and room server only). Ensure alternate paths exist before disabling. | Turning off may isolate parts of mesh. |
allow.read.only on/off |
|
on / off |
off | Grants passwordless CLI read‑only access and read-only message board access (room server). Useful for public info kiosks. | None |
agc.reset.interval <S> |
|
0‑1020 (÷4)s | 0 |
Front‑end gain recalibration period (<S>econds divided by 4 internally). e.g. a value of 120 = 30 second interval. Shorten when nearby strong interferers. | Node is unable to receive during the reset interval and can potentially miss packets. Be mindful to not set too frequently. |
lat <deg> |
|
geographic coordinates | 0 | Latitude coordinates in degrees. Required for map position. | None |
lon <deg> |
|
geographic coordinates | 0 |
Longitude coordinates in degrees. Required for map position. | None |
name <text> |
|
≤ 32 chars | First 8 characters of public key |
Set the node name that appears in adverts and contact lists. | None |
guest.password <password> |
|
≤ 14 chars |
Repeater: <blank> Room server: hello |
Read‑only users (repeater) and post permission (room server). | None |
password <password> |
|
≤ 14 chars | "admin" | Change immediately. | None |
multi.acks |
|
on/off |
off |
Sends two ACK packets instead of one. Use sparingly; usually not required. | None |
bridge.enabled |
|
on/off |
Enable RS232/ESPNOW bridge | None | |
bridge.delay |
|
Delay time (seconds) before bridge will re-transmit packets. | None | ||
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 |
|
(ESPNOW only) set shared secret for bridge members | All bridge members must use the same shared key | ||
bridge.channel |
|
0 - 14 | (ESPNOW only) channel number for ESPNow bridge | Bridge members must use the same channel number | |
adc.multiplier |
|
Custom value to use as ADC multiplier to determine battery voltage | None | ||
bridge.type |
|
Identify if repeater is acting as a RS232/ESPNOW bridge. | None | ||
bridge.enabled |
|
Identify if repeater is acting as a bridge and what type. | None | ||
bridge.delay |
|
Delay time (seconds) before bridge will re-transmit packets. | |||
bridge.source |
|
Choose whether bridge will re-transmit received or transmitted packets | |||
bridge.baud |
|
(RS232 bridge only) set baud rate of serial bridge port | |||
bridge.secret |
|
(ESPNOW only) set shared secret for bridge | |||
bridge.channel |
|
(ESPNOW only) channel number for ESPNow bridge |