tthandClaude Opus 5.5 2a9126e258
ci / test (push) Successful in 1m12s
image / build (arm64) (push) Successful in 1m52s
image / build (amd64) (push) Successful in 2m1s
image / release (push) Successful in 9s
meshcore-exporter 1.0.0
Prometheus exporter for MeshCore repeaters, read over the mesh: a companion
(USB, BLE, or a companion identity in openHop over TCP) logs in to each
repeater, asks for status and telemetry with direct packets and serves
battery, temperature/humidity, noise floor, RSSI/SNR, packet counters,
airtime and uptime on :9200/metrics.

- meshcore_exporter.py: command line, MC_* environment or a TOML file with
  a password per repeater; --check reads every repeater once and exits;
  interval 1 h (min 15 min); a failed repeater is retried once after 3 min;
  contacts fetched once per round.
- dashboards/: the Grafana dashboard, generated from generate.py
  (datasource, job and the rate window are variables; TX drawn above zero,
  RX below).
- stack/: Docker Compose with Prometheus and Grafana provisioned, for a USB
  companion, or on the host network for openHop on the same machine.
- systemd/: running without Docker.
- README.md (Czech) and AGENTS.md for setting it up with an AI agent.
- CI: lint and tests, gitleaks; PR check builds the image; single-platform
  images per architecture behind a Trivy gate (latest-<arch>, and X.Y.Z-<arch>
  with a release on tag vX.Y.Z); dependencies by Renovate.

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

meshcore-exporter

Grafana pro váš MeshCore repeater: baterie, teplota, šum, RSSI/SNR, provoz, airtime a duty cycle — čtené přes samotný mesh, takže repeater může stát na kopci bez kabelu i bez Wi-Fi.

repeater ))) mesh ((( companion rádio ── USB ── meshcore-exporter ── Prometheus ── Grafana

Dashboard za 7 dní: baterie, teplota, provoz, signál, airtime a duty cycle (vysílání nad nulou, příjem pod ní, okno 3 h); 1. 11. nová anténa a filtr

Companion rádio (libovolná MeshCore deska s companion firmwarem, připojená k počítači) se jednou za hodinu přihlásí na repeater, vyžádá si stav a telemetrii přímými pakety a exportér to vystaví na :9200/metrics.

English: a Prometheus exporter that logs in to MeshCore repeaters over the mesh from a companion radio (USB, TCP or BLE) and exports status and telemetry. Docs below are Czech; meshcore-exporter --help is English.

Mám… Čtěte
nic, chci hotovou Grafanu 1. Kompletní stack (Docker)
vlastní Prometheus a Grafanu 2. Jen exportér
openHop (repeater nebo observer) a nechci kvůli tomu obětovat desku 3. Bez vyhrazené desky: openHop
AI agenta, který to rozjede za mě dejte mu tohle repo; pravidla pro něj jsou v AGENTS.md

Co je potřeba

  • Repeater s MeshCore a jeho heslo — admin, nebo guest (set guest.password … na repeateru). Guest dostane všechno kromě externích senzorů (vlhkost, venkovní teplota).
  • Companion v dosahu repeateru: buď companion identita v openHopu, který už provozujete (žádná deska navíc, viz 3.), nebo companion rádio připojené k počítači, který běží pořád (Raspberry Pi, server, NAS). USB companion firmware, nebo Wi-Fi companion (TCP). Na repeater musí být spojení oběma směry — stačí i přes další repeatery.
  • Rádio nesmí mít zároveň připojenou jinou aplikaci (telefon, Meshy, meshcli). Companion obslouží jen jednoho klienta; vyhrazená deska je nejjednodušší.
  • Linux (amd64 nebo arm64). Docker pro variantu 1, Python 3.10+ pro variantu 2 (soubor --config chce 3.11+).

1. Kompletní stack (Docker)

git clone https://git.rfa.cz/tth-pub/meshcore-exporter.git
cd meshcore-exporter/stack
cp .env.example .env
ls -l /dev/serial/by-id/          # najděte svou desku
nano .env                         # vyplňte řádky REPLACE_ME
docker compose up -d
docker compose logs -f exporter   # čekejte na "OK bat=…"

Grafana poběží na http://<počítač>:3000 (uživatel admin, heslo z .env), dashboard MeshCore — repeater je domovská stránka. První čísla jsou tam do minuty, grafy rychlostí (duty cycle, trend baterie) se naplní za pár hodin (počítají se z okna 3 h, proměnná dashboardu Okno).

Data drží Prometheus 400 dní (PROMETHEUS_RETENTION v .env). Aktualizace: docker compose pull && docker compose up -d. Stack jede na latest; na konkrétní verzi z Releases ho připnete řádkem MC_VERSION=1.0.0 v .env.

2. Jen exportér

Z Pythonu:

pipx install git+https://git.rfa.cz/tth-pub/meshcore-exporter
meshcore-exporter --serial /dev/serial/by-id/usb-… --repeaters muj-rpt --password … --check
meshcore-exporter --serial /dev/serial/by-id/usb-… --repeaters muj-rpt --password …

Nebo kontejner (latest-amd64 / latest-arm64, nebo verze z Releases, např. 1.0.0-amd64; jeden tag = jedna architektura):

docker run -d --name meshcore-exporter --restart unless-stopped \
  --device /dev/serial/by-id/usb-…:/dev/meshcore --group-add dialout -p 9200:9200 \
  -e MC_SERIAL=/dev/meshcore -e MC_REPEATERS=muj-rpt -e MC_PASSWORD=… \
  git.rfa.cz/tth-pub/meshcore-exporter:latest-amd64

Bez Dockeru jako služba: systemd/meshcore-exporter.service (postup v hlavičce souboru).

Do Prometheu:

- job_name: meshcore_exporter
  static_configs:
    - targets: ["host:9200"]

Dashboard: importujte dashboards/meshcore-repeater.json (je i jako příloha každého release) (Dashboards → New → Import). Zdroj dat a hodnota labelu job jsou proměnné dashboardu, takže sedne na libovolný Prometheus, Mimir nebo VictoriaMetrics.

3. Bez vyhrazené desky: openHop

openHop (repeater nebo observer na Linuxu s openHop modemem, SPI nebo CH341 rádiem) umí vedle sebe několik companion identit, každou na vlastním TCP portu. Exportéru stačí jedna z nich, rádio sdílí s tím, co na openHopu už běží.

  1. Přidejte do config.yaml openHopu companion jen pro exportér (port s jiným klientem nesdílejte: openHop obslouží jednoho klienta na companion a odpovědi doručí jen tomu, kdo se připojil první):

    identities:
      companions:
        - name: ExporterCompanion
          identity_key: "…"            # python3 -c "import secrets; print(secrets.token_hex(32))"
          settings:
            node_name: "muj-exporter"
            tcp_port: 5002
            bind_address: 127.0.0.1    # companion protokol nemá heslo: jen lokálně
            tcp_timeout: 0             # exportér drží spojení i hodinu mezi čteními
    

    tcp_timeout: 0 je nutný: výchozích 120 s by spojení mezi dvěma čteními zavřelo.

  2. Restart openHopu, pak meshcore-exporter --tcp 127.0.0.1:5002 --repeaters … --password … --check.

  3. Docker stack na stejném stroji: do .env místo řádků MC_SERIAL* dejte MC_TCP=127.0.0.1:5002 a COMPOSE_FILE=docker-compose.yml:docker-compose.host.yml (v .env.example připravené). Celý stack pak běží v síti hosta a na openHop se připojí přes 127.0.0.1. Cesta z Docker sítě na hosta (host.docker.internal) se nepoužívá, protože ji běžný firewall (ufw, výchozí nftables) zablokuje. Exportér i Prometheus poslouchají jen na 127.0.0.1, Grafana na GRAFANA_PORT jako jindy. Bez Dockeru stačí exportér podle 2. s --tcp 127.0.0.1:5002.

Nastavení

Každá volba má tři podoby: přepínač, proměnnou prostředí, klíč v TOML (--config repeaters.toml, vzor repeaters.example.toml). Přepínač má přednost před proměnnou a ta před souborem.

přepínač proměnná výchozí
--serial MC_SERIAL — USB port companionu, ideálně /dev/serial/by-id/…
--tcp MC_TCP — host:port Wi-Fi companionu (port 5000)
--ble, --ble-pin MC_BLE, MC_BLE_PIN — BLE companion (mimo Docker)
--repeaters MC_REPEATERS — jméno[=pubkey][@cesta], víc přes čárku
--password MC_PASSWORD — heslo pro --repeaters
--config MC_CONFIG — TOML s bloky [[repeater]] (heslo pro každý zvlášť)
--interval MC_INTERVAL 3600 sekundy mezi čteními, minimum 900
--path-hash-bytes MC_PATH_HASH_BYTES neměnit šířka hashů cesty companionu; CZ mesh: 2
--rf-timeout MC_RF_TIMEOUT 30 čekání na jednu odpověď
--listen, --port MC_LISTEN, MC_METRICS_PORT 0.0.0.0, 9200 kde vystavit metriky
--check — — přečte každý repeater jednou, vypíše hodnoty a skončí

Jméno repeateru musí sedět s tím, co rozesílá v advertu. Pubkey je potřeba, jen když companion repeater nikdy neslyšel (pak plných 64 hex). Cesta (@5361) vnutí trasu přes jiné repeatery: hodí se, když repeater companion slyší napřímo, ale opačně to nedoletí.

Metriky

Všechny mají label node (jméno repeateru).

metrika
meshcore_battery_millivolts napětí baterie
meshcore_temperature_celsius, meshcore_humidity_percent, meshcore_pressure_hpa telemetrie (vlhkost a tlak jen s externím senzorem a admin heslem)
meshcore_noise_floor_dbm, meshcore_last_rssi_dbm, meshcore_last_snr_db rádio
meshcore_uptime_seconds, meshcore_queue_length stav
meshcore_packets_{received,sent}_total, …_{flood,direct}_total, meshcore_receive_errors_total, meshcore_{flood,direct}_duplicates_total, meshcore_queue_full_events_total provoz
meshcore_{tx,rx}_airtime_seconds_total airtime
meshcore_tx_start_fail_total, meshcore_tx_timeout_total jen firmware, který je posílá
meshcore_up, meshcore_last_scrape_success_timestamp, meshcore_scrape_errors_total, meshcore_repeater_logins_total stav exportéru

Kolik to stojí éteru

Jedno čtení repeateru (status + telemetrie, tam i zpět) zabere na českém nastavení (SF7/62,5 kHz) zhruba 0,8 s kanálu, který sdílí všichni. Výchozí interval je hodina, tedy necelá sekunda za hodinu na repeater. Kratší interval přidá provoz všem okolo a nic užitečného nepřinese: baterie, teplota ani šum se za pár minut nezmění. Exportér pod 15 minut nejde.

Než interval zkrátíte, zamyslete se, jak často ta data opravdu potřebujete. Dobře to rozebírá návod Telemetrie, senzory, GPS na meshcore.repeater.cz.

Když to nejde

příznak příčina
the companion does not answer špatný port, rádio drží jiná aplikace, nebo na desce není companion firmware
Permission denied na portu uživatel/kontejner není ve skupině portu (MC_SERIAL_GID, dialout/uucp)
no contact '…' on the companion companion advert repeateru ještě neslyšel: počkejte, nebo dejte plný pubkey
login failed špatné heslo — MeshCore bere jen prvních 15 znaků, delší heslo se tiše usekne —, nebo odpověď nedoletěla
jednou login failed / no status reply, pak retrying … in 180 s ztracená odpověď v éteru, nebo repeater krátce po předchozím přihlášení (např. --check) nový login zahodil; exportér to sám zkusí znovu za 3 minuty, nic nedělejte
no status reply spojení jen jedním směrem: zkuste trasu přes jiný repeater (@cesta)
prázdné nebo zubaté grafy rychlostí počítají se z okna Okno (výchozí 3 h): po startu počkejte pár hodin; při jiném intervalu nastavte okno aspoň na 2–3× interval

Podrobný log: --log-level DEBUG.

Licence

MIT.

S
Description
Prometheus exporter + Grafana dashboard for MeshCore repeaters, read over the mesh
Readme MIT
450 KiB
0 Stars 1 Watchers 0 Forks
2026-11-13 11:58:24 +01:00
Languages
Python 97.5%
Dockerfile 2.5%