Generic Web Export
Das Export Modul "Generic Web Export" stellt die Verbindung zu einem MQTT Broker her und veröffentlicht Status Nachrichten unter verschiedenen Topics.
Diese Topics sind von der Struktur her ähnlich aufgebaut wie die URL Struktur des "Generic REST Server" Export Moduls.
Die versendeten Nachrichten verwenden das Generic IoT Datenmodell innerhalb eines Container Objektes, welches Informationen zur Nachrichten Identifikation bereitstellt.
Es können mehrere Export Instanzen angelegt werden, jedoch immer nur eine Instanz pro Broker URL.
Nachdem die Verbindung zu einem Broker aufgebaut wurde, werden alle verfügbaren Geräte als Update übertragen. Somit ist sichergestellt das der aktuelle Gerätestatus übermittelt wurde.
Nachrichten werden grundsätzlich als String übertragen und sind im Regelfall als JSON Objekte formatiert.
Im Bereich IoT Export der Web Konfiguration oder der BSC Remote können die Export Verbindung angelegt, sowie die Parameter konfiguriert werden.
Es werden TCP/SSL sowie Web Socket (http/https) Verbindungen unterstützt. Die Authentifizierung ist per Nutzername und Passwort oder Client Zertifikat möglich.
Die entsprechenden Zertifikate oder Zugangsdaten können während der Konfiguration hinterlegt werden.
Es besteht die Möglichkeit die Basis Topics zum veröffentlichen von Nachrichten anzupassen.
Parameter | Standardwert | Mögliche Werte | Beschreibung |
---|---|---|---|
Thing Topic Prefix | GATEWAY_ID/things | | Alle Thing updates werden in Topics mit diesem Prefix veröffentlicht. |
Command Topic | GATEWAY_ID/cmd |
| Unter diesem Topic können Kommandos an das Gateway gesendet werden. |
Status Topic | GATEWAY_ID/status |
| Unter diesem Topic veröffentlich das Gateway seine Status Informationen. Der Verbindungsstatus Verbunden/Getrennt kann hier ausgelesen werden. |
Notification Topic | GATEWAY_ID/msg |
| Push Benachrichtigungen für den ausgewählten Benutzer werden unter diesem Topic veröffentlicht. |
Alle Nachrichten, ausgenommen RAW Nachrichten, werden als JSON Objekte übertragen.
Grundlegende Informationen für die Zuordnung von Nachrichten sind in allen Objekten vorhanden.
Feld | Datentype | Beschreibung |
---|---|---|
nodeId | String | Eine eindeutige ID, welche das Gateway identifiziert. |
eventId | String | Eine eindeutige ID, welche das auslösende Event identifiziert. Es ist möglich das mehrere Nachrichten durch das gleiche Event erzeugt werden und somit die gleiche Event ID erhalten. Ein Beispiel dafür wären Geräte Updates. Dort werden Sub Topics verwendet, somit erhalten die einzelnen Kanal Sub Topics Nachrichten mit der gleichen Event ID. Es ist garantiert das eine Event ID innerhalb von 24 Stunden nur einmalig vorkommt. |
timestamp | Number | Unterschied, gemessen in Millisekunden, zwischen der aktuellen Zeit und dem 01.01.1970 00:00 Uhr basierend auf der UTC Zeitzone. Dieser Zeitstempel kann, zusammen mit der Event ID, auch dazu genutzt werden Nachrichten eindeutig zu identifizieren. |
Das in der Konfiguration hinterlegte "Thing Topic Prefix" dient als Basis für alle Geräte Aktualisierungen. Ein Beispiel dafür wäre "ACDBDA59E9CF/things".
Die eigentlichen Geräte Aktualisierungen werden über verschachtelte "Sub Topics" veröffentlicht.
Die Sub Topics werden nur bei einer Änderung von Werten benachrichtigt.
So kann bei der "Subscription" gezielt entschieden werden, über welche Daten man benachrichtigt wird.
Sub Topic | Beschreibung |
---|---|
/<Thing ID> | Das komplette Thing Objekt. |
/<Thing ID>/state | Den Online/Offline Status des Gerätes. |
/<Thing ID>/metaInfos | Die Meta Informationen des Gerätes. |
/<Thing ID>/<Channel ID>/value | Der Wert eines einzelnen Kanals. |
/<Thing ID>/<Channel ID>/value/raw | Der Wert als Plaintext String ohne Nachrichten Container. |
Die Änderung eines Wertes kann über ein extra dafür vorgesehenes "Sub Topic" angestoßen werden:
/<Thing ID>/<Channel ID>/value/set
Der neue Wert wird einfach als Nachricht an dieses Topic gesendet.
Sobald der Wert (real) geändert wurde, werden entsprechende Aktualisierungen an die vorher schon beschriebenen "Sub Topics" gesendet.
Alternativ gibt es auch ein Kommando Objekt zum ändern von Werten, näheres dazu ist im Abschnitt zum Kommando Topic nachzulesen.
Über das Kommando Topic, welches in der Konfiguration als "Command Topic" hinterlegt ist, können verschiedene Befehle an das Gateway gesendet werden.
Ein Kommando besteht immer aus dem Kommando Type sowie einigen Parametern. Die Parameter sind immer Strings.
Kommando Type | Parameter | Mögliche Werte | Erforderlich | Beschreibung |
---|---|---|---|---|
CHANGE_VALUE | thingId |
| X | Eindeutige Thing ID des Gerätes. |
| channelId |
| X | Die eindeutige Channel ID es Kanals welcher geschaltet werden soll. |
| newValue |
| X | Der neue Wert welcher gesetzt werden soll. |
AUTO_PAIRING | pairingEnabled |
| X | Gibt an ob das automatische Anlenen aktiviert werden soll. Ist es bereits aktiviert passiert nicht weiter. |
| targetGrpID | Positiver Wert | X | Die ID der Gruppe, zu welcher neue Geräte hinzugefügt werden sollen. Sind keine Gruppen vorhanden, muss 0 angegeben werden. Die Geräte werden dadurch ohne Gruppenzuordnung angelegt. |
| enabledForSec | Positiver Wert | X | Zeit in Sekunden bis der Anlernmodus automatisch wieder ausgeschaltet wird. Ein Wert von 0 deaktiviert die automatische Abschaltung. |
DELETE_THING | thingId |
| X | Eindeutige ID des Thing |
Über das Status Topic, welches in der Konfiguration als "Status Topic" hinterlegt ist, werden Status Informationen zum Gateway übertragen.
Insbesondere der Online Status hat hier besondere Bedeutung. Dieser gibt an ob das Gateway mit dem MQTT Broker verbunden ist.
Falls das Gateway nicht mit dem Broker verbunden ist, wird die Event ID der Status Nachricht auf "disconnect" gesetzt und der Timestamp auf -1. Dies kann innerhalb von 24 Stunden mehrfach auftreten!
Feld | Datentype | Beschreibung |
---|---|---|
version | String | Die aktuelle Software Version des Gateways. |
connected | Boolean | Status ob das Gateway aktuell verbunden ist. |
metaInfos | Objekt | Ein Objekt mit zusätzlichen Informationen. Jedes Feld ist vom Datentype String, der Feldname fungiert als "Key" um eine Map abzubilden. |
Über das Benachrichtigungs Topic, welches in der Konfiguration als "Notification Topic" hinterlegt ist, werden Push Benachrichtigungen übertragen.
Die Push Benachrichtigungen müssen für den unter "User" ausgewählten Benutzer bestimmte sein.
Feld | Datentype | Beschreibung |
---|---|---|
msg | String | Der Text der Push Benachrichtigung. Es können \n für Zeilenumbrüche enthalten sein. |