Anbindung an Cordaware bestinformed über MQTT
Nach erfolgreichem Verbindungsaufbau zwischen Broker und Client und der Authentifizierung des externen MQTT-Clients, sieht der Ablauf der Anbindung an Cordaware bestinformed folgendermaßen aus:
MQTT-Client übermittelt Event an Cordaware bestinformed Schnittstelle
Sobald ein Event lokalisiert wird, erhält der externe MQTT-Client die entsprechende Informationen z. B. einer Warnanlage (oder dessen Broker) und sendet dieses Event über ein zuvor definiertes Topic (z. B. an "/bestinformed/mqtt/m2i") an die Cordaware bestinformed-Schnittstelle/Broker. Dieser verarbeitet dieses Event und übergibt die übermittelten Details oder Aktionen an den Cordaware bestinformed-Server. Entsprechende Tasks werden von Cordaware bestinformed verarbeitet und automatisch ausgeführt, wie z. B. der Aufruf und Versand einer Templatevorlage.
Zur korrekten Verarbeitung müssen die Daten über MQTT in einem JSON-Datenformat für den Cordaware bestinformed-Broker vorliegen.
Nachrichtenversand über die MQTT-Schnittstelle
Damit Sie eine Info über die MQTT-Schnittstelle von Cordaware bestinformed versenden können, müssen Sie zunächst in der App Passwort (System -> Passwort) ein Passwort für einen Benutzer (z. B. "mqtt_admin") anlegen.´
Klicken Sie hierzu in der Toolbar auf den Button 
(Neu) und geben Sie nun als Alias den MQTT-Benutzernamen "mqtt_<user>" ein.
Die Beschreibung ist hierbei ein optionales Feld und kann frei befüllt werden.
Geben Sie im Anschluss noch das gewünschte Passwort ein, bestätigen Sie dieses durch eine wiederholte Eingabe und speichern Sie den Eintrag ab.
Für z. B. den Admin mit dem Passwort "bestinformed" würde der Eintrag folgendermaßen aussehen:
Beispiele zur Übermittlung
In diesen Beispielen wird demonstriert, welche Syntax zu verwenden ist, um über unsere Schnittstellen einen automatischen Aufruf und Versand eines Templates vollziehen zu können.
Zur Veranschaulichung wird das Datenformat für die MQTT-Übermittlung (JSON) im Vergleich zur Syntax für eine MailToInfo-Weitergabe dargestellt.
MQTT (JSON) |
MailToInfo |
||
Host |
bestinformed.cordaware.local |
SMTP-Server |
bestinformed.cordaware.local |
Port |
1883 |
Port |
8025 |
User |
mqtt_admin |
Absender |
frei wählbar |
Passwort |
bestinformed |
Empfänger |
frei wählbar |
Topic |
bestinformed/mqtt/m2i |
Betreff |
newinfo |
Nachricht |
{ "action": "newinfo", "templatename": "Chemikalienaustritt" } |
Nachricht |
username=admin password=bestinformed templatename=Chemikalienaustritt |
Zur Vereinfachung der Generierung der korrekten Syntax kann über die Oberfläche von Cordaware bestinformed der benötigte Ausdruck per Knopfdruck erzeugt werden.
Nehmen Sie hierzu die gewünschten Einstellungen pro Info bzw. Template vor und konvertieren Sie diese über die entsprechenden Buttons in der Oberfläche des Infoeditors.
MQTT (JSON) |
MailToInfo |
Ein Auszug der Konvertierung für ein JSON-Objekt wäre folgender Syntaxausdruck (ohne Template):
 |
Die Konvertierung in MailToInfo-Syntax:
 |
Nachrichtenversand
Neben den Werten innerhalb eines Template sind bei unseren Schnittstellen auch weitere Kriterien relevante Eigenschaften und bestimmen eine Info.
Grundsätzlich definiert der Parameter "action" selbstredend die Aktion einer ausgehenden Info/Nachricht in Cordaware bestinformed. Hier bieten sich folgende Möglichkeiten:
•newinfo - Erstellt eine neue Info.
•editinfo - Editiert eine bestehende Info.
•cancelinfo - Bricht eine bestehende Info ab.
•copycancel - Bricht eine bestehende Info ab und entwarnt diese.
Um Infos über die MQTT-Schnittstellen bearbeiten oder abbrechen zu können, muss beim Erstellen der Info eine beliebige, eindeutige ID über den Schlüssel "myid" angegeben werden. Dieser Schritt ist nicht erforderlich, trotzdem empfehlen wir Infos über MQTT und MailToInfo immer mit einer eindeutigen ID zu erstellen, um somit die Info später über die Schnittstellen ebenfalls bearbeiten oder abbrechen zu können. Ohne ID kann dies nur über die Weboberfläche erledigt werden.
Für die "myid" können Sie beliebige Buchstaben, Zahlen sowie Bindestriche verwenden. Um möglichst viele Freiheiten zu schaffen, obliegt die Verwaltung dieser IDs den Kunden selbst. |
Beispiel zur Angabe einer eindeutigen ID
Im Folgenden wird eine neue Info erzeugt, die das Template "Chemikalienaustritt" verwendet und die ID "bi-info_mqtt_0123456789abcdef" bekommt.
{ "action": "newinfo", "myid": "bi-info_mqtt_0123456789abcdef", "templatename": "Chemikalienaustritt" } |
Beispiel zum Bearbeiten einer bestehenden Info
Hier wird die zuvor erstellte Info editiert und der Nachrichtentext geändert.
{ "action": "editinfo", "myid": "bi-info_mqtt_0123456789abcdef", "info": "Giftige Chemikalien sind ausgetreten! Bitte schließen Sie sofort alle Fenster und Türen." } |
Beispiel zum Abbrechen einer bestehenden Info
Jetzt wird die zuvor erstellte und editierte Info über die MQTT-Schnittstelle abgebrochen.
{ "action": "cancelinfo", "myid": "bi-info_mqtt_0123456789abcdef" } |
Abbrechen und Entwarnen einer bestehenden Info
Um Infos über die MQTT-Schnittstelle mittels "copycancel" zu entwarnen, muss beim Erstellen der ursprünglichen Info der Entwarnungstext angegeben werden.
Dieser muss, sofern er bei Benutzung eines Templates nicht darin hinterlegt ist, mit Hilfe des Schlüssels "info_10000" angegeben werden.
{ "action": "newinfo", "myid": "bi-info_mqtt_0123456789abcdef_2", "info": "Der Nachrichtentext der Info.", "info_10000": "Der Entwarnungstext der Info." } |
Diese Info kann nun mit der Aktion "copycancel" unter Angabe der "myid" abgebrochen und entwarnt werden. Dadurch wird automatisch eine neue Entwarnungsinfo erzeugt und versendet.
{ "action": "copycanel", "myid": "bi-info_mqtt_0123456789abcdef_2" } |
Diese Entwarnungsinfo kann ebenfalls über die MQTT-Schnittstelle bearbeitet und abgebrochen werden.
Hierbei muss als "myid" die ID der ursprünglichen Nachricht mit dem Suffix "_allclear" angegeben werden.
Beispielsweise wird also aus der ID "bi-info_mqtt_0123456789abcdef_2" die Entwarnungs-ID "bi-info_mqtt_0123456789abcdef_2_allclear".
Beispiel zum Bearbeiten einer Entwarnungsinfo
Hier wird die Entwarnungsinfo editiert und der Nachrichtentext geändert.
{ "action": "editinfo", "myid": "bi-info_mqtt_0123456789abcdef_2_allclear", "info": "Geänderter Entwarnungstext der Info." } |
Beispiel zum Abbrechen einer Entwarnungsinfo
Jetzt wird die zuvor editierte Entwarnungsinfo über die MQTT-Schnittstelle abgebrochen.
{ "action": "cancelinfo", "myid": "bi-info_mqtt_0123456789abcdef_2_allclear" } |
Generelle Funktionsweise
Alle Optionen/Tasks werden im Fall des Eintretens eines neuen Events vom externen MQTT-Client an das zuvor definierte Topic und somit den MQTT-Broker übergeben und dieser leitet gemeinsam mit den ebenfalls beinhalteten Details des Events die weiteren Schritte ein, wie den Nachrichtenversand in Cordaware bestinformed.
