[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	What it does	Typical use‑case
`ver`	–	Print firmware version and build date.	Confirm code revision before reporting bugs.
`reboot`	–	Soft‑restarts MCU. Clock usually retained.	Apply radio settings, recover from faults.
`erase`	–	Formats the on‑board file‑system. Requires physical console (ignored remotely).	Start clean after corrupted storage.
`advert`	–	Transmit a 400 ms flood advert packet.	Force discovery by other nodes.
`neighbors`	–	Dump current neighbour table with RSSI & airtime stats.	Assess link health and connectivity.
`clear stats`	–	Reset airtime/packet counters in all link records.	Benchmark after network tweaks.
`start ota`	–	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`	–	Show current UTC time from the real‑time clock.	Quick sanity check after power loss.
`clock sync`	–	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`	Manually set RTC (value must be in the future).	Manually set time when no external source (e.g. companion node) present.

Logging

Command	Effect	When to use
`log start`	Enable runtime logging to on‑device file.	Investigating intermittent issues.
`log stop`	Disable logging (frees flash wear and airtime).	Normal low‑power operation.
`log erase`	Delete the stored log file.	Clear space or privacy/rotation.
`log`	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	Description	Example Use Case
`af`	Airtime factor (0 – 9, float). Higher = longer RX windows (slower network).	Trade throughput for range/robustness.
`radio`	`freq,bw,sf,cr` current tuple.	One‑shot snapshot of radio stack.
`freq`	Centre frequency in MHz.	Verify channel plan (e.g., 915.8).
`tx`	TX power dBm.	Ensure legal limit / link budget.
`lat`	Fixed position - Latitude.	Map display in apps, manual routing hints.
`lon`	Fixed position - Longitude.	Map display in apps, manual routing hints.
`rxdelay`	Base RX delay in seconds.	Align receive window in dense nets.
`txdelay`	TX delay factor in seconds.	Randomise channel access in collisions.
`direct.txdelay`	Direct path TX delay factor.	Delay for nodes within single hop.
`int.thresh`	Interference threshold RSSI (0‑255).	Ignore very weak/strong garbage signals.
`agc.reset.interval`	Seconds between AGC resets (multiple of 4).	Improve front‑end recovery in RF‑noisy sites.
`allow.read.only`	(Room Server 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`	Minutes between local adverts (0 = off). Min 60.	Zero-hop advertisement of the node ID.
`flood.advert.interval`	Hours between flood adverts (0 = off). Min 3.	Flood advertisement of the node ID (Long‑range periodic beaconing).
`flood.max`	Maximum simultaneous flood forwards of messages (0‑64).	Limit the number of repeats for a message to prevent broadcast storms.
`name`	Node’s name label in the contact list.	Advert payload, UI display.
`guest.password`	Retrieve guest password.	Credential check.
`repeat`	(Repeater and Room Server only) `on` if packet forwarding enabled, else `off`.	Confirm node acting as repeater.
`public.key`	Hex of node ECC public key (64 B).	Out‑of‑band key exchange.
`role`	Current node role (repeater, room server).	Identify which role firmware is installed and presented to other nodes.

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 misaligned RX slots can lose first packet if wildly different.	Tune if in a dense network.
`txdelay <f>`	≥ 0	0.5	None on demodulation; affects collision rate.	Increase on congested channels.
`direct.txdelay <f>`	≥ 0	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 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.

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