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).
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
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
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
- 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:
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.
HTTPS://HS_IP/opt/hsmonitor/index.htmlIP-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.
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:
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).
wss://HS_IP/cogw?authorization=AUTHIP-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:
x/z wird umgerechnet zu:
Numerisch -> Experte
In ihrer numerischen Form ist die Gruppenadresse im Attribut "ganum" in der XML-Datei angegeben.
Experte -> numerisch
x/y/z wird umgerechnet zu:
GRPADR = x*2048 + y*256 + zx/z wird umgerechnet zu:
GRPADR = x*2048 + zNumerisch -> Experte
x = GRPADR / 2048, Nachkommastellen werden ignorierty = (GRPADR - x*2048) / 256, Nachkommastellen werden ignoriertz = (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:
oder
Die Angabe des 3. Parameters "value" ist optional und hängt vom 1. Parameter "cmd" ab. Siehe folgende Tabelle.
{"cmd": COMMAND, "ga": GRPADR, "value": VAL]} (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 des 3. Parameters "value" 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 muss base64-kodiert angegeben werden! |
| 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:
2.3.3.1.Initialisierung
Dieses Telegramm wird nach einem Neustart für jedes über das KO-Gateway kommunizierte K-Objekt versendet.
Aufbau:
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:
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:
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.
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:
Datenstruktur der XML-Datei (Beispiel):
HTTPS://HS_IP/opt/sys/cobjects.xmlIP-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" = EIB-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 |
| fmtex | Datenformat 2 integer |
| 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 |