Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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íčů, typ, rozsah a krok známých klíčů ověří před odesláním; navíc gps (off/on/duty), gps.period, gps.firstfix, powersaving. freq, radio, hesla, klíč a ne-trvalé klíče odmítne |
MeshCore (gps duty, radio.silence: meshcore-tth) |
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:
- přečte
fw status— velikost a otisk obrazu, na kterém uzel běží; - 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; - přenese ho, zkontroluje (
fw verify) a nahraje (fw apply, sapply: falsejen 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 sasync. Přerušený přenos dokončíresume: true— uzel drží, co dostal, do příštíhofw beginnebo 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; - přes rádio, ale mimo sdílený kanál (
side: "869.525,62.5,7,5"): přihlášení afw statusjdou meshem, pak uzel dostanetempradiona vedlejší preset, companion se přeladí na stejný a delta jde tam, napřímo (zero-hop) — companion tedy musí být v přímém dosahu uzlu a musí to být companion firmware, který umí přeladit vlastní rádio. Virtuální companion openHopu změnu rádia jen potvrdí; modul to pozná a skončí chybou. Uzel se vrací sám: rebootem pofw apply, příkazem na konci, nebo vlastním časovačem, když se companion ztratí (okno 3 min, po ověření spojeníwindow, obnovuje se). Companion dostane zpátky svůj preset i cestu ke kontaktu; jen když úlohu zabijeasynctimeout, musí se přeladit ručně.
Celý přenos je v plugins/module_utils/meshcore_ota_engine.py a nepotřebuje
Ansible — stejný kód volají i nástroje tools/ota_mesh_push.py a
tools/ota_push.py v meshcore-tth. Protokol se mění jen tam.
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.
--checknic 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.intervalje v minutách (0 nebo 60–240, sudé — uzel ukládá polovinu, 25 by přečetl jako 24),flood.advert.intervalv hodinách (0 nebo 3–168).meshcore_prefstakovou hodnotu odmítne dřív, než cokoli pošle. - Odpověď na
getnení vždycky holá hodnota:radio.silence→30 min (now x1), quiet …,batt.icon→on (level 3/5, …),dutycycle→50.0%. Známé klíče (plugins/module_utils/meshcore_prefspec.py, ze zdrojáků CLI meshcore-tth) z ní hodnotu vyčtou; neznámý klíč modul porovná jako text a varuje.set repeat <cokoli kromě off>znamená na uzlu ON — modul proto bere jen on/off/true/false. lat/lonporovnává modul na ~1 m (na uzlu jsoufloat32). Dřív to bylo 0,001° (~100 m) a menší posun se nikdy nepropsal; zaokrouhlená hodnota v inventáři teď uzel jednou přesune na ni.- 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 savezmizí 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 protopinpošle jen uzlu s výchozím PINem; změnu vynutípin_force. Každéble pinsmaže na uzlu všechna spárování, takžepin_forcepatří do jednoho běhu, ne do playbooku, který jezdí pravidelně. - Výpadek napájení během ~30 s přepisu po
fw applynechá 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 statusji ukazuje,min 3800) uzelapplysá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ě).