From 45b05d045ae948b65c400493710cb1420dc8ad9a Mon Sep 17 00:00:00 2001 From: root Date: Sat, 7 Nov 2026 20:00:02 +0000 Subject: [PATCH] feat(linux): add persistent Avahi discovery for InfluxDB Add a Debian NUC installer, IPv4 service definition and usage guide with backup and legacy alias migration. Document the user-confirmed SEN54-to-InfluxDB connection without including credentials. --- AGENTS.md | 2 + linux-app/README.md | 158 +++++++++++++++++++++++ linux-app/avahi/nanopsx-influxdb.service | 11 ++ linux-app/install-avahi.sh | 80 ++++++++++++ 4 files changed, 251 insertions(+) create mode 100644 linux-app/README.md create mode 100644 linux-app/avahi/nanopsx-influxdb.service create mode 100644 linux-app/install-avahi.sh diff --git a/AGENTS.md b/AGENTS.md index 7cc127c..6219c4c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -154,6 +154,8 @@ Beim letzten Hardwaretest wurden festgestellt: Diese Anwendungsprobleme sind unabhängig vom erfolgreich getesteten Flash-Workflow zu untersuchen. +Aktualisierung vom 07.11.2026: Für den NUC-WLAN-Access-Point ist die InfluxDB-Adresse `http://192.168.50.1:8086`. Die Einrichtung unter `linux-app/` kündigt `_influxdb2._tcp` über Avahi an. Den vorhandenen Avahi-Hostnamen verwenden; ein zusätzlicher statischer Alias auf dieselbe lokale IP verursachte in dieser Einrichtung `Local name collision`. Der Benutzer bestätigte die Auflösung auf dem WLAN und nach erneuter Konfiguration die funktionierende SEN54-Übertragung zu InfluxDB (Organisation `Home`, Bucket `nanoPSX`). Serielle Tests bestätigten zuvor die HTTP-Erreichbarkeit, aber Authentifizierungsfehler; die abschließende erfolgreiche Datenübertragung wurde vom Benutzer bestätigt. SD-Karten-Timeout und WLAN-Rückfall auf 11N wurden durch die Netzwerkeinrichtung nicht behoben. Tokens weiterhin ausschließlich lokal verwalten und nicht committen. + Der Upload selbst schreibt nicht in NVS. Die Anwendung kann NVS aber zur Laufzeit verändern und löscht NVS bei `ESP_ERR_NVS_NO_FREE_PAGES` oder `ESP_ERR_NVS_NEW_VERSION_FOUND` während der Initialisierung (`firmware/src/main.c`, `firmware/components/storage/src/storage.c`). Keine absolute Unveränderlichkeit von NVS nach Anwendungsstart zusichern. Beim Referenztest änderten sich WLAN-Journal-Einträge für `opmode`; die gültigen Einstellungswerte blieben im Vor-/Nachvergleich gleich. ## Dokumentation diff --git a/linux-app/README.md b/linux-app/README.md new file mode 100644 index 0000000..15e579e --- /dev/null +++ b/linux-app/README.md @@ -0,0 +1,158 @@ +# InfluxDB auf dem Linux-NUC per Avahi bekannt machen + +Diese Dateien richten eine dauerhafte mDNS/DNS-SD-Ankündigung für die vorhandene +ESP32-Firmware ein. Avahi läuft auf dem **Debian-13-NUC**, außerhalb von Docker. +Die Konfiguration wird nach einem NUC-Neustart automatisch geladen. + +## Vorgesehener Aufbau + +| Einstellung | Wert | +| --- | --- | +| NUC-WLAN/AP-Interface | `wlp2s0` | +| NUC-WLAN-Adresse | `192.168.50.1/24` | +| InfluxDB-URL für den ESP | `http://192.168.50.1:8086` | +| Diensttyp | `_influxdb2._tcp.local.` | +| Dienstname | `nanoPSX InfluxDB NUC` | +| mDNS-Hostname | vorhandener Avahi-Hostname, auf diesem NUC `nuc.local` | + +Der ESP muss mit dem NUC-WLAN verbunden sein. Der InfluxDB-Container muss Port +8086 an `192.168.50.1` veröffentlichen; das ist beim untersuchten NUC bereits +eingerichtet. Ein fehlender Listener an `127.0.0.1:8086` ist dabei erwartbar. + +Der Dienst verwendet den vorhandenen Avahi-Hostnamen (`nuc.local` auf diesem +NUC). Es wird kein zusätzlicher Hostname für dieselbe IP registriert, da dies bei +Avahi eine lokale Namenskollision verursachen kann. Auf dem WLAN muss die +Auflösung `192.168.50.1` liefern; dies nach der Installation prüfen. Die allgemeine +Avahi-Interface-Konfiguration bleibt erhalten. Die Ankündigung kann auch auf +anderen von Avahi bedienten Interfaces sichtbar sein. Kein mDNS-Reflector wird +eingerichtet. + +## Installation + +1. Das Projekt oder mindestens den vollständigen Ordner `linux-app` auf den NUC + kopieren. Die folgenden Befehle dort in einer lokalen Shell ausführen. +2. Das frühere Python-mDNS-Skript bzw. dessen Systemdienst für diese + InfluxDB-Ankündigung beenden und dessen Autostart deaktivieren. Ebenso einen + laufenden Test mit `avahi-publish-service` beenden. Andere mDNS-Dienste erhalten. +3. Im Projektverzeichnis ausführen: + + ```bash + sudo bash linux-app/install-avahi.sh + ``` + +Das Skript prüft die AP-Adresse und InfluxDB `/health`, installiert mit APT +`avahi-daemon`, `avahi-utils`, `curl` und `python3`, sichert vorhandene Dateien +unter `/var/backups/nanopsx-avahi/install.*` und installiert: + +- `/etc/avahi/services/nanopsx-influxdb.service` +- keinen neuen Eintrag in `/etc/avahi/hosts`. Der exakt markierte Alias der ersten + Skriptversion wird nach Sicherung entfernt, falls vorhanden. + +Andere Hosteinträge und Dienste bleiben erhalten. Eine unbekannte abweichende +Dienstdatei führt zum Abbruch. Die unveränderte erste Version der mitgelieferten +Dienstdatei wird anhand ihres SHA-256 erkannt und automatisch aktualisiert. +Wiederholtes Ausführen mit unveränderten Einstellungen erzeugt keine doppelten +Hosteinträge. Ein fehlgeschlagener Installationslauf ist kein Erfolgsnachweis; +die ausgegebenen Fehler zuerst prüfen. Bereits installierte Pakete bleiben bei +einem späteren Fehler installiert. + +Es werden weder Docker, Firewall, WireGuard, SSH noch ESP-Firmware geändert. +Es sind keine Influx-Tokens oder WLAN-Passwörter in diesen Dateien erforderlich. + +## Funktion prüfen + +Auf dem NUC: + +```bash +systemctl is-enabled avahi-daemon.service +systemctl is-active avahi-daemon.service +curl --noproxy '*' -fsS --max-time 5 http://192.168.50.1:8086/health +avahi-browse -r -t _influxdb2._tcp +``` + +Erwartet: `enabled`, `active`, Health-Status `pass` und beim aufgelösten Dienst +auf Interface `wlp2s0` mit IPv4 die Adresse `192.168.50.1`, Port `8086` +und Hostname `nuc.local` (sofern der Rechnername nicht geändert wurde). +`avahi-browse` unterstützt weder `-4` noch `-i`; die Ausgabe enthält Interface +und IP-Protokoll als Spalten. +Zusätzlich von einem anderen Linux-Rechner im NUC-WLAN prüfen, sofern verfügbar: + +```bash +avahi-browse -r -t _influxdb2._tcp +curl --noproxy '*' -fsS --max-time 5 http://192.168.50.1:8086/health +``` + +Ein lokaler NUC-Test allein beweist noch keine Erreichbarkeit vom ESP. +Die Firmware sucht ungefähr alle 60 Sekunden, bis sie einen Dienst gefunden +hat, und speichert dessen URL. Hat sie bereits einen anderen Dienst gefunden, +den ESP einmal neu starten, nachdem die richtige Ankündigung aktiv ist. + +Die seriellen ESP-Logs sollen anschließend `mDNS URL: http://192.168.50.1:8086` +zeigen. Erst erfolgreiche Influx-Schreibvorgänge mit HTTP-Status `204` und +aktuelle Messwerte im Influx-Bucket bestätigen die vollständige Verbindung. +Organisation, Bucket und ein Token mit Schreibrecht für diesen Bucket müssen +zusätzlich im ESP-Konfigurationsportal hinterlegt sein. Tokens dort lokal +eingeben und nicht in Git oder Diagnoseausgaben veröffentlichen. + +Avahi kündigt statisch an: Es überwacht die Verfügbarkeit des Containers nicht. +Die Installation prüft `/health` einmalig. Nach einem NUC-Neustart kann die +Ankündigung schon sichtbar sein, bevor InfluxDB bereit ist; die Firmware muss +Verbindungsversuche wiederholen. + +## Fehler untersuchen + +```bash +journalctl -u avahi-daemon.service -b --no-pager -n 80 +ip -br -4 addr +ss -ltn '( sport = :8086 )' +``` + +- Kein Dienst gefunden: Avahi-Status und Logs prüfen. In + `/etc/avahi/avahi-daemon.conf` darf `wlp2s0` nicht ausgeschlossen und Publishing + nicht deaktiviert sein. Das Installationsskript überschreibt diese Einstellungen + bewusst nicht. +- Nur lokal sichtbar: Firewall für mDNS (UDP 5353, IPv4-Multicast + `224.0.0.251`) auf dem WLAN und mögliche AP-Client-Isolation prüfen. +- HTTP-Timeout: TCP 8086 vom WLAN, Docker-Portfreigabe und Firewall prüfen. +- HTTP 401/403: Influx-Token und dessen Bucket-Schreibrechte prüfen. +- Mehrere Influx-Dienste: Die Firmware nimmt einen passenden Treffer. Alte + konkurrierende Ankündigungen entfernen, bevor die Erkennung erneut startet. + +Keine Firewall-Regeln pauschal löschen und keine unbekannten Dienste abschalten. +Für einen anderen AP die Adresse und das Interface im Installationsskript +gezielt anpassen und die Auflösung auf dem neuen WLAN prüfen. + +## Ankündigung entfernen + +Nur die von dieser Einrichtung angelegten Einträge entfernen: + +```bash +sudo rm /etc/avahi/services/nanopsx-influxdb.service +sudo systemctl reload avahi-daemon.service +``` + +Falls die Dateien inzwischen manuell geändert wurden, vor dem Entfernen prüfen. +Vorhandene Hosteinträge bleiben erhalten. Avahi und seine anderen Dienste bleiben aktiv. Die Sicherung enthält +die vorherigen Dateien; diese nicht pauschal zurückkopieren, wenn inzwischen +weitere Änderungen vorgenommen wurden. + +## Referenzen + +- [Debian: statische Avahi-Dienste](https://manpages.debian.org/trixie/avahi-daemon/avahi.service.5.en.html) +- [Debian: avahi-browse und gültige Optionen](https://manpages.debian.org/trixie/avahi-utils/avahi-browse.1.en.html) +- [InfluxDB: Health-Prüfung](https://docs.influxdata.com/influxdb/v2/api/health/) + +## Getesteter Stand (2026-11-07) + +Skriptsyntax, XML, Installation und Migration der ersten Konfiguration wurden +im Entwicklungscontainer mit isolierten Systemaufrufen geprüft. Der Benutzer +hat die Konfiguration auf dem Debian-NUC installiert und die korrigierte +Dienstdatei ohne zusätzlichen Hostnamen eingesetzt. Seine `avahi-browse`-Ausgabe +bestätigt auf `wlp2s0` die Auflösung von `nuc.local` zu `192.168.50.1:8086`. + +Serielle Tests des ESP bestätigten anschließend HTTP-Verbindungen zu dieser +Adresse. Nach Einrichtung von Organisation `Home`, Bucket `nanoPSX` und einem +passenden Token hat der Benutzer die funktionierende SEN54-Übertragung zu +InfluxDB bestätigt. Diese abschließende Funktionsbestätigung stammt vom Benutzer; +eine weitere serielle Aufzeichnung mit erfolgreichen Schreibantworten wurde +danach nicht erstellt. Zugangsdaten gehören nicht in diese Dokumentation. diff --git a/linux-app/avahi/nanopsx-influxdb.service b/linux-app/avahi/nanopsx-influxdb.service new file mode 100644 index 0000000..fd28388 --- /dev/null +++ b/linux-app/avahi/nanopsx-influxdb.service @@ -0,0 +1,11 @@ + + + + nanoPSX InfluxDB NUC + + _influxdb2._tcp + local + 8086 + path=/ + + diff --git a/linux-app/install-avahi.sh b/linux-app/install-avahi.sh new file mode 100644 index 0000000..2920dbb --- /dev/null +++ b/linux-app/install-avahi.sh @@ -0,0 +1,80 @@ +#!/usr/bin/env bash +# Auf dem Debian-NUC ausführen, nicht im Codex- oder InfluxDB-Container. +set -euo pipefail + +SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd) +SOURCE="$SCRIPT_DIR/avahi/nanopsx-influxdb.service" +DEST=/etc/avahi/services/nanopsx-influxdb.service +HOSTS=/etc/avahi/hosts +AP_INTERFACE=wlp2s0 +AP_ADDRESS=192.168.50.1 +# Exakter Hash unserer ersten Version: nur diese darf automatisch migriert werden. +LEGACY_SERVICE_SHA256=b5dadb78f624dd5e6e4fa8b7243af23b687e1adf9c88712207510a4c52bc7357 + +if (( EUID != 0 )); then + echo "Bitte auf dem NUC mit sudo bash $0 ausführen." >&2 + exit 1 +fi +if [[ ! -f /etc/debian_version || ! -d /run/systemd/system ]]; then + echo 'Benötigt einen Debian/Ubuntu-Host mit laufendem systemd.' >&2 + exit 1 +fi +if ! ip -4 -o addr show dev "$AP_INTERFACE" | awk '{print $4}' | cut -d/ -f1 | grep -Fxq "$AP_ADDRESS"; then + echo "Die erwartete AP-Adresse $AP_ADDRESS fehlt auf $AP_INTERFACE. Abbruch." >&2 + exit 1 +fi +for target in "$HOSTS" "$DEST"; do + if [[ -L "$target" || ( -e "$target" && ! -f "$target" ) ]]; then + echo "Unerwarteter Dateityp: $target. Abbruch." >&2 + exit 1 + fi +done +if [[ -e "$DEST" ]] && ! cmp -s "$SOURCE" "$DEST"; then + if [[ $(sha256sum "$DEST" | cut -d' ' -f1) != "$LEGACY_SERVICE_SHA256" ]]; then + echo "Abweichende Dienstdatei $DEST vorhanden; bitte zuerst manuell prüfen." >&2 + exit 1 + fi +fi + +apt-get update +apt-get install -y avahi-daemon avahi-utils curl python3 + +# Vor jeder Änderung: InfluxDB muss an der tatsächlich angekündigten IP antworten. +curl --noproxy '*' --fail --silent --show-error --max-time 5 \ + "http://$AP_ADDRESS:8086/health" | + python3 -c 'import json, sys; d=json.load(sys.stdin); sys.exit(0 if d.get("status")=="pass" else "InfluxDB health meldet nicht pass; Abbruch.")' + +install -d -m 700 /var/backups/nanopsx-avahi +BACKUP=$(mktemp -d /var/backups/nanopsx-avahi/install.XXXXXXXX) +for target in "$HOSTS" "$DEST"; do + if [[ -e "$target" ]]; then + cp -a -- "$target" "$BACKUP/$(basename -- "$target")" + else + touch "$BACKUP/$(basename -- "$target").was-absent" + fi +done +echo "Sicherung vor Änderungen: $BACKUP" + +install -d -m 755 /etc/avahi/services +# Ausschließlich den von unserer ersten Version angelegten Alias entfernen. +# Avahi verwendet für den Dienst seinen vorhandenen lokalen Hostnamen. +python3 - "$HOSTS" <<'PY' +from pathlib import Path +import sys + +p = Path(sys.argv[1]) +if p.exists(): + original = p.read_bytes() + cleaned = b"".join(line for line in original.splitlines(keepends=True) + if line.rstrip(b"\r\n") != + b"192.168.50.1 nanopsx-influx.local # nanopsx-avahi") + if cleaned != original: + p.write_bytes(cleaned) +PY +install -o root -g root -m 644 "$SOURCE" "$DEST" + +systemctl enable --now avahi-daemon.service +systemctl reload avahi-daemon.service +systemctl is-active --quiet avahi-daemon.service +echo "Avahi läuft und startet beim Booten. Ziel: http://$AP_ADDRESS:8086" +echo 'Die erfolgreiche mDNS-Auflösung und ESP-Übertragung jetzt gemäß README prüfen.'