From 0a88dda5f810d8dc40c51ab6f2f037b99d29b1f9 Mon Sep 17 00:00:00 2001 From: TeTeHacko Date: Tue, 17 Nov 2026 02:08:33 +0100 Subject: [PATCH] README: the fork's extras as they really ship -- watchdogs, defaults, what is release vs own build Co-Authored-By: Claude Opus 5.5 --- README.md | 165 ++++++++++++++++++++++++++++++++++++++-------------- docs/ota.md | 14 +++-- 2 files changed, 131 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 2e672877..3a835ccb 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,13 @@ označený `CUSTOM (TeTeHacko)`. Nic z toho nemění protokol na rádiu. ### Repeater: antispam (všechno vypínatelné, nic z toho není v upstreamu) +**Po nahrání je zapnutý jen FairnessLimiter**, s limity se zhruba +dvojnásobnou rezervou nad 30 dní skutečného provozu CZ meshe: na kanál dávka +100 zpráv a pak jedna za 30 s, na odesílatele 150 a jedna za 10 s, na +původce advertu 30 a jeden za 10 min. Je to síť na utržené floody, ne kvóta; +`fairness off` ho vypne natrvalo. Okno na adverty, filtry a dry-run jsou +vypnuté, dokud je nezapnete. + * **FairnessLimiter** – token buckety na přeposílané floody podle 1bajtových identifikátorů, které jsou v paketu stejně v čitelné podobě (hash kanálu, hash odesílatele, původce advertu). Port návrhu Beanowa @@ -47,23 +54,51 @@ označený `CUSTOM (TeTeHacko)`. Nic z toho nemění protokol na rádiu. nastavuj ho na dny. * `filter dryrun on` započítá každý verdikt `filter`, ale přepošle i tak. -### Repeater: diagnostika a provoz +### Diagnostika a provoz -* 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. -* Kanálový bot v analyzer buildu (`!link`, dotazy na cestu, cooldown na - odesílatele, ignore list) – odpovídá, aniž by přeposílal. -* `dfu [uf2|serial|ota]` (spolehlivý reboot do bootloaderu), `blink`, `txpwr` - s verdiktem RadioLibu, `i2c` sken sběrnice, čítače chyb vysílání ve stavové - odpovědi, důvod resetu vypsaný při startu. +Repeater, room server i senzor (všechno s textovou konzolí) mají: + +* **Watchdogy rádia.** Hardwarový watchdog chytí jen zamrzlou smyčku; dva naše + uzly ale byly nalezeny hluché s běžící smyčkou a pomohl až restart. + * `set radio.silence ` – **hluchý přijímač**: když se za `` minut + nepohne čítač přijatých rámců (počítá se i rámec s chybou CRC), uzel + napřed znovu nahodí příjem, a když ani to nepomůže, restartuje se. Každý + takový restart zdvojnásobí práh pro příští start (až 16×), první přijatý + rámec ho vrátí, takže tiché místo neskončí ve smyčce restartů. Uloží se; + **ve výchozím stavu vypnutý** (`0`) – práh volte s rezervou nad nejdelší + běžné ticho na místě. + * **Zaseknuté vysílání** (jen repeater): pakety čekají ve frontě a čítač + odeslaných se nehýbe → znovu nahodí rádio, pak restart. Prázdná fronta se + nepočítá. **Zapnutý, 15 min** (`RADIO_TXSTALL_MIN`); `set radio.txstall + |off` platí jen do restartu. + * `get radio.reboots` – kolik restartů watchdogy udělaly (přežije i výpadek + 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). + +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. -* Build flag `RADIO_DIAG`: `radiostat` / `radiokick` na přijímač SX1262, který - přestal přijímat. -* Provoz bez DIO1 (`LORA_POLL_IRQ`) pro desku s mrtvou linkou přerušení. +* Jen observer varianty (`*-observer`): 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. +* Jen vlastní buildy, ne releasy: + * kanálový bot (`BOT_CHANNEL_PSK`: `!link`, `!path`, `!snr`, `!heard`, + `!noise`, `!ping`, `!help`, výběr přes `BOT_COMMANDS`, cooldown na + odesílatele, ignore list) – odpovídá, aniž by přeposílal; + * `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); + * `LORA_POLL_IRQ`: provoz bez DIO1 pro desku s mrtvou linkou přerušení. ### Opravy jádra @@ -84,12 +119,16 @@ označený `CUSTOM (TeTeHacko)`. Nic z toho nemění protokol na rádiu. Dotaz na polohu přijímač probudí pro příští dotaz. * Uzel bez GPS startuje na čase sestavení firmwaru, ne v roce 2024; hodiny a záznam o hardfaultu přežijí teplý reset (`.noinit`); `clkreboot`. -* Na solárních uzlech žádná blikající LED a pomalejší BLE advertising; stav - baterie jako ikona na konci advertovaného jména (volitelné). -* Volitelný RX duty cycle (`set radio.rxps`, port PowerSaving z EasySkyMesh): - SX1262 mezi krátkými okny poslechu spí. Ve veřejných buildech je zabudovaný - a **vypnutý**; `max` na lavici ušetřil ~2,3 mA bez ztráty paketů - ([docs/power.md](docs/power.md)). Jen SX1262, ne LR1110 (T1000-E). +* Na solárních uzlech žádná blikající LED a pomalejší BLE advertising. +* Stav baterie jako ikona na konci advertovaného jména: `set batt.icon on`, + prahy `set batt.icon.lo|hi ` (výchozí vypnuté; dlouhé jméno ikonu + nepojme a příkaz na to upozorní). +* Volitelný RX duty cycle (`set radio.rxps off|on|balanced|max`, jemněji + `level <1-10>`; port PowerSaving z EasySkyMesh): SX1262 mezi krátkými okny + poslechu spí. Ve veřejných buildech je zabudovaný a **vypnutý**; `max` na + lavici ušetřil ~2,3 mA bez ztráty paketů ([docs/power.md](docs/power.md)), + na ostrém meshi ale jeden náš stožár ztratil 16 % příjmu – zapínat s rozmyslem. Jen + SX1262, ne LR1110 (T1000-E). * Podpěťová pojistka při startu (`PWRMGT_VOLTAGE_BOOTLOCK`) je na nRF52 **vypnutá**, stejně jako v upstreamu od v1.18.0 ([#2377](https://github.com/meshcore-dev/MeshCore/pull/2377)): pevný práh @@ -231,8 +270,8 @@ zůstane v bootloaderu a vrátí se přes USB/BLE DFU. takový, který nenabootuje, chce USB/BLE DFU v ruce. Vyzkoušeno na lavici (XIAO, USB, mesh, vedlejší kanál) a od 13. 11. 2026 na dvou našich stožárech. Proti obrazu, který nabootuje s mrtvým rádiem, jsou watchdogy - `set radio.silence` / `set radio.txstall` (výchozí vypnuté, - [docs/ota.md](docs/ota.md)). Stojí ~10 kB RAM navíc. + rádia (viz Diagnostika a provoz): pro uzly, kam posíláte OTA, zapněte + `set radio.silence`. Stojí ~10 kB RAM navíc. ### Sestavení @@ -266,6 +305,13 @@ twice a day; everything below is on top of that. Our code is marked ### Repeater: antispam (all of it off-switchable, none of it upstream) +**After flashing only the FairnessLimiter is on**, with limits about twice +above 30 days of real CZ mesh traffic: per channel a burst of 100 messages, +then one per 30 s; per sender 150 and one per 10 s; per advert origin 30 and +one per 10 min. It is a net for runaway floods, not a quota; `fairness off` +switches it off for good. The advert window, the filters and dry-run stay +off until you turn them on. + * **FairnessLimiter** -- token buckets on forwarded floods, keyed on the 1-byte ids already in the clear (channel hash, sender hash, advert origin). Port of Beanow's proposal [#1502](https://github.com/meshcore-dev/MeshCore/pull/1502), @@ -290,23 +336,52 @@ twice a day; everything below is on top of that. Our code is marked clock, so companions without a time sync are dropped too -- keep it in days. * `filter dryrun on` counts every `filter` verdict but forwards anyway. -### Repeater: diagnostics and operations +### Diagnostics and operations -* 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. -* Channel bot for the analyzer build (`!link`, path questions, per-sender - cooldown, ignore list) -- answers without repeating. -* `dfu [uf2|serial|ota]` (deterministic reboot into the bootloader), `blink`, - `txpwr` with RadioLib's verdict, `i2c` bus scan, TX-failure counters in the - status reply, reset reason printed at boot. +Repeater, room server and sensor (everything with a text console) have: + +* **Radio watchdogs.** The hardware watchdog only catches a frozen loop; two + of our nodes were found deaf with the loop running, and only a reboot + helped. + * `set radio.silence ` -- **deaf receiver**: when the received-frame + counter does not move for `` minutes (a frame with a CRC error + counts), the node re-arms its receiver first and reboots if that does not + help either. Each such reboot doubles the threshold for the next boot (up + to 16x) and the first frame received resets it, so a quiet site does not + end in a reboot loop. Saved; **off by default** (`0`) -- pick a threshold + well above the longest normal quiet spell of the site. + * **Stalled TX** (repeater only): packets wait in the queue and the sent + counter does not move -> re-arm the radio, then reboot. An empty queue + never counts. **On, 15 min** (`RADIO_TXSTALL_MIN`); `set radio.txstall + |off` holds until the next reboot. + * `get radio.reboots` -- reboots done by the watchdogs (survives power + 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). + +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 + 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. -* `RADIO_DIAG` build flag: `radiostat` / `radiokick` for an SX1262 receiver - that stops receiving. -* DIO1-less operation (`LORA_POLL_IRQ`) for a board with a dead IRQ line. + 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 -- + `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. +* Own builds only, not in the releases: + * channel bot (`BOT_CHANNEL_PSK`: `!link`, `!path`, `!snr`, `!heard`, + `!noise`, `!ping`, `!help`, narrowed by `BOT_COMMANDS`, per-sender + cooldown, ignore list) -- answers without repeating; + * `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); + * `LORA_POLL_IRQ`: DIO1-less operation for a board with a dead IRQ line. ### Core fixes @@ -326,12 +401,16 @@ twice a day; everything below is on top of that. Our code is marked a fix again in 6 h). A position request warms it for the next request. * A node without GPS starts at its build epoch, not in 2024; the clock and a hardfault record survive a warm reset (`.noinit`); `clkreboot`. -* No blinking LED and slower BLE advertising on solar nodes; battery level as - an icon at the end of the advertised name (opt-in). -* Optional RX duty cycle (`set radio.rxps`, ported from EasySkyMesh - PowerSaving): the SX1262 sleeps between short listening windows. Built into - the public releases and **off**; `max` saved ~2.3 mA on the bench with no - packet loss ([docs/power.md](docs/power.md)). SX1262 only, not the LR1110 +* No blinking LED and slower BLE advertising on solar nodes. +* Battery level as an icon at the end of the advertised name: `set batt.icon + on`, thresholds `set batt.icon.lo|hi ` (off by default; a long name has + no room for it and the command says so). +* Optional RX duty cycle (`set radio.rxps off|on|balanced|max`, finer + `level <1-10>`; ported from EasySkyMesh PowerSaving): the SX1262 sleeps + between short listening windows. Built into the public releases and + **off**; `max` saved ~2.3 mA on the bench with no packet loss + ([docs/power.md](docs/power.md)), but on the live mesh one of our masts lost + 16 % of its reception -- switch it on with care. SX1262 only, not the LR1110 (T1000-E). * The nRF52 boot undervoltage lock (`PWRMGT_VOLTAGE_BOOTLOCK`) is **off**, as in upstream since v1.18.0 @@ -474,9 +553,9 @@ cut during the rewrite leaves it in the bootloader, back via USB/BLE DFU. rollback. A bad firmware that boots keeps running until you push the next one; one that does not boot needs USB/BLE DFU in hand. Tried on the bench (XIAO, USB, mesh, side channel) and on two of our masts since 13. 11. 2026. - The watchdogs `set radio.silence` / `set radio.txstall` (off by default, - [docs/ota.md](docs/ota.md)) catch an image that boots with a dead radio. - Costs ~10 kB of RAM. + The radio watchdogs (see Diagnostics and operations) catch an image that + boots with a dead radio: switch `set radio.silence` on for nodes you push + to. Costs ~10 kB of RAM. ### Build diff --git a/docs/ota.md b/docs/ota.md index a0fe49b5..ce3b2fb8 100644 --- a/docs/ota.md +++ b/docs/ota.md @@ -79,15 +79,19 @@ What the node checks before it touches its own image: No second bank, no automatic rollback. The checks above stop a *corrupt* package, but firmware that passes them and still boots into a broken state keeps running. -Two watchdogs catch that, both **off by default** -- turn them on for nodes you -push to: +Two watchdogs catch that. The deaf-receiver one is **off by default** -- turn it +on for nodes you push to; the TX stall one is on in repeaters: - set radio.silence reboot if the radio hears nothing for (persisted); - catches an OTA that boots with a dead radio - set radio.txstall reboot if the TX queue stalls (RAM only) + set radio.silence re-arm the receiver, then reboot, if it hears nothing + for (persisted, off by default); catches an OTA + that boots with a dead radio + set radio.txstall the same when the TX queue stalls (repeater only, on + at 15 min by default, a change holds until reboot) get radio.reboots watchdog reboots so far (survives power loss) get boot why the board last reset, plus the hardfault record +Details: `docs/cli_commands.md`, "Radio silence watchdog" and "TX stall watchdog". + A node that will not boot at all has to be reflashed over USB/BLE DFU. After an `fw apply` over **BLE** the bond can drop (a supervision timeout while the node reboots) -- re-pair from the same host; it is not a brick.