Intrexx Industrial - MQTT in Intrexx

1. Zertifikat importieren

Die Verbindungen zum Test-MQTT-Broker von United Planet steht nur verschlüsselt zur Verfügung. Wenn Sie diesen für die fogenden Beispiele verwenden wollen, importieren Sie bitte im ersten Schritt die Self-Signed-Zertifikate des Servers in den Portaleigenschaften. Wählen Sie im Dialog "Zertifikatsquelle" die Option "Download von Internetadresse" aus. Tragen Sie dort den Server "message-broker.unitedplanet.com" und den Port 8883 für MQTT ein.

2. Nachrichten lesen

Auf dem Test-MQTT-Broker gibt es das Topic "guest/sampleMachine/machineState", das den Status einer Maschine protokolliert. Hier zeigen wir Ihnen, wie Sie die Nachrichten aus diesem Topic lesen und in eine Intrexx-Applikation schreiben können.

2.1. Applikation erstellen

Legen Sie eine neue Applikation mit der Vorlage "Basisapplikation" an.

Wechseln Sie auf die Eingabeseite. Löschen Sie alle vorhandenen Elemente mit Ausnahme der Schaltflächen. Legen Sie dann die folgenden neuen Eingabefelder mit dem Kontrolltyp "Text" an:

Device Operational Status
Message Title

Wechseln Sie auf die Seite "Alle Einträge" und nehmen Sie die neuen Felder als Tabellenspalten auf. Für die Sortierung kann das Datenfeld "Erstellungsdatum" aufgenommen werden. Die vorhandene Spalte "Titel" kann entfernt werden. Speichern und veröffentlichen Sie die Applikation.

2.2. Prozess erstellen

Erstellen Sie einen neuen Prozess.

Entfernen Sie alle eventuell vorhandenen Prozess-Elemente. Legen Sie dann eine Generische Ereignisquelle an. Wählen Sie in der Konfiguration die Klasse
"de.uplanet.lucy.server.mqtt.workflow.eventsource.MQTTWorkflowEventSource" aus. Fügen Sie die folgenden Eigenschaften hinzu:

serverUri: ssl://message-broker.unitedplanet.com:8883
topic: guest/sampleMachine/machineState
userName: guest

Wenn die generische MQTT-Ereignisquelle konfiguriert und der Prozess gespeichert ist, wird bereits eine Verbindung zum Message Broker hergestellt.

Markieren Sie die Generische Ereignisquelle und öffnen Sie den Details-Dialog mit der Taste F4. Kopieren Sie dort die GUID der Ereignisquelle.

Legen Sie dann einen Generischen Ereignisbehandler an. Wählen Sie in der Konfiguration die Klasse "de.uplanet.lucy.server.mqtt.workflow.eventhandler.MQTTWorkflowEventHandler" aus. Fügen Sie die Eigenschaft "MQTTSourceGuid" hinzu. Fügen Sie als Wert die aus der Ereignisquelle kopierte GUID ein. Damit wird der Generische Ereignisbehandler mit der Generischen Ereignisquelle verbunden und hört auf die Ereignisse, die die Quelle liefert.

Legen Sie eine Groovy-Aktion mit einer Verbindung zum Generischen Ereignisbehandler an. Fügen Sie das folgende Skript ein:

import de.uplanet.util.ISODateTimeUtil
import groovy.json.JsonSlurper

def bytes = g_event.message.payload
def strMsg = new String(bytes, "UTF-8")

def l_jsonSlurper = new JsonSlurper()
def l_parsedJSON = l_jsonSlurper.parseText(strMsg)

g_sharedState.deviceOperationalStatus = l_parsedJSON.device.operationalStatus
g_sharedState.messagesTitle = l_parsedJSON.messages[0].title

In diesem Skript werden die Werte des Maschinenstatus (deviceOperationalStatus) und der Nachrichtentitel (messagesTitle) abgefragt und dem sharedState zugewiesen.

Legen Sie eine Datengruppen-Aktion mit einer Verbindung zur Groovy-Aktion an. Wählen Sie die Aktion "Datensatz hinzufügen" aus.

Wählen Sie als Zieldatengruppe die Datengruppe der in diesem Beispiel erstellten Applikation aus.

In der Feldzuordnung fügen Sie die benutzerdefinierten Systemwerte "deviceOperationalStatus" und "messagesTitle", deren Werte in der vorausgehenden Groovy-Aktion und an den sharedState übergeben werden, mit dem Typ "Verabeitungskontext" hinzu. Ordnen Sie die Systemwerte den entsprechenden Ziel-Feldern aus der Applikation zu. Speichern Sie den Prozess.

2.3. Die Applikation im Browser

Wenn Sie die Applikation im Browser öffnen, sehen Sie nun, soweit Änderungen auf dem Test-MQTT-Broker erfolgt sind, das Protokoll des Maschinenstatus. Bei jeder Änderung auf dem Broker wird vom Prozess ein neuer Datensatz mit den aktuellen Daten in der Applikation angelegt.

3. Nachrichten schreiben und administrieren

3.1. Applikation erstellen

Legen Sie eine neue Applikation mit der Vorlage "Basisapplikation" an.

Wechseln Sie auf die Eingabeseite. Legen Sie ein neues Eingabefeld mit dem Titel "Lesen" und dem Kontrolltyp "Text" an.

Wechseln Sie auf die Seite "Alle Einträge" und nehmen Sie das neue Feld als Tabellenspalte auf. Für die Sortierung kann das Datenfeld "Erstellungsdatum" aufgenommen werden. Speichern und veröffentlichen Sie die Applikation.

3.2. Prozess erstellen

3.2.1. Erste Prozesskette: Nachrichten schreiben

Erstellen Sie einen neuen Prozess mit einem Datengruppen-Ereignisbehandler.

Wählen Sie in den Eigenschaften des Ereignisbehandlers die zuvor erstellte Applikation aus.

Wählen Sie im nächsten Schritt die Datengruppe und das Datensatz-Ereignis "Ändern" aus.

Erstellen Sie eine Groovy-Aktion und verbinden Sie diese mit dem Datengruppen-Ereignisbehandler. Tragen Sie das folgende Groovy-Skript ein.

def myVal = g_record["78A3E6FCB1CB525C159079D97DADA7BAE21F0CC4"].value /* datafield Titel <string> */
g_sharedState.msgOut = '{"name":"' + myVal + '"}'

Ersetzen Sie dabei die GUID "78A3E6FCB1CB525C159079D97DADA7BAE21F0CC4" mit der GUID des Datenfeldes "Titel" aus Ihrer eigenen Applikation. Diese GUID können Sie direkt im Editor im Bereich Applikationsstruktur ermitteln und einfügen. In diesem Skript wird eine Referenz auf das Titel-Datenfeld aus der zuvor erstellten Applikation gebildet. In der zweiten Zeile wird der aktuelle Wert des Datenfeldes in den sharedState geschrieben.

Erstellen Sie eine Generische Aktion und verbinden Sie sie mit der Groovy-Aktion. Wählen Sie in den Eigenschaften die Klasse
"de.uplanet.lucy.server.mqtt.workflow.action.MQTTMessageProducerWorkflowAction" aus und tragen Sie die folgenden Eigenschaften ein:

data.contextVariableName, Wert "urn:sharedState:msgOut"
serverUri, Wert "ssl://message-broker.unitedplanet.com:8883"
topic, Wert "guest/[beliebiger Topic-Name]
userName, Wert "extuser"
password, Wert "haithabu"

Mit diesem Teil des Prozesses wird, wenn Sie im Browser einen Datensatz in der Applikation ändern, der Wert des Datenfeldes "Titel" in das Topic "guest/[Ihr Topic-Name]" geschrieben.

3.2.2. Exkurs Kontextvariablen

Neben statischen Werten können für die Eigenschaft "data.contextVariableName" der Generischen Aktion auch dynamische Werte aus dem aktuellen Verarbeitungskontext verwendet werden. Folgende Präfixe werden unterstützt:

urn:sharedState:
urn:request:
urn:session:
urn:user:
urn:systemDataGroup:

Weitere Informationen zu diesem Thema finden Sie hier.

3.2.3. Zweite Prozesskette: Nachrichten lesen

Um zu kontrollieren, ob das Schreiben der Nachrichten auf dem Test-MQTT-Broker funktioniert, kann nun zusätzlich eine lesende Prozesskette erstellt werden. Gehen Sie dazu genauso vor wie bei der Erstellung des Prozesses im ersten Beispiel beschrieben, mit den folgenden Unterschieden:

Die Prozesskette wird im aktuellen Prozess erstellt. Es muss kein neuer Prozess angelegt werden.
Verwenden Sie in der Generischen Ereignisquelle statt dem userName "guest" den userName "extuser". Tragen Sie auch die zusätzliche Eigenschaft "password" mit dem Wert "haithabu" ein.
Verwenden Sie in der Eigenschaft "topic" den Topic-Namen, den Sie in der ersten Prozesskette in der generischen Aktion definiert haben (guest/[beliebiger Topic-Name]).

Tragen Sie in der Groovy-Aktion das folgende Skript ein:

import de.uplanet.util.ISODateTimeUtil
import groovy.json.JsonSlurper

def bytes = g_event.message.payload
def strMsg = new String(bytes, "UTF-8")

def l_jsonSlurper = new JsonSlurper()
def l_parsedJSON = l_jsonSlurper.parseText(strMsg)

g_sharedState.msg = l_parsedJSON.name

Tragen Sie in der Feldzuordnung der Datengruppenaktion den benutzerdefinierten Systemwert "msg" mit dem Typ "Verarbeitungskontext" ein und ordnen Sie diesen Wert dem Datenfeld "Lesen" aus der zuvor erstellten Applikation zu.
Speichern Sie den Prozess.

Der komplette Prozess sollte nun wie folgt aussehen:

3.3. Die Applikation im Browser

Legen Sie auf der Eingabeseite einen beliebigen Titel an. Auf der Seite "Alle Einträge" kann dieser Titel dann geändert werden, wenn Sie auf die Lupenschaltfläche in der ersten Spalte der Tabelle klicken. Diese Änderung löst den Prozess aus, der die Änderung auf den Broker schreibt. Die zweite Prozesskette reagiert und schreibt den geänderten Wert in einen neuen Datensatz, den Sie dann auch gleich in der Tabelle auf der Seite "Alle Einträge" sehen können.

4. Klassen

4.1. MQTTWorkflowEventSource

Die Klasse MQTTWorkflowEventSource stellt Nachrichten eines oder mehrerer MQTT-Topics zur Verfügung. Weitere Informationen zur Klasse und den im Folgenden beschriebenen Eigenschaften finden Sie hier.

Eigenschaft serverUri

Pflichtangabe, als Wert muss die Verbindungs-URI für den MQTT-Server eingetragen werden (z.B. ssl://message-broker.unitedplanet.com:8883).

Eigenschaft topic

Pflichtangabe, als Wert muss das MQTT-Topic, das konsumiert werden soll, angegeben werden (z.B. guest/sampleMachine/machineState). Weitere Informationen finden Sie hier.

Eigenschaft userName

Geben Sie hier als Wert den Benutzernamen für die Anmeldung am Server an.

Eigenschaft password

Geben Sie hier als Wert das Passwort des Benutzers für die Anmeldung am Server an.

Eigenschaft clientId

Client-Identifier, der den MQTT-Client gegenüber dem Server identifiziert. Diese Eigenschaft muss in der Regel nicht gesetzt werden, da Intrexx automatisch eine eindeutige Client-ID generiert.

Eigenschaft randomizeClientId

Ist der Wert true (default), so wird ein global eindeutiges Suffix an die konfigurierte Client-ID angehängt.

Eigenschaft globalSharedState

globalSharedState (default: false) ist eine Standard-Eigenschaft für Ereignisquellen oder Timer. Diese Eigenschaft legt fest, ob ein gemeinsamer globaler Shared-State verwendet werden soll.

Eigenschaft impersonateUserGuid

impersonateUserGuid ist eine Standard-Eigenschaft für Ereignisquellen oder Timer. Geben Sie hier als Wert die GUID des Benutzers, mit dem diese Ereignisquelle ausgeführt werden soll, an. Wird keine Benutzer-GUID angegeben, so werden Prozesse mit dem Systemkonto und Administratorberechtigungen ausgeführt.

Eigenschaft runWithLocalSystemPrivileges

runWithLocalSystemPrivileges (default: true) ist eine Standard-Eigenschaft für Ereignisquellen oder Timer. Gibt an, ob der Prozess mit Administratorberechtigungen ausgeführt werden soll.

Eigenschaft logVerbose

Ausführlicheres Logging (Default: false).

Eigenschaft reconnect

Diese Eigenschaft (default: true) steuert, ob der Client (also diese Ereignisquelle) nach einem Verbindungsabbruch versuchen soll, sich erneut mit dem Server zu verbinden.

Eigenschaft sendBeforeStartEvent

Gibt an, ob vor dem Starten der Ereignisquelle ein Event erzeugt werden soll (default: false).

Eigenschaft sendAfterStopEvent

Gibt an, ob nach dem Beenden der Ereignisquelle ein Event erzeugt werden soll (default: false).

Eigenschaft startDelay

Ist eine Standard-Eigenschaft für viele Ereignisquellen oder Timer. Bestimmt die Wartezeit in Millisekunden bevor die Ereignisquelle startet (default: 0).

Eigenschaft onErrorRestartWaitTimeout

Wartezeit in Millisekunden für erneute Arbeitsaufnahme nach Fehler (default: 60 Sekunden = 60000 ms).

Eigenschaft stopWaitTimeout

Wartezeit in Millisekunden für die Beendigung der Verbindung.

4.2. QOS

Mit dieser Klasse wird die MQTT-Dienstqualität (Quality of Service) geregelt. Folgende Werte sind möglich:

0: At most once delivery
1: At least once delivery
2: Exactly once delivery

Weitere Informationen finden Sie hier.