Netzwerk API

Mit diesem Funktionsbaustein stellt die Steuerung eine einfache, offene Schnittstelle für Fremdgeräte und Fremdprogramme bereit – etwa ein Energiemanagement, Home Assistant, Node-RED, eine eigene Anwendung oder ein Skript. Über eine TCP-Verbindung können die Werte aller Variablen der Adressliste gelesen und geschrieben werden, wahlweise über ein einfaches Textprotokoll oder über HTTP.

Die Netzwerk API ist die dokumentierte Schnittstelle für Fremdgeräte. Der Port 10001, über dem Studio und APP mit der Steuerung sprechen, ist dafür nicht vorgesehen: dessen Protokoll ist verschlüsselt, nicht offengelegt und kann sich mit jeder Version ändern.

Der Baustein wird wie jeder andere Funktionsbaustein auf einer Programmseite angelegt, Port und Protokoll eingestellt und das Projekt in die Steuerung übertragen. Mehrere Netzwerk API Bausteine mit unterschiedlichen Ports sind möglich, z.B. einer für das Textprotokoll und einer für HTTP.

Ausgänge
AC	Anzahl Clients	Anzahl der aktuell verbundenen Clients, im Sekundentakt aktualisiert. Es sind höchstens 32 Verbindungen gleichzeitig möglich. Beim Protokoll HTTP ist eine Verbindung nur für die Dauer einer Anfrage offen, der Wert steht deshalb meist auf 0.
Parameter
	Port	TCP-Port, auf dem die Steuerung Verbindungen annimmt (1 bis 65535, Vorgabe 9090). Der Port darf nicht von einem anderen Dienst der Steuerung belegt sein, z.B. 10001 (Studio/APP), 80/443 (Weboberfläche) oder 502 (Modbus Slave).
	Protokoll	Text (Vorgabe): Dauerhafte TCP-Verbindung, Befehle und Antworten zeilenweise im Format `1/1/1=1` mit abschließendem LF (\n). Wertänderungen werden selbsttätig an alle verbundenen Clients gemeldet. HTTP: Je Anfrage ein Aufruf im Format `http://192.168.1.90:9090/?1/1/0=1`. Die Steuerung antwortet mit einer normalen HTTP-Antwort und schließt danach die Verbindung. Wertänderungen werden nicht selbsttätig gemeldet.

Siehe auch allgemeine Parameter aller Funktionsbausteine.

Befehle

Jeder Befehl besteht aus einer Adresse der Adressliste, einem Gleichheitszeichen und einem Wert bzw. einem Fragezeichen.

Befehl	Wirkung	Antwort
`3/0/3=21.5`	Setzt die Variable 3/0/3 auf 21,5 und sendet den Wert wie ein Bedienelement der APP (siehe „Schreiben“).	keine (Text) bzw. leere Antwort (HTTP)
`3/0/0=?`	Fragt den aktuellen Wert der Variable 3/0/0 ab.	`3/0/0=21.340000`
`?`	Fragt alle Variablen der Adressliste ab.	eine Zeile je Variable, zum Schluss `?=FINISHED`

Adressen: Es gelten die Adressen der Adressliste im Studio, dreistufig in der Form Hauptgruppe/Mittelgruppe/Untergruppe, z.B. 3/1/0. Als Trennzeichen wird auch der Punkt angenommen (3.1.0), eine zweistufige Adresse (3/256) wird wie in der ETS umgerechnet. Die Steuerung antwortet immer dreistufig mit Schrägstrich. Es sind KNX-Gruppenadressen ebenso erreichbar wie interne Variablen. Eine Adresse, die in der Adressliste nicht angelegt ist, wird ignoriert und im Protokoll der Steuerung vermerkt – es gibt keine Fehlerantwort.

Werte: Zahlen werden mit Punkt als Dezimaltrennzeichen übertragen. In Antworten stehen sie immer mit sechs Nachkommastellen, z.B. 1.000000 für Ein und 0.000000 für Aus. Beim Schreiben genügt 1 oder 21.5. Text-Variablen (EIS 15 Zeichenkette) werden als Klartext übertragen, der Text darf selbst ein Gleichheitszeichen enthalten. Alle übrigen Werte werden als Zahl übergeben, die Umrechnung in das KNX-Format (z.B. 2-Byte-Gleitkomma) übernimmt die Steuerung. Uhrzeit, Datum und Farbwerte werden über die Netzwerk API nicht unterstützt.

Zeilenende: Im Textprotokoll muss jeder Befehl mit LF (\n) abgeschlossen werden, ein zusätzliches CR (\r) wird ignoriert. Jede Antwortzeile endet mit LF. Eine Zeile darf höchstens 1023 Zeichen lang sein.

Lesen

Ein Lesebefehl liefert den Wert, den die Steuerung aktuell für diese Variable kennt. Es wird dabei kein Telegramm auf den KNX-Bus gesendet und am Projekt nichts verändert. Der Wert ist der zuletzt empfangene bzw. gesendete Wert – bei einer KNX-Adresse also der Wert des letzten Telegramms, das die Steuerung auf dem Bus gesehen hat.

Wer ausschließlich liest, sendet nur Befehle mit ?. Die Schnittstelle selbst kennt keinen Nur-Lese-Modus, siehe „Sicherheit“.

Schreiben

Ein Schreibbefehl wirkt genauso, als würde der Wert in der APP bedient: Die Steuerung übernimmt den Wert in die Variable, verknüpfte Funktionsbausteine reagieren darauf, und ist die Adresse eine KNX-Gruppenadresse, wird ein Schreibtelegramm auf den KNX-Bus gesendet. Bei einer internen Variable bleibt der Wert in der Steuerung.

Die Steuerung meldet nicht zurück, ob ein Aktor den Befehl ausgeführt hat. Dafür die Rückmeldeadresse des Aktors abfragen bzw. im Textprotokoll deren Änderungsmeldung abwarten.

Änderungsmeldungen (nur Textprotokoll)

Im Textprotokoll muss nicht zyklisch abgefragt werden. Solange die Verbindung besteht, sendet die Steuerung jede Wertänderung einer Variable unaufgefordert an alle verbundenen Clients, im selben Format wie eine Antwort, z.B. 3/0/0=21.400000. Das gilt für Telegramme vom KNX-Bus ebenso wie für Werte aus Funktionsbausteinen, der APP oder anderen Schnittstellen. Werte, die ein Client selbst über die Netzwerk API geschrieben hat, werden nicht an die Clients zurückgemeldet.

Es gibt keine Auswahl einzelner Adressen – der Client erhält alle Änderungen und filtert selbst. Üblich ist: nach dem Verbinden einmal ? senden, um den Anfangsstand zu erhalten, danach nur noch die Änderungsmeldungen auswerten.

Beim Protokoll HTTP werden keine Änderungen gemeldet, hier muss zyklisch abgefragt werden.

Beispiele

Textprotokoll, z.B. mit netcat (Eingaben mit Enter abschließen):

nc 192.168.1.90 9090
3/0/0=?
3/0/0=21.340000
3/1/1=?
3/1/1=1.000000
3/0/0=21.400000      <- Änderungsmeldung, unaufgefordert

HTTP, z.B. mit curl oder im Browser:

curl "http://192.168.1.90:9090/?3/0/0=?"
3/0/0=21.340000

curl "http://192.168.1.90:9090/??"
1/1/0=0.000000
...
?=FINISHED

curl "http://192.168.1.90:9090/?3/0/3=21.5"

Im HTTP-Aufruf müssen Leerzeichen und Sonderzeichen wie üblich codiert werden (%20 für ein Leerzeichen). Mehrere Befehle in einem Aufruf werden durch %0A getrennt, z.B. /?3/0/0=?%0A3/0/4=?. Die Antwort ist reiner Text (text/plain, UTF-8).

Python, Textprotokoll mit Änderungsmeldungen:

import socket
s = socket.create_connection(("192.168.1.90", 9090))
s.sendall(b"?\n")                        # Anfangsstand
buf = b""
while True:
    buf += s.recv(4096)
    while b"\n" in buf:
        line, buf = buf.split(b"\n", 1)
        addr, value = line.decode().split("=", 1)
        print(addr, value)

Sicherheit

Die Netzwerk API hat keine Anmeldung und keine Verschlüsselung. Jedes Gerät, das den eingestellten Port erreicht, kann alle Variablen lesen und schreiben – und damit über KNX-Adressen auch Heizung, Warmwasser, Beschattung oder Türöffner schalten. Deshalb:

Den Baustein nur anlegen, wenn er gebraucht wird. Ohne Netzwerk API Baustein ist der Port geschlossen.
Den Port niemals im Router nach außen freigeben. Für den Fernzugriff ein VPN verwenden.
Den Zugriff im Netzwerk auf die Geräte beschränken, die ihn brauchen, z.B. über eine Firewall-Regel oder ein eigenes Netzsegment.
Mit dem allgemeinen Parameter „Deaktivieren“ lässt sich der Baustein abschalten, ohne ihn zu löschen – der Port ist dann geschlossen.

Grenzen

Höchstens 32 gleichzeitige Verbindungen je Baustein. Weitere Verbindungen werden erst angenommen, wenn wieder ein Platz frei ist (spätestens nach 10 Sekunden).
Ein Client, der Daten nicht innerhalb von 5 Sekunden abnimmt, wird getrennt.
Eine HTTP-Anfrage muss innerhalb von 5 Sekunden vollständig eintreffen.
Es gibt kein festes Mindestintervall. Im Textprotokoll ist zyklisches Abfragen unnötig. Wird per HTTP abgefragt, genügt für Zustände und Temperaturen ein Intervall von 5 bis 60 Sekunden. Die Abfrage ? aller Variablen erzeugt bei großen Projekten viel Datenverkehr und sollte nicht im Sekundentakt laufen.
Jeder Schreibbefehl auf eine KNX-Adresse erzeugt ein Telegramm auf dem Bus. Werte daher nur bei Änderung schreiben, nicht zyklisch – ein KNX-Bus verträgt nur wenige Dutzend Telegramme pro Sekunde.

Häufige Fragen zur Anbindung von Fremdsystemen

Welche Schnittstelle ist für ein Fremdsystem vorgesehen?

Für das Lesen und Schreiben von Variablen ist diese Netzwerk API die offene, dokumentierte Schnittstelle. Daneben gibt es MQTT Adressen I/O (Variablen als MQTT-Topics, z.B. für Home Assistant, ioBroker oder Node-RED) und den Modbus TCP Slave. Port 10001 gehört Studio und APP; dessen Protokoll ist nicht offengelegt und für Fremdsysteme nicht freigegeben.

Alle diese Schnittstellen sind Funktionsbausteine. Sie sind erst aktiv, wenn sie im Projekt angelegt und das Projekt in die Steuerung übertragen wurde – ohne Übertragung lässt sich keine davon einschalten. Deshalb immer vom Projektstand ausgehen, der aktuell in der Steuerung läuft (siehe unten „Projekt mit älterem Studio“).

Braucht die Netzwerk API eine Lizenz oder Freischaltung?

Nein. Die Netzwerk API benötigt keine eigene Lizenzoption, sie steht auf jeder Steuerung zur Verfügung, die ein Programm ausführt.

Wie meldet sich ein Fremdsystem an?

Gar nicht – es gibt weder Benutzer noch Passwort noch Verschlüsselung. Wer den Port erreicht, hat Zugriff. Der Schutz muss über das Netzwerk erfolgen, siehe „Sicherheit“.

Kann ausschließlich gelesen werden?

Lesebefehle (…=? und ?) ändern nichts und senden kein KNX-Telegramm. Einen gesperrten Schreibzugriff gibt es jedoch nicht: ob nur gelesen wird, bestimmt das Fremdsystem. Erst ein Befehl mit Wert (3/1/0=1) schreibt.

Gibt es Push-Meldungen bei Wertänderungen?

Ja, im Textprotokoll werden alle Änderungen selbsttätig gesendet, siehe „Änderungsmeldungen“. Bei HTTP muss zyklisch abgefragt werden.

Gibt es Testwerkzeuge oder Beispiele?

Zum Testen genügen netcat, curl oder ein Browser, siehe „Beispiele“. Um ein Fremdsystem gefahrlos zu erproben, zunächst nur lesen. Ungültige Befehle und Adressen, die in der Adressliste fehlen, werden im Protokoll der Steuerung vermerkt.

Welcher KNX-Datentyp gilt für eine Variable?

Die Datentypen im Studio sind nach der alten EIS-Zählung benannt, nicht nach der KNX-DPT-Nummer. Die Zahl im Namen ist daher nicht die DPT-Hauptnummer:

Studio	KNX DPT
EIS 1: Bit schalten (Bit)	DPT 1 (1 Bit)
EIS 5: Fließkomma (2 Byte)	DPT 9 (2-Byte-Gleitkomma, z.B. 9.001 Temperatur)
EIS 6: Relativ Wert 0-100% (1 Byte)	DPT 5.001
EIS 9: Fließkomma (4 Byte)	DPT 14
EIS 10: Zähler Wert 16 Bit (2 Byte)	DPT 7 (ohne Vorzeichen) bzw. DPT 8
EIS 11: Zähler Wert 32 Bit (4 Byte)	DPT 12 (ohne Vorzeichen) bzw. DPT 13
EIS 14: Zähler Wert (1 Byte)	DPT 5 (ohne Vorzeichen) bzw. DPT 6
EIS 15: Zeichenkette (14/255 Byte)	DPT 16

Über die Netzwerk API spielt die Byte-Kodierung keine Rolle: Werte werden als Klartext-Zahl übertragen (21.500000), die Steuerung rechnet in das KNX-Format um. Die DPT-Angabe wird nur gebraucht, wenn ein Fremdsystem direkt am KNX-Bus mitliest.

Lassen sich Adressen und Datentypen exportieren?

Ja, im Studio über „Bearbeiten – Adressen ODBC Export“, wahlweise alle oder nur die markierten Adressen. Zur Wahl stehen das XML-Format des ETS-Gruppenadressexports (Name, Adresse, DPT) und das ESF-Format (Textdatei mit Gruppennamen, Adresse, Kommentar und Datentyp). Die Verknüpfungen mit Funktionsbausteinen und Bedienelementen werden nicht exportiert.

Kann die KNX-Schnittstelle der Steuerung als KNXnet/IP-Schnittstelle genutzt werden?

Steuerungen mit eingebauter KNX-Schnittstelle bringen ein internes KNX IP Gateway mit. Solange es ausgeschaltet ist, ist UDP-Port 3671 nicht erreichbar. Eingeschaltet wird es im Studio unter „Steuerung – Dienste“ oder im Webinterface eingeschaltet. Im Baustein KNX Schnittstelle muss dafür der Typ „KNX-IP Gateway onboard“ eingestellt sein.

KNXnet/IP Tunneling über UDP, Port 3671, das Gateway wird von der Schnittstellensuche gefunden. Routing nur, wenn im Baustein KNX Schnittstelle „Router Funktion“ eingeschaltet ist.
Mehrere Tunnelverbindungen gleichzeitig sind möglich. Die Anzahl ergibt sich aus „Phys. Adresse Anzahl“ im Baustein KNX Schnittstelle: die erste Adresse erhält die Steuerung, die zweite das Gateway, die übrigen die Tunnelverbindungen – eine davon belegt die Steuerung selbst. Bei der Vorgabe 4 bleibt also genau eine Verbindung frei, z.B. für die ETS. Für ein zusätzliches Fremdsystem die Anzahl erhöhen (bis 8).
Die physikalische Adresse einer Tunnelverbindung wird aus diesem Bereich vergeben, sie lässt sich nicht einzeln festlegen.
Das Gateway ist für die Programmierung mit der ETS gedacht. Es handelt sich um Fremdsoftware; KNX IP Secure wird nicht unterstützt. Ein Fremdsystem am Tunnel sieht und sendet Telegramme direkt am Bus, an der Steuerung vorbei – es darf die Anlage genauso wenig stören wie ein weiteres KNX-Gerät.

Wer Werte nur lesen oder einzelne Funktionen ansteuern will, fährt mit der Netzwerk API oder MQTT meist besser: das Fremdsystem arbeitet dann mit denselben Variablen wie die Steuerung, auch mit internen Variablen, die nie auf den Bus gelangen.

Kann der Modbus-TCP-Slave für ein Fremdsystem genutzt werden?

Ja. Dafür wird ein Baustein Modbus TCP Slave angelegt, an dessen Eingängen die Variablen verknüpft werden, die als Register bereitstehen sollen. Port 502 ist erst offen, wenn ein solcher Baustein im Projekt ist. Registerbelegung und Funktionscodes stehen in der Hilfe des Bausteins.

Projekt mit älterem Studio: „Unbekannter Funktionsbaustein“

Zeigt das Studio beim Öffnen „Unbekannter Funktionsbaustein“, ist das Studio älter als das Projekt und kennt diesen Baustein noch nicht. Es handelt sich nicht um kundenspezifische Bausteine.

Das Projekt in diesem Zustand nicht speichern und nicht übertragen – beim Speichern wird der unbekannte Baustein endgültig durch einen Kommentar ersetzt und fehlt danach im Programm.
Das aktuelle Studio installieren. Welche Version in der Steuerung läuft, zeigt „Steuerung – Steuerungsinformationen“; das Studio sollte mindestens diese Version haben.
Vor jeder Änderung eine Kopie des Projektes sichern (Datei – Speichern unter), erst dann den neuen Baustein anlegen und das Projekt übertragen.