[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.	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 self‑advert packet immediately.	Force discovery by nearby nodes/phones.
`neighbors`	–	Dump current neighbour table with RSSI & airtime stats.	Assess link health and connectivity.
`clear stats`	–	Zero airtime/packet counters in all link records.	Benchmark after network tweaks.
`start ota`	–	Kick off OTA update; image tag is the saved node name.	Push a compiled image from a companion app.
`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.	Automatic time‑sync from a "master" node.
`time <epoch>`	`Unix‑epoch seconds`	Manually set RTC (value must be in the future).	First‑boot time set when no external sync 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`	(Repeater 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).	Direct advertisement of the node ID.
`flood.advert.interval`	Hours between flood adverts (0 = off).	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.	OTA tag, 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	915.8	Same as above (freq only).	Reboot required.
`tx <dBm>`	1‑30	14	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)	5	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 uniformly if dense network.
`txdelay <f>`	≥ 0	0.5	None on demodulation; affects collision rate.	Increase on congested channels.
`direct.txdelay <f>`	≥ 0	0.0	None	Lower 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	3	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`	on	Turning off may isolate parts of mesh.	Ensure alternate paths exist before disabling.
`allow.read.only on/off`	`on` / `off`	off	None	Grants guest 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 OTA image tag and adverts.
`guest.password <password>`	≤ 14 chars	<blank>	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.