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 a antispamové filtry. Ke stožáru nikdo nemusí: moduly mluví s repeaterem přes companion, který ho slyší (openHop TCP companion, nebo companion na USB).

Firmware kolekce neflashuje — jen přečte, jaká verze na uzlu běží. Jak nahrát meshcore-tth: 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

English: an Ansible collection that converges MeshCore repeaters (admin ACL, CLI prefs, region tree; BLE and filters 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), 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

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

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. 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ý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%