IoT Export
Verbindungs Template

Generic Web Export

17min

Einleitung

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.

Konfiguration

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



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.

Basis Daten von Nachrichten

Alle Nachrichten, ausgenommen RAW Nachrichten, werden als JSON Objekte übertragen.

Grundlegende Informationen für die Zuordnung von Nachrichten sind in allen Objekten vorhanden.

Basis Felder

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.

Geräte Topics

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.

Sub Topics

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.

Ändern von Werten

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.

Beispiel Daten

Kommando Topic

Ü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

  • true
  • false

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

Beispiel Kommandos

Status Topic

Ü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!

Status Objekt

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.

Verbunden
Getrennt


Benachrichtigungs Topic

Ü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.

Benachrichtigungs Objekt

Feld

Datentype

Beschreibung

msg

String

Der Text der Push Benachrichtigung.

Es können \n für Zeilenumbrüche enthalten sein.

Benachrichtigungs Objekt