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
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 | 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 | If the broker offers a TLS-secured connection, the required configuration can be implemented here. | |
stAuth | This structure can be used to pass extended authentication information to the message broker. | |
stConnect | 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 | 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. |
Methods
Name | Description |
---|---|
Method for background communication with the TwinCAT driver. The method must be called cyclically. | |
Method for executing a publish operation to a MQTT message broker. | |
This can be used to send a request as part of the request/response procedure of MQTTv5. | |
This can be used to send a response as part of the request/response procedure of MQTTv5. | |
Method for establishing a subscription. | |
Method for removing a subscription. | |
Activates the exponential backoff function | |
Deactivates the exponential backoff function | |
Method for querying the time (in ms) since the last message from the message broker. |
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. |
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) |