tthandClaude Opus 5.5 4dfe998409
ci / test (push) Failing after 30s
README, examples/firmware-ota.yml: OTA updates -- how a package is picked, RF vs BLE console, what to watch
The intro said the collection does not touch firmware; it now updates an
-ota node. The example downloads a release's packages, refuses them without
the release signature (ssh-keygen -Y verify) and runs meshcore_fw_ota.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-14 21:08:25 +01:00

tth.meshcore — MeshCore repeatery jako kód

Ansible kolekce, která drží stav MeshCore repeaterů deklarativně a na dálku přes rádio: kdo je admin (ACL), nastavení (get/set) a strom regionů — to umí každý MeshCore repeater. S firmwarem meshcore-tth navíc zapínání BLE konzole, antispamové filtry a aktualizace firmwaru přes rádio (OTA). Ke stožáru nikdo nemusí: moduly mluví s repeaterem přes companion, který ho slyší (openHop TCP companion, nebo companion na USB).

Firmware: meshcore_fw_facts přečte, jaká verze na uzlu běží, a meshcore_fw_ota aktualizuje uzel, který už běží na OTA obrazu meshcore-tth (*-ota), deltou z releasu — přes rádio, nebo přes jeho BLE konzoli. První OTA obraz se nahrává normálním flashem: návod k flashování (webový flasher, Custom Firmware s .zip).

ansible-playbook -i inventory.yml repeaters.yml --check --diff   # co by se změnilo
ansible-playbook -i inventory.yml repeaters.yml --diff           # nasadit
ansible-playbook -i inventory.yml firmware-ota.yml -e ota_release=<tag> --check   # který balíček by šel

English: an Ansible collection that converges MeshCore repeaters (admin ACL, CLI prefs, region tree; BLE, filters and OTA firmware updates on meshcore-tth) over RF through a companion radio, with --check --diff and read-back verification. Module docs are English (ansible-doc tth.meshcore.meshcore_acl); this README is Czech.

Instalace

ansible-galaxy collection install git+https://git.rfa.cz/tth-pub/meshcore-ansible.git

Na hostu, kde moduly běží (ten s companionem), potřebuje Python knihovnu meshcore (a bleak jen pro meshcore_companion_acl a pro meshcore_fw_ota přes BLE konzoli), viz requirements.txt. Na Archu python-meshcore z AUR, jinde venv a ansible_python_interpreter na něj.

Moduly

modul co spravuje firmware
meshcore_acl admini repeateru (setperm), čte skutečné ACL binárním dotazem MeshCore
meshcore_prefs get/set klíčů; freq, radio, hesla a klíč odmítne MeshCore
meshcore_region strom regionů, domovský region, default scope, region save MeshCore 1.10+
meshcore_fw_facts jen čte: verze z ver a odchylka hodin uzlu MeshCore
meshcore_companion_acl "remote CLI" příznak kontaktů na companionu, přes jeho BLE MeshCore 1.18+
meshcore_ble ble on/off, vlastní BLE PIN (ble pin, z vaultu, v logu zamaskovaný), výkon BLE spojení (blepwr) meshcore-tth
meshcore_filter_hash zákaz přeposílání kanálů podle hashe meshcore-tth
meshcore_filter stáří zpráv a dry-run filtru meshcore-tth
meshcore_fairness okno na adverty podle původce a dry-run meshcore-tth
meshcore_fw_ota OTA aktualizace z balíčků releasu (.mcfw): delta podle fw status, přes RF v limitu airtime, přes BLE konzoli bez vysílání meshcore-tth, obraz *-ota

Moduly pro meshcore-tth na běžném firmwaru skončí chybou nebo skipped (Unknown command), nic jiného nepošlou.

OTA aktualizace (meshcore_fw_ota)

Release meshcore-tth nese u každého *-ota artefaktu plný obraz a delty od několika předchozích releasů (.mcfw), SHA256SUMS je podepsaný. Modul:

  1. přečte fw status — velikost a otisk obrazu, na kterém uzel běží;
  2. vybere balíček: deltu, která z toho obrazu vychází, nebo (jen po BLE konzoli) plný obraz. Uzel, který cílový obraz už má, je changed: false; když nesedí nic, vrátí no_package: true (ne chybu) a je na vás nahrát plný obraz jinak — třeba proto, že uzel vynechal víc releasů, než kolik delt release nese;
  3. přenese ho, zkontroluje (fw verify) a nahraje (fw apply, s apply: false jen připraví), po restartu přečte novou verzi.

Cesty:

  • přes rádio (companion transport jako u ostatních modulů): jen delty, binární kousky po 128 B bez odpovědí, chybějící podle bitmapy, textové jako záloha. Tempo hlídá limit airtime duty (procenta za hodinu, počítá požadavek i odpověď krát počet hopů + 1). Delta ~25 kB přes dva hopy trvá ~40 min při 3 %, pouštějte s async. Přerušený přenos dokončí resume: true — uzel drží, co dostal, do příštího fw begin nebo restartu;
  • přes BLE konzoli uzlu (transport: {type: ble_console, address: <MAC>}): nic nevysílá do meshe a projde i plný obraz. Uzel musí být spárovaný na hostu, kde modul běží (konzole chce šifrované spojení), a nesmí k němu být připojený jiný centrál — připojený uzel neadvertuje.

Stažení releasu a kontrola podpisu jsou na volajícím (examples/firmware-ota.yml to dělá s ssh-keygen -Y verify); uzel každý balíček kontroluje i sám (podpis Ed25519, cíl, základní obraz, nesmí být starší) a cizí odmítne po prvních kouscích, než se pošle zbytek.

Jak to funguje

  • Každý repeater je host v inventáři, úlohy běží na hostu s companionem (delegate_to: mc_via), transport říká jak: {type: tcp, host, port}, {type: serial, port, baud} nebo {type: ble, address}. BLE companion musí být spárovaný na hostu, kde modul běží (bluetoothctl pair); PIN modul schválně nebere, aby neskončil v logu. Jeden repeater po druhém (serial: 1): companion obslouží jednoho klienta a víc přihlášení naráz by se srazilo ve vzduchu.
  • Každá změna je přečíst → poslat rozdíl → přečíst znovu. --check nic nevysílá kromě čtení, druhý běh má být 0 změn.
  • Odpovědi přes RF se ztrácí a chodí pozdě: každá výměna ověřuje odesílatele a tvar odpovědi a opakuje se (transport.retries, transport.reply_timeout).
  • Pojistky:
    • transport.expect_freq: companion na jiném kmitočtu = nepošle se nic (testovací běh nedoletí do ostrého meshe);
    • companion, přes který se spravuje, se z ACL nikdy neodebere;
    • login, který projde jen jako host (heslo = guest heslo), je chyba, ne tiché čekání na odpovědi, které nepřijdou.

Příklad

examples/inventory.yml a examples/repeaters.yml, OTA v examples/firmware-ota.yml (stáhne balíčky releasu, ověří podpis, aktualizuje). Admin heslo patří do ansible-vault (vault_meshcore_admin_password).

Pasti, které stály čas

  • Uložené prefs přebíjejí výchozí hodnoty buildu. Jiný uzel z téže várky může mít jiné admin heslo; login pak projde jen jako host.
  • Jednotky advert intervalů: advert.interval je v minutách, flood.advert.interval v hodinách (3–168). Hodnotu mimo rozsah uzel odmítne a modul selže — nikdy po něm nezůstane tiché OK.
  • Heslo nikdy přes heredoc s rourou (echo heslo | python - <<EOF): stdin je heredoc, roura se zahodí a uzel dostane prázdné heslo.
  • Region bez region save zmizí rebootem; modul ukládá sám. Výpis stromu delší než ~160 B firmware ořízne a modul takový strom odmítne spravovat.
  • Uzel s připojeným BLE klientem ztrácí DIRECT odpovědi — proto výchozí 4 pokusy.
  • BLE PIN se nedá přečíst zpátky: firmware řekne jen own/build default. Modul proto pin pošle jen uzlu s výchozím PINem; změnu vynutí pin_force. Každé ble pin smaže na uzlu všechna spárování, takže pin_force patří do jednoho běhu, ne do playbooku, který jezdí pravidelně.
  • Výpadek napájení během ~30 s přepisu po fw apply nechá uzel v bootloaderu: polovičatý obraz se nespustí, ale oprava je DFU na místě. Na solárním uzlu proto aktualizujte přes den s nabitým článkem; pod hranicí baterie (fw status ji ukazuje, min 3800) uzel apply sám odmítne.
  • BLE spojení se napoprvé často nenaváže (timeout u uzlu, který o vteřinu později odpoví); modul to zkouší pětkrát. Když BLE konzole mlčí úplně, bývá to zaseklý BlueZ na hostu (systemctl restart bluetooth), ne mrtvý uzel.

Vývoj

Importy kolekce i ansible-test chtějí cestu ansible_collections/tth/meshcore (skutečný adresář, ne symlink), takže klonujte rovnou tam:

git clone https://git.rfa.cz/tth-pub/meshcore-ansible.git ~/src/ansible_collections/tth/meshcore
cd ~/src/ansible_collections/tth/meshcore
PYTHONPATH=~/src python -m pytest tests/unit
ruff check . && ruff format --check . && yamllint .
ansible-test sanity --python 3.14 --local   # verze = váš Python 3.12–3.14

Licence

GPL-3.0-or-later (jako Ansible moduly obecně).

S
Description
Ansible collection tth.meshcore: MeshCore repeaters as code, over RF through a companion
Readme GPL-3.0
201 KiB
0 Stars 1 Watchers 0 Forks
Languages
Python 100%