Files
meshcore-ansible/plugins/modules/meshcore_prefs.py
T
tthandClaude Opus 5.5 0a4cfafc78
ci / test (push) Successful in 2m39s
tth.meshcore: MeshCore repeaters as code, over RF
Ansible collection that converges MeshCore repeaters through a companion
radio (TCP, USB serial or BLE): admin ACL, CLI prefs, region tree,
firmware facts, companion remote-CLI ACL, and the meshcore-tth extras
(BLE on/off and own BLE PIN, channel-hash filter, message age, advert
fairness). Every change is read, diffed, sent and read back; --check
only reads. ansible-test sanity, unit tests and a galaxy build in CI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 02:23:24 +01:00

106 lines
4.1 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, `get <key>`; when it differs from the wanted value,
`set <key> <value>` and `get` again to prove it took. Numbers compare
numerically, on/off/true/false/1/0 as booleans.
- Refuses keys that can cut the node off or are local-console only
(freq, radio, bw/sf/cr, prv.key, password, guest.password).
- Units are the firmware's, `advert.interval` is MINUTES, `flood.advert.interval`
HOURS (3-168). A value out of range is rejected by the node and the module
fails -- it never leaves a silent `OK` behind.
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
"""
from ansible.module_utils.basic import AnsibleModule, missing_required_lib
from ansible_collections.tth.meshcore.plugins.module_utils.meshcore_link import HAS_MESHCORE, Link, LinkError, run
from ansible_collections.tth.meshcore.plugins.module_utils.meshcore_plan import DANGEROUS_PREFS, same_value
def as_cli(value):
if isinstance(value, bool):
return "on" if value else "off"
return str(value)
async def work(module, link):
prefs = module.params["prefs"]
await link.open()
try:
await link.login()
before, changes = {}, {}
for key, want in prefs.items():
before[key] = await link.get(key)
if not same_value(before[key], as_cli(want)):
changes[key] = as_cli(want)
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, value in changes.items():
reply = await link.cli(f"set {key} {value}", r"^(OK|Err|\?)")
if not reply.startswith("OK"):
raise LinkError(f"`set {key} {value}`: {reply}")
now = await link.get(key)
if not same_value(now, value):
raise LinkError(f"`set {key} {value}` answered OK but `get` 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"))
bad = sorted(set(module.params["prefs"]) & DANGEROUS_PREFS)
if bad:
module.fail_json(msg=f"refusing prefs that can cut the node off (change them on site): {bad}")
link = Link(module.params["transport"], module.params["target"], module.params["password"])
try:
result = run(work(module, link))
except LinkError as e:
module.fail_json(msg=str(e), log=link.log)
module.exit_json(log=link.log, **result)
if __name__ == "__main__":
main()