commit 2a9126e2587acbed11ce9ace7d1540a92c82188f Author: TeTeHacko Date: Mon Nov 2 21:52:21 2026 +0100 meshcore-exporter 1.0.0 Prometheus exporter for MeshCore repeaters, read over the mesh: a companion (USB, BLE, or a companion identity in openHop over TCP) logs in to each repeater, asks for status and telemetry with direct packets and serves battery, temperature/humidity, noise floor, RSSI/SNR, packet counters, airtime and uptime on :9200/metrics. - meshcore_exporter.py: command line, MC_* environment or a TOML file with a password per repeater; --check reads every repeater once and exits; interval 1 h (min 15 min); a failed repeater is retried once after 3 min; contacts fetched once per round. - dashboards/: the Grafana dashboard, generated from generate.py (datasource, job and the rate window are variables; TX drawn above zero, RX below). - stack/: Docker Compose with Prometheus and Grafana provisioned, for a USB companion, or on the host network for openHop on the same machine. - systemd/: running without Docker. - README.md (Czech) and AGENTS.md for setting it up with an AI agent. - CI: lint and tests, gitleaks; PR check builds the image; single-platform images per architecture behind a Trivy gate (latest-, and X.Y.Z- with a release on tag vX.Y.Z); dependencies by Renovate. Co-Authored-By: Claude Opus 5.5 diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..af06d2c --- /dev/null +++ b/.dockerignore @@ -0,0 +1,3 @@ +* +!meshcore_exporter.py +!requirements.txt diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml new file mode 100644 index 0000000..9b35d78 --- /dev/null +++ b/.gitea/workflows/ci.yml @@ -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 diff --git a/.gitea/workflows/image.yml b/.gitea/workflows/image.yml new file mode 100644 index 0000000..19528a0 --- /dev/null +++ b/.gitea/workflows/image.yml @@ -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- moves after the Trivy gate. +# +# A tag vX.Y.Z (must equal __version__) also gets X.Y.Z- 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- 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 <"$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)" diff --git a/.gitea/workflows/pr-check.yml b/.gitea/workflows/pr-check.yml new file mode 100644 index 0000000..b0b2787 --- /dev/null +++ b/.gitea/workflows/pr-check.yml @@ -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 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..fbdb494 --- /dev/null +++ b/.gitignore @@ -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 diff --git a/.yamllint b/.yamllint new file mode 100644 index 0000000..4d38c5c --- /dev/null +++ b/.yamllint @@ -0,0 +1,5 @@ +extends: default +rules: + line-length: {max: 120} + document-start: disable + truthy: {check-keys: false} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..fabb173 --- /dev/null +++ b/AGENTS.md @@ -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' `. +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://: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. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..241910a --- /dev/null +++ b/Dockerfile @@ -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"] diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..8b3ca74 --- /dev/null +++ b/LICENSE @@ -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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..d6e5f17 --- /dev/null +++ b/README.md @@ -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://: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. diff --git a/dashboards/generate.py b/dashboards/generate.py new file mode 100644 index 0000000..def75bf --- /dev/null +++ b/dashboards/generate.py @@ -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}") diff --git a/dashboards/meshcore-repeater.json b/dashboards/meshcore-repeater.json new file mode 100644 index 0000000..a674611 --- /dev/null +++ b/dashboards/meshcore-repeater.json @@ -0,0 +1,1223 @@ +{ + "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": "1h", + "value": "1h", + "selected": false + }, + { + "text": "3h", + "value": "3h", + "selected": true + }, + { + "text": "6h", + "value": "6h", + "selected": false + }, + { + "text": "12h", + "value": "12h", + "selected": false + } + ], + "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": { + "type": "prometheus", + "uid": "${datasource}" + }, + "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": [ + { + "id": 1, + "type": "stat", + "title": "Baterie % (odhad z napětí)", + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "gridPos": { + "h": 5, + "w": 4, + "x": 0, + "y": 0 + }, + "fieldConfig": { + "defaults": { + "unit": "percent", + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "red", + "value": null + }, + { + "color": "orange", + "value": 20 + }, + { + "color": "yellow", + "value": 40 + }, + { + "color": "green", + "value": 60 + } + ] + }, + "min": 0, + "max": 100 + }, + "overrides": [] + }, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "textMode": "auto", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": false + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "clamp(100 * (meshcore_battery_millivolts{job=~\"$job\", node=\"$node\"} - 3300) / 900, 0, 100)", + "refId": "A" + } + ], + "description": "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." + }, + { + "id": 2, + "type": "stat", + "title": "Teplota", + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "gridPos": { + "h": 5, + "w": 4, + "x": 4, + "y": 0 + }, + "fieldConfig": { + "defaults": { + "unit": "celsius", + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "blue", + "value": null + }, + { + "color": "green", + "value": 0 + }, + { + "color": "orange", + "value": 40 + } + ] + } + }, + "overrides": [] + }, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "textMode": "auto", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": false + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "meshcore_temperature_celsius{job=~\"$job\", node=\"$node\"}", + "refId": "A" + } + ], + "description": "Externí senzor, pokud ho uzel má a exportér je přihlášený jako admin; jinak teplota MCU." + }, + { + "id": 3, + "type": "stat", + "title": "Uptime", + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "gridPos": { + "h": 5, + "w": 4, + "x": 8, + "y": 0 + }, + "fieldConfig": { + "defaults": { + "unit": "s", + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + } + ] + } + }, + "overrides": [] + }, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "textMode": "auto", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": false + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "meshcore_uptime_seconds{job=~\"$job\", node=\"$node\"}", + "refId": "A" + } + ] + }, + { + "id": 4, + "type": "stat", + "title": "Stáří posledního čtení", + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "gridPos": { + "h": 5, + "w": 4, + "x": 12, + "y": 0 + }, + "fieldConfig": { + "defaults": { + "unit": "s", + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "yellow", + "value": 4000 + }, + { + "color": "red", + "value": 7500 + } + ] + } + }, + "overrides": [] + }, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "textMode": "auto", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": false + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "time() - meshcore_last_scrape_success_timestamp{job=~\"$job\", node=\"$node\"}", + "refId": "A" + } + ], + "description": "Kdy naposledy uzel odpověděl. Při výchozím intervalu 1 h je normál do ~3600 s." + }, + { + "id": 5, + "type": "stat", + "title": "Fronta TX", + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "gridPos": { + "h": 5, + "w": 4, + "x": 16, + "y": 0 + }, + "fieldConfig": { + "defaults": { + "unit": "none", + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "yellow", + "value": 3 + }, + { + "color": "red", + "value": 8 + } + ] + } + }, + "overrides": [] + }, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "textMode": "auto", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": false + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "meshcore_queue_length{job=~\"$job\", node=\"$node\"}", + "refId": "A" + } + ] + }, + { + "id": 6, + "type": "stat", + "title": "Šumové pozadí", + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "gridPos": { + "h": 5, + "w": 4, + "x": 20, + "y": 0 + }, + "fieldConfig": { + "defaults": { + "unit": "dBm", + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "yellow", + "value": -105 + }, + { + "color": "red", + "value": -95 + } + ] + } + }, + "overrides": [] + }, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "textMode": "auto", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": false + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "meshcore_noise_floor_dbm{job=~\"$job\", node=\"$node\"}", + "refId": "A" + } + ], + "description": "Čím níž, tím líp. Nad −100 dBm uzel hůř slyší slabé signály (rušení, blízký vysílač)." + }, + { + "id": 10, + "type": "timeseries", + "title": "Baterie (mV)", + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 5 + }, + "fieldConfig": { + "defaults": { + "unit": "mV", + "color": { + "mode": "palette-classic" + }, + "custom": { + "drawStyle": "line", + "lineWidth": 1, + "fillOpacity": 10, + "showPoints": "never", + "spanNulls": 3600000, + "axisSoftMin": 3000, + "axisSoftMax": 4300 + } + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "multi", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "meshcore_battery_millivolts{job=~\"$job\", node=\"$node\"}", + "refId": "A", + "legendFormat": "baterie" + } + ] + }, + { + "id": 11, + "type": "timeseries", + "title": "Teplota a vlhkost", + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 5 + }, + "fieldConfig": { + "defaults": { + "unit": "celsius", + "color": { + "mode": "palette-classic" + }, + "custom": { + "drawStyle": "line", + "lineWidth": 1, + "fillOpacity": 10, + "showPoints": "never", + "spanNulls": 3600000 + } + }, + "overrides": [ + { + "matcher": { + "id": "byName", + "options": "vlhkost (%)" + }, + "properties": [ + { + "id": "unit", + "value": "humidity" + }, + { + "id": "custom.axisPlacement", + "value": "right" + } + ] + } + ] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "multi", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "meshcore_temperature_celsius{job=~\"$job\", node=\"$node\"}", + "refId": "A", + "legendFormat": "teplota (°C)" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "meshcore_humidity_percent{job=~\"$job\", node=\"$node\"}", + "refId": "B", + "legendFormat": "vlhkost (%)" + } + ], + "description": "Externí senzor, pokud ho uzel má a exportér je přihlášený jako admin; jinak teplota MCU." + }, + { + "id": 12, + "type": "timeseries", + "title": "Provoz — pakety za hodinu", + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 13 + }, + "fieldConfig": { + "defaults": { + "unit": "none", + "color": { + "mode": "palette-classic" + }, + "custom": { + "drawStyle": "line", + "lineWidth": 1, + "fillOpacity": 10, + "showPoints": "never", + "spanNulls": 3600000, + "axisLabel": "↓ přijato / ↑ odesláno" + } + }, + "overrides": [ + { + "matcher": { + "id": "byName", + "options": "odesláno" + }, + "properties": [ + { + "id": "color", + "value": { + "mode": "fixed", + "fixedColor": "orange" + } + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "přijato" + }, + "properties": [ + { + "id": "color", + "value": { + "mode": "fixed", + "fixedColor": "blue" + } + }, + { + "id": "custom.transform", + "value": "negative-Y" + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "chyby příjmu (CRC)" + }, + "properties": [ + { + "id": "color", + "value": { + "mode": "fixed", + "fixedColor": "red" + } + }, + { + "id": "custom.transform", + "value": "negative-Y" + } + ] + } + ] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "multi", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "rate(meshcore_packets_received_total{job=~\"$job\", node=\"$node\"}[$window]) * 3600", + "refId": "A", + "legendFormat": "přijato" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "rate(meshcore_packets_sent_total{job=~\"$job\", node=\"$node\"}[$window]) * 3600", + "refId": "B", + "legendFormat": "odesláno" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "rate(meshcore_receive_errors_total{job=~\"$job\", node=\"$node\"}[$window]) * 3600", + "refId": "C", + "legendFormat": "chyby příjmu (CRC)" + } + ], + "description": "Nad nulou odeslané pakety, pod nulou přijaté a chyby příjmu." + }, + { + "id": 13, + "type": "timeseries", + "title": "Signál — RSSI / SNR / šum", + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 13 + }, + "fieldConfig": { + "defaults": { + "unit": "none", + "color": { + "mode": "palette-classic" + }, + "custom": { + "drawStyle": "line", + "lineWidth": 1, + "fillOpacity": 10, + "showPoints": "never", + "spanNulls": 3600000 + } + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "multi", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "meshcore_last_rssi_dbm{job=~\"$job\", node=\"$node\"}", + "refId": "A", + "legendFormat": "RSSI posledního paketu (dBm)" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "meshcore_last_snr_db{job=~\"$job\", node=\"$node\"}", + "refId": "B", + "legendFormat": "SNR posledního paketu (dB)" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "meshcore_noise_floor_dbm{job=~\"$job\", node=\"$node\"}", + "refId": "C", + "legendFormat": "šumové pozadí (dBm)" + } + ] + }, + { + "id": 14, + "type": "timeseries", + "title": "Airtime za hodinu (s)", + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 21 + }, + "fieldConfig": { + "defaults": { + "unit": "s", + "color": { + "mode": "palette-classic" + }, + "custom": { + "drawStyle": "line", + "lineWidth": 1, + "fillOpacity": 10, + "showPoints": "never", + "spanNulls": 3600000, + "axisLabel": "↓ příjem / ↑ vysílání" + } + }, + "overrides": [ + { + "matcher": { + "id": "byName", + "options": "vysílání" + }, + "properties": [ + { + "id": "color", + "value": { + "mode": "fixed", + "fixedColor": "orange" + } + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "příjem" + }, + "properties": [ + { + "id": "color", + "value": { + "mode": "fixed", + "fixedColor": "blue" + } + }, + { + "id": "custom.transform", + "value": "negative-Y" + } + ] + } + ] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "multi", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "rate(meshcore_tx_airtime_seconds_total{job=~\"$job\", node=\"$node\"}[$window]) * 3600", + "refId": "A", + "legendFormat": "vysílání" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "rate(meshcore_rx_airtime_seconds_total{job=~\"$job\", node=\"$node\"}[$window]) * 3600", + "refId": "B", + "legendFormat": "příjem" + } + ], + "description": "Nad nulou čas vysílání, pod nulou čas příjmu." + }, + { + "id": 15, + "type": "timeseries", + "title": "Přeposílání a potíže s vysíláním (za hodinu)", + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 21 + }, + "fieldConfig": { + "defaults": { + "unit": "none", + "color": { + "mode": "palette-classic" + }, + "custom": { + "drawStyle": "line", + "lineWidth": 1, + "fillOpacity": 10, + "showPoints": "never", + "spanNulls": 3600000 + } + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "multi", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "rate(meshcore_packets_sent_flood_total{job=~\"$job\", node=\"$node\"}[$window]) * 3600", + "refId": "A", + "legendFormat": "flood přeposláno" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "rate(meshcore_packets_sent_direct_total{job=~\"$job\", node=\"$node\"}[$window]) * 3600", + "refId": "B", + "legendFormat": "direct přeposláno" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "rate(meshcore_flood_duplicates_total{job=~\"$job\", node=\"$node\"}[$window]) * 3600", + "refId": "C", + "legendFormat": "flood duplikáty" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "rate(meshcore_tx_start_fail_total{job=~\"$job\", node=\"$node\"}[$window]) * 3600", + "refId": "D", + "legendFormat": "TX start fail" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "rate(meshcore_tx_timeout_total{job=~\"$job\", node=\"$node\"}[$window]) * 3600", + "refId": "E", + "legendFormat": "TX timeout" + } + ], + "description": "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." + }, + { + "id": 20, + "type": "row", + "title": "Baterie a duty cycle", + "collapsed": false, + "panels": [], + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 29 + } + }, + { + "id": 21, + "type": "stat", + "title": "Trend baterie (mV/h, + nabíjí)", + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "gridPos": { + "h": 6, + "w": 4, + "x": 0, + "y": 30 + }, + "fieldConfig": { + "defaults": { + "unit": "none", + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "red", + "value": null + }, + { + "color": "green", + "value": 0 + } + ] + }, + "decimals": 0 + }, + "overrides": [] + }, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "textMode": "auto", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": false + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "deriv(meshcore_battery_millivolts{job=~\"$job\", node=\"$node\"}[$window]) * 3600", + "refId": "A" + } + ], + "description": "Změna napětí za hodinu, spočítaná z okna `Okno`." + }, + { + "id": 22, + "type": "stat", + "title": "TX duty cycle", + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "gridPos": { + "h": 6, + "w": 4, + "x": 4, + "y": 30 + }, + "fieldConfig": { + "defaults": { + "unit": "percent", + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "yellow", + "value": 5 + }, + { + "color": "red", + "value": 10 + } + ] + }, + "decimals": 2 + }, + "overrides": [] + }, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "textMode": "auto", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": false + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "rate(meshcore_tx_airtime_seconds_total{job=~\"$job\", node=\"$node\"}[$window]) * 100", + "refId": "A" + } + ], + "description": "Podíl času, kdy uzel vysílá. Pásmo 869,4–869,65 MHz v EU dovoluje 10 %." + }, + { + "id": 23, + "type": "timeseries", + "title": "Duty cycle %", + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "gridPos": { + "h": 6, + "w": 16, + "x": 8, + "y": 30 + }, + "fieldConfig": { + "defaults": { + "unit": "percent", + "color": { + "mode": "palette-classic" + }, + "custom": { + "drawStyle": "line", + "lineWidth": 1, + "fillOpacity": 10, + "showPoints": "never", + "spanNulls": 3600000, + "axisLabel": "↓ RX / ↑ TX" + } + }, + "overrides": [ + { + "matcher": { + "id": "byName", + "options": "vysílání (TX)" + }, + "properties": [ + { + "id": "color", + "value": { + "mode": "fixed", + "fixedColor": "orange" + } + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "příjem (RX)" + }, + "properties": [ + { + "id": "color", + "value": { + "mode": "fixed", + "fixedColor": "blue" + } + }, + { + "id": "custom.transform", + "value": "negative-Y" + } + ] + } + ] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "multi", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "rate(meshcore_tx_airtime_seconds_total{job=~\"$job\", node=\"$node\"}[$window]) * 100", + "refId": "A", + "legendFormat": "vysílání (TX)" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${datasource}" + }, + "expr": "rate(meshcore_rx_airtime_seconds_total{job=~\"$job\", node=\"$node\"}[$window]) * 100", + "refId": "B", + "legendFormat": "příjem (RX)" + } + ], + "description": "Nad nulou podíl času vysílání (limit pásma 10 %), pod nulou příjmu." + } + ] +} diff --git a/docs/dashboard.png b/docs/dashboard.png new file mode 100644 index 0000000..ff24472 Binary files /dev/null and b/docs/dashboard.png differ diff --git a/meshcore_exporter.py b/meshcore_exporter.py new file mode 100644 index 0000000..5b60d4d --- /dev/null +++ b/meshcore_exporter.py @@ -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://: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()) diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..df90655 --- /dev/null +++ b/pyproject.toml @@ -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 diff --git a/repeaters.example.toml b/repeaters.example.toml new file mode 100644 index 0000000..1af60c1 --- /dev/null +++ b/repeaters.example.toml @@ -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) diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..7feeee3 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,3 @@ +# Exact versions for the container image; pyproject.toml has the ranges. +meshcore==2.3.17 +prometheus_client==0.26.0 diff --git a/stack/.env.example b/stack/.env.example new file mode 100644 index 0000000..625bab8 --- /dev/null +++ b/stack/.env.example @@ -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 diff --git a/stack/docker-compose.host.yml b/stack/docker-compose.host.yml new file mode 100644 index 0000000..2122c76 --- /dev/null +++ b/stack/docker-compose.host.yml @@ -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 diff --git a/stack/docker-compose.yml b/stack/docker-compose.yml new file mode 100644 index 0000000..234e452 --- /dev/null +++ b/stack/docker-compose.yml @@ -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: diff --git a/stack/grafana/provisioning/alerting/.gitkeep b/stack/grafana/provisioning/alerting/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/stack/grafana/provisioning/dashboards/meshcore.yml b/stack/grafana/provisioning/dashboards/meshcore.yml new file mode 100644 index 0000000..937fc8e --- /dev/null +++ b/stack/grafana/provisioning/dashboards/meshcore.yml @@ -0,0 +1,8 @@ +apiVersion: 1 +providers: + - name: meshcore + type: file + disableDeletion: true + allowUiUpdates: false + options: + path: /var/lib/grafana/dashboards diff --git a/stack/grafana/provisioning/datasources/prometheus.yml b/stack/grafana/provisioning/datasources/prometheus.yml new file mode 100644 index 0000000..9feba24 --- /dev/null +++ b/stack/grafana/provisioning/datasources/prometheus.yml @@ -0,0 +1,8 @@ +apiVersion: 1 +datasources: + - name: Prometheus + type: prometheus + uid: prometheus + access: proxy + url: http://prometheus:9090 + isDefault: true diff --git a/stack/grafana/provisioning/plugins/.gitkeep b/stack/grafana/provisioning/plugins/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/stack/host-network/datasource.yml b/stack/host-network/datasource.yml new file mode 100644 index 0000000..b681e93 --- /dev/null +++ b/stack/host-network/datasource.yml @@ -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 diff --git a/stack/host-network/prometheus.yml b/stack/host-network/prometheus.yml new file mode 100644 index 0000000..dcaf5e3 --- /dev/null +++ b/stack/host-network/prometheus.yml @@ -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"] diff --git a/stack/prometheus.yml b/stack/prometheus.yml new file mode 100644 index 0000000..ed53023 --- /dev/null +++ b/stack/prometheus.yml @@ -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"] diff --git a/systemd/meshcore-exporter.service b/systemd/meshcore-exporter.service new file mode 100644 index 0000000..d2f0d0b --- /dev/null +++ b/systemd/meshcore-exporter.service @@ -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 diff --git a/tests/test_config.py b/tests/test_config.py new file mode 100644 index 0000000..1e422aa --- /dev/null +++ b/tests/test_config.py @@ -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]