FB_MqttClient
Functional Description
The function block FB_MqttClient is used to establish a connection with the specified MQTT server. The connection is initiated upon a rising edge of the input i_xEnable. The output q_xActive indicates that the function block is in progress and must be called cyclically. The status of the connection is indicated by the output q_xReady. If this output is TRUE, the client is connected.
If the input i_xEnable is set to FALSE while a connection establishment is in progress, the process is aborted.
If the input i_xEnable is set to FALSE and a connection exists, the connection is closed as a clean session. This means that the active subscriptions belonging to this client identifier are cleared on the MQTT server.
After a successfully established connection, the function block manages the messages received from the server in the background. Therefore, the function block must also be called cyclically after the connection has been established.
Proxy Configuration
The function block FB_MqttClient supports establishing a connection to the MQTT server through a proxy server.
If a proxy server prohibits a direct connection between your client and the MQTT server but it supports establishing a tunnel to the remote server, you can implement the connection to the remote server with the help of the interface IF_ProxyHandler and the corresponding implementation.
The function block FB_MqttClient provides the property ProxyHandler that allows you to assign an interface of type IF_ProxyHandler. Once a valid interface has been assigned to the property, the interface methods are called from the function block while establishing a connection to the MQTT server.
The call sequence is as follows:
-
When the function block is enabled, the interface method ConnectToProxy is called.
If TLS encryption is selected for the connection to the MQTT server, the socket type StartTls is set to TRUE. The method is called cyclically until one of the outputs q_xDone (connection established) or q_xError (unsuccessful connection) indicates TRUE.
-
After the connection to the proxy server has been established, the interface method ConnectToRemoteServer is called.
If TLS encryption is selected for the connection to the MQTT server, the option UpgradeToTls is set to TRUE. The method is called cyclically until one of the outputs q_xDone (connection established) or q_xError (unsuccessful connection) indicates TRUE.
-
After the method ConnectToRemoteServer has been completed successfully, the next step is establishing the MQTT connection on the MQTT protocol level. The interface IF_ProxyHandler is not required until the next activation of the function block.
If an error is detected during establishing a connection using the interface IF_ProxyHandler, the interface method Abort is called once.
To deactivate the usage of the interface IF_ProxyHandler, pass an unassigned interface or a null pointer to the property ProxyHandler. For example: fbMqttClient.ProxyHandler := 0;
For more information about the implementation of the interface methods or about implementations already provided, refer to the ProxyCommunicationSupport Library Guide.
MQTT Server Address
The MQTT server address is specified by the IPv4 address. If the connection is established through a proxy server (see Proxy Configuration) it is also supported to specify the address by the host name of the server. If this is the case, only one parameter may be used, either the IP address or the host name.
Interface
|
Input |
Data type |
Description |
|---|---|---|
|
i_xEnable |
BOOL |
The function block establishes a connection to the MQTT server upon a rising edge of this input. If the input is set to FALSE, the function block is reset and an existing connection is closed or the connection establishment is aborted. Refer to Behavior of Function blocks with the Input i_xEnable. |
|
i_stConnectionSettings |
ST_ConnectionSettings |
Structure to transfer the connection parameter. |
|
i_timTimeout |
TIME |
Time span in which a successful connection is expected. If the value is T#0 s, the default value T#10 s is applied. |
|
Output |
Data type |
Description |
|---|---|---|
|
q_xActive |
BOOL |
Indicates that the execution of the function block is active. As long this output is TRUE the function block must be executed cyclically. |
|
q_xReady |
BOOL |
Indicates that the connection is established. The MQTT client is ready for application message exchange with the MQTT server. |
|
q_xError |
BOOL |
If this output is set to TRUE, an error has been detected. For details, refer to q_etResult and q_etResultMsg. |
|
q_xTlsUsed |
BOOL |
Indicates if connection to MQTT server is secured via TLS (Transport Layer Security). |
|
q_etResult |
ET_Result |
Provides diagnostic and status information as a numeric value. |
|
q_sResultMsg |
STRING [80] |
Provides additional diagnostic and status information as a text message. |
Properties
The table describes the property ProxyHandler provided by the FB_MqttClient function block.
|
Name |
Data type |
Accessing |
Description |
|---|---|---|---|
|
ProxyHandler |
PXCS.IF_ProxyHandler |
Get/Set |
Function block implementing the interface IF_ProxyHandler. If a valid interface is assigned, the connection to the MQTT server is established using the interface methods. |