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.