The prefs were a free dict compared as text with the `get` reply, so lint and sanity could not see that several keys never converge: - `get radio.silence` -> '30 min (now x1), quiet ...', `get batt.icon` -> 'on (level 3/5, ...)', `get dutycycle` -> '50.0%': a change on every run, then a failure after the `set`; - `advert.interval` is stored halved (25 reads back as 24, and the node takes only 0 or 60-240), `agc.reset.interval` in steps of 4; - `set repeat <anything but off>` means ON, so `repeat: 0` turned it on; - lat/lon compared to 1e-3 (~100 m), so a smaller move never went out; - errors like 'ERR - ...', 'unknown config: ...', 'Invalid ...' did not match the expected reply and ended as a timeout after five resends. module_utils/meshcore_prefspec.py now holds kind, range, step, tolerance and a reply parser for every pref of the meshcore-tth CLI (CommonCLI.cpp, CommonRadioPrefs.cpp, NodeMaintenance.cpp, CommonGpsPrefs.cpp); the module refuses a value the node would refuse or alter before it sends anything, in check mode too. Unknown keys still go, compared as before, with a warning. radio.txstall (RAM only) and radio.rxps (compound) are refused with a reason. New keys that are plain commands in the firmware: gps (off/on/duty), gps.period, gps.firstfix and powersaving; gps.period goes first and conflicts with gps off/duty. Tests: replies as the firmware prints them and as a bench board and three repeaters answered; with MESHCORE_TTH_SRC set, a drift check that every key is still in the CLI sources.
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.
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ě).