Files
meshcore-tth/docs/tth-commands.md
T

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.