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