docs/tth-commands.md: every console command of the fork, where it exists, defaults
pub-release / release (push) Canceled after 22s

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
tthandClaude Opus 5.5 committed 2026-11-17 02:11:04 +01:00
1 parent 0a88dda5f8
commit 41d3ba93ea
2 files changed
+220 -17

No files matched your search

+27 -17
View File
@@ -56,6 +56,9 @@ vypnuté, dokud je nezapnete.
### Diagnostika a provoz
Všechny příkazy forku, kde je který build má a výchozí hodnoty:
[docs/tth-commands.md](docs/tth-commands.md).
Repeater, room server i senzor (všechno s textovou konzolí) mají:
* **Watchdogy rádia.** Hardwarový watchdog chytí jen zamrzlou smyčku; dva naše
@@ -75,19 +78,19 @@ Repeater, room server i senzor (všechno s textovou konzolí) mají:
napájení); `get boot` – proč se deska naposledy resetovala a záznam
o hardfaultu (vypíše se i při startu).
* `dfu [uf2|serial|ota]` – spolehlivý reboot do bootloaderu (jen z lokální
konzole).
konzole); `i2c` – sken sběrnice.
Repeater navíc:
* `blink` (rozbliká LED, i přes mesh – najdete uzel na stožáru), `txpwr`
(vysílací výkon do restartu, s verdiktem RadioLibu), `i2c` (sken sběrnice),
`dio1` (stav přerušení v čipu proti úrovni na pinu), čítače chyb vysílání ve
stavové odpovědi.
* Textová konzole přes BLE vedle USB, `ble on|off` uložené přes reboot
(`RPT_BLE_DEFAULT_OFF`: startuje vypnuté), vlastní BLE PIN (`ble pin`),
uložený vysílací výkon spojení (`blepwr`), `bleconn`, neblokující BLE
vysílání a parametry spojení, které vydrží i na slabém linku.
* Jen observer varianty (`*-observer`): pasivní analyzátor v konzoli – `nodes`
(vysílací výkon do restartu, s verdiktem RadioLibu), čítače chyb vysílání
ve stavové odpovědi.
* Jen observer varianty (`*-observer`): textová konzole přes BLE vedle USB,
`ble on|off` uložené přes reboot (`RPT_BLE_DEFAULT_OFF`: startuje vypnuté),
vlastní BLE PIN (`ble pin`), uložený vysílací výkon spojení (`blepwr`),
`bleconn`, neblokující BLE vysílání a parametry spojení, které vydrží i na
slabém linku.
* Taky jen observer varianty: pasivní analyzátor v konzoli – `nodes`
(slyšené repeatery a roomy, klíč pro spojení více cest), `rxlog` (každý
slyšený rámec: typ, cesta, SNR, RSSI), `pktlog` (surové rámce pro feed
observeru), velké stránkované odpovědi.
@@ -98,6 +101,8 @@ Repeater navíc:
* `RADIO_DIAG`: `radiostat` (stav přijímače SX1262 bez zásahu) a
`radiokick rx|clrirq|standby|agc` (jeden krok obnovy, od nejjemnějšího –
první, který pomůže, ukáže rozbitou vrstvu);
* `PIN_DIAG`: `dio1` (stav přerušení v čipu proti úrovni na pinu – který
konec mrtvé linky DIO1 je přerušený);
* `LORA_POLL_IRQ`: provoz bez DIO1 pro desku s mrtvou linkou přerušení.
### Opravy jádra
@@ -338,6 +343,9 @@ off until you turn them on.
### Diagnostics and operations
Every command of the fork, which builds have it and the defaults:
[docs/tth-commands.md](docs/tth-commands.md).
Repeater, room server and sensor (everything with a text console) have:
* **Radio watchdogs.** The hardware watchdog only catches a frozen loop; two
@@ -358,19 +366,19 @@ Repeater, room server and sensor (everything with a text console) have:
loss); `get boot` -- why the board last reset, and the hardfault record
(also printed at boot).
* `dfu [uf2|serial|ota]` -- a deterministic reboot into the bootloader (local
console only).
console only); `i2c` -- bus scan.
The repeater also has:
* `blink` (flashes the LED, also over the mesh -- finds a node on a mast),
`txpwr` (TX power until reboot, with RadioLib's verdict), `i2c` (bus scan),
`dio1` (the chip's IRQ status against the level on the pin), TX-failure
`txpwr` (TX power until reboot, with RadioLib's verdict), TX-failure
counters in the status reply.
* Text console over BLE next to USB, `ble on|off` saved across reboots
(`RPT_BLE_DEFAULT_OFF`: starts off), own BLE PIN (`ble pin`), persisted
connection TX power (`blepwr`), `bleconn`, a non-blocking BLE TX pump and
connection parameters that hold on a weak link.
* Observer variants only (`*-observer`): a passive analyzer in the console --
* Observer variants only (`*-observer`): text console over BLE next to USB,
`ble on|off` saved across reboots (`RPT_BLE_DEFAULT_OFF`: starts off), own
BLE PIN (`ble pin`), persisted connection TX power (`blepwr`), `bleconn`, a
non-blocking BLE TX pump and connection parameters that hold on a weak
link.
* Also observer variants only: a passive analyzer in the console --
`nodes` (heard repeaters/rooms, multi-path join key), `rxlog` (every frame
heard, type/path/SNR/RSSI), `pktlog` (raw frames for an observer feed), big
paged replies.
@@ -381,6 +389,8 @@ The repeater also has:
* `RADIO_DIAG`: `radiostat` (SX1262 receiver state, hands off) and
`radiokick rx|clrirq|standby|agc` (one recovery step at a time, gentlest
first -- the first that helps names the broken layer);
* `PIN_DIAG`: `dio1` (the chip's IRQ status against the level on the pin --
which end of a dead DIO1 line is broken);
* `LORA_POLL_IRQ`: DIO1-less operation for a board with a dead IRQ line.
### Core fixes
+193
View File
@@ -0,0 +1,193 @@
# 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](../README.md)).
Everything this fork adds to the text console of a node, on top of upstream's
[cli_commands.md](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](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](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](https://git.rfa.cz/tth-pub/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](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 |
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.