FB_IotCommunicator

Der Funktionsbaustein ermöglicht die Kommunikation zu einem MQTT-Broker.

Ein FB_IotCommunicator-Funktionsbaustein ist für die Verbindung zu genau einem Broker und für das Senden und Empfangen von Daten genau eines Gerätes („Device“) zuständig. Um die Hintergrundkommunikation zu diesem Broker zu gewährleisten und somit das Senden und Empfangen von Daten und Nachrichten zu ermöglichen, muss die Execute-Methode des Funktionsbausteins zyklisch aufgerufen werden.

Alle Verbindungsparameter sind als Eingangsparameter vorhanden und werden beim Verbindungsaufbau ausgewertet.

Syntax

Definition:

FUNCTION_BLOCK FB_IotCommunicator
VAR_INPUT
    sHostName           : STRING := '127.0.0.1';
    nPort               : UINT := 1883;
    sClientId           : STRING;
    sMainTopic          : STRING;
    sDeviceName         : STRING;
    sUser               : STRING;
    sPassword           : STRING;
    stTls               : ST_IotCommunicatorTls; 
    bRetain             : BOOL := TRUE;
    eQoS                : TcIotMqttQos := TcIotMqttQos.AtLeastOnceDelivery;
    sDeviceIcon         : STRING;
    tHeartbeatInterval  : TIME := TIME#1m0s0ms;
    sPermittedUsers     : STRING(512) := '*';
END_VAR
VAR_OUTPUT
    bError              : BOOL;
    hrErrorCode         : HRESULT;
    eConnectionState    : ETcIotMqttClientState;
    bConnected          : BOOL;
    nActiveAppInstances : UINT;
    bNewAppSubscribe    : BOOL; 
    fbCommand           : FB_IoTCommand;
END_VAR

Eingänge

Name	Typ	Beschreibung
sHostName	STRING	sHostName kann als Hostname oder als IP-Adresse angegeben werden. Bei fehlender Angabe wird Local Host verwendet.
nPort	UINT	Hier wird der Host Port angegeben. (Default: 1883)
sClientId	STRING	Die Client-ID kann individuell angegeben werden. Bei fehlender Angabe wird eine ID generiert.
sMainTopic	STRING	Hier wird angegeben, in welches Haupt-Topic die Daten und Nachrichten gesendet werden.
sDeviceName	STRING	Hier wird der Name des Gerätes eingetragen, zu dem die Daten und Nachrichten gehören.
sUser	STRING	Optional kann ein Benutzername angegeben werden.
sPassword	STRING	Zum Benutzernamen kann hier ein Passwort angegeben werden.
stTLS	ST_IotCommunicatorTls	Parameterstruktur Wenn der Broker eine TLS gesicherte Verbindung anbietet, kann hier die nötige Konfiguration vorgenommen werden.
bRetain	BOOL	Die aktuellen Daten und die letzten 255 Nachrichten, sowie der aktuelle Status des Gerätes werden standardmäßig vom Broker gespeichert. Ist dies nicht erwünscht, kann bRetain auf FALSE gesetzt werden.
eQoS	TcIotMqttQos	Mit dieser Einstellung kann der Quality of Service (kurz: QoS) eingestellt werden.
sDeviceIcon	STRING	Mit dieser Einstellung kann das Icon des Communicator-Bausteins verändert werden. Wenn die Einstellung nicht gesetzt wird, wird standardmäßig die TwinCAT-CD als Icon verwendet. Die Liste der verfügbaren Icons ist unter Liste der verfügbaren Icons zu finden.
tHeartbeatInterval	TIME	Die Zeitspanne, nach der die Online-Informationen dieses Funktionsbausteins aktualisiert werden. Die Online-Informationen sind auf der obersten Ebene in der App sichtbar, auf der man die Übersicht der einzelnen Funktionsbausteine sieht. Der Default-Wert sind 60 Sekunden.
sPermittedUsers	STRING(512)	Mit dieser Variable können die Benutzer angegeben werden, die ein Device sehen dürfen. Die Benutzer werden dabei mit einem Komma getrennt. Mit dem Standardwert '*' sind alle Benutzer berechtigt, das Gerät zu sehen.

Ausgänge

Name	Typ	Beschreibung
bError	BOOL	TRUE, sobald eine Fehlersituation eintritt.
hrErrorCode	HRESULT	Liefert bei einem gesetzten bError-Ausgang einen Fehlercode.
eConnectionState	ETcIotMqttClientState	Gibt den Zustand der Verbindung vom Client zum Broker als Enumeration ETcIotMqttClientState an.
bConnected	BOOL	TRUE, wenn eine Verbindung vom Client zum Broker besteht.
nActiveAppInstances	UINT	Zeigt die Anzahl der aktuell verbundenen App-Instanzen.
bNewAppSubscribe	BOOL	Geht für einen Zyklus auf TRUE, wenn sich eine neue App-Instanz verbunden hat. Kann bei der Verwendung von OnChange-Funktionalitäten genutzt werden, um bei der Verbindung den aktuellen Stand der Daten wieder als Retain-Nachricht zu veröffentlichen.
fbCommand	FB_IotCommand	Stellt alle nötigen Funktionalitäten bereit, um empfangene Daten („Commands“) auswerten zu können.

Methoden

Name	Beschreibung
Execute	Methode zur Hintergrundkommunikation mit dem TwinCAT-Treiber. Diese Methode muss zyklisch aufgerufen werden.
SendData	Methode zum Senden von Daten an den angegebenen MQTT Message Broker als Retain-Nachricht.
SendMessage	Methode zum Senden einer (Push-)Nachricht an den angegebenen MQTT Message Broker.
SendDataAsString	Methode zum Senden von Daten an den angegebenen MQTT Message Broker bei der das JSON-Dokument direkt übergeben wird.
SendData_OnChange	Methode zum Senden von OnChange-Daten an den angegebenen MQTT Message Broker.
SendDataAsString_OnChange	Methode zum Senden von OnChange-Daten an den angegebenen MQTT Message Broker bei der das JSON-Dokument direkt übergeben wird.

	Strings im UTF-8-Format Die hier verwendeten Variablen vom Typ STRING nutzen das UTF-8-Format. Diese STRING-Formatierung ist üblich bei der MQTT-Kommunikation. Um auch Sonderzeichen und Texte verschiedenster Sprachen empfangen zu können, wird der Zeichensatz in der Tc3_IotCommunicator-Bibliothek 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.

Voraussetzungen

Entwicklungsumgebung	Zielplattform	Einzubindende SPS-Bibliotheken
TwinCAT v3.1.4022.0	IPC oder CX (x86, x64, ARM)	Tc3_IotCommunicator

Weiterführende Informationen