Files
meshcore-ansible/README.md
T
tthandClaude Opus 5.5 0a4cfafc78
ci / test (push) Successful in 2m39s
tth.meshcore: MeshCore repeaters as code, over RF
Ansible collection that converges MeshCore repeaters through a companion
radio (TCP, USB serial or BLE): admin ACL, CLI prefs, region tree,
firmware facts, companion remote-CLI ACL, and the meshcore-tth extras
(BLE on/off and own BLE PIN, channel-hash filter, message age, advert
fairness). Every change is read, diffed, sent and read back; --check
only reads. ansible-test sanity, unit tests and a galaxy build in CI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 02:23:24 +01:00

5.6 KiB
Raw Blame History

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ě).