Files
tth 8306d91b48
ci / test (push) Failing after 1m29s
meshcore_prefs: a spec per known key -- range and step checked before sending, the value read out of replies that are not bare; gps and powersaving
The prefs were a free dict compared as text with the `get` reply, so lint and
sanity could not see that several keys never converge:
- `get radio.silence` -> '30 min (now x1), quiet ...', `get batt.icon` ->
  'on (level 3/5, ...)', `get dutycycle` -> '50.0%': a change on every run,
  then a failure after the `set`;
- `advert.interval` is stored halved (25 reads back as 24, and the node takes
  only 0 or 60-240), `agc.reset.interval` in steps of 4;
- `set repeat <anything but off>` means ON, so `repeat: 0` turned it on;
- lat/lon compared to 1e-3 (~100 m), so a smaller move never went out;
- errors like 'ERR - ...', 'unknown config: ...', 'Invalid ...' did not match
  the expected reply and ended as a timeout after five resends.

module_utils/meshcore_prefspec.py now holds kind, range, step, tolerance and a
reply parser for every pref of the meshcore-tth CLI (CommonCLI.cpp,
CommonRadioPrefs.cpp, NodeMaintenance.cpp, CommonGpsPrefs.cpp); the module
refuses a value the node would refuse or alter before it sends anything, in
check mode too. Unknown keys still go, compared as before, with a warning.
radio.txstall (RAM only) and radio.rxps (compound) are refused with a reason.

New keys that are plain commands in the firmware: gps (off/on/duty),
gps.period, gps.firstfix and powersaving; gps.period goes first and conflicts
with gps off/duty.

Tests: replies as the firmware prints them and as a bench board and three
repeaters answered; with MESHCORE_TTH_SRC set, a drift check that every key is
still in the CLI sources.
2026-11-15 14:03:11 +01:00

137 lines
5.7 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_prefs
short_description: CLI prefs (`get`/`set`) of a MeshCore repeater, over RF
author: TeTeHacko (@TeTeHacko)
description:
- For every key, read the value; when it differs from the wanted value, set it
and read it again to prove it took.
- Known keys (module_utils/meshcore_prefspec.py, from the meshcore-tth CLI) are
checked BEFORE anything is sent -- kind, range, step -- so a value the node
would refuse or keep altered (C(advert.interval) is stored halved, C(agc.reset.interval)
in steps of 4) fails the task instead of leaving a change behind on every run.
The value is read out of the reply, which is not always bare
('30 min (now x1), quiet ...', 'on (level 3/5, ...)', '50.0%').
- "Besides the get/set prefs: C(gps) (off/on/duty), C(gps.period), C(gps.firstfix)
(seconds) and C(powersaving) (on/off), which the firmware has as plain commands."
- A key not known there is sent anyway and compared as text, numbers numerically,
on/off/true/false/1/0 as booleans -- with a warning.
- Refuses keys that can cut the node off, are local-console only, secret, or
not persistent (freq, radio, bw/sf/cr, prv.key, password, guest.password,
radio.txstall, radio.rxps).
- Units are the firmware's, C(advert.interval) is MINUTES (0 or 60-240, even),
C(flood.advert.interval) HOURS (0 or 3-168), C(radio.silence) minutes (0 = off).
options:
transport: {description: Companion to talk through (see meshcore_acl)., type: dict, required: true}
target: {description: Full 64-hex pubkey of the repeater., type: str, required: true}
password: {description: Admin password (empty = blank login)., type: str, default: ""}
prefs:
description: "Map of pref key -> wanted value, e.g. C({repeat: on, advert.interval: 120})."
type: dict
required: true
"""
EXAMPLES = r"""
- name: Two-byte path hash, no zero-hop adverts, flood advert every 47 h
tth.meshcore.meshcore_prefs:
transport: {type: tcp, host: 127.0.0.1, port: 5000}
target: "{{ mc_target }}"
password: "{{ vault_meshcore_admin_password }}"
prefs:
path.hash.mode: 1
advert.interval: 0
flood.advert.interval: 47
- name: GPS only around clock syncs, MCU sleep, reboot a receiver deaf for 30 min
tth.meshcore.meshcore_prefs:
transport: {type: tcp, host: 127.0.0.1, port: 5000}
target: "{{ mc_target }}"
password: "{{ vault_meshcore_admin_password }}"
prefs:
gps: duty
powersaving: true
radio.silence: 30
"""
from ansible.module_utils.basic import AnsibleModule, missing_required_lib
from ansible_collections.tth.meshcore.plugins.module_utils import meshcore_prefspec as spec
from ansible_collections.tth.meshcore.plugins.module_utils.meshcore_link import HAS_MESHCORE, Link, LinkError, run
async def read(link, key):
"""The value as meshcore_prefspec.reading spells it; LinkError when the node cannot say."""
reply = await link.cli(spec.get_cmd(key), spec.GET_REPLY)
if spec.is_error(reply):
raise LinkError(f"`{spec.get_cmd(key)}`: {reply} -- does this firmware have it?")
value = spec.reading(key, reply)
if value is None:
raise LinkError(f"`{spec.get_cmd(key)}`: cannot read a {spec.spec(key)['kind']} out of {reply!r}")
return value
async def work(module, link, want):
await link.open()
try:
await link.login()
before, changes = {}, {}
for key in spec.order(want):
before[key] = await read(link, key)
if not spec.same(key, before[key], want[key]):
changes[key] = want[key]
result = {
"changed": bool(changes),
"set": changes,
"diff": {
"before": "".join(f"{k}: {before[k]}\n" for k in sorted(changes)),
"after": "".join(f"{k}: {changes[k]}\n" for k in sorted(changes)),
},
}
if module.check_mode or not changes:
return result
for key in spec.order(changes):
value = changes[key]
cmd = spec.set_cmd(key, value)
reply = await link.cli(cmd, spec.SET_REPLY)
if not spec.set_ok(key, value, reply):
raise LinkError(f"`{cmd}`: {reply}")
now = await read(link, key)
if not spec.same(key, now, value):
raise LinkError(f"`{cmd}` answered {reply!r} but it reads {now!r}")
return result
finally:
await link.close()
def main():
module = AnsibleModule(
argument_spec={
"transport": {"type": "dict", "required": True},
"target": {"type": "str", "required": True},
"password": {"type": "str", "default": "", "no_log": True},
"prefs": {"type": "dict", "required": True},
},
supports_check_mode=True,
)
if not HAS_MESHCORE:
module.fail_json(msg=missing_required_lib("meshcore"))
# checked before anything is sent, in check mode too
try:
want = {k: spec.wanted(k, v) for k, v in module.params["prefs"].items()}
spec.check_combination(want)
except spec.PrefError as e:
module.fail_json(msg=str(e))
unknown = sorted(k for k in want if spec.spec(k) is None)
if unknown:
module.warn(f"prefs not known to this collection, compared as text: {unknown}")
link = Link(module.params["transport"], module.params["target"], module.params["password"])
try:
result = run(work(module, link, want))
except LinkError as e:
module.fail_json(msg=str(e), log=link.log)
module.exit_json(log=link.log, **result)
if __name__ == "__main__":
main()