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>
5.6 KiB
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.
--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. 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,flood.advert.intervalv 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 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ý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ě).