Experte - KO-Gateway Schnittstelle

Um mit der eigenen Software einfach mit dem HS/FS zu kommunizieren dient diese Schnittstelle. Der HS/FS sendet bei jeder Änderung eines K-Objektes ein Telegramm. Die K-Objekte werden dazu einzeln oder global gekennzeichnet.

Diese Schnittstelle steht in Variante 1 (Kompatibilitätsmodus) seit HS/FS-Firmware v2.2 zur Verfügung.

Ab HS/FS-Firmware v4.7 existiert Variante 2: Verschlüsselte Kommunikation über Websockets (https).

1.Kommunikationsprotokoll

1.1.Art des Zugriffs

Um mit dem HS/FS über die KO-Gateway-Schnittstelle kommunizieren zu können, muss im Experte (unter Projekteinstellungen -> Netzwerk -> KO-Gateway) mindestens eine der beiden Zugriffs-Methoden aktiviert werden.

Websocket aktivieren
Kompatibilitätsmodus aktivieren

Für beide Methoden steht ein HS-Monitor als Verbindung zur KO-Gateway Schnittstelle zur Verfügung.

1.1.1.Websocket aktivieren

Es sind 10 gleichzeitige Zugriffe auf den HS/FS hiermit möglich.

Die mit dieser Methode arbeitende Version von HS-Monitor ist fester Bestandteil der Experte-Software und muss unter der Rubrik Stammdaten -> Projekteinstellungen -> Oberfläche aktiviert werden:

Entweder

muss die Option Alle aktiviert sein

oder

die Option Benutzerdefiniert muss aktiviert sein
und
die Checkbox hsmonitor muss aktiviert sein.

HS-Monitor wird dann mit auf den HS/FS übertragen und kann über einen Browser über die folgende URL abgerufen werden:

HTTPS://HS_IP/opt/hsmonitor/index.html

IP-ADR ist die IP-Adresse des HS/FS, ggf. ergänzt durch einen der im HS/FS-Experte unter "Projekteinstellungen -> Netzwerk -> Sicherheit" aktivierten HTTPS-Ports.

1.1.2.Kompatibilitätsmodus

Diese Methode ist ab Firmware v2.2 verfügbar und ermöglicht eine unverschlüsselte Verbindung mit dem HS/FS.
Es sind 10 gleichzeitige Zugriffe auf den HS/FS mit dieser Methode möglich.

Die mit dieser Methode arbeitende Version von HS-Monitor ist ein auf Windows-PC's ausführbares Programm (hsmonitor.exe, ab v4.7 nicht mehr im Lieferumfang enthalten).
Diese Methode kann parallel zum Zugriff über WebSockets verwendet werden.

2.Informationen für Entwickler

2.1.Authentifizierung

Zum Aufbau der Websocket-Verbindung für eigene Software zum HS/FS muss eine URL angegeben werden. Die zu verwendende URL enthält die notwendige Authentifizierung und muss folgendermaßen aufgebaut sein:

wss://HS_IP/cogw?authorization=AUTH

IP-ADR ist die IP-Adresse des HS/FS, ggf. ergänzt durch einen der im HS/FS-Experte unter "Projekteinstellungen -> Netzwerk -> Sicherheit" aktivierten HTTPS-Ports.

AUTH ist der passende, im Experte unter "Projekteinstellungen -> Netzwerk -> KO-Gateway" angegebene Schlüssel. Er muss hier base64-kodiert angegeben werden.

Schlägt die Authentifizierung fehl, findet kein Aufbau einer stehenden Verbindung statt und der HS/FS antwortet mit Statuscode 403 (Forbidden). Ist die Anfrage nicht vollständig, antwortet der HS/FS mit Statuscode 400 (Bad Request).

Achtung

Nach fehlgeschlagener Authentifizierung ist die IP-Adresse des Clients für 5 Sekunden gesperrt. In dieser Zeit liefert das Gerät auf Anfragen immer den Statuscode 503 zurück.

2.2.Startverhalten

Wenn das Gerät startet, ist der HTTP-Server bereits vor Abschluss der Initialisierung verfügbar. In dieser Zeit liefert das Gerät den Statuscode 503 auf alle Anfragen. Zusätzlich enthält die Antwort den HTTP-Header "Retry-After". Dieses Feld kann ausgewertet werden, um nach der angegebenen Zeit in Sekunden automatisch einen erneuten Versuch zu starten.

2.3.Kommunikation

Die Kommunikation mit dem HS/FS erfolgt mittels Daten in Form von JSON-Strukturen.

2.3.1.Grupenadressen Umrechnung

Die Gruppenadresse wird im HS/FS-Experte in der Form x/y/z oder x/z angegeben. In den an den HS/FS verschickten und den vom HS/FS kommenden Telegrammen ist die Gruppenadresse in einem numerischen Format angegeben. Die Umrechnung wird wie folgt vorgenommen:

Experte -> numerisch
x/y/z wird umgerechnet zu: GRPADR = x*2048 + y*256 + z
x/z wird umgerechnet zu: GRPADR = x*2048 + z

Numerisch -> Experte
x = GRPADR / 2048, Nachkommastellen werden ignoriert
y = (GRPADR - x*2048) / 256, Nachkommastellen werden ignoriert
z = (GRPADR - x*2048 - y*256)

In ihrer numerischen Form ist die Gruppenadresse im Attribut "ganum" in der XML-Datei angegeben.

2.3.2.Telegramm an den HS/FS

Aufbau:
{"cmd": COMMAND, "ga": GRPADR, "value": VAL, "encoding": ENCODE]} (bei cmd = 1,2)

oder

{"cmd": COMMAND, "ga": GRPADR} (bei cmd = 3,4,5,6)

COMMAND ist ein Integer von 1 bis 6. Erklärung siehe nachfolgende Tabelle.

GRPADR ist die Gruppenadresse. Sie muss numerisch angegeben werden und kann aus den im Experte verwendeten Formaten errechnet werden.

Die Angabe der Parameter 3. ("value") und 4. ("encoding") ist optional und hängt vom 1. Parameter "cmd" ab. Siehe folgende Tabelle.

`COMMAND`	Beschreibung	`VAL`
1	Wert setzen absolut	Float oder Text, abhängig vom jeweiligen K-Objekt. Ein Text kann bei Bedarf (z.B. wenn er Binärdaten enthält) base64-kodiert angegeben werden. Dazu muss das zusätzliche Feld "encoding" angegeben und mit dem Wert "base64" gesetzt sein. Z.B. `{"cmd": 1, "ga": 204854, "value": "YmVpc3BpZWw=", "encoding": "base64"}`
2	Wert setzen relativ	Float
3	Step+	wird nicht angegeben
4	Step-	wird nicht angegeben
5	Liste+	wird nicht angegeben
6	Liste-	wird nicht angegeben

2.3.3.Telegramm vom HS/FS

Es können 3 verschiedene Arten von Telegrammen vom HS/FS gesendet werden:

Initialisierung
Initialisierung abgeschlossen
Folgetelegramm

2.3.3.1.Initialisierung

Dieses Telegramm wird nach einem Neustart für jedes über das KO-Gateway kommunizierte K-Objekt versendet.

Aufbau:
{"cmd": 2, "ga": GRPADR, "value": VAL]}

GRPADR ist die Gruppenadresse. Sie muss numerisch angegeben werden und kann aus den im Experte verwendeten Formaten errechnet werden.

VAL kann ein Integer oder ein String sein. Handelt es sich um einen String, ist er base64-kodiert.

2.3.3.2.Initialisierung abgeschlossen

Dieses Telegramm wird vom HS/FS gesendet, wenn nach einem Neustart die Initialisierung aller über das KO-Gateway kommunizierten K-Objekte abgeschlossen ist.

Aufbau:
{"cmd": 2}

2.3.3.3.Folgetelegramm

Dieses Telegramm wird verschickt, wenn dem angegebenen K-Objekt ein Wert zugewiesen wurde. Das geschieht auch dann, wenn der bisherige Wert mit dem neuen Wert des K-Objekts übereinstimmt.

Aufbau:
{"cmd": 1, "ga": GRPADR, "value": VAL]}

GRPADR ist die Gruppenadresse. Sie muss numerisch angegeben werden und kann aus den im Experte verwendeten Formaten errechnet werden.

VAL kann ein Integer oder ein String sein. Handelt es sich um einen String, ist er base64-kodiert.

2.4.Klartextnamen der K-Objekte

Die Namen der Kommunikationsobjekte können über die folgende URL als XML-Datei abgerufen werden.

HTTPS://HS_IP/opt/sys/cobjects.xml

IP-ADR ist die IP-Adresse des HS/FS, ggf. ergänzt durch einen der im HS/FS-Experte unter "Projekteinstellungen -> Netzwerk -> Sicherheit" aktivierten HTTPS-Ports.

Beispiel: HTTPS://192.168.0.11:443/opt/sys/cobjects.xml
Datenstruktur der XML-Datei (Beispiel):

 <cobject
    id="911"
    used="0"
    type="eib"
    path="01 Lighting\2nd Floor\"
    fmt="EIS1+EIS2+EIS7_1BIT"
    fmtex="integer"
    name="FL02 Light"
    rem="0"
    init="0"
    min="0"
    max="1"
    step="0"
    list=""
    ga="1/2/1"
    ganum="2561"
    cogws="1"
    cogwr="0"
    scan="1"
    sbc="1"
    read="0"
    transmit="1"
 />

Alle Felder werden im HS/FS-Experten im Programmpunkt Kommunikationsobjekte bearbeitet. Nähere Infos zu den Feldern können der Online-Hilfe des HS/FS-Experten zu den Kommunikationsobjekten entnommen werden.

Attribut	Beschreibung
id	Eindeutige Nummer des Kommunikationsobjektes
used	1 = Kommunikationsobjekt wird im Projekt verwendet. 0 = keine Verwendung.
type	Art des Kommunikationsobjektes "internal" = internes Kommunikationsobjekt "eib" = KNX-Kommunikationsobjekt
path	Ordner, in dem das Kommunikationsobjekt im HS/FS-Experten abgelegt ist.
fmt	Datenformat 1 Klartext (Texte befinden sich in der Datei minmax.txt im Experte-Unterverzeichnis "/dat") `EIS1+EIS2+EIS7_1BIT EIS6_8BIT NONEIS_8BIT_RTR EIS5_16BIT EIS2+EIS6_8BIT EIS?_8BIT EIS10_16BIT_UNSIGNED EIS10_16BIT_SIGNED EIS11_32BIT_UNSIGNED EIS11_32BIT_SIGNED EIS?_14BYTE EIS3_3BYTE_TIME EIS4_3BYTE_DATE EIS?_4BIT EIS9_4BYTE EIS8_2BIT EIS?_DALI EIS?_SRO EIS?_3BYTE`
fmtex	Datenformat 2 `integer number text date time unknown`
name	Name des Kommunikationsobjektes
rem	1 = remanent im HS/FS 0 = nicht remanent
init	Initwert
min	Minimalwert
max	Maximalwert
step	Schrittgröße
list	Liste
ga	Gruppenadresse wie im HS/FS-Experten erfasst
ganum	Gruppenadresse (numerisch)
cogws	KO-Gateway senden
cogwr	KO-Gateway empfangen
scan	1 = Beim Starten abfragen 0 = Beim Starten nicht abfragen
sbc	1 = Send by Change 0 = kein Send by Change
read	1 = auslesbar 0 = nicht auslesbar
transmit	1 = Übertragen 0 = nicht übertragen