For a single USB/BLE companion also used from a phone, without openHop. Tested over a TCP backend (exporter read a repeater while a second client polled the same proxy for 90 s without an error); not with a USB radio yet. Not for openHop companions: the proxy reconnects aggressively and evicts the other client there. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
14 KiB
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
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 |
| 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
--configchce 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í 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.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ěží.
-
Přidejte do
config.yamlopenHopu 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ímitcp_timeout: 0je nutný: výchozích 120 s by spojení mezi dvěma čteními zavřelo. -
Restart openHopu, pak
meshcore-exporter --tcp 127.0.0.1:5002 --repeaters … --password … --check. -
Docker stack na stejném stroji: do
.envmísto řádkůMC_SERIAL*dejteMC_TCP=127.0.0.1:5002aCOMPOSE_FILE=docker-compose.yml:docker-compose.host.yml(v.env.examplepřipravené). Celý stack pak běží v síti hosta a na openHop se připojí přes127.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 na127.0.0.1, Grafana naGRAFANA_PORTjako 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í)
-
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 5000Frontend 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. -
Exportér na něj jako na TCP companion:
meshcore-exporter --tcp 127.0.0.1:5000 --repeaters … --password … --check(ve stackuMC_TCP=127.0.0.1:5000adocker-compose.host.ymljako 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 |
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čí |
--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 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 (--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í 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.
