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.

---

Warum?

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.

---

Architektur (Konzept)

   ┌───────────────────────┐         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.

---

Features (geplant)

• 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.

---

Hardware (Übersicht)

Bauteil	Beispiel / Hinweis	ca. €
ESP32-Dev-Board	ESP32 DevKitC v4, AZ-Delivery ESP32, WEMOS D1 R32	5–10
KNX-Transceiver-Modul	NCN5120-Breakout oder Selfbus-TPUART-Modul	15–30
DC/DC-Step-Down (KNX → 5 V)	NUR optional, siehe Stromversorgung unten	3–6
KNX-Busklemme	WAGO 216-201 (grün/gelb)	2
Netzteil 5 V (USB-C oder Hohlstecker)	für ESP32 (empfohlene Variante)	5–10
Status-LEDs + Vorwiderstände	rot (Fehler), grün (WLAN), gelb (KNX-Bus)	2
Gehäuse	DIN-Schiene 1 TE (z. B. Hager TE411-Leergehäuse) oder Printgehäuse	5–15
Stift-/Buchsenleisten, Kondensatoren	Beschaltung laut NCN5120-Datenblatt	3

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

⚠️ Stromversorgung – kritischer Designpunkt

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.

---

Firmware (geplant)

• 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.

---

KNX-Mapping (Konzept)

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:

Controller-Feld	KNX DPT	Richtung	Beispiel-GA
TEMP_POOL	9.001 (°C)	Controller→KNX	5/1/1
PH_VALUE	9.005 (pH)	Controller→KNX	5/1/10
PUMP_STATE	1.001 (T/A)	Controller→KNX	3/1/1
PUMP_CMD	1.001 (T/A)	KNX→Controller	3/1/2
HEATER_CMD	1.001	KNX→Controller	3/2/1
ERROR_CODE	5.010	Controller→KNX	5/5/1

---

Sicherheitshinweise

• 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).

---

Status & Roadmap

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:

Dokument	Inhalt
docs/adr/0001-knx-stack.md	Architektur-Entscheidung: thelsing/knx (+ STKNX-Alternative)
docs/hardware.md	Pin-Tabelle, Blockschaltbild, Breadboard-Anleitung, LED-Codes
docs/firmware.md	Architektur, Module, State Machine, Build & Flash
docs/violet-api-fields.md	Alle 143 Controller-Felder, Endpunkte, Zustandscodes
docs/knx-mapping.md	Mapping-Tabelle Controller-Feld ↔ KNX-DPT/GA
docs/hardware-bom.md	Konkrete Einkaufsliste (~88 €) mit Begründung
hardware/case/README.md	3D-Druck DIN-Schienen-Gehäuse (OpenSCAD)
knx_prod/README.md	ETS-importierbare .knxprod-Pipeline
CHANGELOG.md	Versionierung + Release-Notes
TODO.md	10-Phasen-Roadmap mit Checkboxen

---

Lizenz

AGPL-3.0-or-later © Xerolux.

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

---

Danksagung / Verwandte Projekte

• 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.