ci / test (push) Failing after 1m29s
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.
137 lines
5.7 KiB
Python
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()
|