Files
meshcore-ansible/plugins/module_utils/meshcore_link.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

257 lines
12 KiB
Python

"""RF admin link to a MeshCore repeater (or companion) through a companion radio.
Shared by the tth.meshcore modules. The companion is either a TCP companion
(e.g. an openHop companion), a USB serial companion, or a BLE companion
bonded on the host the module runs on. Everything below was
learned the hard way:
* subscribe to replies BEFORE sending anything -- wait_for_event only sees
events created after it is called, so a reply delivered meanwhile is lost;
* set the companion's path hash width to 2 B (its own pref, default 1 B);
* a repeater that never advertised can still be addressed: build the contact
from its full pubkey (the login secret is derived from the contact);
* use send_login_sync -- plain send_login + wait times out on a flood login;
* never echo the password: the node's `password` reply contains it.
A COMPANION target (companion=True), fw 1.18+ / Solo 2.0+: its ACL is the
"remote CLI" flag (ContactInfo flags 0x10) on its contacts, set on the companion
itself -- the same mc_admins keys as on the repeaters, nobody else. A command
comes as TXT_TYPE_CLI_COMMAND (3), encrypted to that contact's shared secret,
so only a flagged key gets an answer; there is no password step on top. Type 1
that send_cmd uses is a CLI *reply* there and only lands in its app.
Plus what the RF itself does: replies get lost and occasionally arrive late,
so every CLI exchange checks that the reply came from the target and looks
like the expected kind of answer, and retries otherwise.
"""
import asyncio
import re
import time
try:
from meshcore import EventType, MeshCore
HAS_MESHCORE = True
except ImportError: # reported by the module via missing_required_lib
HAS_MESHCORE = False
HEX64 = re.compile(r"^[0-9a-f]{64}$")
class LinkError(Exception):
pass
class Link:
def __init__(
self,
transport,
target,
password="",
path_hash_mode=1,
reply_timeout=None,
retries=None,
companion=False,
name=None,
):
self.transport = transport
self.companion = companion
self.last_reply_ts = None # node clock (sender_timestamp) of the last matched reply
self.last_reply_at = None
self.contact_name = (name or "target")[:31]
self.target_pk = target.lower()
if not HEX64.match(self.target_pk):
raise LinkError("target must be the node's full 64-hex pubkey")
self.password = password or ""
self.path_hash_mode = path_hash_mode
# A repeater with a BLE client connected lost three CLI replies in a row
# (a BLE link mutes DIRECT traffic, and CLI replies are DIRECT), so the
# default is generous; both can be set per host in mc_transport.
self.reply_timeout = float(reply_timeout or transport.get("reply_timeout", 20))
self.retries = int(retries if retries is not None else transport.get("retries", 4))
self.mc = None
self.contact = None
self.inbox = []
self.log = [] # human-readable trace, returned by the modules (no secrets)
# ── session ─────────────────────────────────────────────────────────────
async def open(self):
t = self.transport
if t.get("type") == "serial":
self.mc = await MeshCore.create_serial(t["port"], int(t.get("baud", 115200)))
elif t.get("type") == "ble":
# No PIN here on purpose: it would end up in the task's logged
# arguments. The companion is bonded once by hand (bluetoothctl pair)
# on the host the module runs on, and the bond does the encryption.
self.mc = await MeshCore.create_ble(t["address"])
else:
self.mc = await MeshCore.create_tcp(
host=t.get("host", "127.0.0.1"), port=int(t["port"]), auto_reconnect=False
)
if self.mc is None:
raise LinkError(f"cannot connect to companion {t}")
# Bench guard: an inventory that says which frequency its companion must
# be on never transmits anywhere else (a bench run must not reach the
# live mesh because a cable went to the wrong board).
if t.get("expect_freq") is not None:
freq = float((self.mc.self_info or {}).get("radio_freq") or 0)
if abs(freq - float(t["expect_freq"])) > 0.01:
await self.mc.disconnect()
raise LinkError(f"companion is on {freq} MHz, inventory expects {t['expect_freq']} -- nothing sent")
self.mc.subscribe(EventType.CONTACT_MSG_RECV, lambda ev: self.inbox.append(ev.payload))
if (await self.mc.commands.get_path_hash_mode()) != self.path_hash_mode:
await self.mc.commands.set_path_hash_mode(self.path_hash_mode)
await self.mc.ensure_contacts()
self.contact = self._find_contact()
if self.contact is None:
await self._add_contact()
await self.mc.start_auto_message_fetching()
async def close(self):
if self.mc is not None:
await self.mc.disconnect()
def self_pubkey(self):
return (self.mc.self_info or {}).get("public_key", "").lower()
def _find_contact(self):
for c in (self.mc.contacts or {}).values():
if (c.get("public_key") or "").lower() == self.target_pk:
return c
return None
async def _add_contact(self):
contact = {
"public_key": self.target_pk,
"type": 1 if self.companion else 2,
"flags": 0,
"out_path": "",
"out_path_len": -1,
# last_advert = now: with 0 it is the "oldest" contact and the next
# eviction (table full) would pick exactly the one just created.
"out_path_hash_mode": 0,
"adv_name": self.contact_name,
"last_advert": int(time.time()),
"adv_lat": 0.0,
"adv_lon": 0.0,
}
ev = await self.mc.commands.add_contact(contact)
if ev is not None and ev.type == EventType.ERROR:
# Table full (a busy companion with auto-add sits at 1000/1000):
# make room the way the firmware's own auto-add does -- drop the
# contact heard longest ago that is not a favourite.
cands = [
c
for c in (self.mc.contacts or {}).values()
if not (c.get("flags") or 0) & 1 and (c.get("public_key") or "").lower() != self.target_pk
]
if not cands:
raise LinkError(f"companion refused the contact ({ev.payload}) and nothing can be evicted")
victim = min(cands, key=lambda c: c.get("last_advert") or 0)
await self.mc.commands.remove_contact(victim["public_key"])
self.log.append(f"contact table full: evicted {victim.get('adv_name') or victim['public_key'][:12]}")
await self.mc.commands.add_contact(contact)
await asyncio.sleep(2)
fresh = await self.mc.commands.get_contacts()
for c in ((fresh.payload if fresh else None) or {}).values():
if (c.get("public_key") or "").lower() == self.target_pk:
self.contact = c
self.log.append("contact created from pubkey")
return
raise LinkError("could not create a contact for the target")
async def login(self):
"""Admin login; blank password works for a client already in the ACL."""
for attempt in range(1 + self.retries):
# a stale path from an earlier session would send the login nowhere
await self.mc.commands.reset_path(self.contact)
ev = await self.mc.commands.send_login_sync(self.contact, self.password, timeout=45)
if ev is not None and ev.type == EventType.LOGIN_SUCCESS:
# LOGIN_SUCCESS alone is not enough: a password that equals the
# node's GUEST password (or a blank one when guest is blank) logs
# in as guest, and the admin requests then just go unanswered.
if not (ev.payload or {}).get("is_admin"):
raise LinkError(
"logged in as GUEST, not admin -- the node's admin password differs "
"(prefs override the build) or this companion is not admin in its ACL"
)
self.log.append(f"login ok as admin (attempt {attempt + 1})")
return True
raise LinkError("login refused or no reply (wrong password, or not in the ACL)")
# ── CLI ─────────────────────────────────────────────────────────────────
def _from_target(self, msg):
pfx = (msg.get("pubkey_prefix") or "").lower()
return bool(pfx) and self.target_pk.startswith(pfx)
async def cli(self, cmd, expect):
"""Send one CLI command and return the reply text that matches `expect` (regex).
A reply that does not match (a late answer to an earlier command, or
another node) is drained and the command is resent, up to `retries`.
"""
# never log a secret the command carries (the trace is returned to Ansible)
shown = cmd
for secret_cmd in ("password ", "ble pin "):
if cmd.startswith(secret_cmd):
shown = secret_cmd + "***"
for attempt in range(1 + self.retries):
self.inbox.clear()
if self.companion:
await self.send_cli_command(cmd)
else:
await self.mc.commands.send_cmd(self.contact, cmd)
deadline = time.monotonic() + self.reply_timeout
while time.monotonic() < deadline:
for msg in list(self.inbox):
text = (msg.get("text") or "").strip()
if self._from_target(msg) and re.search(expect, text):
self.log.append(f"$ {shown} -> {self._redact(text)}")
# The reply carries the NODE's clock: what fw_facts reports as skew.
self.last_reply_ts = msg.get("sender_timestamp")
self.last_reply_at = time.time()
await asyncio.sleep(0.5) # let a straggler land before the next command
return text
await asyncio.sleep(0.3)
seen = [self._redact((m.get("text") or "").strip()) for m in self.inbox]
self.log.append(f"$ {shown} -> no matching reply (attempt {attempt + 1}, got {seen})")
raise LinkError(f"no reply matching /{expect}/ to `{shown}`")
async def send_cli_command(self, cmd):
"""CMD_SEND_TXT_MSG with txt_type 3 -- what a companion's remote CLI answers."""
data = (
b"\x02\x03\x00" + int(time.time()).to_bytes(4, "little") + bytes.fromhex(self.target_pk[:12]) + cmd.encode()
)
ev = await self.mc.commands.send(data, [EventType.MSG_SENT, EventType.ERROR])
if ev is not None and ev.type == EventType.ERROR:
raise LinkError(f"companion refused to send `{cmd}`: {ev.payload}")
def name(self):
return (self.contact or {}).get("adv_name") or ""
def _redact(self, text):
return text.replace(self.password, "***") if self.password else text
async def get(self, key):
"""`get <key>` -> the value string (reply is '> value')."""
text = await self.cli(f"get {key}", r"^(>|Err|\?)")
if not text.startswith(">"):
raise LinkError(f"`get {key}`: {text}")
return text[1:].strip()
async def acl(self):
"""Real ACL as {prefix12: perm}, via the binary access-list request."""
for attempt in range(1 + self.retries):
res = await self.mc.commands.req_acl_sync(self.contact, timeout=40)
if res is not None:
return {e["key"].lower(): e["perm"] for e in res}
self.log.append(f"ACL request: no reply (attempt {attempt + 1})")
raise LinkError("ACL request: no reply")
def run(coro):
return asyncio.run(coro)