PLCnext Engineer Library

MQTT_Client_2

Version: 2.0

For PLCnext Engineer >= 2023.0

Table of Contents
1. Overview ............................................................................................................................................. 4
2. Important Information......................................................................................................................... 4
3. Change Notes ...................................................................................................................................... 4
4. Function Blocks.................................................................................................................................... 5
5. MQTT_Client_3.................................................................................................................................... 5
5.1 Change Notes............................................................................................................................. 5
5.2 Function Block Call ..................................................................................................................... 6
5.3 Input Parameters ....................................................................................................................... 7
5.4 Output Parameters .................................................................................................................... 9
5.5 Input - Output Parameters ......................................................................................................... 9
6. MQTT_Publish_1 ................................................................................................................................. 9
6.1 Change Notes............................................................................................................................. 9
6.2 Function Block Call ..................................................................................................................... 9
6.3 Input Parameters ..................................................................................................................... 10
6.4 Output Parameters .................................................................................................................. 10
6.5 Input - Output Parameters ....................................................................................................... 10
7. MQTT_Subscribe_1 ........................................................................................................................... 11
7.1 Change Notes........................................................................................................................... 11
7.2 Function Block Call ................................................................................................................... 11
7.3 Input Parameters ..................................................................................................................... 11
7.4 Output Parameters .................................................................................................................. 11
7.5 Input - Output Parameters ....................................................................................................... 12
8. JSON_Add_Object_1 .......................................................................................................................... 12
8.1 Change Notes........................................................................................................................... 12
8.2 Function Block Call ................................................................................................................... 12
8.3 Input Parameters ..................................................................................................................... 12
8.4 Output Parameters .................................................................................................................. 13
8.5 Input - Output Parameters ....................................................................................................... 13
9. JSON_Extract_Object_1 ..................................................................................................................... 13
 9.1 Change Notes........................................................................................................................... 13
9.2 Function Block Call ................................................................................................................... 13
9.3 Input Parameters ..................................................................................................................... 13
9.4 Output Parameters .................................................................................................................. 14
10. MQTT_Azure_1................................................................................................................................ 14
10.1 Change Notes ......................................................................................................................... 14
10.2 Function Block Call ................................................................................................................. 14
10.3 Input Parameters ................................................................................................................... 14
10.4 Output Parameters ................................................................................................................ 14
10.5 Input - Output Parameters ..................................................................................................... 14
Datatypes .............................................................................................................................................. 15
Custom Arrays ............................................................................................................................... 15
MQTT_DATA .................................................................................................................................. 15
MQTT_SUB .................................................................................................................................... 15
MQTT_PUB .................................................................................................................................... 16
Appendix 1: Using the JSON_Add_Object_1 function block with MQTT_Publish_1................................. 16
Appendix 2: Using the JSON_Extract_Object_1 function block with MQTT_Subscribe_1 ........................ 17
Application Examples ............................................................................................................................ 17
1. Overview
The Function Blocks MQTT_Connect_3, MQTT_Publish_1, and MQTT_Subscribe_1 was created as a
wrapper of the existing IIOT_Library. This wrapper was created to turn the complex methods into a
simple publish/subscribe configuration. There are also blocks to build JSON strings and extract objects
from JSON strings to reduce the number of necessary topics.

2. Important Information
The IIOT_Library_4 must be downloaded separately to this library to allow functionality of this library.
* This issue will be fixed in a future version*

This library only allows one broker connection at a time.

There is a maximum of 100 publish and subscribe blocks allowed, and the more blocks that are used the
maximum rate of publishing messages will decrease.

3. Change Notes
Library Library PLCnext Change Notes Supported
Version Build Engineer PLC
Version
1 20220307 >= 2022.0.2 LTS Initial Release AXC F 1152
AXC F 2152
AXC F 3152
1.1 >= 2022.0.2 LTS New inputs for additional AXC F 1152
connection options, bug fixes AXC F 2152
AXC F 3152
2.0 >= 2023.0 LTS New inputs for additional AXC F 1152
MQTT brokers, Azure block AXC F 2152
created to simplify Azure AXC F 3152
communication, updated
packet sizes to library
maximum, upgraded to 2023.0.
4. Function Blocks
Function Block Description Ver Supported Articles License

MQTT_Client_3 Initializes the MQTT 2 None

Connection to the
broker, as well as all
connection parameters
MQTT_Publish_1 Function block to 1 None
publish a message to
the MQTT broker if
connected
MQTT_Subscribe_1 Function block to 1 None
subscribe/unsubscribe
from a topic on the
MQTT broker
JSON_Add_Object_1 Function block to build 1 None
JSON objects to send
over MQTT_Publish_1
JSON_Extract_Object_1 Function block to 1 None
extract an object from a
JSON object received
from
MQTT_Subscribe_1
MQTT_Azure_1 Function block to set 1 None
Azure parameters for
communication

5. MQTT_Client_3
The MQTT_Client_3 function block connects to an MQTT broker (local or internet based) and allows publishing and
subscribing to topics on that broker.

This Function Block may only be called one time, if called more than once this will cause unknown errors.

5.1 Change Notes

Version Change Note
1 Initial Release
2 Added additional inputs for more connection options, bug fixes.
3 Added additional inputs for more connection options
5.2 Function Block Call
5.3 Input Parameters
Name Type Description
xEnable BOOL On Rising Edge, the Function Block starts to initialize the
connection to the MQTT Broker with the input parameters.
On Falling Edge, the Function Block disconnects from the
Broker, and disables MQTT communication.
xReset BOOL On Rising Edge, clears the error from xError as well as the
error codes and restarts from its failed state.
strURI STRING URL or IP Address of the broker.
If using a URL do not include http:// or https://, and do not
include any ports!
strClientID STRING Name of the client connecting to the MQTT Broker. This
name must be unique for each device connecting to the
broker if multiple devices are connecting
xCleanSession BOOL If TRUE, the MQTT Broker will remember the state of the
client prior to a reconnect. If FALSE, all subscriptions will
have to re-subscribe on reconnection.
xSSL BOOL If TRUE, SSL will be used. If FALSE, no SSL will be used.
xServerCertAuth BOOL If TRUE, there is verification of the server certificate. If
FALSE, the server certificate will not be verified.
strUsername STRING The username to allow communication to the MQTT
Broker. If no username is required, leave this variable blank
strPassword STRING The password to allow communication to the MQTT
Broker. If no password is required, leave this variable blank
strCertificate STRING The location and name of the Certificate on the PLCnext
Controller. The certificate must be located inside the
/opt/plcnext/ directory. It can be inside a folder within this
directory but it must be included in this variable.

EX: Certificate location: “/opt/plcnext/cert.crt”

strCertificate = ‘cert.crt’
Certificate location: “/opt/plcnext/certificates/cert.crt”
strCertificate = ‘certificates/cert.crt’

If no certificate is used leave this variable blank.

strPrivateKey STRING The location and name of the Private Key on the PLCnext
Controller. The certificate must be located inside the
/opt/plcnext/ directory. It can be inside a folder within this
directory but it must be included in this variable.

EX: Private Key location: “/opt/plcnext/private.key”

strPrivateKey = ‘cert.crt’
Private Key location:
“/opt/plcnext/certificates/private.key”
strPrivateKey = ‘certificates/private.key’

If no private key is used leave this variable blank.

strMQTTCA STRING The location and name of the CA (Certificate Authority) on
the PLCnext Controller. The certificate must be located
inside the /opt/plcnext/ directory. It can be inside a folder
within this directory but it must be included in this variable.

EX: Certificate location: “/opt/plcnext/CA.pem”

strMQTTCA = ‘CA.pem’
Certificate location: “/opt/plcnext/certificates/CA.pem”
strMQTTCA = ‘certificates/CA.pem’

If no CA is used leave this variable blank.

strPrivateKeyPassword STRING The password to load the client’s privateKey (if
encrypted).
Pass an empty string ’’ if not required.
strEnabledCipherSuites BOOL The list of cipher suites that the client will present to the
server during the SSL handshake*.
Pass an empty string ’’ if not required.

*The list of cipher suites that the client will present to

the server during the SSL handshake. For a full
explanation of the cipher list format, please see the
OpenSSL on-line documentation. If this setting is
ommitted, its default value will be “ALL”, that is, all the
cipher suites - excluding those offering no encryption -
will be considered.
xBuffer BOOL If TRUE, when connection is lost and messages publish
before error they will be buffered.
If FALSE, any message that is trying to be sent on
connection loss will be discarded.
diConnectionTimeout DINT The time interval in seconds to allow a connection or
reconnection to complete. If exceeded an error will occur.
diKeepAliveInterval DINT The maximum time interval in seconds that should pass
without communication between the client and server.
xLWT BOOL If TRUE, Last Will and Testament will be used. If FALSE, Last
Will and Testament will not be used.
strLWTtopic STRING The Last Will and Testament Topic
strLWTmsg STRING The message to be posted to the Last Will and Testament
on an unexpected disconnection
diLWTQOS DINT The QOS (Quality of Service) of the Last Will and Testament
message.
xLWTRetain BOOL If TRUE, the Last Will and Testament message will be
retained on the broker. If FALSE, the message will not be
retained.
5.4 Output Parameters
Name Type Description
xConnected BOOL The MQTT_Client_1 block is currently connected to the
broker.
xError BOOL There is an error in the MQTT communication to the
broker
wErrorCode WORD The Error Code
wAddDiagCode WORD The Additional Diagnostic code associated with the
Error Code
strErrorMsg STRING The Error that occurred written in string.

5.5 Input – Output Parameters

Name Type Description
udtMQTTdata MQTT_DATA MQTT Messages being passed, as well as other
parameters.

6. MQTT_Publish_1
The MQTT_Publish_1 function block publishes data to the MQTT Broker when connected.

6.1 Change Notes

Version Change Note
1 Initial Release
6.2 Function Block Call
6.3 Input Parameters
Name Type Description
xEnable BOOL On Rising Edge, the Function Block checks the input
parameters to ensure a valid message is trying to be sent,
and allows operation.
xPublish BOOL On Rising Edge, the message will attempt to publish. If
there is an error the block will not attempt to publish!
strTopic STRING The topic to publish the message to
strPayload STR2000 The payload to send on the strTopic.
diQOS DINT The QOS (Quality of Service) to publish the message.
xRetain BOOL If TRUE, the message will be retained on the broker. If
FALSE, the message will not be retained.
NOTE: Not all brokers support Retain, make sure your
broker does!
xReset BOOL Clears the error associated with this block. This block will
only have errors on its internal processes, NOT the clients
errors.

6.4 Output Parameters

Name Type Description
xPublished BOOL On Rising Edge the message was published to the
broker successfully.
xError BOOL There is an error in publishing, or configuration of the
block.
strErrorMsg STRING The error that occurred in the block.

6.5 Input - Output Parameters

Name Type Description
udtMQTTdata MQTT_DATA MQTT Messages being passed, as well as other
parameters.
7. MQTT_Subscribe_1
The MQTT_Subscribe_1 function block subscribes to a topic on the MQTT Broker when triggered.

7.1 Change Notes

Version Change Note
1 Initial Release
7.2 Function Block Call

7.3 Input Parameters

Name Type Description
xEnable BOOL On Rising Edge, the Function Block checks the input
parameters to ensure a valid subscription is trying to be
sent, and allows operation.
xSubscribe BOOL On Rising Edge, the MQTT Client will subscribe to the topic.
On Falling Edge, the MQTT Client will un-subscribe from the
topic.
strTopic STRING The topic to subscribe to.
diQOS DINT The maximum QOS (Quality of Service) at which to
subscribe.
xReset BOOL Clears the error associated with this block. This block will
only have errors on its internal processes, NOT the clients
errors.
7.4 Output Parameters
Name Type Description
xSubscribed BOOL When true, the MQTT Client is subscribed to the topic.
xError BOOL There is an error in subscribing, or configuration of the
block.
strErrorMsg STRING The error that occurred in the block.
xNewMsg BOOL On Rising Edge, a new message was received on the
topic.
strPayload STR2000 The payload received. Only valid when xNewMsg is True
7.5 Input - Output Parameters
Name Type Description
udtMQTTdata MQTT_DATA MQTT Messages being passed, as well as other
parameters.

8. JSON_Add_Object_1
The JSON_Add_Object_1 function block either creates a JSON or adds a new JSON object to an existing JSON.

For correct operation of this block refer to Appendix 1.

8.1 Change Notes

Version Change Note
1 Initial Release
8.2 Function Block Call

8.3 Input Parameters

Name Type Description
xEnable BOOL When TRUE, allows operation of the JSON build.
xAppend BOOL If TRUE, the object will be added to the JSON string.
If FALSE, the JSON string will be cleared. The first block in
the chain must be False!
xAddObject BOOL Add the JSON object to the JSON string.
strJsonKey STRING The key of the JSON object being added to JSON string
strJsonValue STRING The value of the JSON key being added to JSON string
xReset BOOL Clears the error associated with this block. This block will
only have errors on its internal processes.
8.4 Output Parameters
Name Type Description
xComplete BOOL On rising edge, the JSON object has been added to the
JSON string successfully.
xError BOOL There is an error in building the JSON object or
appending to the current JSON string.
strErrorMsg STRING The error that occurred in the block.
8.5 Input - Output Parameters
Name Type Description
strPayload STR2000 The JSON string to be built.

9. JSON_Extract_Object_1
The JSON_Extract_Object_1 function block extracts a JSON object from a JSON string.

For correct operation of this block refer to Appendix 2.

9.1 Change Notes

Version Change Note
1 Initial Release
9.2 Function Block Call

9.3 Input Parameters

Name Type Description
xEnable BOOL When TRUE, allows operation of the JSON extract.
xGetValue BOOL On Rising Edge, the block will attempt to extract the value
of the JSON key provided.
strPayload STRING The JSON string to search for the JSON key
strJsonKey DINT The JSON key to extract from the JSON string
xReset BOOL Clears the error associated with this block. This block will
only have errors on its internal processes.
9.4 Output Parameters
Name Type Description
xError BOOL There is an error in searching, ensure the JSON string is
valid.
strErrorMsg STRING The error that occurred in the block.
strValue STRING The value received from the search if successful

10. MQTT_Azure_1
The MQTT_Azure_1 function block is used to set all settings required for connecting to Azure. The only inputs
required to connect is the certificates and (optional) private key password.

10.1 Change Notes

Version Change Note
1 Initial Release
10.2 Function Block Call

10.3 Input Parameters

Name Type Description
xEnable BOOL When TRUE, allows operation of the JSON extract.
strIOThubName STRING512 The name of the Azure IOT Hub you are connecting to.
strDeviceName STRING512 The name of the device in the Azure IOT Hub
10.4 Output Parameters
Name Type Description
xDone BOOL The Azure configuration is set correctly.
10.5 Input - Output Parameters
Name Type Description
udtMQTTdata MQTT_DATA MQTT Messages being passed, as well as other
parameters.
Datatypes
Custom Arrays
Name Type Description
MQTT_Msg Array of 32,765 Bytes Array for the maximum MQTT message size
MQTT_Key Array of 100 bytes Array for a 100 character MQTT Key
STR2000 Custom length string 2,000 Character String
strMsg Custom length string 32,700 character string for max message size
MQTT_DATA
Name Type Description
xEnabled BOOL MQTT Client Enabled (READ ONLY)
xConnected BOOL MQTT Client Connected (READ ONLY)
xDisconnect BOOL MQTT Client Disconnect (READ ONLY)
xResetSub BOOL Used to Reset subscriptions in the event of a broker
reboot
xResetPub BOOL Used to Reset Publishes in the event of an unknown
error
xAzure BOOL True if Azure configuration is used
strIOThubName STRING512 Name of the Azure IOT Hub if used
strDeviceName STRING512 Name of the Azure Device connecting
strURI STR2000 URI of the connection. Used for Azure Pub/Sub
arrSubMsg MQTT_Sub[100] Array of 100 MQTT_Sub
arrPubMsg MQTT_Pub[100] Array of 100 MQTT_Pub
MQTT_SUB
Name Type Description
xUsed BOOL If the slot is used
xSubscribe BOOL Rising Edge triggers subscription
xSubscribed BOOL The topic is subscribed
xUnsubscribe BOOL Rising Edge triggers un-subscribe
xRead BOOL Read New Message
strTopic STRING Topic subscribed to
diQOS DINT The maximum QOS (Quality of Service) at which to
subscribe.
arrMsg MQTT_Msg Array of 2000 bytes for raw data transmission
udiLength UDINT Length of array used
xError BOOL Error on Subscribing
strErrorCode STRING Cause of error.
MQTT_PUB
Name Type Description
xUsed BOOL If the slot is used
xPublish BOOL Rising Edge triggers subscription
xPublished BOOL The topic is subscribed
strTopic STRING Topic subscribed to
arrMsg MQTT_Msg Array of 2000 bytes for raw data transmission
xRetain BOOL Message retain
udiLength UDINT Length of array used
diQOS DINT Quality Of Service
xError BOOL Error on Subscribing
strErrorCode STRING Cause of error.

Appendix 1: Using the JSON_Add_Object_1 function block with

MQTT_Publish_1
The way the block is built, it uses an Input Output to build the payload. Therefore, the JSON Build must
be connected directly to the MQTT_Publish if the JSON is built at a cyclic rate, and if the payload is being
published at a cyclic rate. If it is not connected directly, the MQTT_Publish can send partial payloads!

To create larger payloads, the JSON_Add_Object blocks must be connected together, as shown in the
image below. Once the first object is added and the xComplete bit goes high, the next object can be
added and so on. Once the final object is added it can be attached to the MQTT_Publish to send.

The image above will send a message of : {“Temperature”: “70.50535”, “Count”: “13”}
Appendix 2: Using the JSON_Extract_Object_1 function block
with MQTT_Subscribe_1
This block connects directly to a MQTT_Subscribe block and extracts the specified object. This block will
only output all values as a string, so conversion is necessary. Below is an example of how to extract
objects from a JSON payload.

JSON Payload: {“Temperature”: “70.50535”, “Count”: “13”}

Extraction code:

Application Examples
Multiple application examples are included in the download of this library. It is located here:
MQTT_Client_2>Files>Examples