diff --git a/README.md b/README.md index 3a835ccb..af2b4ad9 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/tth-commands.md b/docs/tth-commands.md new file mode 100644 index 00000000..e5815e03 --- /dev/null +++ b/docs/tth-commands.md @@ -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 ` | burst caps 0..255, `0` = build default (100 / 150 / 30) | +| `fairness refill ` | 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 [\|clear]` | per-origin advert window: one flood advert per origin per `` (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 ` / `filter del ` | 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 [secs]` | block the byte, or let one packet through per `secs` (1..65535); re-adding changes the interval | +| `filter hash del ` / `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 |off` (1..10080, default off): do not forward a group text +on a decrypted channel whose sender timestamp is older than `` 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 \|off` / `get radio.silence` | deaf receiver: re-arm RX, then reboot after `` 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 \|off` / `get radio.txstall` | repeater only: packets queued and nothing sent for `` -> 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 ` | 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 ` | 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.