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
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:
1 parent
891be3afbe
commit
4dfe998409
3 files changed
+160
-21
No files matched your search
@@ -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
|
||||
|
||||
|
||||
@@ -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
@@ -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: {}
|
||||
|
||||
Reference in new issue
Block a user