MQTT (MQ Telemetry Transport) protocol handling

The system includes a set of functions and blocks for managing the MQTT protocol from IEC applications. Functions and blocks described here enable the establishment of MQTT connections, subscribing and publishing MQTT message. Additional functions are provided for passing IEC variable values in message data.

 

MQtt functions are designed for working with text buffers. Text buffers are used for storing MQTT message data.

 

Important notes:

 

  • MQTT message topic names are stored in STRING variables and thus cannot exceed 255 characters.

  • There must be one instance of the TxbManager declared in your application for using text buffers related functions.

 

Below are the functions and function blocks for handing MQTT connections and messages:

 

Connection and status:

 

MQttConnection: Handles a connection to a MQTT message broker

MQttLastError: Get detailed error report about last call

MQttMsgStatus: Get current status of a message

 

Messaging:

 

MQttPublish: Published a message

MQttSubscribe: Subscribe to a message

MQttUnsubscribe: Unsubscribe to a message

MQttReceivePub: Get received messages
MQttNbRec: Get number of messages received

 

Additional functions:

 

MQttIECFormat: Format an IEC value in message data

MQttIECParse: Parse an IEC value in message data

 

 


MQttConnection – Function block
 

 

InstanceName

 

 

MQttConnection

 

BOOL -

Connect 

Q

- BOOL

STRING -

ClientID

hConn

- DINT

STRING -

HostAddr 

status

- DINT

DINT -

Port 

infoCode

- DINT

lib:MQttConnOpts -

connOpts 

 

 

 

 

 

 

 

Description:

 

This function block is used for establishing a connection to a message broker (server). When conection is established, the "hConn" output is the handle of the connection, to be passed to other functions in charge of messaging.

 

Inputs:

 

Connect : BOOL

A connection is established when this input changes from FALSE to TRUE. See status output to know the connection status.
The connection is released when this input changes from TRUE to FALSE.

 

clientID : STRING

ID of the client application. If you establish several connections at the same time, each connection must be identified by a unique client ID.

 

HostAddr : STRING
 

Address of the broker.

Port : DINT
 
IP port of the broker.
connOpts :
   lib:MQttConnOpts
Connection options (see details below). The MQttConnOpts type is a structure defined in library

 

Outputs:

 

Q : BOOL

TRUE when connection is established. This output simply indicates that the connection procedure is finished. Connection is not ensured to be OK. See the "status" output to know the state of the current connection.

 

hConn : DINT

Handle of the connection, that must be passed to other MQtt functions to identify the MQTT connection.

 

status : DINT
 

Current status of the connection. See details below.

infoCode : DINT
 
Additional information about current connection status.

 

The MQttConnOpts type is a structure defined in library and has the following form:

 

STRUCT

    retryInterval : DINT;
    keeAlive : DINT;

    willData : DINT;

    willTopic : STRING;

    cleanStart : BOOL;

    bWill : BOOL;
END_STRUCT

 

retryInterval

Interval in seconds at which messages should be retried if a send fails.

 

KeepAlive
 
A length of time in seconds. If the MQTT server does not receive data within this time limit it will assume the client application has terminated.
 
willData
 
Handle of a text buffer containing the will message data, if specified.
willTopic
 
Willl topic name if specified
cleanStart
 
If TRUE, it means that when the application disconnects cleanly or otherwise, the broker will clean up on behalf of the application, removing all active subscriptions and any outstanding data for that connection.
 
bWill Indicates if a will message is specified. The will message will be publihsed in the event of the unexpected termination of this application

 

Below are the possible values for the status of the connection. You must check the status after asking for a connection to be established:

0     Connection status unknown - please wait

2009  Trying to find MQTT server - please wait

6     Connecting to the server - please wait

7     Connection is OK

8     Disconnected

9     Connection was broken

The status can also be an error code if connection fails or in case of invalid parameters. See description of the MQttLastError function for further information

 

See also...

 


MQttLastError – Function

 

 

MQttLastError

 

 

 

iErr

- DINT

 

 

 

 

 

Description:

 

Most of MQTT functions and blocks simply return a boolean information as a return value. This function can be called after any other function giving a FALSE return. It gives a detailed error code about the last detected error.

 

Outputs:

 

iErr : DINT

Error code reported by the last call:

0 = OK

other = error

 

Below are possible error codes:

 

1001 MQTT protocol version mismatch
1002 Hostname not found
1003 MQTT queues overflow
1004 MQTT messaging failed
1005 Timeout
1006 MQTT message overflow
1007 Message persistence failed
1008 Invalid connection handle
1010 Will topic not supported
1011 Internal error
1012 Frame error
1013 Data is too big
1014 MQTT is already connected
1019 Bad client ID
1020 Broker is unavailable
1021 MQTT socket closed
1022 Out of memory
2001 Cannot start MQ tasks Cannot start MQTT tasks
2002 Connection already established
2003 No connection established
2004 Invalid text buffer handle
2005 Text buffers are not initialized
2006 Library not licensed
2007 Too many open connections
2008 Invalid connection for reading pubs
2009 Connection in progress - not ready yet
2010 Client ID used more than once
2011 Internal error
 

See also...

 


MQttMsgStatus – Function
 

 

MQttMsgStatus

 

DINT -

hConn

status

- DINT

DINT -

hMsg

 

 

 

 

 

 

 

Description:

 

This function returns the current status of a MQTT message. The message is identified by a handle returned by other MQTT functions (publish, subscribe...)

 

Inputs:

 

hConn : DINT
 

Handle of the MQTT connection, returned by MQttConnection block

hMsg : DINT Handle of the message

 

Outputs:

 

status : DINT

Current status of the message.

 

Possible status values are:

 

1   Message delivered

2   Retrying

3   In progress

4   Invalid message handle

 

See also...

 


MQttPublish – Function
 

 

MQttPublish

 

DINT -

hConn

hMsg

- DINT

STRING -

topic

 

 

DINT -

data

 

 

DINT -

QOS

 

 

BOOL -

bRet

 

 

 

 

 

 

 

Description:

 

This function publishes a MQTT message on a valid connection.

 

Important note: The "data" text buffer is no more used after the call to the function. The application is responsible for releasing the text buffer after the call if no more needed, in order to avoid memory leaks.

 

Inputs:

 

hConn : DINT
 

Handle of the MQTT connection, returned by MQttConnection block
 

topic : STRING
 
Message topic name
 
data : DINT
 
Handle of a text buffer containing message data
 
QOS : DINT
 
Quality of service (0 or 1 or 2)
 
bRet : BOOL If TRUE, the message will be retained by the MQTT borker until another publication is received for the same topic

 

Outputs:

 

hMsg : DINT

Handle of the message. This handle can be passed to the MQttMsgStatus function to track the status of the message.

 

See also...

 

 

MQttSubscribe – Function

 

 

MQttSubscribe

 

DINT -

hConn

hMsg

- DINT

STRING -

topic

 

 

DINT -

QOS

 

 

 

 

 

 

 

Description:

 

This function subscribes to a MQTT message.

 

Inputs:

 

hConn : DINT
 

Handle of the MQTT connection, returned by MQttConnection block
 

topic : STRING
 
Message topic name
 
QOS : DINT Quality of service (0 or 1 or 2)

 

Outputs:

 

hMsg : DINT

Handle of the message. This handle can be passed to the MQttMsgStatus function to track the status of the message.

 

See also...

  


MQttUnsubscribe – Function

 

 

MQttUnsubscribe

 

DINT -

hConn

hMsg

- DINT

STRING -

topic

 

 

 

 

 

 

 

Description:

 

This function unsubscribes to a MQTT message.

 

Inputs:

 

hConn : DINT
 

Handle of the MQTT connection, returned by MQttConnection block
 

topic : STRING Message topic name

 

Outputs:

 

hMsg : DINT

Handle of the message. This handle can be passed to the MQttMsgStatus function to track the status of the message.

 

See also...

 


MQttNbRec – Function

 

 

MQttNbRec

 

DINT -

hConn

nb

- DINT

DINT -

QOS

 

 

 

 

 

 

 

Description:

 

This function returns the number of messages received not pumped yet by the application. The number returned matches the quality of services specified in the QOS input argument. Call the MQttReceivePub function block for pumping received messages.

 

Inputs:

 

hConn : DINT
 

Handle of the MQTT connection, returned by MQttConnection block
 

QOS : DINT Wished quality of serrvice (0, 1, 2) or -1 for all messages

 

Outputs:

 

nb : DINT

Number of messages received, according to the specified quality of service:
QOS=0 : received messages with quality 0
QOS=1 : received messages with quality 1
QOS=2 : received messages with quality 2
QOS=-1 : all received messages

 

See also...

 

 

MQttReceivePub – Function block

 

 

InstanceName

 

 

MQttReceivePub

 

DINT -

hConn

Q

- BOOL

 

 

 topic

- STRING 

 

 

 data

- DINT 

 

 

 QOS

- DINT 

 

 

 bRet

- BOOL 

 

 

 dupl

- BOOL 

 

 

 

 

 

Description:

 

Use this function block to pump messages received on a valid MQTT connection.

 

Important note: The "data" text buffer is allocated by the function block if a new message is received. The application is responsible for releasing the text buffer after the call when no more needed, in order to avoid memory leaks.

 

Received messages with higher quality of services are returned first.

 

The message is "poped" from a FIFO internally managed by MQTT function blocks, and thus must be managed immediately after the call.

 

Inputs:

 

hConn : DINT
 

Handle of the MQTT connection, returned by MQttConnection block
 

 

Outputs:

 

Q : BOOL
 

TRUE if a message is available. In that case, you must handle tte message immediately after the call and release the text buffer associated to message data.
 

topic : STRING
 
Message topic name.
 
data : DINT
 
Handle of a new text buffer filled with message data. The application is responsible for releasing text buffer memory.
 
QOS : DINT
 
Quality of service originally given to the message.
 
bRet : BOOL
 
Indicates a message retained by the server.
 
dupl : BOOL Indicates a duplicated message.

 

See also...

  

 

MQttIECFormat – Function

 

 

MQttIECFormat

 

ANY -

IN

data

- DINT

 

 

 

 

 

Description:

 

This function allocates a new text buffer and fills it with the formatted IEC value of the variable connected to the IN input. See formatting specifications below.

 

Important: The function return s a new allocated text buffer. The application is responsible for releasing the text buffer memory when no more needed.

 

Inputs:

 

IN : ANY

Any single variable. This input must be directly linked to the variable. 

 

Outputs:

 

data : DINT

New allocated text bufer containing the formatted message data

 

Message format:

 

The value is formatted on a single line text, using the following format:

 

type:value

 

The type specified conforms to IEC convention (BOOL, DINT, REAL...). Exceptions are BYTE, WORD, DWORD that are markes as respectively USINT, UINT and UDINT.

The value is expressed in decimal form for numbers, and with the following format for special data types:

 

STRING: No quote is appended.
TIME: Expressed as a number of milliseconds.

 

See also...

   

 

MQttIECParse – Function

 

 

MQttIECParse

 

DINT -

data

Q

- BOOL

ANY -

@OUT

 

 

 

 

 

 

 

Description:

 

This function parses the contents of a message data containing an IEC value, and assigns the value to the variable connected to the @OUT input.

 

Important: The text buffer memory is not released by this function.

 

See description of the MQttIECFormat function for exact specification of message format.

 

Inputs:

 

data : DINT
 

Handle of the XML tag
 

@OUT : ANY Must be directly linked to the variable that will be forced to the value specified in the message.

 

Outputs:

 

Q : BOOL

TRUE if the text buffer contains a valid IEC value

 

See also...