FB_IotMqtt5Client

The function block enables communication to a message broker based on MQTT version 5.0.

A client function block is responsible for the connection to precisely one broker. The Execute() method of the function block must be called cyclically in order to ensure the background communication with this broker and facilitate receiving of messages.

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

Use the FB_IotMqtt5Client, if you do not want to implement callback methods yourself and incoming new messages should be provided in the message queue available at the output. Use the FB_IotMqtt5ClientBase if you want to implement the callback methods (OnMqtt5Message() and others) yourself.

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
    fbMessageQueue    : FB_IotMqtt5MessageQueue;         // received messages are queued during call of Execute()
    fbConnAckProps    : FB_IotMqtt5ConnAckProperties;    // info is set when a connection is acknowledged
    fbDisconnectProps : FB_IotMqtt5DisconnectProperties; // info is set after disconnection
END_VAR

Inputs

Name	Type	Description
sClientId	STRING(255)	The client ID can be specified individually and must be unique for most message brokers. If not specified, an ID based on the PLC project name is automatically generated by the TwinCAT driver.
sHostName	STRING(255)	sHostName can be specified as name or as IP address. If no information is provided, the local host is used.
nHostPort	UINT	The host port is specified here. The default is 1883.
sTopicPrefix	STRING(255)	Here you can specify a topic prefix that will be added automatically for all publish and subscribe commands.
nKeepAlive	UINT	Here you can specify the watchdog time (in seconds), with which the connection between client and broker is monitored.
sUserName	STRING(255)	Optionally, a user name can be specified.
sUserPassword	STRING(255)	A password for the user name can be entered here.
stWill	ST_IotMqtt5Will	If the client is disconnected from the broker irregularly, a last preconfigured message can optionally be sent from the broker to the so-called “will topic”. This message is specified here.
stTLS	ST_IotMqtt5Tls	If the broker offers a TLS-secured connection, the required configuration can be implemented here.
stAuth	ST_IotMqtt5Auth	This structure can be used to pass extended authentication information to the message broker.
stConnect	ST_IotMqtt5Connect	This structure can be used to pass advanced connection settings to the message broker.

Outputs

Name	Type	Description
bError	BOOL	Becomes TRUE as soon as an error situation occurs.
hrErrorCode	HRESULT	Returns an error code if the bError output is set. An explanation of the possible error codes can be found in the Appendix.
eConnectionState	ETcIotMqttClientState	Indicates the state of the connection between client and broker as enumeration ETcIotMqttClientState.
bConnected	BOOL	This output is TRUE if a connection exists between client and broker.
fbMessageQueue	FB_IotMqtt5MessageQueue	The message queue of the received messages is provided at the output. This output can be accessed directly to work with the message queue.
fbConnAckProps	FB_IotMqtt5ConnAckProperties	If the client has received ConnAck Properties from the message broker, they are displayed here.
fbDisconnectProps	FB_IotMqtt5DisconnectProperties	If the client has received Disconnect Properties from the message broker, they are displayed here.

Methods

Name	Description
Execute	Method for background communication with the TwinCAT driver. The method must be called cyclically.
Publish	Method for executing a publish operation to a MQTT message broker.
Request	This can be used to send a request as part of the request/response procedure of MQTTv5.
Response	This can be used to send a response as part of the request/response procedure of MQTTv5.
Subscribe	Method for establishing a subscription.
Unsubscribe	Method for removing a subscription.
ActivateExponentialBackoff	Activates the exponential backoff function
DeactivateExponentialBackoff	Deactivates the exponential backoff function
GetTimeSinceLastBrokerMessage	Method for querying the time (in ms) since the last message from the message broker.

	Message payload formatting Note that the data type and the formatting of the content must be known to the sender and receiver side, particularly when binary information (alignment) or strings (with or without zero termination) are sent.

	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 as well as for JSON documents. In order to be able to receive special characters and texts from a wide range of languages, the character set in the Tc3_IotBase and Tc3_JsonXml libraries 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. Further information on the UTF-8 STRING format and available display and conversion options can be found in the documentation for the Tc2_Utilities PLC library.

Requirements

Development environment	Target platform	PLC libraries to include
TwinCAT v3.1.4026.0	IPC or CX (x86, x64, ARM)	Tc3_IotBase (>= v3.4.2.0)

Further Information