violet-knx-bridge

Status: 🧪 Konzept / frühe Planungsphase. Noch keine Hardware gebaut, keine Firmware lauffähig.

ESP32-basierte Brücke zwischen dem Violet Pool Controller (HTTP/JSON-API) und einem KNX-Bus (Twisted Pair, TP-UART). Ermöglicht die Einbindung aller Pool-Werte (Temperatur, pH, ORP, Chlor, Pumpenstatus, ...) und -Aktoren (Pumpe, Heizung, Solar, Dosierung, Licht) in eine bestehende KNX-Smart-Home- Installation – ohne Home Assistant, ohne Cloud, deterministisch und autark.

License: AGPL-3.0-or-later

Der Violet Pool Controller spricht nur JSON/HTTP (/getReadings?ALL, /setFunctionManually?...). KNX ist TP-UART-basiert. Es gibt keinen direkten Pfad – man braucht immer einen Übersetzer. Dieses Projekt baut genau diesen Übersetzer als kompaktes, stromsparendes Embedded-Gerät:

• Autark: läuft unabhängig von Home Assistant / PC / Server.
• Deterministisch: zyklisches Polling + Echtzeit-KNX-Telegramme.
• Kostengünstig: BOM ~30–60 €.
• Offen: Hardware-Design + Firmware unter AGPL-3.0.

 ┌───────────────────────┐ LAN / WLAN ┌──────────────────────┐
 │ Violet Pool │ ◀── HTTP/JSON (GET/POST) ─▶ │ ESP32 │
 │ Controller │ │ ┌────────────────┐ │
 │ (192.168.x.x) │ │ │ WiFi-Client │ │
 └───────────────────────┘ │ │ Polling-Loop │ │
 │ │ Mapping-Tabelle│ │
 │ │ KNX-Stack │ │
 │ └───────┬────────┘ │
 └──────────┼───────────┘
 │ UART
 ┌──────────▼───────────┐
 │ NCN5120 / TPUART │
 │ (KNX-Transceiver) │
 └──────────┬───────────┘
 │ TP
 ┌────────────────▼──────────────┐
 │ KNX-Bus (rot/schwarz, 30 V) │
 │ → Sensoren & Aktoren │
 └───────────────────────────────┘

Datenfluss:

1. Polling (z. B. alle 5–10 s): ESP32 → Controller GET /getReadings?ALL → JSON parsen → Werte auf konfigurierte KNX-Gruppenadressen (GAs) senden.
2. Kommando: KNX-Telegramm auf einer Kommando-GA → ESP32 → GET /setFunctionManually?... an den Controller.

• Zyklisches Polling aller Relevanten Readings (Pool-, Solar-, Ambient-Temp, pH, ORP, Chlor, Leitfähigkeit, DI/AI, Pumpenstatus, Fehlercodes).
• Schreiben von Sensorwerten als DPT 9.001 (°C), DPT 9.005/9.008 (mg/L, pH), DPT 1.001 (Bool) etc. auf Gruppenadressen.
• Empfangen von Schaltbefehlen (Pumpe, Heizung, Solar, DMX-Szenen, Dosierung) und Übersetzen in /setFunctionManually-Calls.
• Konfiguration per Web-UI (WLAN, Controller-URL, GA-Mapping-Tabelle).
• Persistente Konfiguration im NVS (Flash).
• Status-LEDs (WLAN, KNX-Bus, Fehler).
• Watchdog & automatischer Reconnect bei WLAN- oder Controller-Verlust.
• Optionales mDNS-Aufrufen für automatische Controller-Erkennung.

Gesamt: ~30–60 € je nach Beschaffung und ob eine eigene Platine oder ein Breadboard-/Steckboard-Aufbau gewählt wird.

Der KNX-Bus liefert 30 V DC, aber nur wenige mA pro Teilnehmer (typ. 10 mA, per ETS zugeteilt). Ein ESP32 zieht im WLAN-Peak bis zu 240 mA – das ist das 24-Fache des Bus-Budgets.

Echte Optionen:

• (A) ESP32 separativ speisen (empfohlen): USB-C-Netzteil oder 24-V-Aux-Netzteil + Step-Down. NCN5120 holt nur seine ~6–8 mA aus dem Bus. Sauber, zulassungsfreundlich.
• (B) Bus-Powered: Nur möglich mit extremem Power-Management (Deep-Sleep zwischen Polls, WiFi nur kurz an). Realistisch nicht mit dem Polling-Intervall, das wir brauchen. → verworfen.

Entscheidung: Variante (A) – separate Speisung des ESP32.

• Framework: PlatformIO (Arduino-Core) – schneller Einstieg, große Bibliotheksauswahl.
• Sprache: C++17.
• Abhängigkeiten (vorgesehen):
  • WiFiClientSecure / WiFiClient (ESP32 Core)
  • HTTPClient (ESP32 Core)
  • ArduinoJson ≥ 7
  • KNX-Stack: thelsing/KnxDevice oder Selfbus – Entscheidung offen.
  • Preferences (NVS) für Konfiguration
  • LittleFS + Web-UI (z. B. ESPAsyncWebServer)
• Konfigurationsdatei: platformio.ini mit passendem board.
• Build: pio run, Flash: pio run -t upload.

Die Zuordnung Controller-Feld → KNX-Gruppenadresse (inkl. DPT) wird in einer Mapping-Tabelle definiert (z. B. in der Web-UI oder als JSON-Datei im Flash). Beispiele:

• Nur Lesen ist ungefährlich. Sobald Befehle vom KNX an den Controller gesendet werden, kannst du Pumpen, Heizungen und Dosierung schalten – bitte sachgemäß absichern (Hardware-Notausschalter, Freigabesignale, Begrenzung der Kommando-GAs auf vertraute Teilnehmer).
• KNX-Bus und 230 V strikt trennen. Für die 30 V KNX-Leitung gilt die ortsfeste Elektroinstallation – im Zweifel von einer Fachkraft prüfen lassen.
• Zertifikate / Auth am Violet Controller: TLS ggf. mit eigenem CA-Zertifikat (Self-Signed-Support geplant).

v0.1.0 getaggt – Phasen 0, 1, 3–9 abgeschlossen. pio run -e esp32dev baut sauber (RAM 15 %, Flash 63 %), pio test -e native 13/13 grün. Bleibt: Hardware-Beschaffung + Schaltplan-Validierung (Phase 2.2), reale ETS-/Feldeinsatz-Tests (Phase 9 manuell).

Siehe TODO.md für die detaillierte, abarbeitbare Aufgabenliste und docs/ für die Architektur-Entscheidungen und Spezifikationen:

AGPL-3.0-or-later © Xerolux.

Beiträge willkommen – bitte vor größeren Arbeiten ein Issue aufmachen.

• violet-poolController-api – API-Client & Spezifikation der Endpunkte.
• violet-hass – Home-Assistant-Integration für den Violet Pool Controller.
• Selfbus – Open-Source-KNX-Hardware/Software, Inspiration für TPUART-Aufbau.
• thelsing/KnxDevice – schlanke KNX-Stack-Implementierung für MCU.