FB_IotMqtt5ClientBase

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_IotMqtt5ClientBase if you want to implement the callback methods (OnMqtt5Message() and others) yourself. 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.

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

FB_IotMqtt5ClientBase 1: 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.

FB_IotMqtt5ClientBase 2: 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.

FB_IotMqtt5ClientBase 3: 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.

FB_IotMqtt5ClientBase 4: Event-driven methods (callback methods)

Name

Description

OnMqtt5Authentication

Callback method called by the TwinCAT driver when the message broker sends an AUTH message to the client in response to a Connect.

OnMqtt5ConnAck

Callback method called by the TwinCAT driver when the message broker sends a CONNACK message in response to a Connect.

OnMqtt5Disconnected

Callback method that is called by the TwinCAT driver in case of the interruption of a connection to a message broker.

OnMqtt5Message

Callback method used by the TwinCAT driver when a subscription to a topic was established and incoming messages are received.

FB_IotMqtt5ClientBase 5:

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.

FB_IotMqtt5ClientBase 6:

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)