[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	Serial only	What it does

Typical use‑caseDescription ver – All No Print firmware version and build date. Confirmboard code- revisionAll beforeNo reportingPrint bugs.the make and model of the board. reboot – All No Soft‑restarts MCU. Clock usually retained.  Applyclkreboot radio- settings,All recoverNo fromReset faults.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. Requires physical console (ignored remotely). Start clean after corrupted storage. advert – All No Transmit a 400 ms flood advert packet. Forceadvert.zerohop discovery- byAll otherNo nodes.Transmit a zero-hop (non-repeated) advert packet. neighbors – Repeater No Dump current neighbour table with RSSI & airtime stats. Assessneighbor.remove link<Public healthKey> andRepeater connectivity.No Remove a neighbour from the node's neighbour list. 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). Manuallypublic.key set- time when

All

no externalNo sourceReturns the public key of the node. role -

All

No Returns the node's role (e.g.repeater, companionroom node) present.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.

---

ReadingNode Configuration

Syntax: set/get <key> <value> →. returnsImmediately valuepersisted prefixedto withboard >.configuration file.

Key	Command	Node& Type

Value SerialPrefix OnlyValid Range / Format Default Description ExampleInter‑operability Use Case
impact aftempradio <f> <bw> <sf> <cr> <timeout> All

N/A

No

f = 150‑2500 MHz

bw = 7‑500 kHz

sf = 5‑12

cr = 5‑8

timeout=<n> mins

Airtime factor (0 – 9, float). Higher = longer RX windows (slower network).N/A TradeTemporarily throughputassign alternate radio settings for range/robustness.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. radiogps All

N/A

No

N/A

freq,bw,sf,crN/A

Returns current tuple.GPS state. Data returned (in order):

Enabled=on/off

Active=active/deactivated

Fix=fix/no fix

Satellites=<n> sats

One‑shot snapshot of radio stack.None freqgps on/off All

N/A

No

N/A

Centre frequency in MHz.off Verify channel

Enable/disable planGPS (e.g.,location 915.8).services. Requires GPS module fitted to node.

None txgps sync All

N/A

No

N/A

TX power dBm.N/A Ensure legal

Sync limitclock /from linkGPS.

budget. None latgps setloc All

N/A

No

N/A

Fixed position - Latitude.
N/A Map display

Set incurrent apps,node manuallocation routingfrom hints.GPS coordinates.

None longps advert All

N/A

No

N/A

FixedN/A

Retrieves current GPS position -advert Longitude.permissions ("None", "Prefs", "Share")

Map display in apps, manual routing hints.None rxdelaygps advert <none/prefs/share> 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 Room Server No 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.

N/A

Zero-hop advertisement of the node ID. flood.advert.interval All No Hours between flood adverts (0 = off). Min 3.

none/prefs/share

FloodN/A advertisement of

Sets thecurrent GPS position advert permissions.

none=do not share position in adverts

prefs=share configured position from node IDpreferences

(Long‑range

share=share periodiclive beaconing).GPS position

None 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.password
All No Retrieve guest password. Credential check. repeat Repeater, Room Server No 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>

get

set

f = 300‑150‑2500 MHz,MHz

bw = 7‑500 kHz,kHz

sf = 7‑12,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. Reboot required. Change during a maintenance window; push to every node then reboot. freq <MHz> 300‑

get

set

150‑2500 869.525 Sets LoRa radio centre frequency in MHz. Reboot required. Same as above (freq only). Reboot required. tx <dBm>

get

set

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. Balance per‑link budget; stay legal. af <n>

get

set

0–9 (float) 1 MismatchedAirtime extremesFactor. (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. Mismatched extremes (0 vs 9) can shorten RX window on fast nodes so they miss slow packets. rxdelay <sn> ≥

get

set

>= 0.0 0.0 Slight misaligned

Controls RXa slotsper-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:

delay = (pow(rx_delay_base, 0.85 - score) - 1) * air_time_ms

score is 0–1 from SNR vs SF & pkt length. Better SNR -> higher score -> smaller/zero delay.
air_time_ms is the packet’s LoRa airtime estimate. Longer packets/higher SF multiply the delay. If the result is < 50 ms, it forwards immediately; otherwise it queues with that delay.

Practical ranges depend on SF and BW. Examples:

SF7/BW62.5: start 2-3 (adds roughly tens of ms on weak links, ~0 on strong). SF11: be conservative - 1.5-2; airtime is long so delays grow fast. Each hop adds delay; with 16–20 hops, large bases can loseaccumulate firstinto packetsecond-scale iflatency wildlyand different.may Tunetrigger ifapp intimeouts. aVery denselarge network.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>

get

set

≥ 0 0.5 None on demodulation; affects collision rate. 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>

get

set

≥ 0 0.3 None Increase for chatty one‑hop setups. None int.thresh <N>

get

set

0‑255 RSSI 0 Ignore

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 belowbeing RSSIdelayed.

<n>.

 Helps

in

When urbanset RFtoo noise.

high, Surveythe linkshold-off to TX may never trigger and keepbehave thresholdsimilarly 6 dBto belowa weakestdisabled steady(set RSSI.to 0) state. flood.advert.interval <H>

get

set

3‑48 hours, 0=off 12 None 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>

get

set

60‑240 min, 0=off 0 (after first manual cfg) None Local presence beacon; switch off on busy nets. None flood.max <N>

get

set

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. Consider reducing on battery nodes or in high density areas.
repeat on/off

get

set

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. Ensure alternate paths exist before disabling. allow.read.only on/off

get

set

on / off off None Grants passwordless CLI read‑only access and read-only message board access (room server). Useful for public info kiosks. None agc.reset.interval <S>

get

set

0‑1020 s1020 (÷4)s 0
None 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> 
geo coords

get

set

geographic coordinates 0 NoneLatitude coordinates in degrees. Required for map position. Static install coordinates. Enables map overlays.None lon <deg> geo coords

get

set

geographic coordinates 0
NoneLongitude coordinates in degrees. Required for map position. Static install coordinates. Enables map overlays.None name <text>

get

set

≤ 32 chars First 8 characters of public key
NoneSet Appearsthe node name that appears in adverts and contact list.lists. None guest.password <password>

get

set

≤ 14 chars

Repeater: <blank>

Room server: hello

None Read‑only users (repeater) and post permission (room server). None password <password>

get

set

≤ 14 chars "admin" NoneChange immediately. Change immediately.None multi.acks

get

set

on/off off None Sends two ACK packets instead of one. Use sparingly; usually not required. None bridge.enabled

get

set

on/off   None Enable RS232/ESPNOW bridge None bridge.delay

get

set

  None  Delay time (seconds) before bridge will re-transmit packets. None bridge.source

get

set

rx/tx rx   Choose whether bridge will re-transmit received or transmitted packets   bridge.baud

get

set

9600 - 115200     (RS232 bridge only) set baud rate of serial bridge port   bridge.secret

get

set

    (ESPNOW only) set shared secret for bridge members All bridge members must use the same shared key (ESPNOW only) set shared secret for bridge members bridge.channel

get

set

0 - 14
(ESPNOW only) channel number for ESPNow bridge Bridge members must use the same channel number (ESPNOW only) channel number for ESPNow bridge adc.multiplier

get

set

  None Custom value to use as ADC multiplier to determine battery voltage None bridge.type

get

Identify if repeater is acting as a RS232/ESPNOW bridge. None bridge.enabled

get

set

 
Identify if repeater is acting as a bridge and what type. None bridge.delay

get

set

Delay time (seconds) before bridge will re-transmit packets.
bridge.source

get

set

 
Choose whether bridge will re-transmit received or transmitted packets
bridge.baud

get

set

 
(RS232 bridge only) set baud rate of serial bridge port
bridge.secret

get

set

 
(ESPNOW only) set shared secret for bridge
bridge.channel

get

set

 
(ESPNOW only) channel number for ESPNow bridge

No save needed – every set writes straight to /com_prefs.