Files
meshcore-tth/docs/tth-commands.md
T
2026-11-18 10:31:04 +01:00

11 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
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

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.