MQTT Setup
Technical Note 5111
Applicable Model(s)
cMT Series
Graphic HMIs
Title
MQTT Setup
Date
11/09/2022
Rev
02
P/N
0907-5111
Summary
This tech note walks through the steps necessary to configure an HMI as an edge gateway for an MQTT network. There are 4 main tasks that will be addressed in this tech note:
- An EBPro project will be created that enables the HMI to act as an MQTT publisher
- HMI memory addresses will be mapped to MQTT topics
- The project will be run in the EBPro Online Simulation mode on a PC and publish data to a public test broker
- MQTT Explorer will be used to subscribe to topics and receive data from the HMI application
What You Will Need
- The most recent version of EBPro, available for download in our Software & Upgrades page.
- Basic knowledge of using EBPro
- MQTT client software. This guide will use MQTT Explorer, which is available for download here.
- A Windows PC
An MQTT sample project can be downloaded from our Sample Projects page.
Step 1 – Project Setup
This step will create an HMI screen with some numeric inputs to use later:
1.
Start EBPro and create a new project. Any model number can be selected.
2.
Select Object…Numeric from the menu bar.
3.
Under Read address select Local HMI for the PLC
4.
Select LW from the address type dropdown list, and enter 0 in the address field (this is the default).
5.
Click OK to place this object on the screen
6.
Make five copies of this numeric object and configure them with the following addresses:
| Address |
|---|
| LW-0 (already done) |
| LW-1 |
| LW-2 |
| LW-10 |
| LW-11 |
| LW-12 |
7.
In Step 2 the addresses used above are going to be assigned to MQTT topics. You will add some labels to the screen and organize the inputs under the topic they will be assigned to so that it is easy to tell which address is assigned to which topic:
8.
Create five text objects (Under Draw…Text from the menu bar) to create the following labels:
| Label |
| Topic: <name>/machineOne/stats |
| Topic: <name>/machineOne/temp |
| Topic: <name>/machineTwo/stats |
| Topic: <name>/machineTwo/temp |
NOTE: replace <name> with a unique name of your own choosing to use for all topics. Our sample uses HMI_MapleTest.
9.
Arrange the labels on the screen so that the numeric inputs are placed under the label for the topic they will be assigned to as follows:
| Label | Numeric Input Address |
|---|---|
| Topic: <name>/machineOne/stats | LW-0 |
| LW-1 | |
| Topic: <name>/machineOne/temp | LW-2 |
| Topic: <name>/machineTwo/stats | LW-10 |
| LW-11 | |
| Topic: <name>/machineTwo/temp | LW-12 |
10.
The screen should look something like this:
11.
Now add the following labels to the left of each numeric object so that it is clear what the number represents:
| Numeric Input Address | Label |
|---|---|
| LW-0 | TankLevel (LW – 0): |
| LW-1 | Speed (LW – 1): |
| LW-2 | Temp (LW – 2): |
| LW-10 | TankLevel (LW – 10): |
| LW-11 | Speed (LW – 11): |
| LW-12 | Temp (LW – 12): |
12.
The screen should now look something like this:
13.
That completes the screen set up. The screen shot below shows some more optional labels and label formatting that can be added to better organize the screen:
Step 2 – MQTT Object Setup
Next you will add an MQTT object to the project, configure the broker settings and configure the topics.
The settings below will configure the application to publish to a public broker at broker.hivemq.com. There are several public brokers that could be used to complete this project. Another, which is hosted by the Eclipse MosquittoTM project, is test.mosquitto.org. These brokers are public and should only be used for testing purposes.
1.
Select IIoT/Energy >> MQTT from the menu bar.
2.
Click Enable in the MQTT window that is displayed.
For more information on these settings refer to the MQTT chapter in the EBPro Programming Manual.
3.
Check Use Domain Name and enter the broker address.
4.
Set the port to 1883.
5.
Make sure the authentication box is not checked.
6.
Click on the Address tab. Change the Status address from LW – 0 to LW – 100
7.
Click OK to accept the settings and return to the MQTT dialog.
Step 3 – MQTT Topic Configuration
1.
To create topics and assign memory addresses to them, first click on New… in the MQTT dialog window.
2.
- Enter m1stats for the Nickname of this topic.
- Enter <name>/machineOne/stats under Topic. Replace <name> with a unique identifier of your own choosing.
- Leave the Sending mode to Address (Auto.)and check the Value-trigger-based checkbox.
3.
To assign an address to your topic, click on the Address tab of the MQTT Topic window.
4.
Click on New to assign a new address.
5.
Enter TankLevel for the Name.
6.
Set the Type to Word
7.
Select Local HMI, LW and enter 0 for the address fields.
8.
Click OK to add the address to the topic.
9.
This topic will have two addresses. Click new again and enter the following values to configure the second address:
Name: Speed
Type: Word
Address: Local HMI, LW-1
10.
The address tab for this topic should now look like this:
11.
Click OK and the topic should appear in the topic list.
12.
Repeat this process to create the topics and addresses shown below:
| Nickname | Topic | Address Name | Address |
|---|---|---|---|
| m1stats | <name>/machineOne/stats | TankLevel | LW – 0 |
| Speed | LW – 1 | ||
| m1temp | <name>/machineOne/temp | Temp | LW – 2 |
| m2stats | <name>/machineTwo/stats | TankLevel | LW – 10 |
| Speed | LW – 11 | ||
| m2temp | <name>/machineTwo/temp | Temp | LW – 12 |
NOTE: Replace <name> with a unique name of your own choosing. The first topic shown was created in the preceding steps.
13.
The Topic list should now contain four topics:
14.
When everything looks correct click Exit to return to the development screen.
15.
Select file > Save from the menu bar then Tools > Compile to build an executable version of the project that can be run in the simulator.
16.
You have completed the HMI project set up. Now you can run the project in the simulator and start receiving data with an MQTT subscriber application.
Step 4 – Testing
This step will use MQTT Explorer for the subscriber, if you don’t have an MQTT client download and install MQTT Explorer before proceeding.
1.
Start the EBPro Online Simulation by selecting Project…Online Simulation from the menu bar. This will start the publisher on the PC. Leave this simulator running.
2.
Start MQTT Explorer. Click the yellow “+” sign to add a connection. We are going to use the Mosquitto Test broker:
3.
Enter a name for the connection.
4.
Leave Validate certificate active and Encryption (tls) inactive.
5.
Enter test.mosquitto.org as the Host address. Use 1883 for the port number.
6.
Click Save and then click connect.
7.
A list of topics will begin to populate from all of the users currently publishing to this test broker:
8.
To narrow down the view enter the unique topic identifier currently being used in your HMI project. For our sample, this would be HMI_MapleTest.
9.
The list should now only display the topics that were created in the HMI project that is currently running in Online Simulation mode.
10.
Congratulations, the HMI project is configured as a MQTT edge gateway.
The packet payload delivered to the broker is in Java Script Object Notation (JSON).
The data in the “d” object are the data points added to the topic in EBPro, based on the names given in the address tab of the MQTT configuration window.
The data in the “ts” object is a combined date and time timestamp based on the HMI local time when the message was sent.
Once your data is in the broker, you can subscribe to it from several software packages, or your own custom application. This data can be delivered to your entire team without overloading the control network with communications requests.
Troubleshooting Note – If you don’t get any messages from the HMI project try the following:
- Make sure the Client ID is %2 (for random), or something unique,in the MQTT object settings in EBPro. Recompile the project and relaunch the simulator.
- Double check that the MQTT server is active and that the current Domain Name/IP address for the server was entered in the MQTT object.