IoT Tutorial on how to establish bidirectional MQTT communication on ESP32

This is a project targeted at educating the ‘maker community’ on how to use the MQTT protocol for bidirectional communication with the ESP32 to publish messages and subscribe to topics. The code and underlying setup also can also be used as a boilerplate for more professional solutions since it is robust and compatible with a range of hardware systems.

Project Description - Setting up MQTT for ESP32

For this project we are using two TTGO T-Display devices from LilyGO communication over MQTT to eachother. The device we use is a $10 microcontroller based on an ESP32 with a built-in 1.14 inch TFT display. It has a USB-C connection for power and built-in USB to serial converter that makes it easy to program. The board has built-in Wi-Fi and Bluetooth, an reset button, and two additional user defined buttons that we will use for user input and configuration. A range of GPIO, analog and PWM pins are available for extended connectivity, although they are not used in this project.

"MQTT is a Client Server publish/subscribe messaging transport protocol. It is light weight, open, simple, and designed so as to be easy to implement. These characteristics make it ideal for use in many situations, including constrained environments such as for communication in Machine to Machine (M2M) and Internet of Things (IoT) contexts where a small code footprint is required and/or network bandwidth is at a premium."
Citation from the official MQTT 3.1.1 specification

The Wi-Fi along with the I/O capabilities make the TTgo board very useful for our goals to build a simple but fully functional MQTT capable device that both can communicate with Publish/Subscribe to user defined topics on a configurable broker platform. The demo code will publish a certain payload whenever the lower MQTT button is pressed while the display will continuously show the incoming messages on a subscribed topic.

The upper button (long press) is used to activate the device as a Wi-FiAccess Point for the initial configuration. The display will show Wi-Fi SSID information so that you can connect a mobile phone over Wi-Fi. Once connected, a menu is displayed where all the Wi-Fi and MQTT settings can be made from a browser interface. After a restart, the TTGo device will use all the set parameters and connect to the selected Wi-Fi network and MQTT broker.

The Code

The repository for the code can be found here. The setup follows the usual Arduino-like structure in the main MQTTGov2.ino file. The setup function configures the device for startup by checking and loading the SPI memory where the setup (Wi-Fi and MQTT) parameters are stored. It furthermore sets the buttons and backlight I/O, displays the logo, connects to Wi-Fi and to the MQTT broker. With the mqtt.onMessage (MQTT_messageReceived), a callback routine is set for incoming subscribed MQTT messages.

The main infinite loop periodically sends a keep-alive MQTT message and checks the buttons. If one is pressed the appropriate routine (Publish MQTT or SetUp device) is called.

Usage

Programming the Module

Connect the TTgo modules to your computer using a suitable USB-C cables. The repository for the code can be found here.

This repository uses Platform.IO as a compile and programming platform. Please install it before cloning the repository. When cloned cd into it and execute: ‘pio run’. As a result all the necessary support libraries will be downloaded, the code will be compiled and linked, and the resulting code will be automatically uploaded to the module. Repeat this for all the modules you have.

git clone https://github.com/hivemq/MQTTgo-v2 cd MQTTgo-v2 /Pio run

Configuring the module

After (manual, use reset button) reboot, the HiveMQ logo will be shown and the module will try to connect to the Wi-Fi network. In the case of a new module, no settings are present and the module will automatically go into Wi-fi config mode. If this is not the case, please press and hold the Wi-Fi cfg button.

Follow the instructions on the screen that instruct you to connect a mobile phone (or computer) to the SSID that is indicated. After connecting, a setup screen will display, as shown in Figure 1.

MQTT Settings:

In the Broker line you will define the MQTT broker system that is used. The default is broker.hivemq.com. Please select the same broker if you want to communicate between devices.

In the Publish Topic you will define the Topic under which the payload, generated by a button press, is being published.

In the Subscribe field you will define to which subject the device will subscribe and messages that are subsequently displayed in the Oled display.

The payload field describes the actual payload that is published when the MQTT button is pressed. If a curly bracket sequence is present {} this will be replaced by the device’s module name for unique payload sender identification.

The keep alive interval defines the time between the devices I’m still alive messages that are automatically being published.

The default language is Dutch; users can pick a different language using the Wi-Fi configuration portal. To change the default setting to English, change #define LANGUAGE “nl” to #define LANGUAGE “en” in the source code.

Please save by hitting the save button and then restart the device by the ‘restart device’ button on the top.

Demo Setup

We think the best educational setup is to pair groups of two (devices) and set up a mutual, crosswise MQTT communication channel. In this case the payload, generated by pressing the MQTT button on one device (left), will generate an incoming message on the display of the second (Right) device. If this is configured crosswise this also will be the case vice versa.

In order to set up the above, use a publish topic on one device and subscribe to this both on the other devices as on the software MQTT client on a computer. Please be sure to use a shared broker system. A public broker such as ‘broker.hivemq.com’ can be used perfectly for this purpose. And please feel free to define other, more original topic names.

A MQTT client, running on a separate Windows of Mac computer, subscribing to both published topics (preferably via a wildcard) will clearly show the interaction of MQTT messages. For this you can use the excellent HiveMQ edition of MQTT.fx.

Please see the overview layout for a graphic explanation

In the picture below you can see the expected results. Both devices show the other’s payload after the button is pressed on both devices…

… and the software client shows all messages.

Conclusion

The TTgo devices in combination with the HiveMQ Broker form an excellent platform to showcase the effectiveness and ease of implementation of a powerful IoT messaging platform. The communication is robust and easy to implement in more complex situations where the module can control actual physical devices.

The current setup is easily extendable by adding security in the form of a TLS based MQTT connection to the broker.

The public broker can be replaced by your own (cloud) hosted solutions that offer the privacy and security that might be needed in your situation. Please see the getting started section of the HiveMQ website for more information.

If you have questions or comments, or want to share your results from using this tutorial please let me know.

About Kamiel Straatman

Kamiel is part of Solutions Engineering team at HiveMQ. Based out of the Netherlands, Kamiel is an IoT enthusiast with many years of experience working in the data center domain and Azure & AWS cloud architectures.

Contact Kamiel