diff --git a/README.md b/README.md index 53a11fe..c9960b8 100644 --- a/README.md +++ b/README.md @@ -4,22 +4,26 @@ Ansible kolekce, která drží stav MeshCore repeaterů **deklarativně a na dá přes rádio**: kdo je admin (ACL), nastavení (`get`/`set`) a strom regionů — to umí každý MeshCore repeater. S firmwarem [meshcore-tth](https://git.rfa.cz/tth-pub/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). +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 kolekce **neflashuje** — jen přečte, jaká verze na uzlu běží. Jak -nahrát meshcore-tth: [návod k flashování](https://git.rfa.cz/tth-pub/meshcore-tth#flashing-a-release) +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í](https://git.rfa.cz/tth-pub/meshcore-tth#flashing-a-release) (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= --check # který balíček by šel ``` *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 +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 @@ -30,7 +34,8 @@ ansible-galaxy collection install git+https://git.rfa.cz/tth-pub/meshcore-ansibl Na hostu, kde moduly běží (ten s companionem), potřebuje Python knihovnu [`meshcore`](https://pypi.org/project/meshcore/) (a `bleak` jen pro -`meshcore_companion_acl`), viz `requirements.txt`. Na Archu `python-meshcore` +`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 @@ -46,19 +51,42 @@ z AUR, jinde venv a `ansible_python_interpreter` na něj. | `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 firmwaru z balíčků releasu (`.mcfw`): vybere deltu podle `fw status`, přes RF v limitu airtime (`duty`), přes BLE konzoli uzlu bez vysílání; `no_package` = žádná delta nesedí | meshcore-tth, obraz `-ota` | +| `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. -`meshcore_fw_ota` čte balíčky na hostu, kde běží (`packages`: soubor nebo -adresář s balíčky jednoho releasu). Stažení a ověření releasu (podepsaný -`SHA256SUMS`) je na volajícím, uzel ale každý balíček kontroluje sám (podpis -Ed25519, cíl, základní obraz, nesmí být starší) a cizí odmítne po prvních -kouscích. Přes RF jdou jen delty; dlouhý přenos pouštějte s `async`. Výpadek -napájení během ~30 s přepisu po `apply` nechá uzel v bootloaderu (polovičatý -obraz se nespustí, oprava je DFU na místě), pod hranicí baterie uzel `apply` -odmítne. +### 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: + +1. přečte `fw status` — velikost a otisk obrazu, na kterém uzel běží; +2. 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; +3. přenese ho, zkontroluje (`fw verify`) a nahraje (`fw apply`, s `apply: + false` jen 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 s `async`. Přerušený přenos dokončí `resume: true` — uzel drží, + co dostal, do příštího `fw begin` nebo restartu; +- **přes BLE konzoli uzlu** (`transport: {type: ble_console, address: }`): + 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 @@ -82,8 +110,9 @@ odmítne. ## Příklad -`examples/inventory.yml` a `examples/repeaters.yml`. Admin heslo patří do -ansible-vault (`vault_meshcore_admin_password`). +`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 @@ -102,6 +131,13 @@ ansible-vault (`vault_meshcore_admin_password`). 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ýpadek napájení během ~30 s přepisu po `fw apply`** nechá 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 status` ji ukazuje, `min 3800`) uzel `apply` sá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 diff --git a/examples/firmware-ota.yml b/examples/firmware-ota.yml new file mode 100644 index 0000000..3744384 --- /dev/null +++ b/examples/firmware-ota.yml @@ -0,0 +1,103 @@ +# OTA firmware update from a public release of meshcore-tth -- the repeaters +# must already run an -ota image of the same artifact (the first one goes by +# a regular flash, see the meshcore-tth README). +# +# ansible-playbook -i inventory.yml firmware-ota.yml -e ota_release=v1.18.0+tth.20261114.3 --check +# ansible-playbook -i inventory.yml firmware-ota.yml -e ota_release=v1.18.0+tth.20261114.3 +# +# Play 1 downloads the release's packages for the artifact on the controller and +# refuses them unless SHA256SUMS carries the release signature and every file +# matches it. Keep ota_allowed_signers (tools/ota_allowed_signers of +# meshcore-tth) next to this playbook: a key fetched from the same server as +# the release would prove nothing. Play 2 copies them next to the companion and +# lets the module pick the delta that fits each repeater's image. +- name: Release packages + hosts: localhost + gather_facts: false + vars: + ota_artifact: SenseCap_Solar_repeater-observer-ota + ota_api: https://git.rfa.cz/api/v1/repos/tth-pub/meshcore-tth + ota_dir: "{{ playbook_dir }}/ota/{{ ota_release }}" + ota_signers: "{{ playbook_dir }}/ota_allowed_signers" + tasks: + - name: Release {{ ota_release }} + ansible.builtin.uri: + url: "{{ ota_api }}/releases/tags/{{ ota_release | urlencode }}" + register: ota_rel + check_mode: false + + - name: Download directory + ansible.builtin.file: + path: "{{ ota_dir }}/mcfw" + state: directory + mode: "0755" + check_mode: false + + - name: Manifest and the signed checksums + ansible.builtin.get_url: + url: "{{ (ota_rel.json.assets | selectattr('name', 'eq', item) | first).browser_download_url }}" + dest: "{{ ota_dir }}/{{ item }}" + mode: "0644" + loop: [manifest.json, SHA256SUMS, SHA256SUMS.sig] + check_mode: false + + - name: Signature of SHA256SUMS + ansible.builtin.shell: >- + ssh-keygen -Y verify -f {{ ota_signers | quote }} -I meshcore-ota@tth-pub -n meshcore-ota + -s {{ (ota_dir ~ '/SHA256SUMS.sig') | quote }} < {{ (ota_dir ~ '/SHA256SUMS') | quote }} + changed_when: false + check_mode: false + + - name: Packages of {{ ota_artifact }} + ansible.builtin.set_fact: + ota_names: "{{ [_ota.full] + (_ota.deltas | dict2items | map(attribute='value.file') | list) }}" + ota_sums: "{{ dict(lookup('file', ota_dir ~ '/SHA256SUMS').splitlines() | map('split') | map('reverse')) }}" + vars: + _ota: "{{ (lookup('file', ota_dir ~ '/manifest.json') | from_json).envs[ota_artifact].ota }}" + + # only the artifact's .mcfw files, so the module sees nothing else there + - name: Download them, each checked against SHA256SUMS + ansible.builtin.get_url: + url: "{{ (ota_rel.json.assets | selectattr('name', 'eq', item) | first).browser_download_url }}" + dest: "{{ ota_dir }}/mcfw/{{ item }}" + checksum: "sha256:{{ ota_sums[item] }}" + mode: "0644" + loop: "{{ ota_names }}" + check_mode: false + +- name: OTA update + hosts: meshcore_repeaters + gather_facts: false + serial: 1 # RF: one repeater at a time + vars: + meshcore_admin_password: "{{ vault_meshcore_admin_password }}" + ota_dir: "{{ playbook_dir }}/ota/{{ ota_release }}/mcfw/" + tasks: + - name: Packages next to the companion + ansible.builtin.copy: + src: "{{ ota_dir }}" + dest: /tmp/meshcore-ota/ + mode: "0644" + delegate_to: "{{ mc_via }}" + check_mode: false + + # --check: reads `fw status` and says which package would go. A delta of + # ~25 kB over two hops takes ~40 min at duty 3; the node keeps what it got, + # so a stopped transfer goes on with resume: true. + - name: Update + tth.meshcore.meshcore_fw_ota: + transport: "{{ mc_transport }}" + target: "{{ mc_target }}" + password: "{{ meshcore_admin_password }}" + packages: /tmp/meshcore-ota/ + duty: 3 + delegate_to: "{{ mc_via }}" + async: 7200 + poll: 30 + register: ota + + - name: Result + ansible.builtin.debug: + msg: >- + {{ inventory_hostname }}: {{ ota.state }} {{ ota.package | default('') }} + {{ '-- no delta from ' ~ ota.base ~ ', flash the full image' if ota.no_package else '' }} diff --git a/galaxy.yml b/galaxy.yml index 89f9632..9196ee2 100644 --- a/galaxy.yml +++ b/galaxy.yml @@ -4,8 +4,8 @@ version: 0.1.0 readme: README.md authors: [TeTeHacko] description: >- - Declarative admin of MeshCore repeaters (ACL, prefs, regions; BLE and filters - on meshcore-tth) over RF through a companion radio. + Declarative admin of MeshCore repeaters (ACL, prefs, regions; BLE, filters and + OTA firmware updates on meshcore-tth) over RF through a companion radio. license: [GPL-3.0-or-later] tags: [meshcore, lora, mesh, radio] dependencies: {}