meshcore-exporter 1.0.0
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

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>
This commit is contained in:
tthandClaude Opus 5.5 committed 2026-11-02 21:52:21 +01:00
commit 2a9126e258
30 files changed
+3181

No files matched your search

+3
View File
@@ -0,0 +1,3 @@
*
!meshcore_exporter.py
!requirements.txt
+50
View File
@@ -0,0 +1,50 @@
# Lint + tests on every push and PR; the image is built by image.yml.
name: ci
"on":
push:
pull_request:
workflow_dispatch:
env:
RUFF_VERSION: "0.15.7"
MYPY_VERSION: "1.19.1"
YAMLLINT_VERSION: "1.38.0"
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: gitleaks
uses: https://git.rfa.cz/tth-pub/ci-actions/gitleaks@v11
with:
mode: block
- uses: actions/setup-python@v7
with:
python-version: "3.15"
- name: Install
run: |
set -euo pipefail
python -m pip install --quiet -r requirements.txt pytest \
"ruff==$RUFF_VERSION" "mypy==$MYPY_VERSION" "yamllint==$YAMLLINT_VERSION"
- name: Lint
run: |
set -euo pipefail
ruff check .
ruff format --check .
mypy meshcore_exporter.py
yamllint stack .gitea .yamllint
- name: Dashboard is generated from generate.py
run: |
set -euo pipefail
python dashboards/generate.py
git diff --exit-code dashboards/
- name: Tests
run: python -m pytest -q
+147
View File
@@ -0,0 +1,147 @@
# Container image git.rfa.cz/tth-pub/meshcore-exporter, one single-platform
# tag per architecture (latest-amd64, latest-arm64): `docker pull` from this
# registry is unreliable on combined multi-arch manifests. Only the commit tag
# is pushed first; latest-<arch> moves after the Trivy gate.
#
# A tag vX.Y.Z (must equal __version__) also gets X.Y.Z-<arch> images and a
# release with the pull commands and the Grafana dashboard attached.
#
# Secret REGISTRY_TOKEN: a Gitea token with packages:write.
name: image
"on":
push:
branches: [main]
tags: ["v*"]
schedule:
- cron: "40 4 * * 1" # weekly: base image security updates
workflow_dispatch:
inputs:
skip_trivy:
description: "skip the Trivy gate (EMERGENCY, logged)"
type: boolean
default: false
env:
IMAGE: git.rfa.cz/tth-pub/meshcore-exporter
jobs:
build:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
arch: [amd64, arm64]
steps:
- uses: actions/checkout@v7
- name: Trivy config
uses: https://git.rfa.cz/tth-pub/ci-actions/trivy-gate@v11
with:
scan-type: fs
scanners: misconfig
mode: warn
- name: Tag matches __version__
if: startsWith(github.ref, 'refs/tags/v')
run: |
set -euo pipefail
v=$(sed -n 's/^__version__ = "\(.*\)"$/\1/p' meshcore_exporter.py)
[ "v$v" = "${GITHUB_REF_NAME}" ] ||
{ echo "::error::tag ${GITHUB_REF_NAME} but __version__ = $v"; exit 1; }
- uses: docker/setup-qemu-action@v4
- uses: docker/setup-buildx-action@v4
- uses: docker/login-action@v4
with:
registry: git.rfa.cz
username: ${{ gitea.actor }}
password: ${{ secrets.REGISTRY_TOKEN }}
- name: Build date
id: date
run: echo "day=$(date -u +%F)" >> "$GITHUB_OUTPUT"
- name: Build and push the commit tag
uses: docker/build-push-action@v7
with:
context: .
push: true
pull: true
provenance: false
platforms: linux/${{ matrix.arch }}
build-args: OS_UPDATES=${{ steps.date.outputs.day }}
tags: ${{ env.IMAGE }}:${{ github.sha }}-${{ matrix.arch }}
cache-from: type=registry,ref=${{ env.IMAGE }}:buildcache-${{ matrix.arch }}
cache-to: type=registry,ref=${{ env.IMAGE }}:buildcache-${{ matrix.arch }},mode=max
# The runner cannot execute foreign binaries (no binfmt): exec format
# error on arm64. The code is pure Python, so amd64 covers it.
- name: Smoke test (--help, --version)
if: matrix.arch == 'amd64'
run: |
set -euo pipefail
img="$IMAGE:${{ github.sha }}-${{ matrix.arch }}"
docker run --rm --platform "linux/${{ matrix.arch }}" "$img" --version
docker run --rm --platform "linux/${{ matrix.arch }}" "$img" --help | grep -q -- --repeaters
- name: Trivy gate
uses: https://git.rfa.cz/tth-pub/ci-actions/trivy-gate@v11
with:
image: ${{ env.IMAGE }}:${{ github.sha }}-${{ matrix.arch }}
username: ${{ gitea.actor }}
password: ${{ secrets.REGISTRY_TOKEN }}
platform: linux/${{ matrix.arch }}
mode: block
skip: ${{ inputs.skip_trivy && 'true' || 'false' }}
# Pull, tag, push: latest-<arch> stays a plain single-platform manifest
# like the commit tag. `imagetools create` would wrap it in an OCI
# index, the kind of manifest `docker pull` from this registry is
# unreliable on.
- name: Move latest-${{ matrix.arch }}
run: |
set -euo pipefail
src="$IMAGE:${{ github.sha }}-${{ matrix.arch }}"
docker pull -q --platform "linux/${{ matrix.arch }}" "$src"
docker tag "$src" "$IMAGE:latest-${{ matrix.arch }}"
docker push -q "$IMAGE:latest-${{ matrix.arch }}"
if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
ver="${GITHUB_REF_NAME#v}-${{ matrix.arch }}"
docker tag "$src" "$IMAGE:$ver"
docker push -q "$IMAGE:$ver"
fi
release:
needs: build
if: startsWith(github.ref, 'refs/tags/v')
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: Release with the dashboard attached
env:
TOKEN: ${{ github.token }}
run: |
set -euo pipefail
api="${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}"
auth="header = \"Authorization: token $TOKEN\""
ver="${GITHUB_REF_NAME#v}"
body=$(cat <<EOF2
Images (one per architecture):
docker pull $IMAGE:$ver-amd64
docker pull $IMAGE:$ver-arm64
Docker stack: \`MC_VERSION=$ver\` in \`stack/.env\` pins this version.
Grafana: import the attached \`meshcore-repeater.json\`.
Setup and configuration: README.md.
EOF2
)
jq -n --arg t "$GITHUB_REF_NAME" --arg n "meshcore-exporter $ver" --arg b "$body" \
'{tag_name: $t, name: $n, body: $b}' >"$RUNNER_TEMP/rel.json"
id=$(curl -sSf --config - -X POST -H 'Content-Type: application/json' \
--data-binary "@$RUNNER_TEMP/rel.json" "$api/releases" <<<"$auth" | jq -r .id)
curl -sSf --config - -X POST -F "attachment=@dashboards/meshcore-repeater.json" \
"$api/releases/$id/assets?name=meshcore-repeater.json" <<<"$auth" >/dev/null
echo "release $GITHUB_REF_NAME (id $id)"
+61
View File
@@ -0,0 +1,61 @@
# PR check (Renovate and any other PR): the image must build like in
# image.yml, just without a push, and the tree's dependencies are scanned
# (report only). Renovate automerges only after this and ci.yml are green;
# the image after the merge is still guarded by the Trivy gate.
name: pr-check
"on":
pull_request:
# A newer push to the PR branch (Renovate rebases often) cancels the older run.
concurrency:
group: pr-check-${{ github.head_ref }}
cancel-in-progress: true
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: docker/setup-buildx-action@v4
# Read-only use of image.yml's layer cache: a PR never writes it.
- name: Registry login (cache import)
env:
REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
run: |
[ -z "$REGISTRY_TOKEN" ] ||
echo "$REGISTRY_TOKEN" | docker login git.rfa.cz -u "${{ gitea.actor }}" --password-stdin
- name: Build date
id: date
run: echo "day=$(date -u +%F)" >> "$GITHUB_OUTPUT"
- name: Build (no push)
uses: docker/build-push-action@v7
with:
context: .
push: false
load: true
pull: true
provenance: false
platforms: linux/amd64
build-args: OS_UPDATES=${{ steps.date.outputs.day }}
tags: meshcore-exporter:pr
cache-from: type=registry,ref=git.rfa.cz/tth-pub/meshcore-exporter:buildcache-amd64
- name: Smoke test (--help, --version)
run: |
set -euo pipefail
docker run --rm meshcore-exporter:pr --version
docker run --rm meshcore-exporter:pr --help | grep -q -- --repeaters
dependencies:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: Dependencies in the tree
uses: https://git.rfa.cz/tth-pub/ci-actions/trivy-gate@v11
with:
scan-type: fs
mode: warn
+12
View File
@@ -0,0 +1,12 @@
__pycache__/
*.egg-info/
.venv/
.pytest_cache/
.mypy_cache/
.ruff_cache/
build/
dist/
# your setup: passwords live here, never in git
stack/.env
repeaters.toml
stack/repeaters.toml
+5
View File
@@ -0,0 +1,5 @@
extends: default
rules:
line-length: {max: 120}
document-start: disable
truthy: {check-keys: false}
+63
View File
@@ -0,0 +1,63 @@
# 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.
2. USB companion: `ls -l /dev/serial/by-id/`. Use the by-id path, never
`/dev/ttyACM0` (it changes after a replug). Its group:
`stat -c '%G %g' <that path>`.
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.
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+26
View File
@@ -0,0 +1,26 @@
FROM python:3.15-slim@sha256:8c13a3f37a6a5b71498228e902c4b9f51c1f7900d49fabf71f9a650c6120e0d0
# Re-runs the security-update layer once a day despite the layer cache (CI
# passes the date).
ARG OS_UPDATES=none
RUN apt-get update && apt-get -y upgrade && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY requirements.txt .
# pip is not needed at runtime and vendors its own urllib3, msgpack and
# pkg_resources, which the Trivy gate flags whenever they lag behind: install,
# then remove pip and the ensurepip wheel.
RUN pip install --no-cache-dir -r requirements.txt \
&& pip uninstall -y pip \
&& rm -rf /usr/local/lib/python3*/ensurepip
COPY meshcore_exporter.py .
# The serial port belongs to group dialout (20) on most hosts; compose adds
# the group with `group_add` when it differs.
RUN useradd --system --uid 10001 --gid 20 --no-create-home exporter
USER exporter
EXPOSE 9200
HEALTHCHECK --interval=60s --timeout=5s --start-period=30s \
CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:9200/metrics', timeout=4)"
ENTRYPOINT ["python", "/app/meshcore_exporter.py"]
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 TeTeHacko
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
+205
View File
@@ -0,0 +1,205 @@
# 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](docs/dashboard.png)
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)](#1-kompletní-stack-docker) |
| vlastní Prometheus a Grafanu | [2. Jen exportér](#2-jen-exportér) |
| openHop (repeater nebo observer) a nechci kvůli tomu obětovat desku | [3. Bez vyhrazené desky: openHop](#3-bez-vyhrazené-desky-openhop) |
| AI agenta, který to rozjede za mě | dejte mu tohle repo; pravidla pro něj jsou v [AGENTS.md](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.](#3-bez-vyhrazené-desky-openhop)),
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)
```bash
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](https://git.rfa.cz/tth-pub/meshcore-exporter/releases)
ho připnete řádkem `MC_VERSION=1.0.0` v `.env`.
## 2. Jen exportér
Z Pythonu:
```bash
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):
```bash
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`](systemd/meshcore-exporter.service)
(postup v hlavičce souboru).
Do Prometheu:
```yaml
- job_name: meshcore_exporter
static_configs:
- targets: ["host:9200"]
```
Dashboard: importujte [`dashboards/meshcore-repeater.json`](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](https://github.com/openhop-dev/openhop_repeater) (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í):
```yaml
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.](#2-jen-exportér) 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`](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](https://meshcore.repeater.cz/nastaveni/telemetrie/)
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.
+376
View File
@@ -0,0 +1,376 @@
#!/usr/bin/env python3
"""Generate dashboards/meshcore-repeater.json (the Grafana dashboard).
Edit the panels here, run `python3 dashboards/generate.py`, commit both files.
The JSON works both for provisioning (stack/) and for a manual import: the
datasource and the job label are dashboard variables, nothing points at a
particular Grafana.
"""
import json
import sys
from pathlib import Path
if {"-h", "--help"} & set(sys.argv[1:]):
print((__doc__ or "").strip())
sys.exit(0)
DS = {"type": "prometheus", "uid": "${datasource}"}
SEL = 'job=~"$job", node="$node"'
def q(expr, legend=None, ref="A"):
t = {"datasource": DS, "expr": expr.replace("SEL", SEL).replace("[W]", "[$window]"), "refId": ref}
if legend:
t["legendFormat"] = legend
return t
def steps(*pairs):
return {"mode": "absolute", "steps": [{"color": c, "value": v} for v, c in pairs]}
def stat(pid, title, x, y, expr, unit, thr, desc=None, **defaults):
p = {
"id": pid,
"type": "stat",
"title": title,
"datasource": DS,
"gridPos": {"h": 5, "w": 4, "x": x, "y": y},
"fieldConfig": {"defaults": {"unit": unit, "thresholds": thr, **defaults}, "overrides": []},
"options": {
"colorMode": "value",
"graphMode": "area",
"justifyMode": "auto",
"textMode": "auto",
"reduceOptions": {"calcs": ["lastNotNull"], "fields": "", "values": False},
},
"targets": [q(expr)],
}
if desc:
p["description"] = desc
return p
def ts(pid, title, x, y, w, targets, unit, desc=None, h=8, overrides=None, **custom):
p = {
"id": pid,
"type": "timeseries",
"title": title,
"datasource": DS,
"gridPos": {"h": h, "w": w, "x": x, "y": y},
"fieldConfig": {
"defaults": {
"unit": unit,
"color": {"mode": "palette-classic"},
"custom": {
"drawStyle": "line",
"lineWidth": 1,
"fillOpacity": 10,
"showPoints": "never",
"spanNulls": 3600000,
**custom,
},
},
"overrides": overrides or [],
},
"options": {
"legend": {"displayMode": "list", "placement": "bottom", "showLegend": True},
"tooltip": {"mode": "multi", "sort": "none"},
},
"targets": [q(e, leg, chr(65 + i)) for i, (e, leg) in enumerate(targets)],
}
if desc:
p["description"] = desc
return p
def mirrored(up, down):
"""Overrides: `up` series above zero, `down` series drawn below it.
The axis label is rotated and reads bottom to top, so it names the lower
(down) half first.
negative-Y flips only the drawing; tooltip and legend keep the real
(positive) value. Fixed colours, so TX/RX look the same in every panel.
"""
def color(name, c):
return {
"matcher": {"id": "byName", "options": name},
"properties": [{"id": "color", "value": {"mode": "fixed", "fixedColor": c}}],
}
out = [color(name, c) for name, c in up]
for name, c in down:
o = color(name, c)
o["properties"].append({"id": "custom.transform", "value": "negative-Y"})
out.append(o)
return out
TX, RX, ERR = "orange", "blue", "red"
def row(pid, title, y):
return {
"id": pid,
"type": "row",
"title": title,
"collapsed": False,
"panels": [],
"gridPos": {"h": 1, "w": 24, "x": 0, "y": y},
}
BATTERY_PCT = (
"Lineární odhad z napětí: 3,30 V = 0 %, 4,20 V = 100 % (Li-ion článek). LiFePO4 nebo jiný článek "
"má jinou křivku; uprav výraz v panelu."
)
TEMP = "Externí senzor, pokud ho uzel má a exportér je přihlášený jako admin; jinak teplota MCU."
TX_TROUBLE = (
"TX start fail / TX timeout posílají jen některé forky firmwaru; na běžném firmwaru tu nic není. "
"Rostoucí timeout = rádio vysílání nedokončuje."
)
panels = [
stat(
1,
"Baterie % (odhad z napětí)",
0,
0,
"clamp(100 * (meshcore_battery_millivolts{SEL} - 3300) / 900, 0, 100)",
"percent",
steps((None, "red"), (20, "orange"), (40, "yellow"), (60, "green")),
BATTERY_PCT,
min=0,
max=100,
),
stat(
2,
"Teplota",
4,
0,
"meshcore_temperature_celsius{SEL}",
"celsius",
steps((None, "blue"), (0, "green"), (40, "orange")),
TEMP,
),
stat(3, "Uptime", 8, 0, "meshcore_uptime_seconds{SEL}", "s", steps((None, "green"))),
stat(
4,
"Stáří posledního čtení",
12,
0,
"time() - meshcore_last_scrape_success_timestamp{SEL}",
"s",
steps((None, "green"), (4000, "yellow"), (7500, "red")),
"Kdy naposledy uzel odpověděl. Při výchozím intervalu 1 h je normál do ~3600 s.",
),
stat(
5, "Fronta TX", 16, 0, "meshcore_queue_length{SEL}", "none", steps((None, "green"), (3, "yellow"), (8, "red"))
),
stat(
6,
"Šumové pozadí",
20,
0,
"meshcore_noise_floor_dbm{SEL}",
"dBm",
steps((None, "green"), (-105, "yellow"), (-95, "red")),
"Čím níž, tím líp. Nad −100 dBm uzel hůř slyší slabé signály (rušení, blízký vysílač).",
),
ts(
10,
"Baterie (mV)",
0,
5,
12,
[("meshcore_battery_millivolts{SEL}", "baterie")],
"mV",
axisSoftMin=3000,
axisSoftMax=4300,
),
ts(
11,
"Teplota a vlhkost",
12,
5,
12,
[("meshcore_temperature_celsius{SEL}", "teplota (°C)"), ("meshcore_humidity_percent{SEL}", "vlhkost (%)")],
"celsius",
TEMP,
overrides=[
{
"matcher": {"id": "byName", "options": "vlhkost (%)"},
"properties": [{"id": "unit", "value": "humidity"}, {"id": "custom.axisPlacement", "value": "right"}],
}
],
),
ts(
12,
"Provoz — pakety za hodinu",
0,
13,
12,
[
("rate(meshcore_packets_received_total{SEL}[W]) * 3600", "přijato"),
("rate(meshcore_packets_sent_total{SEL}[W]) * 3600", "odesláno"),
("rate(meshcore_receive_errors_total{SEL}[W]) * 3600", "chyby příjmu (CRC)"),
],
"none",
"Nad nulou odeslané pakety, pod nulou přijaté a chyby příjmu.",
overrides=mirrored([("odesláno", TX)], [("přijato", RX), ("chyby příjmu (CRC)", ERR)]),
axisLabel="↓ přijato / ↑ odesláno",
),
ts(
13,
"Signál — RSSI / SNR / šum",
12,
13,
12,
[
("meshcore_last_rssi_dbm{SEL}", "RSSI posledního paketu (dBm)"),
("meshcore_last_snr_db{SEL}", "SNR posledního paketu (dB)"),
("meshcore_noise_floor_dbm{SEL}", "šumové pozadí (dBm)"),
],
"none",
),
ts(
14,
"Airtime za hodinu (s)",
0,
21,
12,
[
("rate(meshcore_tx_airtime_seconds_total{SEL}[W]) * 3600", "vysílání"),
("rate(meshcore_rx_airtime_seconds_total{SEL}[W]) * 3600", "příjem"),
],
"s",
"Nad nulou čas vysílání, pod nulou čas příjmu.",
overrides=mirrored([("vysílání", TX)], [("příjem", RX)]),
axisLabel="↓ příjem / ↑ vysílání",
),
ts(
15,
"Přeposílání a potíže s vysíláním (za hodinu)",
12,
21,
12,
[
("rate(meshcore_packets_sent_flood_total{SEL}[W]) * 3600", "flood přeposláno"),
("rate(meshcore_packets_sent_direct_total{SEL}[W]) * 3600", "direct přeposláno"),
("rate(meshcore_flood_duplicates_total{SEL}[W]) * 3600", "flood duplikáty"),
("rate(meshcore_tx_start_fail_total{SEL}[W]) * 3600", "TX start fail"),
("rate(meshcore_tx_timeout_total{SEL}[W]) * 3600", "TX timeout"),
],
"none",
TX_TROUBLE,
),
row(20, "Baterie a duty cycle", 29),
stat(
21,
"Trend baterie (mV/h, + nabíjí)",
0,
30,
"deriv(meshcore_battery_millivolts{SEL}[W]) * 3600",
"none",
steps((None, "red"), (0, "green")),
"Změna napětí za hodinu, spočítaná z okna `Okno`.",
decimals=0,
),
stat(
22,
"TX duty cycle",
4,
30,
"rate(meshcore_tx_airtime_seconds_total{SEL}[W]) * 100",
"percent",
steps((None, "green"), (5, "yellow"), (10, "red")),
"Podíl času, kdy uzel vysílá. Pásmo 869,4–869,65 MHz v EU dovoluje 10 %.",
decimals=2,
),
ts(
23,
"Duty cycle %",
8,
30,
16,
[
("rate(meshcore_tx_airtime_seconds_total{SEL}[W]) * 100", "vysílání (TX)"),
("rate(meshcore_rx_airtime_seconds_total{SEL}[W]) * 100", "příjem (RX)"),
],
"percent",
"Nad nulou podíl času vysílání (limit pásma 10 %), pod nulou příjmu.",
h=6,
overrides=mirrored([("vysílání (TX)", TX)], [("příjem (RX)", RX)]),
axisLabel="↓ RX / ↑ TX",
),
]
# the two stat panels in the last row are 6 high to match the graph
for p in panels:
if p["id"] in (21, 22):
p["gridPos"].update(h=6)
dashboard = {
"uid": "meshcore-repeater",
"title": "MeshCore — repeater $node",
"description": "Stav MeshCore repeaterů čtený přes mesh (meshcore-exporter).",
"tags": ["meshcore", "lora"],
"editable": True,
"graphTooltip": 1,
"refresh": "5m",
"schemaVersion": 39,
"time": {"from": "now-24h", "to": "now"},
"timezone": "browser",
"templating": {
"list": [
{
"name": "datasource",
"label": "Zdroj dat",
"type": "datasource",
"query": "prometheus",
"current": {},
"hide": 0,
},
{
"name": "job",
"label": "Job",
"type": "textbox",
"query": "meshcore_exporter",
"current": {"text": "meshcore_exporter", "value": "meshcore_exporter"},
"hide": 0,
"description": "Hodnota labelu job, pod kterým Prometheus exportér scrapuje (regex).",
},
{
"name": "window",
"label": "Okno",
"type": "custom",
"query": "1h,3h,6h,12h",
"current": {"text": "3h", "value": "3h"},
"options": [{"text": w, "value": w, "selected": w == "3h"} for w in ("1h", "3h", "6h", "12h")],
"hide": 0,
"description": "Okno pro rychlosti a duty cycle. Data se mění jen při čtení repeateru, "
"takže okno má být aspoň 2–3× interval čtení (výchozí 1 h → 3h).",
},
{
"name": "node",
"label": "Repeater",
"type": "query",
"datasource": DS,
"definition": 'label_values(meshcore_uptime_seconds{job=~"$job"}, node)',
"query": {"query": 'label_values(meshcore_uptime_seconds{job=~"$job"}, node)', "refId": "node"},
"refresh": 2,
"sort": 1,
"current": {},
"hide": 0,
},
]
},
"annotations": {"list": []},
"panels": panels,
}
out = Path(__file__).with_name("meshcore-repeater.json")
out.write_text(json.dumps(dashboard, indent=2, ensure_ascii=False) + "\n")
print(f"wrote {out}")
File diff suppressed because it is too large. Load diff
Binary file not shown.

After

Width:  |  Height:  |  Size: 374 KiB

+582
View File
@@ -0,0 +1,582 @@
#!/usr/bin/env python3
"""Prometheus exporter for MeshCore repeaters, read over the mesh itself.
A companion radio (USB, TCP or BLE) logs in to each repeater in turn, asks for
its status and telemetry with direct packets (no flood) and serves the numbers
on http://<listen>:9200/metrics: battery, temperature, noise floor, RSSI/SNR,
packet counters, airtime, uptime, TX queue.
Every reading costs airtime on a shared channel (~0.8 s per repeater on the
Czech preset), so the interval defaults to an hour and cannot go below 15 minutes.
How often do you really need the numbers? See
https://meshcore.repeater.cz/nastaveni/telemetrie/
Configuration: command line, or the same thing in MC_* environment variables
(the Docker way), or a TOML file with one block per repeater (--config).
Command line beats environment beats the file's defaults.
meshcore-exporter --serial /dev/serial/by-id/usb-... --repeaters my-rpt --password secret
meshcore-exporter --config repeaters.toml --check # one round, print, exit
Only one program may talk to a companion at a time: stop any app (phone, Meshy,
meshcli) that holds the same radio first.
"""
from __future__ import annotations
import argparse
import asyncio
import logging
import os
import sys
import time
from dataclasses import dataclass
from typing import Any
__version__ = "1.0.0"
MIN_INTERVAL = 900
DEFAULT_INTERVAL = 3600
# A failed repeater is retried once after this, not after the full interval:
# a lost reply on air is common, and a repeater also drops a login whose
# timestamp is not newer than the last one from the same client (replay
# check). Seen right after `--check`: two refused logins, then fine.
RETRY_AFTER = 180
CONTACTS_TIMEOUT = 30
@dataclass
class Target:
name: str # the repeater's advertised name, also the `node` label
password: str = ""
pubkey: str = "" # hex prefix; creates the contact if the companion lacks it
path: str = "" # hex hop hashes forced as the route before each read
def parse_targets(raw: str, password: str) -> list[Target]:
"""`name[=pubkey][@path]`, comma separated; every one gets `password`."""
out = []
for item in raw.split(","):
item = item.strip()
if not item:
continue
name, _, rest = item.partition("=")
if "@" in name: # name@path without a pubkey
name, _, rest = item.partition("@")
rest = "@" + rest
pubkey, _, path = rest.partition("@")
out.append(Target(name.strip(), password, pubkey.strip().lower(), path.strip().lower()))
return out
def load_config(path: str) -> tuple[dict[str, Any], list[Target]]:
"""TOML: top-level keys are option defaults, [[repeater]] blocks the targets."""
try:
import tomllib
except ImportError as e: # Python 3.10
raise ValueError("--config needs Python 3.11+; use --repeaters/--password instead") from e
with open(path, "rb") as f:
data = tomllib.load(f)
blocks = data.pop("repeater", [])
default_pw = str(data.get("password", ""))
targets = []
for b in blocks:
if "name" not in b:
raise ValueError(f"{path}: a [[repeater]] block has no name")
targets.append(
Target(
str(b["name"]),
str(b.get("password", default_pw)),
str(b.get("pubkey", "")).lower(),
str(b.get("path", "")).lower(),
)
)
return data, targets
def build_parser() -> argparse.ArgumentParser:
env = os.environ.get
p = argparse.ArgumentParser(
prog="meshcore-exporter",
description=(__doc__ or "").split("\n\n")[0],
epilog="Environment: every option has an MC_* twin, e.g. MC_SERIAL, MC_TCP, MC_BLE, "
"MC_REPEATERS, MC_PASSWORD, MC_INTERVAL, MC_CONFIG. See README.md.",
formatter_class=argparse.RawDescriptionHelpFormatter,
)
radio = p.add_argument_group("companion radio (pick one)")
radio.add_argument(
"--serial",
default=env("MC_SERIAL") or env("MC_PORT"),
help="USB serial port, best /dev/serial/by-id/... [MC_SERIAL]",
)
radio.add_argument("--baud", type=int, default=int(env("MC_BAUD", "115200")), help="[MC_BAUD]")
radio.add_argument("--tcp", default=env("MC_TCP"), help="host:port of a TCP companion [MC_TCP]")
radio.add_argument("--ble", default=env("MC_BLE"), help="BLE address of the companion [MC_BLE]")
radio.add_argument("--ble-pin", default=env("MC_BLE_PIN"), help="BLE pairing PIN [MC_BLE_PIN]")
tg = p.add_argument_group("repeaters")
tg.add_argument(
"--config",
default=env("MC_CONFIG"),
help="TOML file with [[repeater]] blocks (per-repeater password, pubkey, path) [MC_CONFIG]",
)
tg.add_argument(
"--repeaters",
default=env("MC_REPEATERS"),
help="name[=pubkey][@path],... -- name as the repeater advertises it [MC_REPEATERS]",
)
tg.add_argument(
"--password", default=env("MC_PASSWORD"), help="admin or guest password for --repeaters [MC_PASSWORD]"
)
rf = p.add_argument_group("mesh")
rf.add_argument(
"--interval",
type=int,
default=_int_or_none(env("MC_INTERVAL")),
help=f"seconds between rounds, min {MIN_INTERVAL}, default {DEFAULT_INTERVAL} [MC_INTERVAL]",
)
rf.add_argument(
"--rf-timeout",
type=int,
default=_int_or_none(env("MC_RF_TIMEOUT")),
help="seconds to wait for one reply, default 30 [MC_RF_TIMEOUT]",
)
rf.add_argument(
"--path-hash-bytes",
type=int,
choices=(1, 2, 3),
default=_int_or_none(env("MC_PATH_HASH_BYTES")),
help="set the companion's path hash width on connect; unset = leave it "
"(the Czech mesh uses 2) [MC_PATH_HASH_BYTES]",
)
srv = p.add_argument_group("metrics")
srv.add_argument("--listen", default=env("MC_LISTEN"), help="address, default 0.0.0.0 [MC_LISTEN]")
srv.add_argument(
"--port", type=int, default=_int_or_none(env("MC_METRICS_PORT")), help="port, default 9200 [MC_METRICS_PORT]"
)
p.add_argument(
"--check", action="store_true", help="read every repeater once, print the values and exit (0 = all answered)"
)
p.add_argument("--log-level", default=env("MC_LOG_LEVEL", "INFO"), help="[MC_LOG_LEVEL]")
p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
return p
def _int_or_none(v: str | None) -> int | None:
return int(v) if v else None
@dataclass
class Settings:
serial: str | None
baud: int
tcp: str | None
ble: str | None
ble_pin: str | None
targets: list[Target]
interval: int
rf_timeout: int
path_hash_bytes: int | None
listen: str
port: int
check: bool
def resolve(args: argparse.Namespace) -> Settings:
"""Merge command line/env with the config file; raise ValueError on a bad setup."""
file_opts: dict[str, Any] = {}
targets: list[Target] = []
if args.config:
file_opts, targets = load_config(args.config)
if args.repeaters:
targets += parse_targets(args.repeaters, args.password or str(file_opts.get("password", "")))
if not targets:
raise ValueError("no repeater given: --repeaters, MC_REPEATERS or [[repeater]] in --config")
def pick(name: str, default: Any) -> Any:
v = getattr(args, name)
return v if v is not None else file_opts.get(name, default)
serial, tcp, ble = pick("serial", None), pick("tcp", None), pick("ble", None)
if sum(bool(x) for x in (serial, tcp, ble)) != 1:
raise ValueError("give exactly one companion: --serial, --tcp or --ble")
interval = int(pick("interval", DEFAULT_INTERVAL))
if interval < MIN_INTERVAL:
logging.warning("interval %d s is too short for a shared channel, using %d", interval, MIN_INTERVAL)
interval = MIN_INTERVAL
phb = pick("path_hash_bytes", None)
return Settings(
serial,
int(pick("baud", 115200)),
tcp,
ble,
pick("ble_pin", None),
targets,
interval,
int(pick("rf_timeout", 30)),
int(phb) if phb else None,
str(pick("listen", "0.0.0.0")),
int(pick("port", 9200)),
args.check,
)
# --- metrics ---------------------------------------------------------------
# status field -> (metric name without the meshcore_ prefix, help)
STATUS_FIELDS = {
"bat": ("battery_millivolts", "Battery voltage in millivolts"),
"tx_queue_len": ("queue_length", "Outbound packet queue length"),
"noise_floor": ("noise_floor_dbm", "Radio noise floor in dBm"),
"last_rssi": ("last_rssi_dbm", "RSSI of the last received packet in dBm"),
"last_snr": ("last_snr_db", "SNR of the last received packet in dB"),
"uptime": ("uptime_seconds", "Device uptime in seconds"),
"airtime": ("tx_airtime_seconds_total", "Cumulative transmit airtime in seconds"),
"rx_airtime": ("rx_airtime_seconds_total", "Cumulative receive airtime in seconds"),
"nb_recv": ("packets_received_total", "Packets received"),
"nb_sent": ("packets_sent_total", "Packets sent"),
"sent_flood": ("packets_sent_flood_total", "Flood packets sent"),
"sent_direct": ("packets_sent_direct_total", "Direct packets sent"),
"recv_flood": ("packets_received_flood_total", "Flood packets received"),
"recv_direct": ("packets_received_direct_total", "Direct packets received"),
"flood_dups": ("flood_duplicates_total", "Duplicate flood packets dropped"),
"direct_dups": ("direct_duplicates_total", "Duplicate direct packets dropped"),
"recv_errors": ("receive_errors_total", "Packets received with a bad CRC"),
"full_evts": ("queue_full_events_total", "Times the TX queue was full"),
# Only some firmware forks append these to the status frame; on stock
# firmware they are absent and not exported at all.
"tx_start_fail": ("tx_start_fail_total", "Transmits the radio refused to start (requeued)"),
"tx_timeout": ("tx_timeout_total", "Transmits that never completed (requeued)"),
}
# telemetry (Cayenne LPP) type -> metric; the first reading of a type wins,
# which is the external sensor when the node has one, the MCU otherwise.
# A guest login gets voltage and MCU temperature only.
TELEMETRY_FIELDS = {
"voltage": ("telemetry_voltage", "Battery voltage from telemetry (V)"),
"temperature": ("temperature_celsius", "Temperature (external sensor, else MCU) in Celsius"),
"humidity": ("humidity_percent", "Relative humidity in percent"),
"barometer": ("pressure_hpa", "Barometric pressure in hPa"),
}
class Metrics:
def __init__(self) -> None:
from prometheus_client import Counter, Gauge, Info
self.status = {k: Gauge(f"meshcore_{n}", d, ["node"]) for k, (n, d) in STATUS_FIELDS.items()}
self.telemetry = {k: Gauge(f"meshcore_{n}", d, ["node"]) for k, (n, d) in TELEMETRY_FIELDS.items()}
self.up = Gauge("meshcore_up", "1 if the last read of the repeater succeeded", ["node"])
self.last_ok = Gauge(
"meshcore_last_scrape_success_timestamp", "Unix time of the last successful read", ["node"]
)
self.errors = Counter("meshcore_scrape_errors", "Failed reads", ["node"])
self.logins = Counter("meshcore_repeater_logins", "Logins performed", ["node"])
Info("meshcore_exporter", "Exporter version").info({"version": __version__})
def extend_status_parser() -> None:
"""Read the two counters some forks append to the status frame.
The library reads fixed offsets and ignores a longer frame; bytes 56..64
after the header hold tx_start_fail and tx_timeout. Without them both stay
None and are not exported.
"""
try:
import meshcore.parsing as parsing
import meshcore.reader as reader
except ImportError:
return
orig = parsing.parse_status
def parse_status(data, pubkey_prefix=None, offset=0): # type: ignore[no-untyped-def]
res = orig(data, pubkey_prefix, offset)
off = 8 if pubkey_prefix is None else offset
if len(data) >= off + 64:
res["tx_start_fail"] = int.from_bytes(data[off + 56 : off + 60], "little")
res["tx_timeout"] = int.from_bytes(data[off + 60 : off + 64], "little")
else:
res["tx_start_fail"] = res["tx_timeout"] = None
return res
parsing.parse_status = parse_status
if hasattr(reader, "parse_status"):
reader.parse_status = parse_status # the reader imported the name itself
# --- mesh ------------------------------------------------------------------
log = logging.getLogger("meshcore-exporter")
class Exporter:
def __init__(self, s: Settings, metrics: Metrics | None) -> None:
self.s = s
self.m = metrics
self.contacts: dict[str, dict[str, Any]] = {}
self._contact_list: list[dict[str, Any]] | None = None
async def connect(self) -> Any:
from meshcore import MeshCore
s = self.s
if s.tcp:
host, _, port = s.tcp.rpartition(":")
mc = await MeshCore.create_tcp(host=host or s.tcp, port=int(port or 5000))
elif s.ble:
mc = await MeshCore.create_ble(address=s.ble, pin=s.ble_pin)
else:
mc = await MeshCore.create_serial(s.serial or "", s.baud)
if mc is None:
raise RuntimeError("the companion does not answer (wrong port, or another app holds it?)")
if s.path_hash_bytes:
# The width of hashes in packets the companion ORIGINATES is its own
# pref; a 1-byte hash collides with many repeaters on a 2-byte mesh.
try:
if (await mc.commands.get_path_hash_mode()) != s.path_hash_bytes - 1:
await mc.commands.set_path_hash_mode(s.path_hash_bytes - 1)
log.info("companion path hash set to %d B", s.path_hash_bytes)
except Exception as e: # noqa: BLE001 -- older companion firmware
log.warning("could not set the path hash width: %s", e)
return mc
async def contact_list(self, mc: Any) -> list[dict[str, Any]]:
"""The companion's contacts, fetched once per round.
A companion that has heard the whole mesh holds hundreds of contacts;
streaming them takes seconds, and asking again for every repeater made
the second request time out (library default 5 s).
"""
from meshcore import EventType
if self._contact_list is None:
for attempt in (1, 2):
res = await mc.commands.get_contacts(timeout=CONTACTS_TIMEOUT)
if res is not None and res.type != EventType.ERROR:
self._contact_list = list((res.payload or {}).values())
break
if attempt == 2:
raise RuntimeError(f"get_contacts failed: {res}")
return self._contact_list or []
async def contact(self, mc: Any, t: Target) -> dict[str, Any]:
"""The contact by name, else by pubkey, else created from the pubkey."""
contacts = await self.contact_list(mc)
for c in contacts:
if c.get("adv_name") == t.name:
return dict(c)
if t.pubkey:
for c in contacts:
if (c.get("public_key") or "").lower().startswith(t.pubkey):
return dict(c)
if len(t.pubkey) == 64:
# A login is encrypted with a secret derived from the contact,
# so a repeater never heard by this companion needs one made.
log.info("%s: no contact, creating it from the public key", t.name)
await mc.commands.add_contact(
{
"public_key": t.pubkey,
"type": 2,
"flags": 0,
"out_path": "",
"out_path_len": -1,
"out_path_hash_mode": 0,
"adv_name": t.name,
"last_advert": 0,
"adv_lat": 0.0,
"adv_lon": 0.0,
}
)
await asyncio.sleep(2)
self._contact_list = None
return await self.contact(mc, Target(t.name, t.password, t.pubkey[:12]))
raise RuntimeError(
f"no contact '{t.name}' on the companion: wait for its advert, or give the full 64-hex public key"
)
async def pin_path(self, mc: Any, t: Target, c: dict[str, Any]) -> None:
"""Force a fixed route (a local companion command, nothing on air).
For a link that works one way only: the companion learns a 0-hop route
from the repeater's advert even when the repeater cannot hear it back.
"""
if not t.path:
return
mode = (self.s.path_hash_bytes or 2) - 1
if c.get("out_path") == t.path and c.get("out_path_hash_mode") == mode:
return
from meshcore import EventType
res = await mc.commands.change_contact_path(c, t.path, path_hash_mode=mode)
if res is None or res.type == EventType.ERROR:
raise RuntimeError(f"could not set path {t.path}: {res}")
c["out_path"], c["out_path_hash_mode"] = t.path, mode
log.info("%s: route pinned to %s", t.name, t.path)
async def login(self, mc: Any, t: Target, c: dict[str, Any]) -> None:
from meshcore import EventType
res = await mc.commands.send_login_sync(c, t.password, timeout=self.s.rf_timeout)
if res is None or res.type == EventType.ERROR:
raise RuntimeError("login failed (wrong password, or no reply on the mesh)")
if self.m:
self.m.logins.labels(node=t.name).inc()
async def read(self, mc: Any, t: Target) -> dict[str, float]:
"""One status + telemetry round of one repeater."""
if t.name not in self.contacts:
self.contacts[t.name] = await self.contact(mc, t)
await self.pin_path(mc, t, self.contacts[t.name])
await self.login(mc, t, self.contacts[t.name])
c = self.contacts[t.name]
await self.pin_path(mc, t, c)
st = await mc.commands.req_status_sync(c, timeout=self.s.rf_timeout)
if st is None: # the repeater forgot us (reboot): log in again
await self.login(mc, t, c)
st = await mc.commands.req_status_sync(c, timeout=self.s.rf_timeout)
if st is None:
raise RuntimeError("no status reply, not even after a new login")
values = {k: float(st[k]) for k in STATUS_FIELDS if st.get(k) is not None}
tel = await mc.commands.req_telemetry_sync(c, timeout=self.s.rf_timeout)
if isinstance(tel, dict):
tel = tel.get("lpp", [])
for ch in tel or []:
kind = ch.get("type")
if kind in TELEMETRY_FIELDS and kind not in values and isinstance(ch.get("value"), (int, float)):
values[kind] = float(ch["value"])
return values
def publish(self, t: Target, values: dict[str, float]) -> None:
if not self.m:
return
for k, v in values.items():
gauge = self.m.status.get(k) or self.m.telemetry.get(k)
if gauge is not None:
gauge.labels(node=t.name).set(v)
self.m.up.labels(node=t.name).set(1)
self.m.last_ok.labels(node=t.name).set(time.time())
def failed(self, t: Target) -> None:
if self.m:
self.m.errors.labels(node=t.name).inc()
self.m.up.labels(node=t.name).set(0)
async def round(self, mc: Any, targets: list[Target] | None = None) -> list[Target]:
"""Read `targets` (default all); return the ones that failed."""
failed = []
self._contact_list = None
for t in targets if targets is not None else self.s.targets:
try:
values = await self.read(mc, t)
except Exception as e: # noqa: BLE001 -- one dead repeater must not stop the others
self.failed(t)
self.contacts.pop(t.name, None)
log.warning("%s: %s", t.name, e)
failed.append(t)
continue
self.publish(t, values)
log.info(
"%s: OK bat=%smV up=%ss recv=%s sent=%s",
t.name,
_i(values.get("bat")),
_i(values.get("uptime")),
_i(values.get("nb_recv")),
_i(values.get("nb_sent")),
)
if self.s.check:
for k, v in sorted(values.items()):
name = (STATUS_FIELDS.get(k) or TELEMETRY_FIELDS[k])[0]
print(f' meshcore_{name}{{node="{t.name}"}} {v:g}')
return failed
async def run(self) -> int:
if self.s.check:
try:
mc = await self.connect()
except RuntimeError:
raise
except Exception as e: # noqa: BLE001 -- serial/BLE/TCP errors: one line, not a traceback
raise RuntimeError(f"cannot open the companion: {e}") from e
try:
ok = len(self.s.targets) - len(await self.round(mc))
finally:
await mc.disconnect()
print(f"{ok}/{len(self.s.targets)} repeaters answered")
return 0 if ok == len(self.s.targets) else 1
fails = 0
while True:
mc = None
try:
mc = await self.connect()
self.contacts.clear()
while True:
# Reconnect only after rounds with NO success at all: one
# unreachable repeater must not stop reading the others.
failed = await self.round(mc)
wait = self.s.interval
if failed and RETRY_AFTER < self.s.interval:
names = ", ".join(t.name for t in failed)
log.info("retrying %s in %d s", names, RETRY_AFTER)
await asyncio.sleep(RETRY_AFTER)
failed = await self.round(mc, failed)
wait -= RETRY_AFTER
fails = fails + 1 if len(failed) == len(self.s.targets) else 0
if fails >= 3:
raise RuntimeError("3 rounds in a row without a single answer")
await asyncio.sleep(wait)
except Exception as e: # noqa: BLE001
for t in self.s.targets:
self.failed(t)
log.error("companion: %s -- reconnecting in 30 s", e)
if mc is not None:
try:
await mc.disconnect()
except Exception: # noqa: BLE001
pass
await asyncio.sleep(30)
def _i(v: float | None) -> str:
return "?" if v is None else f"{v:.0f}"
def main(argv: list[str] | None = None) -> int:
args = build_parser().parse_args(argv) # --help / --version exit here, before any import
logging.basicConfig(level=args.log_level.upper(), format="%(asctime)s %(levelname)s %(message)s")
try:
s = resolve(args)
except (ValueError, OSError) as e:
print(f"meshcore-exporter: {e}", file=sys.stderr)
return 2
extend_status_parser()
metrics = None
if not s.check:
from prometheus_client import start_http_server
metrics = Metrics()
start_http_server(s.port, addr=s.listen)
log.info(
"metrics on %s:%d/metrics, %d repeater(s), every %d s, companion %s",
s.listen,
s.port,
len(s.targets),
s.interval,
f"tcp {s.tcp}" if s.tcp else f"ble {s.ble}" if s.ble else f"serial {s.serial}",
)
try:
return asyncio.run(Exporter(s, metrics).run())
except KeyboardInterrupt:
return 130
except RuntimeError as e:
print(f"meshcore-exporter: {e}", file=sys.stderr)
return 1
if __name__ == "__main__":
sys.exit(main())
+36
View File
@@ -0,0 +1,36 @@
[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"
[project]
name = "meshcore-exporter"
dynamic = ["version"]
description = "Prometheus exporter for MeshCore repeaters, read over the mesh"
readme = "README.md"
license = "MIT"
requires-python = ">=3.10"
dependencies = [
"meshcore>=2.3",
"prometheus_client>=0.20",
]
[project.optional-dependencies]
dev = ["pytest", "ruff", "mypy"]
[project.scripts]
meshcore-exporter = "meshcore_exporter:main"
[tool.setuptools]
py-modules = ["meshcore_exporter"]
[tool.setuptools.dynamic]
version = { attr = "meshcore_exporter.__version__" }
[tool.ruff]
line-length = 120
[tool.ruff.lint]
select = ["E", "F", "W", "I", "B", "UP"]
[tool.mypy]
ignore_missing_imports = true
+24
View File
@@ -0,0 +1,24 @@
# Copy to repeaters.toml (git ignores it) and fill in. Top-level keys are the
# defaults of the command-line options; command line and MC_* env win.
# The companion radio -- exactly one of these:
serial = "/dev/serial/by-id/usb-REPLACE_ME-if00" # `ls /dev/serial/by-id/`
# tcp = "192.168.1.50:5000" # WiFi companion
# ble = "AA:BB:CC:DD:EE:FF" # BLE companion
# ble_pin = "123456"
interval = 3600 # seconds between rounds (min 900)
# path_hash_bytes = 2 # Czech mesh: 2
# Default password for the blocks below that have none. Admin or guest:
# a guest gets everything except external sensors (humidity, ambient temp).
password = "REPLACE_ME"
[[repeater]]
name = "my-repeater" # exactly as the repeater advertises itself
# [[repeater]]
# name = "other-repeater"
# password = "its own password"
# pubkey = "64 hex chars" # only if the companion never heard its advert
# path = "5361" # force a route via other repeaters (hex hop hashes)
+3
View File
@@ -0,0 +1,3 @@
# Exact versions for the container image; pyproject.toml has the ranges.
meshcore==2.3.17
prometheus_client==0.26.0
+35
View File
@@ -0,0 +1,35 @@
# Copy to .env (git ignores it) and fill in the REPLACE_ME lines.
# --- the companion: EITHER a radio on USB (A) OR an openHop companion (B) ----
# (A) USB
MC_SERIAL=/dev/meshcore
# `ls -l /dev/serial/by-id/` -- the long name stays the same after a replug,
# /dev/ttyACM0 does not.
MC_SERIAL_HOST=/dev/serial/by-id/REPLACE_ME
# group of that port on this computer: `stat -c %g /dev/ttyACM0`
MC_SERIAL_GID=20
# (B) openHop on this machine (README "Bez vyhrazené desky"): delete the three
# MC_SERIAL* lines above and uncomment these two
# MC_TCP=127.0.0.1:5002
# COMPOSE_FILE=docker-compose.yml:docker-compose.host.yml
# amd64 = PC; arm64 = Raspberry Pi 4/5 with a 64-bit system
MC_ARCH=amd64
# latest, or a release (e.g. 1.0.0) to stay on it
MC_VERSION=latest
# --- the repeaters ------------------------------------------------------------
# Name exactly as the repeater advertises it; several: comma separated.
MC_REPEATERS=REPLACE_ME
# Admin or guest password of the repeater(s). Guest: all but external sensors.
MC_PASSWORD=REPLACE_ME
# Seconds between readings (min 900). Each reading takes ~1 s of a channel
# everyone shares. A battery does not change in minutes: an hour is plenty;
# https://meshcore.repeater.cz/nastaveni/telemetrie/
MC_INTERVAL=3600
# Czech mesh: 2 (width of route hashes in packets this radio sends)
MC_PATH_HASH_BYTES=2
# --- Grafana ------------------------------------------------------------------
GRAFANA_PASSWORD=REPLACE_ME
GRAFANA_PORT=3000
+38
View File
@@ -0,0 +1,38 @@
# openHop on this machine: everything on the host network, so the exporter
# reaches the openHop companion on 127.0.0.1 -- no Docker-bridge-to-host
# traffic, which host firewalls (ufw, the default nftables ruleset) block.
#
# Enable it with one line in .env:
# COMPOSE_FILE=docker-compose.yml:docker-compose.host.yml
#
# Exporter and Prometheus listen on 127.0.0.1 only; Grafana on GRAFANA_PORT
# of every interface, as in the default setup.
services:
exporter:
network_mode: host
environment:
MC_LISTEN: 127.0.0.1
MC_METRICS_PORT: "9200"
prometheus:
network_mode: host
command:
- --config.file=/etc/prometheus/prometheus.yml
- --storage.tsdb.path=/prometheus
- --storage.tsdb.retention.time=${PROMETHEUS_RETENTION:-400d}
- --web.listen-address=127.0.0.1:${PROMETHEUS_PORT:-9090}
volumes: !override
- ./host-network/prometheus.yml:/etc/prometheus/prometheus.yml:ro
- prometheus:/prometheus
grafana:
network_mode: host
ports: !reset []
environment:
GF_SERVER_HTTP_PORT: ${GRAFANA_PORT:-3000}
PROMETHEUS_PORT: ${PROMETHEUS_PORT:-9090}
volumes: !override
- ./grafana/provisioning/dashboards:/etc/grafana/provisioning/dashboards:ro
- ./host-network/datasource.yml:/etc/grafana/provisioning/datasources/prometheus.yml:ro
- ../dashboards:/var/lib/grafana/dashboards:ro
- grafana:/var/lib/grafana
+58
View File
@@ -0,0 +1,58 @@
# Exporter + Prometheus + Grafana with the dashboard ready.
#
# cp .env.example .env # fill in: port of the radio, repeater, password
# docker compose up -d
# open http://localhost:3000 (admin / GRAFANA_PASSWORD from .env)
#
# Already have Prometheus and Grafana? You do not need this file: run only the
# exporter (README, section "Jen exportér").
services:
exporter:
image: git.rfa.cz/tth-pub/meshcore-exporter:${MC_VERSION:-latest}-${MC_ARCH:-amd64}
# build: .. # or build it from this checkout instead
restart: unless-stopped
env_file: .env
# USB companion: MC_SERIAL_HOST in .env is mapped here. Without one
# (openHop companion over TCP) /dev/null stands in and nothing uses it.
# openHop on this machine: docker-compose.host.yml (see .env.example).
devices:
- "${MC_SERIAL_HOST:-/dev/null}:/dev/meshcore"
# The serial port's group on the host (`stat -c %g /dev/ttyACM0`):
# dialout = 20 on Debian/Ubuntu/Raspberry Pi OS, uucp = 986 on Arch.
group_add:
- "${MC_SERIAL_GID:-20}"
# Per-repeater passwords: put them in repeaters.toml (see
# repeaters.example.toml), set MC_CONFIG=/config/repeaters.toml in .env
# and uncomment the volume:
volumes: []
# - ./repeaters.toml:/config/repeaters.toml:ro
prometheus:
image: prom/prometheus:v3.15.1@sha256:fa3302279710be2f21a8301ec17a8b4f2301fd829bd113839b3b6b02b6f191a2
restart: unless-stopped
command:
- --config.file=/etc/prometheus/prometheus.yml
- --storage.tsdb.path=/prometheus
- --storage.tsdb.retention.time=${PROMETHEUS_RETENTION:-400d}
volumes:
- ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
- prometheus:/prometheus
grafana:
image: grafana/grafana:13.3.0@sha256:488984b716c0862639f91a698adbe2862677a5a07bad42da5f03f3030883b205
restart: unless-stopped
ports:
- "${GRAFANA_PORT:-3000}:3000"
environment:
GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD:?set GRAFANA_PASSWORD in .env}
GF_ANALYTICS_REPORTING_ENABLED: "false"
GF_DASHBOARDS_DEFAULT_HOME_DASHBOARD_PATH: /var/lib/grafana/dashboards/meshcore-repeater.json
volumes:
- ./grafana/provisioning:/etc/grafana/provisioning:ro
- ../dashboards:/var/lib/grafana/dashboards:ro
- grafana:/var/lib/grafana
volumes:
prometheus:
grafana:
Whitespace-only changes.
@@ -0,0 +1,8 @@
apiVersion: 1
providers:
- name: meshcore
type: file
disableDeletion: true
allowUiUpdates: false
options:
path: /var/lib/grafana/dashboards
@@ -0,0 +1,8 @@
apiVersion: 1
datasources:
- name: Prometheus
type: prometheus
uid: prometheus
access: proxy
url: http://prometheus:9090
isDefault: true
Whitespace-only changes.
+9
View File
@@ -0,0 +1,9 @@
# docker-compose.host.yml: Prometheus on the host's loopback
apiVersion: 1
datasources:
- name: Prometheus
type: prometheus
uid: prometheus
access: proxy
url: http://127.0.0.1:${PROMETHEUS_PORT}
isDefault: true
+8
View File
@@ -0,0 +1,8 @@
# docker-compose.host.yml: the exporter on the host's loopback
global:
scrape_interval: 60s
scrape_configs:
- job_name: meshcore_exporter
static_configs:
- targets: ["127.0.0.1:9200"]
+9
View File
@@ -0,0 +1,9 @@
global:
# The exporter reads the mesh every 15 min; scraping its page more often
# costs nothing on air and just repeats the last values.
scrape_interval: 60s
scrape_configs:
- job_name: meshcore_exporter
static_configs:
- targets: ["exporter:9200"]
+24
View File
@@ -0,0 +1,24 @@
# Without Docker:
# sudo useradd --system --no-create-home --groups dialout meshcore (Arch: uucp)
# sudo python3 -m venv /opt/meshcore-exporter
# sudo /opt/meshcore-exporter/bin/pip install git+https://git.rfa.cz/tth-pub/meshcore-exporter
# sudo install -m 600 -o meshcore /dev/null /etc/meshcore-exporter.env # then fill in MC_* lines
# sudo cp meshcore-exporter.service /etc/systemd/system/ && sudo systemctl enable --now meshcore-exporter
[Unit]
Description=MeshCore repeater Prometheus exporter
After=network-online.target
Wants=network-online.target
[Service]
User=meshcore
EnvironmentFile=/etc/meshcore-exporter.env
ExecStart=/opt/meshcore-exporter/bin/meshcore-exporter
Restart=always
RestartSec=30
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
[Install]
WantedBy=multi-user.target
+146
View File
@@ -0,0 +1,146 @@
"""Configuration and parsing -- no radio, no network."""
import os
import subprocess
import sys
from pathlib import Path
import pytest
import meshcore_exporter as mx
ROOT = Path(__file__).resolve().parent.parent
def settings(argv, monkeypatch, env=None):
for k in [k for k in os.environ if k.startswith("MC_")]:
monkeypatch.delenv(k)
for k, v in (env or {}).items():
monkeypatch.setenv(k, v)
return mx.resolve(mx.build_parser().parse_args(argv))
def test_targets_syntax():
t = mx.parse_targets("a, b=ABCD, c=ef01@5361, d@6162", "pw")
assert [(x.name, x.pubkey, x.path, x.password) for x in t] == [
("a", "", "", "pw"),
("b", "abcd", "", "pw"),
("c", "ef01", "5361", "pw"),
("d", "", "6162", "pw"),
]
def test_cli_minimal(monkeypatch):
s = settings(["--serial", "/dev/x", "--repeaters", "rpt", "--password", "pw"], monkeypatch)
assert s.serial == "/dev/x" and s.interval == mx.DEFAULT_INTERVAL and s.port == 9200
assert s.targets[0].password == "pw" and s.path_hash_bytes is None
def test_env_twins(monkeypatch):
s = settings(
[], monkeypatch, {"MC_TCP": "h:5000", "MC_REPEATERS": "rpt", "MC_INTERVAL": "1800", "MC_PATH_HASH_BYTES": "2"}
)
assert s.tcp == "h:5000" and s.interval == 1800 and s.path_hash_bytes == 2
def test_interval_floor(monkeypatch):
s = settings(["--serial", "/dev/x", "--repeaters", "r", "--interval", "10"], monkeypatch)
assert s.interval == mx.MIN_INTERVAL
@pytest.mark.parametrize(
"argv",
[
["--repeaters", "r"], # no companion
["--serial", "/dev/x", "--tcp", "h:1", "--repeaters", "r"], # two companions
["--serial", "/dev/x"], # no repeater
],
)
def test_bad_setup(argv, monkeypatch):
with pytest.raises(ValueError):
settings(argv, monkeypatch)
def test_toml(tmp_path, monkeypatch):
f = tmp_path / "r.toml"
f.write_text(
'serial = "/dev/y"\ninterval = 1800\npassword = "common"\n'
'[[repeater]]\nname = "one"\n'
'[[repeater]]\nname = "two"\npassword = "own"\npath = "5361"\n'
)
s = settings(["--config", str(f)], monkeypatch)
assert s.serial == "/dev/y" and s.interval == 1800
assert [(t.name, t.password, t.path) for t in s.targets] == [("one", "common", ""), ("two", "own", "5361")]
# the command line wins over the file
s = settings(["--config", str(f), "--interval", "2400"], monkeypatch)
assert s.interval == 2400
def test_example_toml_loads(monkeypatch):
s = settings(["--config", str(ROOT / "repeaters.example.toml")], monkeypatch)
assert s.targets
def test_status_extension():
pytest.importorskip("meshcore")
import meshcore.parsing as parsing
mx.extend_status_parser()
frame = bytes(8) + bytes(56) + (7).to_bytes(4, "little") + (3).to_bytes(4, "little")
res = parsing.parse_status(frame)
assert (res["tx_start_fail"], res["tx_timeout"]) == (7, 3)
assert parsing.parse_status(bytes(8) + bytes(56))["tx_timeout"] is None
def test_help_without_dependencies():
# --help must work before meshcore/prometheus_client are installed
code = (
"import sys, builtins; real = builtins.__import__\n"
"def imp(n, *a, **k):\n"
" if n.split('.')[0] in ('meshcore', 'prometheus_client'): raise ImportError(n)\n"
" return real(n, *a, **k)\n"
"builtins.__import__ = imp; sys.argv = ['x', '--help']\n"
"import runpy; runpy.run_path('meshcore_exporter.py', run_name='__main__')"
)
r = subprocess.run([sys.executable, "-c", code], cwd=ROOT, capture_output=True, text=True)
assert r.returncode == 0 and "--repeaters" in r.stdout
def test_round_returns_failed_targets(monkeypatch):
import asyncio
s = settings(["--serial", "/dev/x", "--repeaters", "good,bad"], monkeypatch)
ex = mx.Exporter(s, None)
async def read(mc, t):
if t.name == "bad":
raise RuntimeError("login failed")
return {"bat": 4100.0}
monkeypatch.setattr(ex, "read", read)
failed = asyncio.run(ex.round(None))
assert [t.name for t in failed] == ["bad"]
assert asyncio.run(ex.round(None, failed)) == failed
def test_contacts_fetched_once_per_round(monkeypatch):
import asyncio
from types import SimpleNamespace
pytest.importorskip("meshcore")
from meshcore import EventType
calls = []
async def get_contacts(timeout=5):
calls.append(timeout)
payload = {"a": {"adv_name": "one", "public_key": "aa" * 32}, "b": {"adv_name": "two", "public_key": "bb" * 32}}
return SimpleNamespace(type=EventType.CONTACTS, payload=payload)
mc = SimpleNamespace(commands=SimpleNamespace(get_contacts=get_contacts))
s = settings(["--serial", "/dev/x", "--repeaters", "one,two=bbbb"], monkeypatch)
ex = mx.Exporter(s, None)
ex._contact_list = None
for t in s.targets:
assert asyncio.run(ex.contact(mc, t))["adv_name"] == t.name
assert calls == [mx.CONTACTS_TIMEOUT]