FB_MqttSubscribe

Overview

Type:	Function block
Available as of:	V1.0.0.0

Functional Description

The function block FB_MqttSubscribe is used to manage a subscription to a specific topic on the MQTT server.

The following functions are supported:

Subscription of the specified topic
Unsubscription of the specified topic
Reading out of the data according to the subscribed topic

The function block uses the connection to the MQTT server that was previously established with the FB_MqttClient.

After the function block is activated, the subscription for the specified topic is sent to the connected MQTT server. The status of the subscription and thus the possibility of receiving data is indicated by output q_xReady. New received data are indicated by the output q_xNewMessage.

Disabling the function block sends the unsubscription to the previously subscribed topic. The state of the unsubscription is indicated by the output q_xActive. A new subscription is only allowed if the output q_xActive is set to FALSE.

After the specified topic is successfully subscribed, the data received to this topic can be read by setting the command i_xExecute to TRUE.

Quality of Service

Subscribe level	Description
QoS 0	The last data on the subscribed topic can be read.
QoS 1	The messages published with QoS 1 can be read. The sequence of the messages remains unchanged (First In First Out). The first received message is stored in the function block FB_MqttSubscribe. It can be read immediately by triggering the execution of the function block. After receiving the first message, the function block is ready to receive the next message. If the message has already been sent from the MQTT server, the function block waits for the duplicate. The time until the function block delivers the next message depends on the time until the server sends the duplicate. When using Mosquitto as MQTT server, this can take up to 30 seconds. The last message with QoS 0 can be read if the QoS 1 messages previously sent by the MQTT server have been received and already read. The received QoS 0 message can be overwritten by a new message at any time.

Subscribe level

Description

QoS 0

The last data on the subscribed topic can be read.

QoS 1

The messages published with QoS 1 can be read. The sequence of the messages remains unchanged (First In First Out).

The first received message is stored in the function block FB_MqttSubscribe. It can be read immediately by triggering the execution of the function block. After receiving the first message, the function block is ready to receive the next message. If the message has already been sent from the MQTT server, the function block waits for the duplicate. The time until the function block delivers the next message depends on the time until the server sends the duplicate.

When using Mosquitto as MQTT server, this can take up to 30 seconds.
The last message with QoS 0 can be read if the QoS 1 messages previously sent by the MQTT server have been received and already read.

The received QoS 0 message can be overwritten by a new message at any time.

Interface

Input	Data type	Description
i_xEnable	BOOL	The function block sends a subscription to the specified topic to the connected MQTT server upon a rising edge of this input. Refer to Behavior of Function Blocks with the Inputs i_xEnable and i_xExecute and i_xErrorQuit.
i_stSubscribeTopic	ST_SubscribeTopic	Structure to specify the topic to subscribe.
i_xExecute	BOOL	The function block reads the latest received application message to the subscribed topic upon a rising edge of this input. Refer to Behavior of Function Blocks with the Inputs i_xEnable and i_xExecute and i_xErrorQuit.
i_xErrorQuit	BOOL	The function block acknowledges a detected error indicated by q_xError upon a rising edge of this input. Refer to Behavior of Function Blocks with the Inputs i_xEnable and i_xExecute and i_xErrorQuit.
i_pbyBuffer	POINTER TO BYTE	Pointer to the buffer in which the received message is copied.
i_udiBufferSize	UDINT	Size of the buffer in bytes. NOTE: The length must not be greater than the size of the variable to which i_pbyBuffer points to.
i_stTimeout	ST_Timeout	Structure to specify the timeouts.

Innput/Output	Data type	Description
iq_fbMqttClient	FB_MqttClient	Reference to the associated FB_MqttClient used for the data exchange with the MQTT server.

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 subscription to the specified topic is successfully sent to the MQTT server.
q_xDone	BOOL	Indicates that the last received application message is successfully copied into the buffer specified with the input i_pbyBuffer.
q_xBusy	BOOL	Indicates that the subscription is in progress.
q_xError	BOOL	Indicates that an error was detected during the execution of the function block.
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.
q_xNewMessageAvailable	BOOL	Indicates that a new application message to the subscribed topic is available.
q_udiMessageLength	UDINT	Indicates the number of bytes copied into the buffer specified with the input i_pbyBuffer.
q_xTruncated	BOOL	If this output is set to TRUE, the copied application message has been truncated.

Usage of Variables of Type POINTER TO … or REFERENCE TO …

The function block provides inputs and/or in/outputs of type POINTER TO… or REFENCE TO…. With the use of such a pointer or reference, the function block accesses the addressed memory area. In case of an online change event, it may happen that memory areas are moved to new addresses and in consequence a pointer or reference becomes invalid. To prevent errors associated with invalid pointers, variables of type POINTER TO… or REFERENCE TO… must be updated cyclically or at least at the beginning of the cycle in which they are used.

CAUTION
	INVALID POINTER Verify the validity of the pointers when using pointers on addresses and executing the Online Change command. Failure to follow these instructions can result in injury or equipment damage.

Unified Modeling Language (UML) Sequence Diagram

Following UML sequence diagram illustrates the interaction with the function block FB_MqttClient, which needs to be called cyclically to process received messages and to detect a possible communication interruption to the server.

NOTE: The diagram illustrates a successful subscribe process and does not indicate any error handling.