Files
meshcore-exporter/meshcore_exporter.py
tthandClaude Opus 5.5 e2d3c72ba2 1.1.0: default interval 8 h, minimum 1 h
A repeater's battery, temperature and noise do not change by the hour, and
every reading is airtime on a channel everyone shares. The dashboard window
follows: 24 h by default (2-3x the interval), staleness thresholds too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 11:41:54 +01:00

614 lines
25 KiB
Python

#!/usr/bin/env python3
"""Prometheus exporter for MeshCore repeaters, read over the mesh itself.
A companion radio (USB, TCP or BLE) logs in to each repeater in turn, asks for
its status and telemetry with direct packets (no flood) and serves the numbers
on http://<listen>:9200/metrics: battery, temperature, noise floor, RSSI/SNR,
packet counters, airtime, uptime, TX queue.
Every reading costs airtime on a shared channel (~0.8 s per repeater on the
Czech preset), so the interval defaults to 8 hours and cannot go below an hour.
How often do you really need the numbers? See
https://meshcore.repeater.cz/nastaveni/telemetrie/
Configuration: command line, or the same thing in MC_* environment variables
(the Docker way), or a TOML file with one block per repeater (--config).
Command line beats environment beats the file's defaults.
meshcore-exporter --serial /dev/serial/by-id/usb-... --repeaters my-rpt --password secret
meshcore-exporter --config repeaters.toml --check # one round, print, exit
Only one program may talk to a companion at a time: stop any app (phone, Meshy,
meshcli) that holds the same radio first.
"""
from __future__ import annotations
import argparse
import asyncio
import logging
import os
import sys
import time
from dataclasses import dataclass
from typing import Any
__version__ = "1.1.0"
MIN_INTERVAL = 3600
DEFAULT_INTERVAL = 28800
# A failed repeater is retried once after this, not after the full interval:
# a lost reply on air is common, and a repeater also drops a login whose
# timestamp is not newer than the last one from the same client (replay
# check). Seen right after `--check`: two refused logins, then fine.
RETRY_AFTER = 180
CONTACTS_TIMEOUT = 30
@dataclass
class Target:
name: str # the repeater's advertised name, also the `node` label
password: str = ""
pubkey: str = "" # hex prefix; creates the contact if the companion lacks it
path: str = "" # hex hop hashes forced as the route before each read
def parse_targets(raw: str, password: str) -> list[Target]:
"""`name[=pubkey][@path]`, comma separated; every one gets `password`."""
out = []
for item in raw.split(","):
item = item.strip()
if not item:
continue
name, _, rest = item.partition("=")
if "@" in name: # name@path without a pubkey
name, _, rest = item.partition("@")
rest = "@" + rest
pubkey, _, path = rest.partition("@")
out.append(Target(name.strip(), password, pubkey.strip().lower(), path.strip().lower()))
return out
def load_config(path: str) -> tuple[dict[str, Any], list[Target]]:
"""TOML: top-level keys are option defaults, [[repeater]] blocks the targets."""
try:
import tomllib
except ImportError as e: # Python 3.10
raise ValueError("--config needs Python 3.11+; use --repeaters/--password instead") from e
with open(path, "rb") as f:
data = tomllib.load(f)
blocks = data.pop("repeater", [])
default_pw = str(data.get("password", ""))
targets = []
for b in blocks:
if "name" not in b:
raise ValueError(f"{path}: a [[repeater]] block has no name")
targets.append(
Target(
str(b["name"]),
str(b.get("password", default_pw)),
str(b.get("pubkey", "")).lower(),
str(b.get("path", "")).lower(),
)
)
return data, targets
def build_parser() -> argparse.ArgumentParser:
env = os.environ.get
p = argparse.ArgumentParser(
prog="meshcore-exporter",
description=(__doc__ or "").split("\n\n")[0],
epilog="Environment: every option has an MC_* twin, e.g. MC_SERIAL, MC_TCP, MC_BLE, "
"MC_REPEATERS, MC_PASSWORD, MC_INTERVAL, MC_CONFIG. See README.md.",
formatter_class=argparse.RawDescriptionHelpFormatter,
)
radio = p.add_argument_group("companion radio (pick one)")
radio.add_argument(
"--serial",
default=env("MC_SERIAL") or env("MC_PORT"),
help="USB serial port, best /dev/serial/by-id/... [MC_SERIAL]",
)
radio.add_argument("--baud", type=int, default=int(env("MC_BAUD", "115200")), help="[MC_BAUD]")
radio.add_argument("--tcp", default=env("MC_TCP"), help="host:port of a TCP companion [MC_TCP]")
radio.add_argument("--ble", default=env("MC_BLE"), help="BLE address of the companion [MC_BLE]")
radio.add_argument("--ble-pin", default=env("MC_BLE_PIN"), help="BLE pairing PIN [MC_BLE_PIN]")
tg = p.add_argument_group("repeaters")
tg.add_argument(
"--config",
default=env("MC_CONFIG"),
help="TOML file with [[repeater]] blocks (per-repeater password, pubkey, path) [MC_CONFIG]",
)
tg.add_argument(
"--repeaters",
default=env("MC_REPEATERS"),
help="name[=pubkey][@path],... -- name as the repeater advertises it [MC_REPEATERS]",
)
tg.add_argument(
"--password", default=env("MC_PASSWORD"), help="admin or guest password for --repeaters [MC_PASSWORD]"
)
rf = p.add_argument_group("mesh")
rf.add_argument(
"--interval",
type=int,
default=_int_or_none(env("MC_INTERVAL")),
help=f"seconds between rounds, min {MIN_INTERVAL}, default {DEFAULT_INTERVAL} [MC_INTERVAL]",
)
rf.add_argument(
"--rf-timeout",
type=int,
default=_int_or_none(env("MC_RF_TIMEOUT")),
help="seconds to wait for one reply, default 30 [MC_RF_TIMEOUT]",
)
rf.add_argument(
"--path-hash-bytes",
type=int,
choices=(1, 2, 3),
default=_int_or_none(env("MC_PATH_HASH_BYTES")),
help="set the companion's path hash width on connect; unset = leave it "
"(the Czech mesh uses 2) [MC_PATH_HASH_BYTES]",
)
srv = p.add_argument_group("metrics")
srv.add_argument("--listen", default=env("MC_LISTEN"), help="address, default 0.0.0.0 [MC_LISTEN]")
srv.add_argument(
"--port", type=int, default=_int_or_none(env("MC_METRICS_PORT")), help="port, default 9200 [MC_METRICS_PORT]"
)
p.add_argument(
"--check", action="store_true", help="read every repeater once, print the values and exit (0 = all answered)"
)
p.add_argument("--list-ports", action="store_true", help="list the serial ports of this computer (any OS) and exit")
p.add_argument("--log-level", default=env("MC_LOG_LEVEL", "INFO"), help="[MC_LOG_LEVEL]")
p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
return p
def _int_or_none(v: str | None) -> int | None:
return int(v) if v else None
@dataclass
class Settings:
serial: str | None
baud: int
tcp: str | None
ble: str | None
ble_pin: str | None
targets: list[Target]
interval: int
rf_timeout: int
path_hash_bytes: int | None
listen: str
port: int
check: bool
def resolve(args: argparse.Namespace) -> Settings:
"""Merge command line/env with the config file; raise ValueError on a bad setup."""
file_opts: dict[str, Any] = {}
targets: list[Target] = []
if args.config:
file_opts, targets = load_config(args.config)
if args.repeaters:
targets += parse_targets(args.repeaters, args.password or str(file_opts.get("password", "")))
if not targets:
raise ValueError("no repeater given: --repeaters, MC_REPEATERS or [[repeater]] in --config")
def pick(name: str, default: Any) -> Any:
v = getattr(args, name)
return v if v is not None else file_opts.get(name, default)
serial, tcp, ble = pick("serial", None), pick("tcp", None), pick("ble", None)
if sum(bool(x) for x in (serial, tcp, ble)) != 1:
raise ValueError("give exactly one companion: --serial, --tcp or --ble")
interval = int(pick("interval", DEFAULT_INTERVAL))
if interval < MIN_INTERVAL:
logging.warning("interval %d s is too short for a shared channel, using %d", interval, MIN_INTERVAL)
interval = MIN_INTERVAL
phb = pick("path_hash_bytes", None)
return Settings(
serial,
int(pick("baud", 115200)),
tcp,
ble,
pick("ble_pin", None),
targets,
interval,
int(pick("rf_timeout", 30)),
int(phb) if phb else None,
str(pick("listen", "0.0.0.0")),
int(pick("port", 9200)),
args.check,
)
# --- metrics ---------------------------------------------------------------
# status field -> (metric name without the meshcore_ prefix, help)
STATUS_FIELDS = {
"bat": ("battery_millivolts", "Battery voltage in millivolts"),
"tx_queue_len": ("queue_length", "Outbound packet queue length"),
"noise_floor": ("noise_floor_dbm", "Radio noise floor in dBm"),
"last_rssi": ("last_rssi_dbm", "RSSI of the last received packet in dBm"),
"last_snr": ("last_snr_db", "SNR of the last received packet in dB"),
"uptime": ("uptime_seconds", "Device uptime in seconds"),
"airtime": ("tx_airtime_seconds_total", "Cumulative transmit airtime in seconds"),
"rx_airtime": ("rx_airtime_seconds_total", "Cumulative receive airtime in seconds"),
"nb_recv": ("packets_received_total", "Packets received"),
"nb_sent": ("packets_sent_total", "Packets sent"),
"sent_flood": ("packets_sent_flood_total", "Flood packets sent"),
"sent_direct": ("packets_sent_direct_total", "Direct packets sent"),
"recv_flood": ("packets_received_flood_total", "Flood packets received"),
"recv_direct": ("packets_received_direct_total", "Direct packets received"),
"flood_dups": ("flood_duplicates_total", "Duplicate flood packets dropped"),
"direct_dups": ("direct_duplicates_total", "Duplicate direct packets dropped"),
"recv_errors": ("receive_errors_total", "Packets received with a bad CRC"),
"full_evts": ("queue_full_events_total", "Times the TX queue was full"),
# Only some firmware forks append these to the status frame; on stock
# firmware they are absent and not exported at all.
"tx_start_fail": ("tx_start_fail_total", "Transmits the radio refused to start (requeued)"),
"tx_timeout": ("tx_timeout_total", "Transmits that never completed (requeued)"),
}
# telemetry (Cayenne LPP) type -> metric; the first reading of a type wins,
# which is the external sensor when the node has one, the MCU otherwise.
# A guest login gets voltage and MCU temperature only.
TELEMETRY_FIELDS = {
"voltage": ("telemetry_voltage", "Battery voltage from telemetry (V)"),
"temperature": ("temperature_celsius", "Temperature (external sensor, else MCU) in Celsius"),
"humidity": ("humidity_percent", "Relative humidity in percent"),
"barometer": ("pressure_hpa", "Barometric pressure in hPa"),
}
class Metrics:
def __init__(self) -> None:
from prometheus_client import Counter, Gauge, Info
self.status = {k: Gauge(f"meshcore_{n}", d, ["node"]) for k, (n, d) in STATUS_FIELDS.items()}
self.telemetry = {k: Gauge(f"meshcore_{n}", d, ["node"]) for k, (n, d) in TELEMETRY_FIELDS.items()}
self.up = Gauge("meshcore_up", "1 if the last read of the repeater succeeded", ["node"])
self.last_ok = Gauge(
"meshcore_last_scrape_success_timestamp", "Unix time of the last successful read", ["node"]
)
self.errors = Counter("meshcore_scrape_errors", "Failed reads", ["node"])
self.logins = Counter("meshcore_repeater_logins", "Logins performed", ["node"])
Info("meshcore_exporter", "Exporter version").info({"version": __version__})
def extend_status_parser() -> None:
"""Read the two counters some forks append to the status frame.
The library reads fixed offsets and ignores a longer frame; bytes 56..64
after the header hold tx_start_fail and tx_timeout. Without them both stay
None and are not exported.
"""
try:
import meshcore.parsing as parsing
import meshcore.reader as reader
except ImportError:
return
orig = parsing.parse_status
def parse_status(data, pubkey_prefix=None, offset=0): # type: ignore[no-untyped-def]
res = orig(data, pubkey_prefix, offset)
off = 8 if pubkey_prefix is None else offset
if len(data) >= off + 64:
res["tx_start_fail"] = int.from_bytes(data[off + 56 : off + 60], "little")
res["tx_timeout"] = int.from_bytes(data[off + 60 : off + 64], "little")
else:
res["tx_start_fail"] = res["tx_timeout"] = None
return res
parsing.parse_status = parse_status
if hasattr(reader, "parse_status"):
reader.parse_status = parse_status # the reader imported the name itself
# --- mesh ------------------------------------------------------------------
log = logging.getLogger("meshcore-exporter")
class Exporter:
def __init__(self, s: Settings, metrics: Metrics | None) -> None:
self.s = s
self.m = metrics
self.contacts: dict[str, dict[str, Any]] = {}
self._contact_list: list[dict[str, Any]] | None = None
async def connect(self) -> Any:
from meshcore import MeshCore
s = self.s
if s.tcp:
host, _, port = s.tcp.rpartition(":")
mc = await MeshCore.create_tcp(host=host or s.tcp, port=int(port or 5000))
elif s.ble:
mc = await MeshCore.create_ble(address=s.ble, pin=s.ble_pin)
else:
mc = await MeshCore.create_serial(s.serial or "", s.baud)
if mc is None:
raise RuntimeError("the companion does not answer (wrong port, or another app holds it?)")
if s.path_hash_bytes:
# The width of hashes in packets the companion ORIGINATES is its own
# pref; a 1-byte hash collides with many repeaters on a 2-byte mesh.
try:
if (await mc.commands.get_path_hash_mode()) != s.path_hash_bytes - 1:
await mc.commands.set_path_hash_mode(s.path_hash_bytes - 1)
log.info("companion path hash set to %d B", s.path_hash_bytes)
except Exception as e: # noqa: BLE001 -- older companion firmware
log.warning("could not set the path hash width: %s", e)
return mc
async def contact_list(self, mc: Any) -> list[dict[str, Any]]:
"""The companion's contacts, fetched once per round.
A companion that has heard the whole mesh holds hundreds of contacts;
streaming them takes seconds, and asking again for every repeater made
the second request time out (library default 5 s).
"""
from meshcore import EventType
if self._contact_list is None:
for attempt in (1, 2):
res = await mc.commands.get_contacts(timeout=CONTACTS_TIMEOUT)
if res is not None and res.type != EventType.ERROR:
self._contact_list = list((res.payload or {}).values())
break
if attempt == 2:
raise RuntimeError(f"get_contacts failed: {res}")
return self._contact_list or []
async def contact(self, mc: Any, t: Target) -> dict[str, Any]:
"""The contact by name, else by pubkey, else created from the pubkey."""
contacts = await self.contact_list(mc)
for c in contacts:
if c.get("adv_name") == t.name:
return dict(c)
if t.pubkey:
for c in contacts:
if (c.get("public_key") or "").lower().startswith(t.pubkey):
return dict(c)
if len(t.pubkey) == 64:
# A login is encrypted with a secret derived from the contact,
# so a repeater never heard by this companion needs one made.
log.info("%s: no contact, creating it from the public key", t.name)
await mc.commands.add_contact(
{
"public_key": t.pubkey,
"type": 2,
"flags": 0,
"out_path": "",
"out_path_len": -1,
"out_path_hash_mode": 0,
"adv_name": t.name,
"last_advert": 0,
"adv_lat": 0.0,
"adv_lon": 0.0,
}
)
await asyncio.sleep(2)
self._contact_list = None
return await self.contact(mc, Target(t.name, t.password, t.pubkey[:12]))
raise RuntimeError(
f"no contact '{t.name}' on the companion: wait for its advert, or give the full 64-hex public key"
)
async def pin_path(self, mc: Any, t: Target, c: dict[str, Any]) -> None:
"""Force a fixed route (a local companion command, nothing on air).
For a link that works one way only: the companion learns a 0-hop route
from the repeater's advert even when the repeater cannot hear it back.
"""
if not t.path:
return
mode = (self.s.path_hash_bytes or 2) - 1
if c.get("out_path") == t.path and c.get("out_path_hash_mode") == mode:
return
from meshcore import EventType
res = await mc.commands.change_contact_path(c, t.path, path_hash_mode=mode)
if res is None or res.type == EventType.ERROR:
raise RuntimeError(f"could not set path {t.path}: {res}")
c["out_path"], c["out_path_hash_mode"] = t.path, mode
log.info("%s: route pinned to %s", t.name, t.path)
async def login(self, mc: Any, t: Target, c: dict[str, Any]) -> None:
from meshcore import EventType
res = await mc.commands.send_login_sync(c, t.password, timeout=self.s.rf_timeout)
if res is None or res.type == EventType.ERROR:
raise RuntimeError("login failed (wrong password, or no reply on the mesh)")
if self.m:
self.m.logins.labels(node=t.name).inc()
async def read(self, mc: Any, t: Target) -> dict[str, float]:
"""One status + telemetry round of one repeater."""
if t.name not in self.contacts:
self.contacts[t.name] = await self.contact(mc, t)
await self.pin_path(mc, t, self.contacts[t.name])
await self.login(mc, t, self.contacts[t.name])
c = self.contacts[t.name]
await self.pin_path(mc, t, c)
st = await mc.commands.req_status_sync(c, timeout=self.s.rf_timeout)
if st is None: # the repeater forgot us (reboot): log in again
await self.login(mc, t, c)
st = await mc.commands.req_status_sync(c, timeout=self.s.rf_timeout)
if st is None:
raise RuntimeError("no status reply, not even after a new login")
values = {k: float(st[k]) for k in STATUS_FIELDS if st.get(k) is not None}
tel = await mc.commands.req_telemetry_sync(c, timeout=self.s.rf_timeout)
if isinstance(tel, dict):
tel = tel.get("lpp", [])
for ch in tel or []:
kind = ch.get("type")
if kind in TELEMETRY_FIELDS and kind not in values and isinstance(ch.get("value"), (int, float)):
values[kind] = float(ch["value"])
return values
def publish(self, t: Target, values: dict[str, float]) -> None:
if not self.m:
return
for k, v in values.items():
gauge = self.m.status.get(k) or self.m.telemetry.get(k)
if gauge is not None:
gauge.labels(node=t.name).set(v)
self.m.up.labels(node=t.name).set(1)
self.m.last_ok.labels(node=t.name).set(time.time())
def failed(self, t: Target) -> None:
if self.m:
self.m.errors.labels(node=t.name).inc()
self.m.up.labels(node=t.name).set(0)
async def round(self, mc: Any, targets: list[Target] | None = None) -> list[Target]:
"""Read `targets` (default all); return the ones that failed."""
failed = []
self._contact_list = None
for t in targets if targets is not None else self.s.targets:
try:
values = await self.read(mc, t)
except Exception as e: # noqa: BLE001 -- one dead repeater must not stop the others
self.failed(t)
self.contacts.pop(t.name, None)
log.warning("%s: %s", t.name, e)
failed.append(t)
continue
self.publish(t, values)
log.info(
"%s: OK bat=%smV up=%ss recv=%s sent=%s",
t.name,
_i(values.get("bat")),
_i(values.get("uptime")),
_i(values.get("nb_recv")),
_i(values.get("nb_sent")),
)
if self.s.check:
for k, v in sorted(values.items()):
name = (STATUS_FIELDS.get(k) or TELEMETRY_FIELDS[k])[0]
print(f' meshcore_{name}{{node="{t.name}"}} {v:g}')
return failed
async def run(self) -> int:
if self.s.check:
try:
mc = await self.connect()
except RuntimeError:
raise
except Exception as e: # noqa: BLE001 -- serial/BLE/TCP errors: one line, not a traceback
raise RuntimeError(f"cannot open the companion: {e}") from e
try:
ok = len(self.s.targets) - len(await self.round(mc))
finally:
await mc.disconnect()
print(f"{ok}/{len(self.s.targets)} repeaters answered")
return 0 if ok == len(self.s.targets) else 1
fails = 0
while True:
mc = None
try:
mc = await self.connect()
self.contacts.clear()
while True:
# Reconnect only after rounds with NO success at all: one
# unreachable repeater must not stop reading the others.
failed = await self.round(mc)
wait = self.s.interval
if failed and RETRY_AFTER < self.s.interval:
names = ", ".join(t.name for t in failed)
log.info("retrying %s in %d s", names, RETRY_AFTER)
await asyncio.sleep(RETRY_AFTER)
failed = await self.round(mc, failed)
wait -= RETRY_AFTER
fails = fails + 1 if len(failed) == len(self.s.targets) else 0
if fails >= 3:
raise RuntimeError("3 rounds in a row without a single answer")
await asyncio.sleep(wait)
except Exception as e: # noqa: BLE001
for t in self.s.targets:
self.failed(t)
log.error("companion: %s -- reconnecting in 30 s", e)
if mc is not None:
try:
await mc.disconnect()
except Exception: # noqa: BLE001
pass
await asyncio.sleep(30)
def _i(v: float | None) -> str:
return "?" if v is None else f"{v:.0f}"
def list_ports() -> int:
"""Serial ports with what identifies the board: Linux, macOS and Windows alike.
On Linux the stable /dev/serial/by-id/ name is shown too: /dev/ttyACM0 may
become /dev/ttyACM1 after a replug, the by-id name stays.
"""
from serial.tools import list_ports as lp
by_id: dict[str, str] = {}
base = "/dev/serial/by-id"
if os.path.isdir(base):
for name in os.listdir(base):
by_id[os.path.realpath(os.path.join(base, name))] = os.path.join(base, name)
every = sorted(lp.comports(), key=lambda p: p.device)
ports = [p for p in every if p.vid is not None] # USB only: a companion is a USB device
if not ports:
print("no USB serial ports found -- is the companion plugged in (and, in a VM/WSL, passed through)?")
return 1
for p in ports:
ids = f"{p.vid:04x}:{p.pid:04x}" if p.vid is not None and p.pid is not None else "-"
print(f"{p.device}\n {p.description or '-'} [usb {ids}, serial {p.serial_number or '-'}]")
if os.path.realpath(p.device) in by_id:
print(f" use: {by_id[os.path.realpath(p.device)]}")
if len(every) > len(ports):
print(f"({len(every) - len(ports)} non-USB serial ports not shown)")
return 0
def main(argv: list[str] | None = None) -> int:
args = build_parser().parse_args(argv) # --help / --version exit here, before any import
logging.basicConfig(level=args.log_level.upper(), format="%(asctime)s %(levelname)s %(message)s")
if args.list_ports:
return list_ports()
try:
s = resolve(args)
except (ValueError, OSError) as e:
print(f"meshcore-exporter: {e}", file=sys.stderr)
return 2
extend_status_parser()
metrics = None
if not s.check:
from prometheus_client import start_http_server
metrics = Metrics()
start_http_server(s.port, addr=s.listen)
log.info(
"metrics on %s:%d/metrics, %d repeater(s), every %d s, companion %s",
s.listen,
s.port,
len(s.targets),
s.interval,
f"tcp {s.tcp}" if s.tcp else f"ble {s.ble}" if s.ble else f"serial {s.serial}",
)
try:
return asyncio.run(Exporter(s, metrics).run())
except KeyboardInterrupt:
return 130
except RuntimeError as e:
print(f"meshcore-exporter: {e}", file=sys.stderr)
return 1
if __name__ == "__main__":
sys.exit(main())