Getting Started

Dieser Dokumentationsartikel soll Ihnen einen ersten, schnellen Start in die Verwendung dieses Produkts ermöglichen. Nach der erfolgreichen Installation und Lizenzierung führen Sie die folgenden Schritte aus, um eine Verbindung zu einem MQTT Message Broker herzustellen und Nachrichten zu senden und zu empfangen.

	Message Broker Installation Dieser Dokumentsartikel setzt das Vorhandensein eines lokal installierten und funktionsfähigen MQTT Message Brokers voraus. Als Beispiel verwenden wir hier den Mosquitto Message Broker, sie können aber jeden beliebigen Message Broker verwenden.

Einrichtung des Message Brokers

Der Mosquitto Message Broker wird seit der Version 2.x mit einer Konfiguration ausgeliefert, die die Einrichtung von Security Maßnahmen erfordert, damit ein sicherer Betrieb des Message Brokers gewährleistet wird. Im Folgenden zeigen wir Ihnen, wie Sie die Konfiguration des Mosquitto Message Brokers so abändern, dass eine ungesicherte Kommunikationsverbindung mit dem Broker hergestellt werden kann. Dies soll jedoch ausschliesslich zu Testzwecken in einer vertrauenswürdigen Betriebsumgebung erfolgen. Für den produktiven Betrieb empfehlen wir die Verwendung einer sicheren Broker-Konfiguration.

1. Installieren Sie den Mosquitto Message Broker auf Ihrem System.

2. Erstellen Sie ein Backup der Datei mosquitto.conf aus dem Mosquitto Installationsverzeichnis. Dieses befindet sich typischerweise unter C:\Program Files\mosquitto.

3. Öffnen Sie die Datei mosquitto.conf mit einem Texteditor Ihrer Wahl und entfernen Sie den vorhandenen Inhalt. Fügen Sie den folgenden Inhalt hinzu und speichern Sie die Datei.

listener 1883 allow_anonymous true

4. Starten Sie den Mosquitto Message Broker neu, entweder über den entsprechenden Windows-Dienst oder manuell über die Konsole bzw. die mosquitto.exe.

Sie haben nun den Mosquitto Message Broker so konfiguriert, dass dieser auf eingehende Clientverbindung auf Port 1883 lauscht und keinerlei Security (weder eine Benutzerauthentifizierung, noch Client-Zertifikate) benötigt.

Sie können nun mit der Einrichtung des TwinCAT Projekts beginnen.

Einrichtung des TwinCAT Projekts

Nachdem Sie den Message Broker installiert haben, können Sie nun mit der Einrichtung des TwinCAT Projekts beginnen, um eine Verbindung zum Broker aufzubauen und Nachrichten über diesen auszutauschen.

1. Erstellen Sie ein TwinCAT-Projekt mit einer SPS und fügen Sie die Tc3_IotBase als Bibliotheksreferenz hinzu.

2. Legen Sie einen Programmbaustein an und erstellen Sie im Deklarationsteil eine Instanz von FB_IotMqttClient sowie zwei Hilfsvariablen, um den Programmablauf bei Bedarf steuern zu können.

PROGRAM PrgMqttCom
VAR
    fbMqttClient    : FB_IotMqttClient;
    bSetParameter   : BOOL := TRUE;
    bConnect        : BOOL := TRUE;
END_VAR

3. Deklarieren Sie für die zu verschickende MQTT-Nachricht zwei Variablen für Topic und Payload. Im Beispiel soll jede Sekunde eine Nachricht verschickt werden, was über einen entsprechenden Timer-Baustein realisiert werden soll. Eine Zählervariable soll später für den Nachrichteninhalt verwendet werden.

    (* published message *)
    sTopicPub   : STRING(255) := 'MyTopic';
    sPayloadPub : STRING(255);
    fbTimer : TON := (PT:=T#1S);
    i : UDINT;

4. Deklarieren Sie für den Nachrichtenempfang eine Variable, die das zu empfangende Topic enthält und zwei weitere Variablen, die Topic und Payload der zuletzt empfangenen Nachricht anzeigen. Die empfangenen Nachrichten sollen in einer Warteschlange (Queue) gesammelt werden, um sequenziell ausgewertet werden zu können. Hierfür deklarieren Sie eine Instanz von FB_IotMqttMessageQueue sowie eine Instanz von FB_IotMqttMessage.

    (* received message *)
    bSubscribed    : BOOL;
    sTopicSub      : STRING(255) := 'MyTopic';
    {attribute 'TcEncoding':='UTF-8'}
    sTopicRcv      : STRING(255);
    {attribute 'TcEncoding':='UTF-8'}
    sPayloadRcv    : STRING(255);
    fbMessageQueue : FB_IotMqttMessageQueue;
    fbMessage      : FB_IotMqttMessage;

5. Im Programmteil muss der MQTT Client zyklisch getriggert werden, um den Verbindungsaufbau zum Broker, den Verbindungserhalt und den Nachrichtenempfang zu gewährleisten. In diesem Beispiel werden die Verbindungsparameter einmalig vor dem Client-Aufruf im Programmcode zugewiesen. Weil dies generell meist nur einmal notwendig ist, könnten die Parameter aber auch bereits im Deklarationsteil bei der Instanziierung des MQTT Client angegeben werden. Nicht alle Parameter müssen zugewiesen werden. In unserem Beispiel ist der Broker lokal auf demselben System installiert auf dem Sie auch das SPS Projekt aktivieren wollen. Alternativ können Sie auch die IP-Adresse oder den Hostnamen des Systems angeben, auf dem der Message Broker installiert wurde.

IF bSetParameter THEN
    bSetParameter               := FALSE;
    fbMqttClient.sHostName      := 'localhost';
    fbMqttClient.nHostPort      := 1883;
    fbMqttClient.ipMessageQueue := fbMessageQueue;
END_IF
fbMqttClient.Execute(bConnect);

6. Der zyklische Aufruf vom MQTT Client sorgt für den Empfang der Nachrichten. Der Client empfängt alle Nachrichten, auf deren Topic er sich zuvor beim Broker angemeldet hat (siehe nächster Schritt) und legt diese in der Message Queue ab. Sobald Nachrichten verfügbar sind, rufen Sie die Methode Dequeue() auf und erhalten über das Nachrichtenobjekt fbMessage Zugriff auf die Nachrichteneigenschaften wie Topic und Payload. Bei der folgenden Implementierung der Nachrichtenauswertung wird pro Zyklus eine empfangene Nachricht ausgewertet. Falls mehrere Nachrichten in der Message-Queue gesammelt wurden, verteilt sich deren Auswertung entsprechend auf mehrere Zyklen.

IF fbMessageQueue.nQueuedMessages > 0 THEN
    IF fbMessageQueue.Dequeue(fbMessage:=fbMessage) THEN
        fbMessage.GetTopic(pTopic:=ADR(sTopicRcv), nTopicSize:=SIZEOF(sTopicRcv) );
        fbMessage.GetPayload(pPayload:=ADR(sPayloadRcv), nPayloadSize:=SIZEOF(sPayloadRcv), bSetNullTermination:=FALSE);
    END_IF
END_IF

7. Sobald die Verbindung zum Broker aufgebaut wird, soll sich der Client auf ein bestimmtes Topic anmelden. Ebenso soll jede Sekunde eine Nachricht versandt werden. In diesem Beispiel ist sTopicPub = sTopicSub, sodass ein Loopback entsteht und die gesendeten Nachrichten gleich wieder empfangen werden. In anderen Applikationen unterscheiden sich die Topics typischerweise.

IF fbMqttClient.bConnected THEN
    IF NOT bSubscribed THEN
        bSubscribed := fbMqttClient.Subscribe(sTopic:=sTopicSub, eQoS:=TcIotMqttQos.AtMostOnceDelivery);
    END_IF
    fbTimer(IN:=TRUE);
    IF fbTimer.Q THEN // publish new payload every second
        fbTimer(IN:=FALSE);
        i := i + 1;
        sPayloadPub := CONCAT('MyMessage', TO_STRING(i));
        fbMqttClient.Publish(sTopic:= sTopicPub, pPayload:= ADR(sPayloadPub), nPayloadSize:= LEN2(ADR(sPayloadPub))+1, eQoS:= TcIotMqttQos.AtMostOnceDelivery, bRetain:= FALSE, bQueue:= FALSE );
    END_IF
END_IF

Nächste Schritte

Nachdem Sie nun erfolgreich eine Verbindung zum Message Broker hergestellt haben, empfehlen wir Ihnen den Mosquitto Message Broker wieder auf seinen Auslieferungszustand zurückzusetzen. Hierfür nehmen Sie bitte die Backupdatei der mosquitto.conf, welche Sie in den vorhergehenden Schritten erstellt haben. Diese Datei ist, zusammen mit der Dokumentation des Brokers, eine gute Grundlage für weitere Schritte, z.B. zur Einrichtung einer sicheren Message Broker Betriebsumgebung unter Berücksichtigung von Client/Server Zertifikaten und einer Benutzerauthentifizierung.

In obigem Beispiel haben wir als Payload der Nachricht eine String-Variable verschickt bzw. empfangen. Da das Datenformat bei MQTT nicht spezifiziert ist, können Sie frei entscheiden, wie dieses aufgebaut sein soll. Typische IoT-Anwendungen verwenden jedoch ein JSON- oder XML-basiertes Datenformat. Hierfür stellt Beckhoff die SPS-Bibliothek Tc3_JsonXml bereit, mit deren Hilfe Sie JSON- und XML-Dokumente erstellen und auslesen können.