4.2 KiB
4.2 KiB
Instructions for an AI agent setting this up
You are helping someone run meshcore-exporter: a program that reads MeshCore repeaters over a shared public radio channel and shows them in Grafana. README.md has the full reference. This file is the procedure and the rules.
Rules (not negotiable)
- Read only. The exporter reads; you never configure the repeater or the
companion radio for the user. Do not send
set repeat,set freq,set radio,advert,reboot,eraseor any other CLI command to a node, with meshcli or anything else. A repeater is part of a community network; a wrong setting breaks routing for other people. - Keep the default interval (3600 s). Shorter only if the user explicitly asks for it and understands it costs shared airtime (point them to https://meshcore.repeater.cz/nastaveni/telemetrie/). Never below 900 (the program refuses).
- Passwords go into
stack/.envorrepeaters.tomlonly (both are git-ignored), never into a command you print, a commit, a log or an issue. When you show the config to the user, mask the password. - One client per companion radio. If the radio is used by a phone app, Meshy or meshcli, ask the user to disconnect it; do not kill their processes without asking.
- The user knows the hardware. If they say the board is plugged in, it
is: look (
ls -l /dev/serial/by-id/) instead of arguing. - Do not install system packages, change groups or open firewall ports without telling the user what and why first.
Procedure
- Ask: do they already run Prometheus and Grafana? Yes → README section 2 ("Jen exportér"). No → section 1 (Docker stack). Docker missing → install it the distribution's way, with the user's consent. Do they run openHop (repeater/observer)? Then no extra board is needed: README section 3 (a dedicated companion identity over TCP). Changing their openHop config.yaml is a change to their node: show the block, let them apply it. One companion they also use from a phone app, no openHop: README section 4 (coresplitter shares it). It must be built from source; offer it, do not install a Rust toolchain without asking. Find out the operating system first. Docker Desktop on macOS and Windows cannot pass a USB device into a container: there, use section 2 (pipx) for the exporter, never the Docker stack with a USB board. WSL2 needs the board attached with usbipd-win first.
- USB companion:
meshcore-exporter --list-ports(any OS; installed with pipx, orpython3 meshcore_exporter.py --list-portsfrom the checkout). On Linux use the/dev/serial/by-id/...path it prints, never/dev/ttyACM0(it changes after a replug); its group:stat -c '%G %g' <that path>. macOS:/dev/cu.usbmodem..., Windows:COMn. Not listed = not plugged in, a charge-only cable, or (VM/WSL) not passed through: say so, do not guess another port. - Ask for the repeater name exactly as it appears in the MeshCore app, and its admin or guest password (MeshCore uses only the first 15 characters).
- Fill
stack/.envfromstack/.env.example(or arepeaters.toml). On the Czech mesh setMC_PATH_HASH_BYTES=2. - Verify before starting the service:
docker compose run --rm exporter --check(stack) ormeshcore-exporter … --check. Success =1/1 repeaters answeredand ameshcore_battery_millivoltsline. On failure use the table "Když to nejde" in README.md; do not retry in a tight loop (every try is radio traffic) — wait at least a minute between attempts. - Start:
docker compose up -d, thendocker compose logs exportermust showOK bat=. A first read that fails and logsretrying … in 180 sis normal (a lost reply, or a login refused shortly after--check): wait for the retry instead of restarting. Grafana:http://<host>:3000, useradmin. - Tell the user what runs where, how to update
(
docker compose pull && docker compose up -d) and where the password is stored.
Developing
python3 -m pytest, ruff check, ruff format --check, mypy meshcore_exporter.py.
The dashboard is generated: edit dashboards/generate.py, run it, commit
both files. --help must keep working without the dependencies installed.