Piding IntercomArchitektur & Betrieb
Navigation

Dokumentationsstand · V1-Grundimplementierung

Autarkes Intercom zwischen Saalfelden und Piding.

Piding Intercom verbindet einen stationären Raspberry Pi in Piding mit einer installierbaren PWA in Saalfelden. MQTT steuert den Zustand, WebRTC transportiert das Audio mit niedriger Latenz.

Verbindliche Leitlinie

Dieses Projekt wird auf einem eigenen Debian-13-LXC betrieben. Das bestehende Projekt Piding-LAN dient ausschließlich als lesbare Netzwerkinformation und wird nie verändert.

01 · Systemarchitektur

Komponenten mit klaren Verantwortlichkeiten

Frontend, Signaling, Steuerung und stationäre Audiohardware bleiben bewusst voneinander getrennt.

Intercom-LXC

Eigenständiger Debian-13-LXC mit Nginx, FastAPI, Mosquitto, SQLite, systemd und vorbereitetem TURN-Fallback.

FastAPI

WebRTC-Signaling, Sitzungen, Rollen, Passkey-Pairing, Override-Leases und Health-API — ohne Audioverarbeitung.

Mosquitto

MQTTS für Heartbeats, LWT, Pi-Status und sichere Mute-/Unmute-Befehle mit separaten ACLs.

Raspberry Pi 4

USB-Mikrofon, Klinkenausgabe, lokale Echo-Cancellation, WebRTC, MQTT und später GPIO-LED.

PWA

Desktop und Mobil: Zuhören, Freisprechen, lokaler Piding-Override, Status und sichere Diagnose.

Zoraxy

Aktive TLS-Terminierung für piding-intercom.taxer.at mit Weiterleitung zum eigenständigen LXC.

Kommunikationsfluss und Protokolltrennung

Entwicklungsstand Saalfelden: Die PWA und das Browser-Signaling werden über https://piding-intercom.taxer.at beziehungsweise WSS von Zoraxy bereitgestellt. Der Pi signalisiert während der lokalen Hardwareentwicklung weiterhin innerhalb des privaten Netzes über ws://; die MQTT-Steuerung nutzt bereits MQTTS.

02 · Betriebsmodi

Babyfon als Standard, Override nur gezielt

ModusPi-MikrofonPi-KlinkenausgabeAktiver Audiopfad
Standard / BabyfonAktivAktivPi ↔ ein aktiver Saalfelden-Sprecher; weitere Saalfelden-Geräte hören zu.
Piding-OverrideDeaktiviertDeaktiviertLokales Piding-PWA-Gerät ↔ Saalfelden.
Fehler / OfflineSicher stummSicher stummKein unkontrollierter Audiobetrieb.

Sprechrecht

Mehrere Saalfelden-Geräte dürfen zuhören. Genau ein Gerät besitzt gleichzeitig das automatisch verwaltete Sprechrecht und gibt Sprache über den Pi aus.

Fallback

Freisprechen ist Standard. Push-to-talk wird als bewusst aktivierbarer Rückkopplungs- und Diagnose-Fallback technisch vorbereitet.

03 · Audio & Routing

WebRTC für Daten, lokale AEC für den stationären Endpunkt

WebRTC-Datenebene

  • Opus-Audio, Verschlüsselung und niedrige Latenz.
  • FastAPI vermittelt ausschließlich SDP- und ICE-Daten.
  • Direkter UDP-Pfad über IPsec; interner TURN-Fallback bei Bedarf.

Pi-Audiokette

  • USB-Mikrofon als konfigurierbarer ALSA-Eingang.
  • Klinkenausgabe für Sprache aus Saalfelden.
  • Der aiortc-Daemon verteilt die aktive Stationsquelle an mehrere Hörer und sperrt bei Override die Pi-Audioausgabe logisch.
  • Die konkrete ALSA-Mixer- und AEC-Feinabstimmung folgt mit der realen Hardware in Saalfelden.

04 · Sicherheit & Ausfallsicherheit

Lokale Präsenz wird doppelt geprüft

Override-Berechtigung

Ein Piding-Override erfordert ein registriertes PWA-Gerät mit Passkey/WebAuthn und nach Einrichtung von Split-DNS zusätzlich die Herkunft aus dem Piding-Netz 10.90.0.0/24. Nginx vertraut für die ursprüngliche Client-IP ausschließlich der einzeln verifizierten Zoraxy-Adresse und ersetzt weitergereichte Proxy-Header vor FastAPI durch den bereinigten Wert.

Lease statt Browser-Schließen

Ein Browser-Heartbeat alle zehn Sekunden hält eine 30-Sekunden-Override-Lease. Bei Sperren, Netzverlust oder Absturz läuft sie ab; das Backend gibt den Pi per MQTT wieder frei.

Betriebsabsicherung

Nicht privilegierte systemd-Dienste, Watchdogs, Backoff, TLS mit HSTS, ACLs, bereinigte Logs, SQLite-WAL und geschützte Secrets minimieren Ausfälle und Risiken.

Gesundheitsstatus

/api/health, Pi-Heartbeat, MQTT-Status und nachvollziehbare Diagnosezustände werden in der PWA sichtbar, ohne Zugangsdaten preiszugeben.

05 · PWA-Standard

Eine ruhige Oberfläche mit vollständiger Bedienbarkeit

Design & Icons

Roboto Condensed wird lokal ausgeliefert. Die Salzburg-AG-Dark-Palette ist zentral über semantische CSS-Variablen definiert. Das lokale Intercom-Zeichen wird als SVG sowie als PNG-, Apple-Touch- und ICO-Fallback bereitgestellt.

Mobile

Bis 768 px: kleinere Typografie und Abstände, Hamburger-Navigation, Prüfung auf Oppo Find X9 Ultra in Hoch- und Querformat.

Feedback & Updates

Jeder Toast besitzt ein Schließen-Symbol. Fehler bleiben verständlich und bieten zusätzlich eine bereinigte technische Kopierdiagnose. Ein PWA-Update bleibt bis zum Klick auf „Aktualisieren“ sichtbar; erst nach Aktivierung des neuen Workers lädt die App neu.

Formulare & Dialoge

Einheitliche Feldhöhen und Zustände, zugängliche Constraint-Validation sowie moderne <dialog>-Modals statt Browser-Pop-ups.

06 · Inbetriebnahme

Geplanter Ablauf

  1. 1

    V1-Quellstruktur erstellen

    Erledigt: Backend, PWA, Pi-Client, Konfigurationsvorlagen, Dokumentation und zentrale Release-Kennung wurden modular angelegt.

  2. 2

    Eigenständigen LXC installieren

    Erledigt: Debian-13-LXC mit nicht privilegiertem FastAPI-Dienst, Python-venv, Mosquitto mit MQTTS/ACL, Nginx und geschützten Laufzeit-Secrets ist aktiv. Health- und Passkey-Smoketests laufen erfolgreich.

  3. 3

    Pi in Saalfelden entwickeln

    In Arbeit: Der Raspberry Pi ist registriert und der systemd-Client ist aktiv. WebSocket-Signaling, MQTT-Mute/Unmute und ein kontrollierter Client-Neustart wurden Ende-zu-Ende bestätigt. Das USB-Mikrofon und die GPIO-LED folgen mit der realen Hardware; bis dahin arbeitet der Client bewusst im stillen Testmodus.

  4. 4

    Zoraxy und Subdomain anbinden

    Erledigt: piding-intercom.taxer.at terminiert TLS und leitet zum LXC weiter. Backend-Origin, WebAuthn-RP-ID, CORS, HSTS, WebSockets und die gegen externe Header-Manipulation geprüfte Client-IP-Weitergabe sind aktiv.

  5. 5

    Piding-Endabnahme

    IPsec, Split-DNS, Passkey-Override, Audio, Netzverlust und Wiederanlauf im echten Standortnetz prüfen.

07 · Prüfweg

V1 wird nicht nur gebaut, sondern überprüft

✓ Syntax- und Passkey-Smoketest
✓ systemd-Status und sauberer Pi-Neustart
✓ MQTTS-, HTTPS-, CORS- und WSS-Checks
Ausstehend: WebRTC-Audio in beide Richtungen
✓ Desktop-/Mobilansicht, Modal, Validation und Fehler-Toast
Ausstehend: Ausfall-, Lease- und Wiederanlauftests im Zielnetz

08 · Versionierung

Kleine, nachvollziehbare Releases

SemVer wird bewusst eingesetzt: MAJOR für nicht kompatible Umstellungen, MINOR für zusammenhängende Funktionen und PATCH für kompatible Korrekturen.

Das Repository liegt privat auf GitHub. Lokale Commits und Pushes erfolgen ausschließlich nach ausdrücklicher Freigabe durch den Repository-Eigentümer; Secrets, Zertifikate, Laufzeitdaten und Backups bleiben durch verbindliche Ignore-Regeln außerhalb von Git.

  1. 0.3.1Passkey-Kompatibilitätskorrektur: Credentials werden mit den offiziellen Parsern von WebAuthn 2.8 verarbeitet; ungültige Antworten erzeugen kontrollierte API-Fehler statt HTTP 500. Pairings werden anhand des eingegebenen Code-HMAC geladen, sodass mehrere gleichzeitig offene Gerätecodes unabhängig funktionieren. Ein erweiterter Smoketest deckt beide Credential-Typen und parallele Pairings ab.
  2. 0.3.0Öffentliche PWA-Anbindung: Origin, WebAuthn-RP-ID und Client-Konfiguration auf piding-intercom.taxer.at umgestellt. HSTS, CORS, WSS, Passkey-Optionen und PWA-Ressourcen wurden von außen bestätigt; Nginx vertraut nur dem verifizierten Zoraxy-Host und bestand den kontrollierten Test gegen einen gefälschten Piding-Client-IP-Header.
  3. 0.2.3Shutdown-Pfad begrenzt und diagnostizierbar gemacht: Der Signaling-Socket besitzt eine kurze Schließfrist und wird bei ausbleibender Antwort gezielt abgebrochen. Der reale systemd-Neustart des Pi-Clients wurde danach ohne Stop-Timeout bestätigt.
  4. 0.2.2Erste Härtung des kontrollierten Pi-Neustarts: Ein systemd-Signal fordert nun die aktive Schließung des blockierenden Signaling-WebSockets an, bevor Audio, MQTT und GPIO geordnet beendet werden.
  5. 0.2.1Reale Saalfelden-Integration: LXC-Dienste und Pi-Client installiert, Pi registriert und MQTTS-Steuerung für Mute/Unmute Ende-zu-Ende bestätigt. WebAuthn-Serialisierung und MQTT-v2-Rückmeldung wurden kompatibel korrigiert; die Dokumentation trennt bestätigte Integration von noch ausstehendem Hardware- und Standorttest.
  6. 0.2.0V1-Quellbasis: FastAPI-Signaling mit WebAuthn-Pairing, 30-Sekunden-Override-Lease und MQTT-Brücke; MQTTS-/Nginx-/systemd-Vorlagen; Web-Audio-PWA mit PTT-Fallback sowie aiortc-Pi-Daemon mit GPIO-Abstraktion.
  7. 0.1.0Erste zentrale Architektur- und Betriebsdokumentation mit V1-Ausgangskonzept, Flowchart und vorbereitetem privatem Git-Repository.