FB_IotCommunicator

The function block enables communication with an MQTT broker.

An FB_IotCommunicator function block deals with the connection to precisely one broker and with sending and receiving of data for precisely one device. To ensure the background communication to this broker and thus enable sending and receiving of data and messages, the Execute method of the function block must be called cyclically.

All connection parameters exist as input parameters and are evaluated when a connection is established.

Syntax

Definition:

FUNCTION_BLOCK FB_IotCommunicator
VAR_INPUT
    sHostName        : STRING := '127.0.0.1'; // IP address/hostname of MQTT broker, default 'localhost'
    nPort            : UINT := 1883; // (*optional*) Port to use for connection to broker - default: 1883
    sClientId        : STRING; // (*optional*) Unique name to connect to MQTT broker
    sMainTopic       : STRING; // MQTT topic the TC3 IoT Communicator will communicate with
    sDeviceName      : STRING; // e.g. ’Machine XYZ’ or 'Room 015 - Kitchen'
    sUser            : STRING; // (*optional*) Username for authentication
    sPassword        : STRING; // (*optional*) Password for specified User
    stTls            : ST_IotCommunicatorTls; // (*optional*) Specify details for secure tls connection
    bRetain          : BOOL := TRUE; // (*optional*) default true - if false, data, messages & devices will not be stored
    eQoS             : TcIotMqttQos := TcIotMqttQos.AtLeastOnceDelivery; // (*optional*) quality of service between client & broker - default: 1
    sDeviceIcon      : STRING;
END_VAR
VAR_OUTPUT
    bError            : BOOL;
    hrErrorCode       : HRESULT;
    eConnectionState  : ETcIotMqttClientState;
    bConnected        : BOOL;
 nActiveAppInstances : UINT;
 bNewAppSubscribe : BOOL; 
    fbCommand         : FB_IoTCommand; //provides functionality to receive commands
END_VAR

Inputs

Name	Type	Description
sHostName	STRING	sHostName can be specified as the host name or as the IP address. If no information is provided, the local host is used.
nPort	UINT	The host port is specified here. (Default: 1883)
sClientId	STRING	The client ID can be specified individually. If no ID is specified, it is generated.
sMainTopic	STRING	Here you specify the main topic in which the data and messages are sent.
sDeviceName	STRING	Here you can enter the name of the device to which the data and messages belong.
sUser	STRING	Optionally, a user name can be specified.
sPassword	STRING	A password for the user name can be entered here.
stTLS	STRING	If the broker offers a TLS-secured connection, the required configuration can be implemented here. The parameter structure is of type ST_IotCommunicatorTls.
bRetain	BOOL	By default, the broker stores the current data and the last 255 messages, together with the current device status. If this is not desirable, bRetain can be set to FALSE.
eQoS	TcIotMqttQos	The Quality of Service (QoS for short) can be set with this setting.
sDeviceIcon	STRING	This setting can be used to change the icon of the Communicator function block. If the setting is not set, the TwinCAT CD is used as icon by default. The list of available icons can be found at List of available icons.

Outputs

Name	Type	Description
bError	BOOL	TRUE if an error situation occurs.
hrErrorCode	HRESULT	Returns an error code if the bError output is set.
eConnectionState	ETcIotMqttClientState	Indicates the state of the connection between client and broker as enumeration ETcIotMqttClientState.
bConnected	BOOL	TRUE if there is a connection between the client and the broker.
nActiveAppInstances	UINT	Shows the number of currently connected app instances.
bNewAppSubscribe	BOOL	Goes TRUE for one cycle when a new app instance has connected. Can be used when using OnChange functionalities to publish the current status of the data again as a retain message during the connection.
fbCommand	FB_IoTCommand	Provides all the necessary functionality to evaluate received data ("Commands"). This output is of the type FB_IotCommand.

Methods

Name	Description
Execute	Method for background communication with the TwinCAT driver. This method must be called cyclically.
SendData	Method for sending data to the specified MQTT message broker as a retain message.
SendMessage	Method for sending a (push) message to the specified MQTT message broker.
SendDataAsString	Method for sending data to the specified MQTT message broker where the JSON document is transferred directly.
SendData_OnChange	Method for sending OnChange data to the specified MQTT message broker.
SendDataAsString_OnChange	Method for sending OnChange data to the specified MQTT message broker where the JSON document is transferred directly.

	Strings in UTF-8 format The variables of type STRING used here are based on the UTF-8 format. This STRING formatting is common for MQTT communication. In order to be able to receive special characters and texts from a wide range of languages, the character set in the Tc3_IotCommunicator library is not limited to the typical character set of the data type STRING. Instead, the Unicode character set in UTF-8 format is used in conjunction with the data type STRING. If the ASCII character set is used, there is no difference between the typical formatting of a STRING and the UTF-8 formatting of a STRING.

Requirements

Development environment	Target platform	PLC libraries to include
TwinCAT v3.1.4022.0	IPC or CX (x86, x64, ARM)	Tc3_IotCommunicator

Further Information