FB_IotMqtt5ClientBase

Der Funktionsbaustein ermöglicht die Kommunikation zu einem Message Broker basierend auf MQTT Version 5.0.

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.

Verwenden Sie den FB_IotMqtt5ClientBase, wenn Sie die Callback-Methoden (OnMqtt5Message() und andere) selbst implementieren möchten. Verwenden Sie den FB_IotMqtt5Client, wenn Sie keine Callback-Methoden selbst implementieren möchten und eingehende neue Nachrichten in der am Ausgang vorhandenen Message Queue bereitgestellt werden sollen.

Syntax

Definition:

FUNCTION_BLOCK FB_IotMqtt5Client
VAR_INPUT
    {attribute 'TcEncoding':='UTF-8'}
    sClientId        : STRING(255);        // default is generated during initialization
    {attribute 'TcEncoding':='UTF-8'}
    sHostName        : STRING(255) := '127.0.0.1'; // default is local host
    nHostPort        : UINT := 1883;       // default is 1883
    {attribute 'TcEncoding':='UTF-8'}
    sTopicPrefix     : STRING(255);        // topic prefix for pub and sub of this client (handled internally)
    nKeepAlive       : UINT := 60;         // in seconds    

    {attribute 'TcEncoding':='UTF-8'}
    sUserName        : STRING(255);        // optional parameter
    {attribute 'TcEncoding':='UTF-8'}
    sUserPassword    : STRING(255);        // optional parameter
    stWill           : ST_IotMqtt5Will;    // optional parameter
    stTLS            : ST_IotMqtt5Tls;     // optional parameter
    stAuth           : ST_IotMqtt5Auth;    // optional parameter
    stConnect        : ST_IotMqtt5Connect; // optional parameter
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	ST_IotMqtt5Will	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	ST_IotMqtt5Tls	Wenn der Broker eine TLS gesicherte Verbindung anbietet, kann hier die nötige Konfiguration vorgenommen werden.
stAuth	ST_IotMqtt5Auth	Mit dieser Struktur können erweiterte Authentifizierungsinformationen an den Message Broker übergeben werden.
stConnect	ST_IotMqtt5Connect	Mit dieser Struktur können erweiterte Verbindungseinstellungen an den Message Broker übergeben werden.

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	ETcIotMqttClientState	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
Execute	Methode zur Hintergrundkommunikation mit dem TwinCAT-Treiber. Die Methode muss zyklisch aufgerufen werden.
Publish	Methode zum Ausführen eines Publish an einen MQTT Message Broker.
Request	Hiermit kann ein Request im Rahmen des Request/Response Verfahrens von MQTTv5 verschickt werden.
Response	Hiermit kann eine Response im Rahmen des Request/Response Verfahrens von MQTTv5 verschickt werden.
Subscribe	Methode zum Einrichten einer Subscription.
Unsubscribe	Methode zum Entfernen einer Subscription.
ActivateExponentialBackoff	Aktiviert die Funktion des exponential backoff
DeactivateExponentialBackoff	Deaktiviert die Funktion des exponential backoff
GetTimeSinceLastBrokerMessage	Methode zur Abfrage der Zeit (in ms) seit der letzten Nachricht vom Message Broker.

Ereignisgesteuerte Methoden (Callback-Methoden)

Name	Beschreibung
OnMqtt5Authentication	Callback-Methode, die vom TwinCAT-Treiber aufgerufen wird, wenn der Message Broker eine AUTH-Nachricht als Antwort auf einen Connect an den Client sendet.
OnMqtt5ConnAck	Callback-Methode, die vom TwinCAT-Treiber aufgerufen wird, wenn der Message Broker eine CONNACK-Nachricht als Antwort auf einen Connect verschickt.
OnMqtt5Disconnected	Callback-Methode, die vom TwinCAT-Treiber aufgerufen wird, wenn die Verbindung zu einem Message Broker getrennt wurde.
OnMqtt5Message	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.4026.0	IPC oder CX (x86, x64, ARM)	Tc3_IotBase (>= v3.4.2.0)

Weiterführende Informationen