FB_IotMqttClient
Der Funktionsbaustein ermöglicht die Kommunikation zu einem Message Broker basierend auf MQTT Version 3.1.1.
Ein Client-Funktionsbaustein ist hierbei für die Verbindung zu genau einem Broker zuständig. Um die Hintergrundkommunikation zu diesem Broker zu gewährleisten und Nachrichten empfangen zu können, muss die Methode Execute() des Funktionsbausteins zyklisch aufgerufen werden.
Alle Verbindungsparameter sind als Eingangsparameter vorhanden und werden beim Verbindungsaufbau ausgewertet.
Syntax
Definition:
FUNCTION_BLOCK FB_IotMqttClient
VAR_INPUT
sClientId : STRING(255); // default is generated during initialization
sHostName : STRING(255) := '127.0.0.1'; // default is local host
nHostPort : UINT := 1883; // default is 1883
sTopicPrefix : STRING(255); // topic prefix for pub and sub of this client (handled internally)
nKeepAlive : UINT := 60; // in seconds
sUserName : STRING(255); // optional parameter
sUserPassword : STRING(255); // optional parameter
stWill : ST_IotMqttWill; // optional parameter
stTLS : ST_IotMqttTls; // optional parameter
ipMessageQueue : I_IotMqttMessageQueue; // if received messages should be queued during call of Execute()
END_VAR
VAR_OUTPUT
bError : BOOL;
hrErrorCode : HRESULT;
eConnectionState : ETcIotMqttClientState;
bConnected : BOOL; // TRUE if connection to host is established
END_VAR
Eingänge
Name | Typ | Beschreibung |
|---|---|---|
sClientId | STRING(255) | Die Client-ID kann individuell angegeben werden und muss bei den meisten Message Brokern eindeutig sein. Bei fehlender Angabe wird eine ID automatisch vom TwinCAT Treiber generiert, welche auf dem SPS Projektnamen basiert. |
sHostName | STRING(255) | sHostName kann als Name oder als IP-Adresse angegeben werden. Bei fehlender Angabe wird Local Host verwendet. |
nHostPort | UINT | Hier wird der Host Port angegeben. Dieser ist standardmäßig 1883. |
sTopicPrefix | STRING(255) | Hier kann ein Topic Prefix angegeben werden, das automatisch für alle Publish- und Subscribe-Kommandos angefügt wird. |
nKeepAlive | UINT | Hier kann die Watchdog-Zeit in Sekunden angegeben werden, mit der die Verbindung zwischen Client und Broker überwacht wird. |
sUserName | STRING(255) | Optional kann ein Benutzername angegeben werden. |
sUserPassword | STRING(255) | Zum Benutzernamen kann hier ein Passwort angegeben werden. |
stWill | Bei irregulärem Verbindungsabbau des Clients vom Broker kann optional eine letzte vorkonfigurierte Nachricht vom Broker an das sogenannte „Will-Topic“ versendet werden. Hier wird diese Nachricht spezifiziert. | |
stTLS | Wenn der Broker eine TLS gesicherte Verbindung anbietet, kann hier die nötige Konfiguration vorgenommen werden. | |
ipMessageQueue | I_IotMqttMessageQueue | Hier kann optional eine Instanz von FB_IotMqttMessageQueue zugewiesen werden. Wenn Sie eingehende neue Nachrichten in der Message Queue einsammeln wollen, ohne selbst die Callback-Methode zu implementieren, kann dieser Eingangsparameter gesetzt werden. (Siehe auch IotMqttSampleUsingQueue) Wenn Sie eingehende neue Nachrichten ohne Message Queue auswerten wollen indem Sie die Callback-Methode selbst implementieren, wird dieser Eingangsparameter nicht benötigt. (Siehe auch IotMqttSampleUsingCallback) Wenn die Callback-Methode verwendet bzw. überschrieben wird, wird keine Message Queue verwendet, unabhängig davon, ob ipMessageQueue gesetzt wurde. |
Ausgänge
Name | Typ | Beschreibung |
|---|---|---|
bError | BOOL | Wird TRUE, sobald eine Fehlersituation eintritt. |
hrErrorCode | HRESULT | Liefert bei einem gesetzten bError-Ausgang einen Fehlercode. Eine Erläuterung zu den möglichen Fehlercodes befindet sich im Anhang. |
eConnectionState | Gibt den Zustand der Verbindung vom Client zum Broker als Enumeration ETcIotMqttClientState an. | |
bConnected | BOOL | Dieser Ausgang ist TRUE, wenn eine Verbindung vom Client zum Broker besteht. |
Methoden
Name | Beschreibung |
|---|---|
Methode zur Hintergrundkommunikation mit dem TwinCAT-Treiber. Die Methode muss zyklisch aufgerufen werden. | |
Methode zum Ausführen eines Publish an einen MQTT Message Broker. | |
Methode zum Einrichten einer Subscription. | |
Methode zum Entfernen einer Subscription. | |
Aktiviert die Funktion des exponential backoff | |
Deaktiviert die Funktion des exponential backoff | |
Methode zur Abfrage der Zeit (in ms) seit der letzten Nachricht vom Message Broker. |
Ereignisgesteuerte Methoden (Callback-Methoden)
Name | Beschreibung |
|---|---|
Callback-Methode, die vom TwinCAT-Treiber aufgerufen wird, wenn eine Subscription auf ein Topic erfolgt ist und eingehende Nachrichten empfangen werden. |
 | Message-Payload-Formatierung Beachten Sie, dass der Datentyp und die Formatierung des Inhalts der Sender- und Empfängerseite bekannt sein müssen, insbesondere beim Versand von Binärinformationen (Alignment) oder Strings (mit/ohne Nullterminierung). |
| Strings im UTF-8-Format Die hier verwendeten Variablen vom Typ STRING nutzen das UTF-8-Format. Diese STRING-Formatierung ist üblich bei IoT/MQTT-Kommunikation sowie JSON-Dokumenten. Um Sonderzeichen und Texte verschiedenster Sprachen empfangen zu können, wird der Zeichensatz in den Bibliotheken Tc3_IotBase und Tc3_JsonXml nicht auf den typischen Zeichensatz vom Datentyp STRING beschränkt. Stattdessen wird der Unicode-Zeichensatz als UTF-8-Format in Verbindung mit dem Datentyp STRING verwendet. Bei Verwendung des ASCII-Zeichensatzes besteht kein Unterschied zwischen der typischen Formatierung in einem STRING und der UTF-8-Formatierung eines STRING. Weitere Informationen zum UTF-8-STRING-Format sowie vorhandenen Anzeige- und Konvertierungsmöglichkeiten finden Sie in der Dokumentation der SPS-Bibliothek Tc2_Utilities. |
Voraussetzungen
Entwicklungsumgebung | Zielplattform | Einzubindende SPS-Bibliotheken |
|---|---|---|
TwinCAT v3.1.4022.0 | IPC oder CX (x86, x64, ARM) | Tc3_IotBase |