198 lines
12 KiB
Markdown
198 lines
12 KiB
Markdown
# 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 |
|
|
| `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](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](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 |
|
|
| `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](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.
|