README, examples/firmware-ota.yml: OTA updates -- how a package is picked, RF vs BLE console, what to watch
ci / test (push) Failing after 30s

The intro said the collection does not touch firmware; it now updates an
-ota node. The example downloads a release's packages, refuses them without
the release signature (ssh-keygen -Y verify) and runs meshcore_fw_ota.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
tthandClaude Opus 5.5 committed 2026-11-14 21:08:25 +01:00
1 parent 891be3afbe
commit 4dfe998409
3 files changed
+160 -21

No files matched your search

+55 -19
View File
@@ -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=<tag> --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: <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
@@ -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
+103
View File
@@ -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 '' }}
+2 -2
View File
@@ -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: {}