KO-Gateway Schnittstelle
Inhalt
1.
Kommunikationsprotokoll
1.1.
Art des Zugriffs
1.1.1.
Websocket aktivieren
1.1.2.
Kompatibilitätsmodus
2.
Informationen für Entwickler
2.1.
Authentifizierung
2.2.
Startverhalten
2.3.
Kommunikation
2.3.1.
Grupenadressen Umrechnung
2.3.2.
Telegramm an den HS/FS
2.3.3.
Telegramm vom HS/FS
2.4.
Klartextnamen der K-Objekte
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