Integrationen

KNX einrichten

ETS-Projekte importieren und KNX direkt über den lokalen Werklio-Agent überwachen.

Voraussetzungen

• KNX/IP-Interface mit freiem Tunnelling-Slot im lokalen Netz
• ETS5.7- oder ETS6-Projektdatei im Format .knxproj
• Werklio-Standort mit KNX-Integration und aktivem Integration Key

Schritt für Schritt

1. Öffne die KNX-Integration und wähle Windows, Linux x64 oder Linux ARM64 als Plattform. Für Raspberry Pi OS 64 Bit ist ARM64 vorgesehen.
2. Lade das angezeigte Paket herunter und entpacke es auf dem dauerhaft laufenden Rechner. Unter Windows installierst du den Windows-Dienst als Administrator, unter Linux den systemd-Dienst mit sudo ./install-service.sh.
3. Ermittle das KNX/IP-Gateway mit dem Discovery-Befehl oder trage Adresse, Port und individuelle KNX-Adresse manuell ein.
4. Lade die .knxproj-Datei im Bereich ETS-Projekt importieren hoch und wähle die für die Überwachung relevanten Gruppenadressen aus.
5. Prüfe Namen, DPT und Betriebsart der importierten Datenpunkte und speichere die zentrale Konfiguration.
6. Hinterlege API-URL, Standort-ID und Integration Key lokal beim Agent. Nach dem Start lädt er die freigegebene Konfiguration automatisch und meldet seinen Status an Werklio.
7. Prüfe unter KNX Agents, ob Plattform, Architektur, Version, Gateway und letzter Kontakt angezeigt werden.

Beispielkonfiguration

# Linux x64: Archiv herunterladen und entpacken
wget https://app.werkl.io/downloads/Werklio.Knx.Agent-3.1.1-linux-x64.tar.gz
mkdir -p Werklio.Knx.Agent-linux-x64
tar -xzf Werklio.Knx.Agent-3.1.1-linux-x64.tar.gz -C Werklio.Knx.Agent-linux-x64
cd Werklio.Knx.Agent-linux-x64
# appsettings.json konfigurieren
sudo ./install-service.sh
systemctl status werklio-knx-agent
journalctl -u werklio-knx-agent -f

# Gateway im lokalen Netz suchen (Windows)
Werklio.Knx.Agent.exe --discover

# Gateway im lokalen Netz suchen (Linux)
./Werklio.Knx.Agent --discover

# Konfiguration in appsettings.json oder als .NET-Umgebungsvariablen
Werklio__ApiUrl=https://app.werkl.io
Werklio__SiteId=DEINE-STANDORT-GUID
Werklio__ApiKey=wk_live_DEIN_EINMALIGER_KEY
Knx__UseRemoteConfiguration=true

Testschritt

Starte den Windows- oder systemd-Dienst und beobachte in Werklio den Agent-Status sowie einen bekannten KNX-Datenpunkt.

Erwartetes Ergebnis

Der Agent erscheint online, nennt Version und Gateway und überträgt konfigurierte Gruppenwerte mit aktuellem Zeitstempel.

Empfohlenes Mapping

Fehlerbehebung

• Kein Gateway gefunden: Rechner und KNX/IP-Interface müssen sich im selben lokalen Netz befinden; Firewall, UDP 3671, Multicast und freien Tunnelling-Slot prüfen.
• Linux-Dienst startet nicht: systemctl status werklio-knx-agent und journalctl -u werklio-knx-agent prüfen; SiteId und ApiKey müssen vor dem ersten Start gültig sein.
• Agent bleibt offline: API-URL, Standort-ID, Integration Key, Systemzeit und ausgehendes HTTPS prüfen.
• Wert unplausibel: importierten DPT und die in ETS gesetzten Kommunikationsflags kontrollieren.
• Änderung fehlt: Konfiguration erneut speichern und prüfen, ob der Agent die neue Konfigurationsversion gemeldet hat.

Sicherheitshinweise

• KNX/IP niemals direkt aus dem Internet erreichbar machen; der Agent benötigt nur ausgehendes HTTPS zu Werklio.
• Integration Key ausschließlich in der geschützten lokalen Agent-Konfiguration speichern und nicht protokollieren.
• Nur für die Überwachung notwendige Gruppenadressen importieren; Gebäude- und Raumpfade können Rückschlüsse auf die Nutzung erlauben.