Files
meshcore-exporter/AGENTS.md
T
tthandClaude Opus 5.5 726a618483
ci / test (push) Successful in 1m12s
image / build (arm64) (push) Successful in 1m17s
image / build (amd64) (push) Successful in 1m22s
image / release (push) Skipped
AGENTS.md: offer coresplitter for a companion shared with a phone
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 23:07:00 +01:00

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)

  1. 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, erase or 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.
  2. 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).
  3. Passwords go into stack/.env or repeaters.toml only (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.
  4. 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.
  5. 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.
  6. Do not install system packages, change groups or open firewall ports without telling the user what and why first.

Procedure

  1. 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.
  2. USB companion: meshcore-exporter --list-ports (any OS; installed with pipx, or python3 meshcore_exporter.py --list-ports from 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.
  3. 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).
  4. Fill stack/.env from stack/.env.example (or a repeaters.toml). On the Czech mesh set MC_PATH_HASH_BYTES=2.
  5. Verify before starting the service: docker compose run --rm exporter --check (stack) or meshcore-exporter … --check. Success = 1/1 repeaters answered and a meshcore_battery_millivolts line. 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.
  6. Start: docker compose up -d, then docker compose logs exporter must show OK bat=. A first read that fails and logs retrying … in 180 s is normal (a lost reply, or a login refused shortly after --check): wait for the retry instead of restarting. Grafana: http://<host>:3000, user admin.
  7. 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.