ci / test (push) Failing after 15s
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>
230 lines
9.2 KiB
Python
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()
|