Files
tthandClaude Opus 5.5 185470de08
ci / test (push) Failing after 15s
meshcore_fw_ota: the transfer as an Ansible-free engine shared with meshcore-tth's tools, plus a side channel via tempradio
module_utils/meshcore_ota_engine.py now holds the whole transfer (Console,
Radio, binary and text rounds, update()); the module only maps its
parameters. tools/ota_mesh_push.py and tools/ota_push.py of meshcore-tth
import the same code, so the protocol lives in one place.

New:
- side/window: the node goes to another preset by `tempradio`, the
  companion is retuned (checked -- an openHop virtual companion acks
  set_radio as a no-op and is refused), a fresh login goes zero-hop and
  the delta follows; the window is renewed, and the node and companion
  come back at the end (or the node by its own timer).
- SerialConsole: the node's USB console, the same calls as BleConsole.
- `fw base` when `fw status` shows no base (failed/ready/rx): a node left
  after a refused package was taken for "not an -ota build", i.e. a full
  DFU, and `resume` could never pick its package.
- asyncio.TimeoutError caught too: on Python 3.10 (dopey) a lost bitmap
  reply ended the whole transfer.
- text: text chunks only; update(force=...) for `fw apply force`.

Bench 16. 11. 2026 (x3 companion -> x1 -ota repeater, 866.5 -> side 866.0/SF7):
the module from dopey (py3.10), the firmware role's ota.yml with
mc_fw_ota_side, ota_mesh_push.py and ota_push.py over USB -- each applied
a 2.7 kB delta, ~20 s airtime.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 23:17:41 +01:00

230 lines
9.2 KiB
Python

# Copyright: (c) 2026, TeTeHacko <tth@rfa.cz>
# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)
DOCUMENTATION = r"""
module: meshcore_fw_ota
short_description: OTA firmware update of a meshcore-tth repeater, over RF or its BLE console
author: TeTeHacko (@TeTeHacko)
description:
- Updates a repeater that runs an C(-ota) image of meshcore-tth (the C(fw)
commands of src/helpers/FwUpdate) from the packages of a release (C(.mcfw),
tools/ota_pack.py), and applies it. The node checks each package itself
(Ed25519 signature, target, base image, not older) and refuses a wrong one
after its first chunks.
- Reads C(fw status) and picks the package that fits the image the node runs.
C(changed=false) when the node already runs the image, C(no_package=true)
(not a failure) when no package starts from its image or the node has no
C(fw) at all -- then the caller falls back to a full DFU.
- Over RF (a companion transport, as the other modules) only deltas go, the
node refuses a full image there. Chunks are binary requests (128 B, no
reply, missing ones found by a bitmap query), with text chunks as the
fallback, paced by an airtime budget (C(duty)). A 28 kB delta over two hops
took 40 min at 3 %.
- Over the node's BLE console (C(transport.type=ble_console)) nothing goes on
air and a full image may go too. Prefer it wherever a host with a bond
hears the node.
- A power cut during the ~30 s rewrite after C(apply) leaves the node in its
bootloader (no half image runs; recovery = DFU on site). The node refuses
to apply below its battery gate.
- In check mode it reads C(fw status) and says which package would go.
options:
transport:
description:
- "Companion to talk through (see meshcore_acl), or the node's own BLE
console C({type: ble_console, address}), bonded on the host the module
runs on."
type: dict
required: true
target: {description: Full 64-hex pubkey of the node (not needed for ble_console)., type: str}
name: {description: Name for the contact if the companion has to create it., type: str}
password: {description: Admin password (empty = blank login; not used on ble_console)., type: str, default: ""}
packages:
description:
- A C(.mcfw) package, or a directory with the packages of one release
(the full image and its deltas), on the host the module runs on.
type: path
required: true
apply: {description: Apply after a good C(fw verify) (else the package stays staged)., type: bool, default: true}
duty:
description:
- RF only. Airtime budget in percent per hour (token bucket). Counts what
the transfer puts on the channel, request and reply times (hops + 1).
869.4-869.65 MHz allows 10 %, other sub-bands 1 %.
type: float
default: 3
gap: {description: RF only. Pause in seconds after every reply., type: float, default: 5}
resume:
description:
- Continue a transfer that stopped (the node keeps what it got until the
next C(fw begin) or a reboot) -- no C(fw begin), only what C(fw missing)
lists.
type: bool
default: false
apply_wait: {description: Seconds to wait after C(fw apply) before reading the new version., type: int, default: 60}
text: {description: RF only. Text chunks only (each answered) instead of binary requests., type: bool, default: false}
side:
description:
- "RF only. Carry the transfer on a side channel, off the shared mesh:
C(freq,bw,sf,cr), e.g. C(869.525,62.5,7,5). Login, C(fw status) and
C(get radio) go over the mesh, then the node gets C(tempradio) and the
companion is retuned to the same preset; the chunks go there zero-hop,
so the companion must be in direct range of the node."
- The companion must retune its own radio (a MeshCore companion firmware).
An openHop virtual companion acks the change and stays put -- checked,
and the task fails; the node returns within 3 minutes.
- The node comes back on C(fw apply) (the reboot), by C(tempradio) with its
own preset at the end, or by its own timer. The companion gets its
preset back at the end -- unless the task is killed (async timeout),
then set its radio back by hand.
type: str
window: {description: "Side channel window in minutes, renewed while the transfer runs.", type: int, default: 15}
requirements: [meshcore (RF), bleak (ble_console)]
"""
EXAMPLES = r"""
- name: Update over RF through the companion next to the mast
tth.meshcore.meshcore_fw_ota:
transport: {type: tcp, host: 127.0.0.1, port: 5000, expect_freq: 869.432}
target: "{{ mc_target }}"
password: "{{ vault_meshcore_admin_password }}"
packages: /tmp/ota/ # the .mcfw files of one release
duty: 3
async: 7200
poll: 30
register: ota
- name: The same over the node's BLE console (bonded on this host)
tth.meshcore.meshcore_fw_ota:
transport: {type: ble_console, address: "AA:BB:CC:DD:EE:FF"}
packages: /tmp/ota/
- name: Off the shared channel, through a MeshCore companion in direct range
tth.meshcore.meshcore_fw_ota:
transport: {type: serial, port: /dev/serial/by-id/usb-Seeed_Studio_XIAO_nRF52840_0123-if00, expect_freq: 869.432}
target: "{{ mc_target }}"
password: "{{ vault_meshcore_admin_password }}"
packages: /tmp/ota/
side: 869.525,62.5,7,5
duty: 10
gap: 1
- name: No package fits the node's image -- full DFU instead
ansible.builtin.debug:
msg: "{{ ota.base }}: no delta"
when: ota.no_package
"""
RETURN = r"""
state:
description: current | no_package | would_update | staged | applied
returned: always
type: str
package:
description: Name of the package that went (or would go).
returned: when one fits
type: str
kind:
description: delta | full
returned: when one fits
type: str
base:
description: Size and sha256 prefix of the image the node ran.
returned: when the node has fw
type: str
no_package:
description: No package starts from the node's image, or the node has no fw.
returned: always
type: bool
version:
description: Version the package installs.
returned: when one fits
type: str
version_after:
description: The `ver` reply after the apply, when the node answered.
returned: when applied
type: str
airtime:
description: Channel airtime of the transfer in seconds (RF).
returned: over RF
type: float
log:
description: Trace of the exchange (no secrets).
returned: always
type: list
elements: str
"""
from ansible.module_utils.basic import AnsibleModule, missing_required_lib
from ansible_collections.tth.meshcore.plugins.module_utils.meshcore_console import HAS_BLEAK, ConsoleError
from ansible_collections.tth.meshcore.plugins.module_utils.meshcore_link import HAS_MESHCORE, LinkError, run
from ansible_collections.tth.meshcore.plugins.module_utils.meshcore_ota import parse_preset
from ansible_collections.tth.meshcore.plugins.module_utils.meshcore_ota_engine import (
Console,
OtaError,
Radio,
update,
)
def main():
module = AnsibleModule(
argument_spec={
"transport": {"type": "dict", "required": True},
"target": {"type": "str"},
"name": {"type": "str"},
"password": {"type": "str", "default": "", "no_log": True},
"packages": {"type": "path", "required": True},
"apply": {"type": "bool", "default": True},
"duty": {"type": "float", "default": 3},
"gap": {"type": "float", "default": 5},
"resume": {"type": "bool", "default": False},
"apply_wait": {"type": "int", "default": 60},
"text": {"type": "bool", "default": False},
"side": {"type": "str"},
"window": {"type": "int", "default": 15},
},
supports_check_mode=True,
)
p = module.params
console = p["transport"].get("type") == "ble_console"
if console and not HAS_BLEAK:
module.fail_json(msg=missing_required_lib("bleak"))
if not console and not HAS_MESHCORE:
module.fail_json(msg=missing_required_lib("meshcore"))
if not console and not p["target"]:
module.fail_json(msg="target (the node's pubkey) is required over RF")
if console and p["side"]:
module.fail_json(msg="side is RF only: the BLE console puts nothing on air")
io = None
try:
side = parse_preset(p["side"]) if p["side"] else None
if console:
io = Console(p["transport"]["address"])
else:
io = Radio(
p["transport"],
p["target"],
p["password"],
name=p["name"],
duty=p["duty"],
gap=p["gap"],
side=side,
window=p["window"],
)
result = run(
update(
io,
p["packages"],
apply=p["apply"],
resume=p["resume"],
check=module.check_mode,
apply_wait=p["apply_wait"],
text=p["text"],
)
)
except (LinkError, ConsoleError, OtaError, ValueError, OSError) as e:
module.fail_json(msg=str(e), log=io.log if io else [])
module.exit_json(log=io.log, **result)
if __name__ == "__main__":
main()