MQTT library Function Block description User’s Manual
Application Library:
Introduction
Thank you for using the Application Library: MQTT Sysmac library
Use it when programming with the automation software Sysmac Studio.
This manual contains information that is necessary to use the Application Library with the
Sysmac Studio.
Hereinafter, the function blocks are described as FB, and functions as FNs.
Please read and understand this manual before using the Application Library. Refer also to the
user's manuals for Application Library and the Sysmac Studio Version1 Operation Manual
(Cat.No. W504).
Intended Audience
This manual is intended for the following personnel, who must also have knowledge of
automation and IT systems (an automation and/or IT engineer or the equivalent).
- Personnel in charge of introducing FA systems
- Personnel in charge of designing FA systems
- Personnel in charge of installing and maintaining FA systems
- Personnel in charge of managing FA systems and facilities
- Personnel in charge of designing IT systems and facilities
- Personnel in charge of managing IT systems and facilities
-
For programming, this manual is intended for personnel who understand the programming
language specifications in international standard IEC 61131-3 or Japanese standard JIS B 3503.
Notice
This manual describes the necessary information to use the Application Library.
Please read and understand this manual before using the library. Keep this manual in a safe
place where it will be available for reference during operation.
Terms and Conditions Agreement
1 NO WARRANTY
1)The functions and function block is distributed as a sample in the hope that it will be useful,
but without any warranty. It is provided “as is” without warranty of any kind, either expressed or
implied, including, but not limited to, the implied warranties of merchantability and fitness for a
particular purpose. The entire risk as to the quality and performance of the function blocks is
with you. Should the function block prove defective, you assume the cost of all necessary
servicing, repair or correction.
2)In no event unless required by applicable law the author will be liable to you for damages,
including any general, special, incidental or consequential damages arising out of the use or
inability to use the function blocks (including but not limited to loss of data or data being rendered
inaccurate or losses sustained by you or third parties or a failure of the function blocks to operate
with any other programs), even if the author has been advised of the possibility of such damages.
2 LIMITATION OF LIABILITY
1) OMRON SHALL HAVE NO LIABILITY FOR DEFECT OF THE SOFTWARE.
2) OMRON SHALL HAVE NO LIABILITY FOR SOFTWARE PARTS DEVELOPED BY THE
USER OR ANY THIRD PARTY USING THE FUNCTION BLOCK DESCRIBED ON THIS
MANUAL.
3 APPLICABLE CONDITIONS
USER SHALL NOT USE THE SOFTWARE FOR THE PURPOSE THAT IS NOT
PROVIDED IN THE ATTACHED USER MANUAL.
4 CHANGE IN SPECIFICATION
The software specifications and accessories may be changed at any time based on
improvements and other reasons.
5 ERRORS AND OMISSIONS
The information in this manual has been carefully checked and is believed to be accurate;
however, no responsibility is assumed for clerical, typographical, or proofreading errors, or
omissions.
Applicable Products
This manual covers the following products.
Name Model number Version
MQTT library --- Ver. 0.45.00b14
Sysmac Studio SYSMAC-SE2□□□ Ver.1.22 or later
Machine Automation Controller
NX1P2-□□□□
NJ1-□□□□
NJ3-□□□□
NJ5-□□□□
NX7-□□□□
NX102-1□□□
Ver.1.18 or later
Ver.1.30 or later
Safety Precautions
Definition of Precautionary Information The following notation is used in this manual to provide precautions required to ensure safe
usage of MQTT library.
The safety precautions that are provided are extremely important to safety. Always read
and heed the information provided in all safety precautions.
The following notation is used.
Indicates a potentially hazardous situation which, if not avoided, could result in death or serious injury. Additionally, there may be severe property damage.
Indicates a potentially hazardous situation which, if not avoided, may result in minor or moderate injury, or property damage.
Precautions for Safe Use
Indicates precautions on what to do and what not to do to ensure safe usage of the
product.
Precautions for Correct Use
Indicates precautions on what to do and what not to do to ensure proper operation and
performance.
Additional Information
Additional information to read as required.
This information is provided to increase understanding or make operation easier.
The triangle symbol indicates precautions (including warnings). The specific operation is shown in the triangle and explained in text. This example indicates a general precaution.
The filled circle symbol indicates operations that you must do. The specific operation is shown in the circle and explained in text. This example shows a general precaution for something that you must do.
Warning list
Emergency stop circuits, interlock circuits, hardware limit and similar safety measures must be provided in external control circuits.
Using this FB in a device, confirm that the program and FB operate properly.
Design a program so that safety measures such as fail-safe circuits are implemented
outside of the FB
Caution list
Confirming an operation of the control program, including this FB. Trial operation such as the concerned motor runs in low velocity is recommended.
Performing adjustment of the device controlled by the program with this FB, secure
the safety of the machine.
Do not use this FB for the system with devices and versions not specified in this
document. To use, contact your OMRON representative
If a Task Period Exceeded Error occurred by executing this FB, the CPU Unit shifts to
an error state.
Make sure to set the execution task period to an appropriate value by referring to the
execution time of this FB.
Do not delete the instances from the program with online editing during an execution of this FB. Program communication will stop in error.
Make sure to set the input parameters of this FB appropriately in accordance with the actual device. Make settings as described in this manual.
Table of Contents Introduction .................................................................................. 2
Intended Audience ..................................................................... 2 Terms and Conditions Agreement ............................................. 3 Applicable Products ................................................................... 4 Safety Precautions ..................................................................... 5
1. Overview ................................................................................ 2 1.1. Applications ..................................................................... 2 1.2. Application concept ......................................................... 3 1.3. Symbol ............................................................................ 5 1.4. User cases ...................................................................... 6 1.5. Software configuration .................................................... 8
2. MQTTClient: .......................................................................... 9 2.1. FB Layout ........................................................................ 9 2.1. Function .......................................................................... 9 2.2. Input Variables ................................................................ 9 2.3. Output Variables ............................................................ 10 2.4. In-Out Variables ............................................................ 11
3. MQTTPublish: ..................................................................... 12 3.1. FB Layout ...................................................................... 12 3.2. Function ........................................................................ 12 3.3. Input Variables .............................................................. 12 3.4. Output Variables ............................................................ 13 3.5. In-Out Variables ............................................................ 13
4. MQTTPublishArr: ................................................................ 14 4.1. FB Layout ...................................................................... 14 4.2. Function ........................................................................ 14 4.3. Input Variables .............................................................. 14 4.4. Output Variables ............................................................ 15 4.5. In-Out Variables ............................................................ 15
5. MQTTSubscribe: ................................................................. 16 5.1. FB Layout ...................................................................... 16 5.1. Function ........................................................................ 16 5.2. Input Variables .............................................................. 16 5.3. Output Variables ............................................................ 17 5.1. In-Out Variables ............................................................ 17
6. MQTTSubscribeArr: ........................................................... 18 6.1. FB Layout ...................................................................... 18 6.2. Function ........................................................................ 18 6.3. Input Variables .............................................................. 18 6.4. Output Variables ............................................................ 19 6.5. In-Out Variables ............................................................ 19
7. MQTTPing: .......................................................................... 20 7.1. FB Layout ...................................................................... 20 7.2. Function ........................................................................ 20 7.3. Input Variables .............................................................. 20 7.4. Output Variables ............................................................ 21 7.5. In-Out Variables ............................................................ 21
8. Parameter Description in detail ........................................ 22 8.1. MQTTClient parameters ............................................... 22 8.2. MQTTPublish / MQTTPublishArr parameters ............... 25
8.3. MQTTSubscribe/ MQTTSubscribeArr Parameters ....... 27 8.4. MQTTPing Parameters ................................................. 28
9. Application Example .......................................................... 29 9.1. Scenario ......................... Error! Bookmark not defined. 9.1. Libraries to be add to the project .................................. 30 9.2. MQTT server account ................................................... 30 9.3. Connection Configuration ............................................. 30 9.4. Client Configuration ...................................................... 31 9.5. JSON data codification ................................................. 32 9.6. Publish........................................................................... 33 9.7. Subscribe ...................................................................... 34 9.1. Ping ............................................................................... 34 9.2. Testing , monitoring and Debugging tools .................... 35
10. Resources and tools for MQTT..................................... 37 10.1. MQTT servers: .............................................................. 37 10.2. Software tools for testing : ............................................ 38 10.3. Testing from a dashboard: ............................................ 39
11. Troubleshooting (Response Codes and Corrections)41 11.1. ErrorID codes ................................................................ 41 11.2. Error ID Extended codes ............................................... 41
ATE-CEEXXXXX
1
Revision History
Rev Code Content Created by Checked by Approved by
A None Original production - DRAFT Automation Center Technical
Dept. Europe
Santi Gomez
January 2, 2017
B None Changes added Automation Center Technical
Dept. Europe
Santi Gomez
Nov 2, 2017
C None Changes added Automation Center Technical
Dept. Europe
Santi Gomez
May, 2018
D None Changes added Automation Center Technical
Dept. Europe
Santi Gomez
September, 2018
E None Changes added Automation Center Technical
Dept. Europe
Santi Gomez
February, 2019
2
1. Overview
1.1. Applications
MQTT library is a collection of function blocks (FB) that exchanges messages between devices
by using publisher/subscriber method, through a MQTT server ( also calsed MQTT broker)
connection.
The library meets the open MQTT standard 3.1.1 published on www. http://mqtt.org
By using this method, the subscribers to a message topic may receive information from the
publishers even if those stations are in different network, different location, and the
message can be any type, as per example plain text, JSON, XML, or binary data,
containing topics and subtopics.
A MQTT publisher can also publish a ‘last will’ message to notify that it is disconnected or not
available. In addition, there are different levels of message acknowledge, to notify that the
message has been delivered ( QoS: Quality of service) and may retain last message before its
disconnection.
The number of the subscribers may be from a few units to thousands, from a single connection.
Please note this traffic is managed by the server (hereinafter called MQTT server) and has no
impact on the devices connected to him. So the system is scalable according the server capacity.
Those FB can be used for the following applications.
· Exchange information from/to devices such a huge sensor network, widely and accessed
worldwide: as weather stations, transport, social systems, autonomous vehicles , etc…
· In a manufacturing process, a sub process may communicate some data abroad, to the
processes that are depending of it, regardless its localization and system type .
· On IoT and Big Data processing, from a sensor to a controller, we can collect data and store
for further analysis.
3
1.2. Application concept
It works based on publisher/ subscriber technology. Here, a publisher sends a data
under a topic, then all the subscribers to that topic will receive the message. The
exchange is handled by the MQTT server ( often running remotely in a cloud service) .
The information sent from a publisher can be exchanged from one to thousands, just
with a single publisher connection, because the MQTT server manages the connections
and takes care of the data exchange to the stations subscribed to the published topic.
4
A publisher can be also subscriber and viceversa. The connected stations can operate
anywhere and is not needed to be in the same network, if the server runs in a remote
cloud service. The MQTT server manages the connections through internet.
1.3. Function Specification
This refers to the features available for v.0.45.00, vs previous version.
former 0.44.98f 0.45.00 Comments
Maximum size of
payload at Publish
STRING[1986] STRING[1986] MQTTPublish
- ARRAY[65000] of BYTE MQTTPublishArr
Maximum size of
payload at Subscribe
STRING[256] STRING[1986] MQTTSubscribe
- ARRAY[65000] of BYTE MQTTSubscribeArr
QoS at Publish 0,1 0,1, and 2
QoS at Subscribe 0 0,1, and 2
Wildcard support (#) at
Subscribe N/A YES YES
Aplicable Controllers NX1P2,NJ,
NX102,NX7 NX1P2,NJ, NX102,NX7
5
1.4. Symbol
MQTTClient MQTTPublish MQTTSubscribe MQTTPing
MQTTPublishArr MQTTSubscribeArr
6
1.5. User cases
1.5.1. When the MQTT server belongs to the same network
This is the typical scenario where MQTTclients and MQTT server shares the same network and are
on premises . The MQTT server runs on a local server. This scenario is really interesting for sharing
information between devices ( M2M) on premises.
1.5.2. When the MQTT server is a cloud service:
In this case, the clients connects to a remote MQTT server, usually running in a cloud service .
The networks may be geographically isolated so the MQTT clients connects to MQTT server from
internet and the MQTT server manages the connections between them and delivers the messages to
the subscribes, same as a local network.
7
1.5.3. Mix of local Server and Cloud service :
A common scenario could be a local MQTT server sharing information between the MQTT
clients in a local network, but in addition connected to another MQTT server running in a remote
cloud service. This could be a scenario for storage, data analysis, report generation, etc from a
cloud data service .
The local MQTT server needs to be bridged to the remote MQTT server at the cloud , fortunately
many cloud providers offers this possibility.
A big advantage is that the bridged connection can be TLS/SSL secured .
The use of bridged connections between MQTT servers allow to interconnect different clients regardless their
localization in a secured way.
The bridged connections are out of the scope of this MQTT library, so please check first the MQTTServer / Cloud
server connection bridging / encryption capabilities.
8
1.6. Software configuration
The following settings must be configured in order to assure a proper connection. Otherwise the
FB becomes in error. Select the settings according the parameter set on MQTTConnect ( host
name or IP)
1.6.1. If a host name is used on the MQTTclient FB: On the NJ / NX controller:
Classification Parameter name Set value
IP address IP address Your IP Address
Subnet mask According your subnet
Default Gateway According router gateway
DNS
(Set as “Use” )
Priority DNS server DNS primary address
Secondary DNS server DNS secondary address
Domain Name DNS domain name
Example: Connection to DNS server on www.verisign.com (*1)
(*1) Recommended enter both primary and secondary server addresses for the chosen DNS server.
You can omit DNS domain name. However, you should enter at least a Primary DNS server address.
1.6.2. If a known IP address is used on the MQTTclient FB: On the NJ / NX controller:
Classification Parameter name Set value
IP address IP address Your IP Address
Subnet mask According your subnet
Default Gateway According router gateway
(*2) DNS
(Set as “Do Not use”)
Priority DNS server -
Secondary DNS server -
Domain Name -
(*2) Skip this step if you’re working in a local network with a known MQTT server address.
9
2. MQTTClient:
2.1. FB Layout
2.1. Function This MQTTClient manages the connection to the MQTT server, sends the messages from the MQTTpublish instances and delivers the messages to the MQTTSubscribe instances.
2.2. Input Variables
Variable Name Data Type Initial
Value
Valid
Range
Change over
during execution
Meaning
Enable BOOL FALSE True / false
Stablish the
connection to MQTT
server
Host STRING[256] - String defining
IP or Hostname
NO Server host name or
host IP address
ServerPort UINT 1883 NO Server inbound port
ClientID STRING[128] - Alphanumeric NO Client ID ( optional)
WillConfig WillCnfg Refer to
2.2.1
- NO Configuration of last
will message
CleanSession BOOL TRUE - NO Sets a Clean session
UserLogin Login Refer to
2.2.2
- NO User login ( optional, if
server requires
authentication)
KeepAlive UINT 60 seconds 0..65535
seconds
NO Time agreed to wait
before closing a non
active connection
( server side)
10
2.2.1. WillCnfg structure
This variable is used to configure the last will message if the client disconnects from the server.
Variable Name Data Type Initial Value Valid
Range
Change over during
execution
Comment
WillTopic STRING[128] none Alphanumeric
except # , % or $
NO Sets the Will topic ( topic
to be subscribed if you
want to receive this will
message)
WillMessage STRING[128] none Alphanumeric NO Will message
( subscribers will receive
this message if are
subscribed to the
WillTopic)
WillRetain BOOL False True/false NO Last Will message will be
retained on server
WillQoS BYTE 0
0,1 NO Quality Of Service setting
for Will message
WillFlag BOOL False True/false NO Enables/ disable the
LastWill feature
2.2.2. Login Structure
Variable Name Data Type Initial
Value
Valid
Range
Change over
during execution
Comment
User STRING[256] none Alphanumeric NO Optional ( If required
by Server)
Password STRING[256] none Alphanumeric NO Optional if User is set
2.3. Output Variables
Variable Name Data Type Comment
Connected BOOL TRUE when the connection to server is stablished.
Busy BOOL TRUE during execution.
When [Error] changes to TRUE, Busy becomes FALSE.
Busy is FALSE during non-execution status.
SocketID _sSOCKET Socket ID instance ( used by MQTT Publish / Subscribe)
Error BOOL TRUE if an error occurs.
ErrorID WORD Contains the error code when an error occurs. *3
#0000 is the initial value and indicated as normal end.
ErrorIDEx DWORD Contains the error code when an error occurs. *3
#00000000 is the initial value and indicates a normal end.
*1 Refer to TroubleShooting section for details.
11
2.4. In-Out Variables
Variable Name Data Type Initial
Value
Valid
Range
Change over during
execution(Enable=TRUE)
Comment
BufferÎn MQTT/ClientBuffer - - no Queue data
buffer
The BufferIn I/O variable is used internally by the client and Pub/Sub instances and shouldn’t be changed by the program user.
12
3. MQTTPublish:
3.1. FB Layout
3.2. Function This MQTTPublish builds a publish message as a STRING[1986] and queues at the MQTTClient to be delivered to the connected MQTTserver, that will be delivered to the subscribed clients .
3.3. Input Variables
Variable
Name
Data Type Initial
Value
Valid Range Change over
during execution
Meaning
Execute BOOL FALSE - NO Publish a Topic/Message to
MQTT server
Topic STRING[128] Empty Alphanumeric except # , %
or $
NO Topic to be published
QoS Byte 0 0,1,2 NO Quality of Service level
0: At most once delivery
1: At least one delivery
2: Exactly once delivery
Retained(*5) BOOL FALSE True / false NO If TRUE, the Server stores the
last message to be delivered
to the subscribers as soon a
device subscribes to the
message Topic.
Dup BOOL FALSE True / false NO Duplicated message :
DUP =0: First send of Publish
packet
DUP=1: Re-delivery of publish
packet. It is managed by the
user application program.
*5. For reset a retained message, publish an empty payload message with Retained = TRUE.
13
3.4. Output Variables
Variable Name Data Type Comment
Done BOOL TRUE when message is sent
Busy BOOL TRUE during execution.
When [Error] changes to TRUE, Busy becomes FALSE.
Busy is FALSE during non-execution status.
If TRUE and not Done, means it is on process or queued.
PacketID UINT Packet ID, automatically assigned by client
Size UINT Size of the publish query
Error BOOL TRUE if an error occurs.
ErrorID WORD Contains the error code when an error occurs. (*6)
#0000 is the initial value and indicated as normal end.
ErrorIDEx DWORD Contains the error code when an error occurs. (*6)
#00000000 is the initial value and indicates a normal end.
(*6). Refer to Troubleshooting section for details.
3.5. In-Out Variables
Variable Name Data Type Initial
Value
Valid
Range
Change over during
execution(Enable=TRUE)
Comment
Buffer MQTT/ClientBuffer - - MQTT client
data buffer
Message
STRING[1986] Alphanumeric.
Message to be
published as
Topic/Message
The BufferIn I/O variable is used internally by the client and Pub/Sub instances and shouldn’t be changed by the program user.
14
4. MQTTPublishArr:
4.1. FB Layout
4.2. Function This MQTTPublishArr builds a publish message as a ByteArray up to 65000 bytes and queues at the MQTTClient to be delivered to the connected MQTTserver, that will be delivered to the subscribed clients .
4.3. Input Variables
Variable
Name
Data Type Initial
Value
Valid Range Change over
during execution
Meaning
Execute BOOL FALSE - NO Publish a Topic/Message to MQTT server
Topic STRING[128] Empty Alphanumeric
except # , % or $
NO Topic to be published
QoS Byte 0 0,1,2 NO Quality of Service level
0: At most once delivery
1: At least one delivery
2: Exactly once delivery
Retained(*7) BOOL FALSE True / false NO If TRUE, the Server stores the last
message to be delivered to the
subscribers as soon a device subscribes
to the message Topic.
Dup BOOL FALSE True / false NO Duplicated message :
DUP =0: First send of Publish packet
DUP=1: Re-delivery of publish packet. It is
managed by the application program.
(*7). For reset a retained message, publish an empty payload message with Retained = TRUE.
15
4.4. Output Variables
Variable Name Data Type Comment
Done BOOL TRUE when message is sent
Busy BOOL TRUE during execution.
When [Error] changes to TRUE, Busy becomes FALSE.
Busy is FALSE during non-execution status.
If TRUE and not Done, means it is on process or queued.
PacketID UINT Packet ID, automatically assigned by client
Size UINT Size of the publish query
Error BOOL TRUE if an error occurs.
ErrorID WORD Contains the error code when an error occurs. (*8)
#0000 is the initial value and indicated as normal end.
ErrorIDEx DWORD Contains the error code when an error occurs. (*8)
#00000000 is the initial value and indicates a normal end.
*8. Refer to Troubleshooting section for details.
4.5. In-Out Variables
Variable Name Data Type Initial
Value
Valid
Range
Change over during
execution(Enable=TRUE)
Comment
Buffer MQTT/ClientBuffer - - MQTT client
data buffer
Message
Array[0.64999] OF
Byte (*9)
Byte Array.
Message to be
published as
Topic/Message
(*9) Maximum size.
The BufferIn I/O variable is used internally by the client and Pub/Sub instances and shouldn’t be changed by the program user.
16
5. MQTTSubscribe:
5.1. FB Layout
5.1. Function This MQTTSubscribe builds a subscription message and , once subscribed, looks to the MQTTClient for subscribed topics, receiving the messages as STRING[1986].
5.2. Input Variables
Variable Name Data Type Initial
Value
Valid
Range
Change over during
execution
Meaning
Enable BOOL - TRUE/
FALSE
Subscribe to a Topic
on a MQTT server.
Once subscribed,
setting to FALSE it
unsusbscribes.
Topic (*10) STRING[128] - - Topic to be
subscribed. Note the
Topic is case sensitive
QoS Byte 0 0,1,2 Maximum Quality of
service granted for
that subscription
(*10) The use of Wilcard “#” is supported ( only at the end of the topic)
17
5.3. Output Variables
Variable Name Data Type Comment
Subscribed BOOL TRUE when subscribed to a Topic
Done BOOL TRUE each time the value is updated.
On a rising edge, the information updated will appear on the
Message output (STRING)
Busy BOOL TRUE during execution.
When [Error] changes to TRUE, Busy becomes FALSE.
Busy is FALSE during non-execution status.
PacketID UINT Shows the subscribe PacketID
Error BOOL TRUE if an error occurs.
ErrorID WORD Contains the error code when an error occurs. (*11)
#0000 is the initial value and indicated as normal end.
ErrorIDEx DWORD Contains the error code when an error occurs. (*11)
#00000000 is the initial value and indicates a normal end.
Size UINT Size of the received message
*11 Refer to Troubleshooting for details.
5.1. In-Out Variables
Variable Name Data Type Initial
Value
Valid
Range
Change over during
execution(Enable=TRUE)
Comment
Buffer MQTT/ClientBuffer - - MQTT client
data buffer
Message STRING[1986] (*12) It returns the
Message
payload, without
the subscription
topic
RcvTopic STRING[128] (*12) It returns the
received topic
(*12) Maximum size
18
6. MQTTSubscribeArr:
6.1. FB Layout
6.2. Function This MQTTSubscribeArr builds a subscription message and , once subscribed, looks to the MQTTClient for subscribed topics, receiving the messages up to 65000 bytes.
6.3. Input Variables
Variable Name Data Type Initial
Value
Valid
Range
Change over during
execution
Meaning
Enable BOOL - TRUE/
FALSE
Subscribe to a Topic
on a MQTT server.
Once subscribed,
setting to FALSE it
unsusbscribes.
Topic (*13) STRING[128] - - Topic to be
subscribed. Note the
Topic is case sensitive
QoS Byte 0 0,1,2 Maximum Quality of
service granted for
that subscription
(*13) The use of Wilcard “#” is supported ( only at the end of the topic)
19
6.4. Output Variables
Variable Name Data Type Comment
Subscribed BOOL TRUE when subscribed to a Topic
Done BOOL TRUE each time the value is updated.
On a rising edge, the information updated will appear on the
Message output (STRING)
Busy BOOL TRUE during execution.
When [Error] changes to TRUE, Busy becomes FALSE.
Busy is FALSE during non-execution status.
PacketID UINT Shows the subscribe PacketID
Error BOOL TRUE if an error occurs.
ErrorID WORD Contains the error code when an error occurs. (*14)
#0000 is the initial value and indicated as normal end.
ErrorIDEx DWORD Contains the error code when an error occurs. . (*14)
#00000000 is the initial value and indicates a normal end.
Size UINT Size of the received message
(*14) Refer to Troubleshooting for details.
6.5. In-Out Variables
Variable Name Data Type Initial
Value
Valid
Range
Change over during
execution(Enable=TRUE)
Comment
Buffer MQTT/ClientBuffer - - MQTT client
data buffer
Message Array[0..64999] of
BYTE (*15)
It returns the
Message
payload, without
the subscription
topic
RcvTopic STRING[128] (*15) It returns the
received topic
(*15) Maximum size.
20
7. MQTTPing:
7.1. FB Layout
7.2. Function This FB sends periodically a PINGREQ command to the server and waits to a PINGRESP from server. Use this function to check the server availability.
7.3. Input Variables
Variable Name Data Type Initial Value Valid
Range
Change over during
execution
Meaning
Enable BOOL - TRUE/ FALSE yes Enables / disables the
function
PingTime UINT - 500..65535 ms NO Time period at wich
the client sends a
PINGREQ comand
TimeOut UINT 0 50..65535 ms NO Time to wait to a
PINGRESP from
Server
21
7.4. Output Variables
Variable Name Data Type Comment
PingStatus BOOL TRUE when subscribed to a Topic
Response BOOL TRUE each time the value is updated.
On a rising edge, the information updated will appear on the
Message output (STRING)
Busy BOOL TRUE during execution.
When [Error] changes to TRUE, Busy becomes FALSE.
Busy is FALSE during non-execution status.
PingRESP UINT Shows the last subscribe status
Error BOOL TRUE if an error occurs.
ErrorID WORD Contains the error code when an error occurs. (*16)
#0000 is the initial value and indicated as normal end.
ErrorIDEx DWORD Contains the error code when an error occurs. (*16)
#00000000 is the initial value and indicates a normal end.
(*16) Refer to Troubleshooting for details.
7.5. In-Out Variables
Variable Name Data Type Initial
Value
Valid
Range
Change over during
execution(Enable=TRUE)
Comment
Buffer MQTT/ClientBuffer - - MQTT client
data buffer
22
8. Parameter Description in detail
8.1. MQTTClient parameters
8.1.1. Host and ServerPort : The MQTTConnect stablish a connection between the controller and the MQTT server.
To define a connection, a Host name / host IP and a port connection has to be defined according the
following table:
Examples: We want to connect to a remote MQTT server, hosted on m21.cloudmqtt.com
Input Parameter If Host server is set by name If Host server is set by IP Note
Host ‘m24.Mymqttserver.com’ (*9) ‘82.251.42.52’ (*9) (*11)
ServerPort 12254 12254 (*10)
(*9) It can be set as host name or host IP, either.
(*10) The server port is supplied by your MQTT Server connection.
(*11) If a host name is specified, DNS server must be used and configured on TCP/IP controller
settings or on the router DNS settings.
8.1.2. ClientID: This is the name which the device will be known when connects to the MQTT server. You can use any
alphanumeric ID, however depending of the server service, you should use an ID provided by the
server service after register a device .
If you’re not prompted to register a device on the server service, you can use any client ID name.
Be sure your ClientID name is not already in use by another client session in your MQTT server. If a
session with same ClientID is detected , your connection will be rejected.
8.1.3. KeepAlive: The Keepalive parameter is a time (in seconds) agreed between a MQTT client and the MQTT server
before the server closes the client connection, if there isn’t any Publish / subscribe queries.
After the server disconnects the client, you should reconnect again.
The timeout counter is reset on the server side each time the client triggers a new query.
If a client does not publish / subscribe for a long time, alternatively is recommended to perform a PING
command regularly to renew the time out counter ( see MQTTPing FB)
8.1.4. CleanSession: This flag is to notify to server that the messages stored at server in QoS1( QoS2) that are not delivered
may be rejected, when the client connects again to server.
It can avoid that older undelivered messages arrives to subscribers if aren’t needed anymore.
Set as TRUE ( default ) if you don’t want to store undelivered messages at server.
Set as FALSE to store undelivered messages at the server. Depending the server configuration, the
undelivered messages may expire after a time if those aren’t delivered on time.
23
The servers usually has a limited capacity of undelivered messages, and a delivery expiration
( optionally) ; so use it carefully to not flood the server with undelivered messages, or if you want to
avoid to receive a bunch of old undelivered messages from server , once you resume the connection.
8.1.5. WillCnfg: This structure defines the ‘Last Will” topic and message to be delivered to the subscribers in case the
connection is lost or is disconnected.
You can use this feature to notify to the subscribers that a publisher is disconnected.
5.1.5.1. WillTopic and WillMsg:
It has the same configuration as a normal Topic + Message . Topic is the WillTopic parameter and
message is set at the WillMsg parameter on the structure. This is called the ‘Last will’ message and
it will be delivered to the WillTopic subscribers when the connection expires or is lost, to notify this
situation.
If a publisher connects to the server with the last will field, the server stores the WillMsg under a
WillTopic.
When the client disconnects to the network, all the subscribers to this WillTopic will receive a
WillMsg message, as a notification of publisher disconnection.
5.1.5.2. WillFlag:
If WillFlag is used ( TRUE) the connection is stablished sending the Last Will configuration ( Topic,
message, Retain, QoS)
5.1.5.3. WillRetain:
Last value on WillMsg is retained by the MQTT server to be delivered to the WillTopic subscribers, if
WillRetain flag is TRUE. The last Will status will be notified to subscribers once those are connecting
to the server.
5.1.5.4. WillQoS
It means “Will Quality Of Service” and determines how is delivered the Will message to the subscribers,
according the values below:
24
QoS Value Meaning
0 0: At most once delivery The Will message is sent once by publisher , there isn’t confirmation from server
that it is received. A message won’t be acknowledged by the receiver or stored
and redelivered by the sender
1 1: At least one delivery When using QoS level 1, it is guaranteed that a message will be delivered at
least once to the receiver. But the message can also be delivered more than
once.
The sender will store the message until it gets an acknowledgement in form of
a PUBACK command message from the receiver.
The duplicate (DUP) flag, which is set in the case a PUBLISH is redelivered, is
only for internal purposes and won’t be processed by server or client in the case
of QoS 1. The receiver will send a PUBACK regardless of the DUP flag.
2 2: Exactly once delivery When using QoS level 2, it is guaranteed that a message will be delivered at
most once to the receiver.
The sender will store the message until it gets an acknowledgement in form of
a PUBCOMP command message from the receiver.
The duplicate (DUP) flag, which is set in the case a PUBLISH is redelivered, is
only for internal purposes and won’t be processed by server or client in the case
of QoS 1. The receiver will send a PUBACK regardless of the DUP flag.
Note the resend feature is not automatic at version 0.45.00 . It will be available at further
versions. So, in this version, if a resend is needed, has to be managed by user program.
8.1.6. UserLogin: Depends of the server service, you can be prompted to logging before connect to the MQTTServer.
These credentials are supplied by the server service, and sometimes only consists of a User ID unique
token (without password).
If the User / password is omitted, the MQTT client logs without user.
5.1.5.5. User:
The user name agreed on the MQTT server, ( alphanumeric characters only ).
5.1.5.6. Password:
If required by the server, an password ( alphanumeric characters only )
25
8.1.7. BufferIn: This is a structure that stores the outgoing and the incoming messages, states, etc. from the
connection. It is used as a backplane channel for messages and status between MQTT client and the
Pub/Sub instances. User program shouldn’t modify this variable.
The structure description is not covered on this manual.
8.2. MQTTPublish / MQTTPublishArr parameters
8.2.1. Topic: This is the main subject that will be add to the published message as a reference .
All subscribers to this topic will receive the message published by the MQTTPublish instance.
Example:
In this case , any message under /Tank/Temperature/ will be posted on the MQTT server, and
delivered to the subscribers to /Tank/Temperature/ from the server.
As you see, a topic may contain Subtopics. It is recommended to separate them by “/”.
Topic parameter supports alphanumeric data, but not wildcards such # or $.
26
8.2.2. Message: This is the information to be published under the Topic parameter.
It could contain alphanumeric data only.
8.2.3. QoS: This is the quality of service for this message . The message is delivered according the table below:
QoS Value Meaning
0 0: At most once delivery The publish message is sent once by publisher , there isn’t confirmation from
server that it is received. A message won’t be acknowledged by the receiver or
stored and redelivered by the sender
1 1: At least one delivery When using QoS level 1, it is guaranteed that a message will be delivered at
least once to the receiver. But the message can also be delivered more than
once.
The sender will store the message until it gets an acknowledgement in form of
a PUBACK command message from the receiver.
The duplicate (DUP) flag, which is set in the case a PUBLISH is redelivered, is
only for internal purposes and won’t be processed by server or client in the case
of QoS 1. The receiver will send a PUBACK regardless of the DUP flag.
2 2: Exactly once delivery When using QoS level 2, it is guaranteed that a message will be delivered at
most once to the receiver.
The sender will store the message until it gets an acknowledgement in form of
a PUBCOMP command message from the receiver.
The duplicate (DUP) flag, which is set in the case a PUBLISH is redelivered, is
only for internal purposes and won’t be processed by server or client in the case
of QoS 1. The receiver will send a PUBACK regardless of the DUP flag.
8.2.4. Retained: The retained flag is used to the Publisher to notify to the Server that it has to store the last published
message and its QoS , in order to be delivered in the future to the subscribers that match with the
topic published.
Hence, when a new subscription is stablished, the last retained message is delivered to the
subscribers as a last valid message. To reset a retained message, you should publish an empty payload message with Retained = TRUE.
8.2.5. DUP: It is a flag that is used to the Publisher to notify the message published is duplicated , so it has been
sent before. The flag has to be set from the user application program to notify to the server it is a
duplicated message.
8.2.6. PacketID: This outputs shows the current packet ID that is assigned to the Published message. The packet ID
assignation is automatically managed by the MQTTClient, for QoS1 and QoS2.
8.2.7. Size: It shows the length of the message sent by the MQTTPublish instance. For debugging purposes only.
27
8.2.8. BufferIn: This is a structure that stores the outgoing and the incoming messages, states, etc. from the
connection. The description is not covered on this manual.
Use the same IN/OUT variable used for BufferIn at the MQTTClient.
8.3. MQTTSubscribe/ MQTTSubscribeArr Parameters
A MQTTClient can publish topics by using MQTTPublish instances but can also subscribe to other
topics, by using MQTTSubscribe instances.
8.3.1. Topic: It sets the topic to be subscribed. The MQTTSubscribe FB subscribe to a single topic.
The data specified here can contain SubTopics, usually separated by “/”.
It is possible to subscribe by using the wildcard ‘#’ at the end of the topic.
NOTE: Currently the subscription topic doesn’t support wildcards such’$’ .
8.3.2. RcvTopic: Shows the received topic. It is specially useful if the Subscribed Topic contains the wildcard ‘#’. In this
case it will show the Topic received that matches before the wildcard.
8.3.3. QoS: This is the minimum QoS requested by the subscription. However the MQTT server may grant a
minimum QoS for that subscription. Qos0, 1, and 2 is supported.
Example: If a message is received in Qos1, but the subscription is at QoS0, the Subscriber won’t
acknowledge by a PUBACK ( QoS 0 gantred)
8.3.4. Subscribed: This output signals the subscription has been processed successfully. Then, messages will be
received at the Message output, each time the Done makes a transition from OFF to ON.
If the Enable output goes to OFF once subscribed, a UNSUBSCRIBE command is sent from client to
server for the subscription topic.
8.3.5. Size: This is the size of the message received. The maximum size supported 1986 for a STRING type or
65000 for a ByteArray .
8.3.6. Message: It contains the message received. A new message may be received during the subscription, in this
case the Done output makes a new transition from OFF to ON to signal the message is new. During
the message reception/ processing by the subscriber, the Busy will be TRUE. The maximum size
supported is STRING[1986] for MQTTSubscribe and ByteArray[65000] for MQTTSubscribeArr.
In case of receiving bigger size, the Message won’t be updated ( and may produce error)
28
8.4. MQTTPing Parameters
8.4.1. PingTime: This is the period at which the MQTTClient sends a PINGREQ message in order to notify to MQTT
server the ‘alive state’. When the server receives a PINGREQ message, it sends a PINGRESP and
resets the elapsed time to keepalive, so the connection is maintained.
The PingTime setting is in milliseconds
8.4.2. TimeOut: After sending a PING from the client, if there is no reply from server within the TimeOut time, it may
notify the server is down or a connection is lost. In this case the PingStatus will be FALSE.
In such case, is advised to perform a MQTTClient reconnection , because probably the server is down
or network is unavailable.
8.4.3. PingStatus: This output shows the status of the PINGREQ answer, if the answer arrived in the before the TimeOut
setting, will signal TRUE; otherwise if the answer didn’t arrive at time will signal FALSE.
8.4.4. Busy: This output remains TRUE while the MQTTPing function is on execution, awaiting for a PINGRESP
reply from server.
8.4.5. PingRESP: When a PINGRESP is received from server, the output PingRESP will be true for a single controller
task period cycle.
8.4.6. Response: It shows the response time in milliseconds for a PINGREQ. So it can be used to measure the
latency/response time from the server.
8.4.7. Error: Notifies the error state for the function
8.4.8. ErrorID: Identifies the error state source:
16#2800: Error code from Controller: Check ErrorIDEx from Troubleshooter/Error code at Sysmac manual.
16#2801: Error code from library: Check ErrorIDEx from this manual.
8.4.9. ErrorIDEx:
Extended Error code .
Check error code list from Sysmac Troubleshooter / manuals if the ErrorID is 2800.
Check error code list from this manual if the ErrorID is 2801.
29
9. Application Examples
9.1. Scenario
From a machine we want to publish some data in JSON to an external cloud MQTT server service .
The data is coded in JSON following the structure below:
Topic Variables
MachineData/ TotalProduction, Defects, Production_H, ErrorStop, UserStop, InOperation, LineSpeed,
MachineCycle
OEE/ Availability, Quality, Performance, OEE
MachineEvents/ ErrorStop, time stamp
UserStop, time stamp
InOperation, time stamp
In addition, the machine has to Subscribe to topics published from another station, that publishes
to same server:
Topic Variables
Meteo/temperature strTemperature
Meteo/Humidity strHumidity
To generate the JSON we will find very helpful the JSONv0.55 library.slr file added to Sysmac Studio.
30
9.1. Libraries to add to the project
Current Library version:
MQTT 0.0.45b14
JSON 0.0.56.slr ( optional)
9.2. MQTT server account
In our case we have an account at cloudmqtt.com ™, that offers several MQTTServer hosting plans
starting from free.
Our service provider, after registering , it will provide some connection details:
We can see here the Server(Host) to connect, the User , the Password and the port.
9.3. Connection Configuration
Enter the IP address configuration according the network and the gateway according the router.
31
9.4. Client Configuration
Create a MQTTClient instance, providing the connections details provided by your MQTT server
account:
Enter a ClientID, in our case we identify this client as ‘ATCE_machineOEE’
Test the connection, if the connection is ok the FB will show “Connected”:
32
9.5. JSON data codification
By using the JSON library, we code the variable in JSON to be entered as a Message to publish.
In the following example, we build the JSON structure on the string “txtJSON_MachineData”. This is
the one that is used as a message:
Topic Variable names at program Name at JSON key
MachineData/ TotalProduction,
Defects,
Production_H,
ErrorStop,
UserStop,
InOperation,
LineSpeed,
MachineCycle
‘TotalProduction’
‘Defects’
‘Production_H’
‘ErrorStop’
‘UserStop’
InOperation’
‘LineSpeed’
‘MachineCycle’
OEE/ Availability,
Quality,
Performance,
OEE
‘Availability’
‘Quality’
‘Performance’
‘OEE’
MachineEvents/ ErrorStop+ time stamp
UserStop+ time stamp
InOperation+ time stamp
‘ErrorStop’
‘UserStop’
‘InOperation’
Same for the OEE/:
And for the MachineEvents/:
( Example for ErrorStop variable)
33
9.6. Publish
One the MQTTClient is connected, we send every second the data from the machine , by the coded
JSON strings above:
Topic ‘MachineData/’ : JSON data on ‘txtJSON_machineData’
Topic ‘OEE/’ : JSON data on ‘txtJSON_OEE’
Topic ‘MachineEvents/’ : JSON data on ‘txtJSON_Events’
Publishing ‘MachineData/’ and ‘OEE/’ :
Publishing ‘MachineEvents/’:
34
9.7. Subscribe
For the subscribe, we call two instances of MQTTSubscribe FBs, each one.
9.1. Ping
By using the MQTTPing , we supervise the connection to the server and in case of no published data
for a long time, we reset the keepalive timer, avoiding then a keepalive disconnection by Time out.
In our case we send a PINGREQ every 30s , if there is no answer for 5s we consider the connection
dropped.
35
9.2. Testing , monitoring and Debugging tools
9.2.1. Tools Testing at server :
If the messages goes to the MQTTserver successfully, you should see them in the console:
9.2.2. Testing at Sysmac Program :
Check the connection status at client MQTTClient and by the MQTTPing instance.
36
On publish, the .Done output at the MQTTPublish instances will notice the data has been
published.
For the Subscribers, we have to see if it is subscribed and check the data on
MQTTSubscribe.message:
37
10. Resources and tools for MQTT
10.1. MQTT servers:
Recommended MQTT servers:
Mosquitto™:
https://mosquitto.org/
VerneMQ™:
https://vernemq.com/
EMQX™:
https://www.emqx.io/
Those are popular / free MQTT servers that can run in Windows™ or Linux.
There are many others, those are just an example ( tested with the library) .
10.1. Testing on Server ( Mosquito™):
If your server is Mosquitto™ , you can enable the session in verbose mode, adding the -v attribute.
38
10.2. Software tools for testing :
Some tools MQTT Client / development tools:
MQTTfx™
http://www.mqttfx.org/
mqtt-spy™:
http://kamilfb.github.io/mqtt-spy/
MQTTLens™:
it is an extension for Chrome™ that acts as a MQTT client.
39
MQTTool™
This App for iOS allow to connect to server and check the for subscribed topics and publish new topics, for
testing.
You can use these tools to confirm the correct publication/ subscription from the MQTT clients.
10.3. Testing from a dashboard:
Many Cloud services that includes MQTT servers, offers to the possibility to link to Dashboard applications.
In the example, we use a dashboard from Freeboard.io ™. It is a Dashboard provider that offers evaluation
starting plans for free.
https://freeboard.io
40
10.3.1. Testing from Node-RED™:
Node-RED™ runs from Node.JS runtime .
Allows a graphical flow programming based in JavaScript, with hundreds of collaborative flows and nodes
including MQTTClient and a rich and configurable dashboard features.
One of the nicest feature is the node-red-dashboard that can be installed from the npn console or directly
from Node-RED palette.
Needs to install Node.JS runtime previously to use the NODE-RED™ extension.
https://nodejs.org/
More information at:
https://nodered.org/
41
11. Troubleshooting (Response Codes and Corrections)
11.1. ErrorID codes According [ErrorID] code, the origin of an error can be determined:
Exit Code Status Cause Correction
#0000 Normal end (Normal) - -
#2800 Error end (Error) An error occurred in the standard instruction that is used in the FB.
Check the last 4 digits of the error code that is stored in [ErrorIDEx] and follow the instructions in the Controller manuals to take measures.
#2801 Error end (Error) An error occurred in the FB. Check the error code stored in [ErrorIDEx].
11.2. Error ID Extended codes
By Using [ErrorIDEx] code, the cause of an error can be determined, when [ErrorID] is 16#2801.
Exit Code Cause Correction
00009001
The MQTT server closed the
connection
The connection might be closed due to a KeepAlive time
expiration.
The message has been rejected and as a consequence the port
is closed.
00009101 ClientID is Empty Enter the ClientID at MQTTClient
00009102 Will Topic empty Enter the WillTopic at MQTTClient.WillCfg
00009103 Will QoS out of range Enter QoS 0,1 or 2
00009130 PING time too short Set a PING Time > 500
00009131 PING TimeOut too short Set a PING timeout > 50
00009132 TimeOut >= PingTime Set a PING timeout < PingTime
00009140 PINGRESP answer not in time PINGRESP Timeout. Server could be unavailable.
If server is available, increase the PING timeout value
00009201 Topic empty at MQTTPublish
instance
Enter a valid Topic
00009202
Message empty at MQTTPublish
instance, with Retain=FALSE
Enter a valid Message if Retain=FALSE.
If Retain=TRUE, you can send an empty message to reset
Retain message.
00009203 QoS not valid on Publish Instance Enter QoS 0,1 or 2
00009204 Message size exceeded the
maximum size of 65000 bytes
Enter a message size equal or less than 65000 Bytes at
MQTTPublishArr.MsgSize.
00009211
MQTTPublish not possible due to a
MQTTClient error
MqttClient is on Error State.
Check and apply corrections to fix the error on the MqttClient
instance. Then try to publish/Subscribe again.
42
Exit Code Cause Correction
00009213 PING request had no PINGREQ
because because Client is in error
Check the Client error cause. Correct at Client side.
00009215 DISCONNECT command not
processed because Client is in error
Check the Client error cause. Correct at Client side.
00009220 MQTTClient not connected Check Connection settings
00009301 Topic empty at MQTTSubscribe
instance
Enter a valid Topic
00009302 QoS not valid on Subscribe instance Enter QoS 0 ,1 or 2
0000F001
MQTT Client found a server
command not supported
Check if the version of MQTT protocol is 3.1.1
It could check if QoS2 is used. Library currently doesn’t support
QoS2.
0000FF01
MQTT Connection refused:
unacceptable protocol version from
Server
Check if the server accepts MQTT v 3.1.1
0000FF02 Connection refused: identifier
rejected
Client ID is correct , but connection not allowed by the server.
Check login rules at the server side.
0000FF03 Connection refused: Server
unavailable
Connection is made but MQTT server is unavailable.
Restart MQTT server
0000FF04 Connection refused: invalid login The data in the user login and password is not valid
0000FF05 Connection refused: not authorized The client connection is not authorized to connect.
Check login rules at the server side.