Files
meshcore-exporter/README.md
T
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

14 KiB
Raw Blame History

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 8 hodin 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
jeden companion a chci ho dál používat i z telefonu 4. Sdílený companion: coresplitter
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šší.
  • Počítač, na kterém exportér poběží (cesta podle systému níž).
  • Python 3.10+ pro variantu 2 (soubor --config chce 3.11+).

Podle systému

systém doporučená cesta port companionu
Linux, Raspberry Pi (64bit) 1. Docker stack /dev/serial/by-id/usb-…
macOS 2. Jen exportér přes pipx, Prometheus a Grafana zvlášť /dev/cu.usbmodem…
Windows 2. Jen exportér přes pipx, Prometheus a Grafana zvlášť COM3 apod.
Windows s WSL2 jako Linux, desku do WSL předejte přes usbipd-win /dev/ttyACM0
cokoli s openHopem 3. Bez vyhrazené desky žádný, TCP

Docker Desktop na macOS a Windows neumí předat USB zařízení do kontejneru, varianta 1 s deskou na USB tam nepojede. Který port je companion, vypíše na každém systému meshcore-exporter --list-ports (popis desky, USB ID, sériové číslo; na Linuxu i trvalé jméno z /dev/serial/by-id/, které se po přepojení nezmění, na rozdíl od /dev/ttyACM0). Na Linuxu je ověřené vše, na macOS a Windows zatím ne; hlášení, jak to dopadlo, je vítané.

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=…"

Jen Linux (včetně Raspberry Pi a WSL2 s usbipd): na macOS a Windows Docker desku do kontejneru nepředá, tam použijte 2..

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í až za den (počítají se z okna 24 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.1 v .env.

2. Jen exportér

Z Pythonu:

pipx install git+https://git.rfa.cz/tth-pub/meshcore-exporter
meshcore-exporter --list-ports            # který port je companion
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 …

Na macOS je port /dev/cu.usbmodem…, na Windows COM3 apod. (podle --list-ports). Trvale spuštěný exportér tam zajistí launchd, resp. Plánovač úloh, nebo služba přes NSSM; Prometheus a Grafana mají instalátory pro oba systémy.

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 hodiny 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.

4. Sdílený companion: coresplitter

Companion obslouží jen jednoho klienta, takže bez openHopu je potřeba buď vyhrazená deska, nebo proxy, která jedno rádio rozdělí mezi víc klientů. To umí coresplitter (Rust, GPL-3.0): připojí se k rádiu (USB, BLE nebo TCP) a na TCP ho nabídne více klientům najednou. Příkazy řadí do fronty a odpovědi vrací tomu, kdo se ptal; adverty a zprávy posílá všem; kontakty a stav drží v cache.

companion ── USB ── coresplitter ──┬── TCP ── meshcore-exporter
                                   └── TCP ── aplikace v telefonu (Wi-Fi/TCP připojení)
  1. coresplitter zatím nevydává hotové binárky ani obrazy, je potřeba si ho přeložit (Rust ≥ 1.85):

    git clone https://github.com/ogarcia/coresplitter.git && cd coresplitter
    cargo build --release
    ./target/release/coresplitter --serial /dev/serial/by-id/usb-… --tcp-frontend-port 5000
    

    Frontend poslouchá výchozí na 0.0.0.0. Companion protokol nemá heslo, takže kdo se k portu dostane, může přes rádio posílat zprávy: na telefon v domácí síti ho nechte jen tam (firewall), jinak --tcp-frontend-host 127.0.0.1.

  2. Exportér na něj jako na TCP companion: meshcore-exporter --tcp 127.0.0.1:5000 --repeaters … --password … --check (ve stacku MC_TCP=127.0.0.1:5000 a docker-compose.host.yml jako u openHopu).

Ověřeno 2. 11. 2026 přes TCP backend: exportér přečetl repeater, zatímco druhý klient na stejné proxy 90 s bez chyby četl kontakty a stav. S rádiem na USB zatím ne. Dvě věci k vědomí:

  • Když proxy ztratí spojení s rádiem, odpojí všechny klienty a po návratu rádia se připojí znovu. Exportér si to přežije (připojí se znovu za 30 s).
  • Na openHop companion coresplitter nedávejte. openHop pustí jen jednoho klienta na companion a proxy se při znovupřipojení s ostatními přetahuje. Tam stačí přidat další companion identitu (3.).

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 28800 sekundy mezi čteními (8 h), minimum 3600
--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čí
--list-ports — — vypíše USB sériové porty (Linux, macOS, Windows) 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 8 hodin, tedy necelá sekunda za 8 hodin 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 hodinu 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 (--list-ports), 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í 24 h): po startu počkejte den; při jiném intervalu nastavte okno aspoň na 2–3× interval

Podrobný log: --log-level DEBUG.

Licence

MIT.