# Copyright: (c) 2026, TeTeHacko # 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()