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.
This commit is contained in:
root
2026-11-07 20:00:02 +00:00
parent 3dcfdedc18
commit 45b05d045a
4 changed files with 251 additions and 0 deletions
+2
View File
@@ -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
+158
View File
@@ -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.
+11
View File
@@ -0,0 +1,11 @@
<?xml version="1.0" standalone="no"?>
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
<name replace-wildcards="no">nanoPSX InfluxDB NUC</name>
<service protocol="ipv4">
<type>_influxdb2._tcp</type>
<domain-name>local</domain-name>
<port>8086</port>
<txt-record>path=/</txt-record>
</service>
</service-group>
+80
View File
@@ -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.'