12 KiB
Console commands of this fork (meshcore-tth)
Warning
Part of an experimental fork, not meant for regular users: its releases are a rolling release on MeshCore
dev(see the README).
Everything this fork adds to the text console of a node, on top of upstream's
cli_commands.md. Where a command is described there too
(the watchdogs, rxps, batt.icon, gps duty, dfu, get boot), this page
gives the short form and points to it.
Where a command exists depends on the role and on build flags:
| mark | builds |
|---|---|
| all | repeater, room server and sensor -- every build with a text console |
| repeater | simple_repeater builds |
| observer | the *-observer variants of the nRF52 repeaters in the releases (MAX_HEARD_NODES, RXLOG_SIZE, PKTFEED_SIZE, BLE_PIN_CODE) |
| own build | only with the named flag -- not in the releases |
Where it can be sent from: the USB console, the BLE console (observer variants) and the mesh, as admin in the remote CLI of an app -- unless the entry says local only. Replies over the mesh are cut to one packet (~150 B).
Antispam (repeater)
Forwarding only: what this node hears, logs and feeds to an observer is never affected. Everything is persisted in prefs, so a reboot keeps it.
FairnessLimiter -- fairness
Token buckets on forwarded floods, keyed on the 1-byte ids already in the
clear: channel hash, sender hash, advert origin. Buckets collide (the hash is
masked), and every key is chosen by the sender: it contains runaway floods,
it is not security. Direct-routed traffic is never limited.
On after flashing (FAIRNESS_ENABLED_DEFAULT).
| command | |
|---|---|
fairness |
state, denials per category, caps and refill intervals |
fairness on|off |
the buckets on/off |
fairness cap <group> <sender> <advert> |
burst caps 0..255, 0 = build default (100 / 150 / 30) |
fairness refill <group_s> <sender_s> <advert_s> |
one token per interval, seconds, 0 = default (30 / 10 / 600) |
fairness grid |
the busiest denied buckets per category -- what is being shed |
fairness air |
estimated airtime shed per reason |
fairness advert [<hours>|clear] |
per-origin advert window: one flood advert per origin per <hours> (0..720, 0 = off, default off); clear forgets the origins seen |
fairness dryrun [on|off] |
count every verdict but forward anyway (default off) |
The defaults keep about twice the headroom over 30 days of CZ mesh traffic (the zero-loss frontier was 60 s / cap 60 per channel, 10 s / 60 per sender, 600 s / 12 per advert origin).
Channel filter -- filter
On channels whose key the node knows (FILTER_CHANNEL_PSKS; the releases
know Public, #meshcore and #test) the node decrypts each group text and
refuses to forward listed senders. The sender name is plain text in the
message: anyone can rename around it.
| command | |
|---|---|
filter / filter list |
channels known, drops, the deny list |
filter add <name> / filter del <name> |
exact, case-insensitive; spaces allowed, commas not |
filter clear |
empty the list |
Channel-hash deny-forward -- filter hash (every repeater)
Keyless: the first byte of a group packet is the channel hash, in the clear, so this works on private channels too. One byte is coarse -- every other channel whose key hashes to the same byte is hit as well; check what else lives on it before adding one.
| command | |
|---|---|
filter hash |
drops, passes by a throttle, the list (43 blocked, 43/60 throttled) |
filter hash add <hex> [secs] |
block the byte, or let one packet through per secs (1..65535); re-adding changes the interval |
filter hash del <hex> / filter hash clear |
A throttle's window lives in RAM: the first match after a boot passes.
Message age -- filter age (repeater with channel keys)
filter age <min>|off (1..10080, default off): do not forward a group text
on a decrypted channel whose sender timestamp is older than <min> by this
node's clock. It judges the sender's clock, so a companion that never got a
time sync (it stamps 2024) is dropped too -- keep it in days. Inactive while
the node's own clock reads before 2026; a clock running ahead makes
everything look old.
filter dryrun [on|off]
Count every filter verdict (sender, hash, age) but forward anyway -- try a
rule on a live node before it bites. Default off.
Radio watchdogs and board upkeep (all)
Details: cli_commands.md, "Radio silence watchdog", "TX stall watchdog", "Reboot into the bootloader" and "Why the board last reset".
| command | |
|---|---|
set radio.silence <min>|off / get radio.silence |
deaf receiver: re-arm RX, then reboot after <min> without a received frame (CRC errors count as heard); each such reboot doubles the threshold for the next boot (up to 16x), the first frame clears it. 1..1440, persisted, default off |
set radio.txstall <min>|off / get radio.txstall |
repeater only: packets queued and nothing sent for <min> -> re-arm, then reboot. An empty queue never counts. On, 15 min (RADIO_TXSTALL_MIN); a change holds until reboot |
get radio.reboots |
reboots done by the watchdogs, survives power loss |
get boot |
reset reason and the hardfault record (also printed at boot) |
dfu [uf2|serial|ota] |
local only: reboot into the bootloader -- UF2 drive (default), CDC port for adafruit-nrfutil, or BLE DFU |
fw ... |
-ota images only: admin-pushed firmware update, see ota.md |
Diagnostics
| command | where | |
|---|---|---|
blink [n] / blink on|off |
repeater | flash a spare LED (not the BLE or TX one) n times (default 6, max 999), or until blink off (gives up after 10 min); finds a board on a bench or a node on a mast |
txpwr [dBm] |
repeater | LoRa output power until reboot, with RadioLib's status (set tx saves and says OK even when the radio refused) |
i2c |
all | scan the I2C bus |
get chip |
nRF52 (repeater, room server, sensor) | the silicon (nRF52840 AAD0; variant xxF0 and later = rev3) and UICR.APPROTECT: open means SWD can read the whole flash, keys included (locked-bootloader.md) |
dio1 |
own build: PIN_DIAG |
has the SX1262 raise TX_DONE and compares its IRQ register with the level on the DIO1 pin -- which end of a dead IRQ line is broken |
radiostat |
own build: RADIO_DIAG |
receiver state, interrupt and RX counters, without touching the radio |
radiokick rx|clrirq|standby|agc |
own build: RADIO_DIAG |
one recovery step, gentlest first: re-arm RX, clear latched IRQs, standby + RX, AGC reset; the first that brings recv back names the broken layer |
A board with a dead DIO1 line still runs with LORA_POLL_IRQ (own build):
the IRQ status is polled over SPI.
BLE console (observer)
The text console over BLE (Nordic UART), next to USB. No login of its own:
the BLE PIN is the only lock, and the release PIN is the public placeholder
123456. These commands also work as admin over the mesh.
| command | |
|---|---|
ble |
on/off, PIN own or build default -- never the PIN itself |
ble pin <6 digits> |
set your own PIN (saved, survives a reflash; drops every bond, so paired devices pair again) |
ble on|off |
persisted; off after flashing (RPT_BLE_DEFAULT_OFF), and ble on is refused while the PIN is the placeholder |
blepwr [dBm|default] |
TX power of the connection (-40, -20, -16, -12, -8, -4, 0, 2..8), applied to live connections and saved; default returns to the build value (0 dBm) |
bleconn |
what the central actually agreed to: interval (and what was requested), latency, supervision timeout |
A connected central stops the node advertising: if the BLE console cannot be
found, look for who is connected (ble shows it).
Passive analyzer (observer)
| command | |
|---|---|
nodes [offset] |
heard repeaters and room servers with a key to join several paths, paged |
rxlog [cursor] |
every frame heard: type, path, SNR, RSSI; cursor from the previous page (0 = all) |
pktlog [cursor] |
raw frames heard, for an observer feed (meshcore-repeater-observer) |
A page is as big as the caller's reply buffer: ~1000 B on the local console, one packet over the mesh.
Channel bot (own build: BOT_CHANNEL_PSK)
A repeater that answers on one channel without forwarding anything:
!link, !path, !snr, !heard, !noise, !ping, !help (narrowed by
BOT_COMMANDS), with a per-sender cooldown and an ignore list. bot on the
console shows its state.
Power and clock
| command | where | |
|---|---|---|
set radio.rxps off|on|balanced|max, level <1-10> [preamble 16|32] / get radio.rxps |
all, SX1262 only (WITH_RX_POWERSAVING, in the releases) |
RX duty cycle: the radio sleeps between short listening windows. Off by default. max saved ~2.3 mA on the bench, but a mast on the live mesh lost 16 % of its reception -- see cli_commands.md and power.md |
set batt.icon on|off, set batt.icon.lo|hi <mV> |
all | battery level as an icon at the end of the advertised name (off by default; with a name too long for it the icon is left out, and the reply says so) |
gps duty ... |
GPS boards | the receiver runs only around a clock sync; see cli_commands.md |
clkreboot |
all | reset the clock to the build epoch and reboot -- the only way to move a clock backwards (time and clock sync refuse to) |
Sensors
| command | |
|---|---|
sensor read |
the live telemetry decoded into one line (sensor list shows only settings) |
sensor set ina.shunt <mOhm> |
shunt resistance of an INA219/226/260/3221, saved across reboots |
Build flags
The ones that change what a node does; set in platformio.ini /
platformio.local.ini (-D NAME=value, the last -D wins).
| flag | default | |
|---|---|---|
FAIRNESS_ENABLED_DEFAULT |
1 |
FairnessLimiter on for a node without prefs |
RADIO_SILENCE_MIN_DEFAULT |
0 |
deaf-receiver watchdog for a node without prefs |
RADIO_TXSTALL_MIN |
15 |
TX stall watchdog at boot (repeater), 0 = off |
FILTER_CHANNEL_PSKS |
releases: Public, #meshcore, #test |
channel keys the filter can decrypt |
MAX_HEARD_NODES, RXLOG_SIZE, PKTFEED_SIZE |
0 (observer variants: 128 / 512 / 64) |
the analyzer rings |
BLE_PIN_CODE, RPT_BLE_DEFAULT_OFF |
observer variants | BLE console, starting off |
BOT_CHANNEL_PSK, BOT_COMMANDS |
unset | channel bot |
RADIO_DIAG, PIN_DIAG, LORA_POLL_IRQ |
unset | radio diagnostics, DIO1-less operation |
FW_OTA |
-ota images |
admin-pushed firmware update |
PATH_HASH_MODE_DEFAULT |
1 (2 B per hop) |
path hash width for a node without prefs |
ACL_TS_MAX_AHEAD |
86400 (s) |
a client timestamp further ahead of the node's clock is not stored as the replay floor |
LOCKED_NODE |
unset | a node that keeps its secrets from whoever holds it: get prv.key, get guest.password and get bridge.secret answer Error: locked build to everyone (USB and BLE console, an admin over the mesh); a companion serves only paired BLE (USB, UART and WiFi get the device info and nothing else) and its rescue CLI refuses set pin. Only half of it: locked-bootloader.md |
LOGIN_FAIL_MAX, LOGIN_FAIL_SECS |
4, 180 (s) |
after that many wrong passwords in the window no password is checked until it ends (an admin already in the ACL always gets in) |
Prefs saved on the node override the build defaults: a reflash keeps what a
node already has; only a new node or one after erase takes them.