Home / Tutorials / ESP8266 Tutorial / NodeMCU MQTT Tutorial
NodeMCU Webserver

NodeMCU MQTT Tutorial

So far, we've been using HTTP in our NodeMCU web servers and while it works, the protocol is not really the best way for sending and receiving small-sized data for IoT applications. In this tutorial, I will introduce you to NodeMCU MQTT.

What is MQTT?

MQTT (Message Queue Telemetry Transport) is a publish-subscribe messaging protocol widely used in IoT applications. This protocol is designed for data transfer between devices with limited network bandwidth and power. Thus, it is highly recommended for microcontroller projects that sends data over the internet. In this tutorial, I will show you how to use the MQTT protocol in sending data from the NodeMCU to any web page.

In our previous NodeMCU tutorials, we send data to web servers thru HTTP (Hyper Text Transfer Protocol), which is the de facto standard of how web pages are acquired by web browsers. However, HTTP is document-centric which consumes a lot of network bandwidth. MQTT, in contrast, transfers data as a byte array which is more lightweight. HTTP is also a more sophisticated protocol that can drain more power from microcontrollers and embedded computers.

How MQTT Works

Communication through MQTT needs a "broker" which is responsible for distributing messages to clients based on a certain "topic". A publisher sends data to the broker while subscribers reads data from the broker:

Image result for MQTT

You can create your own MQTT broker through apps like mosquitto on a Raspberry Pi. You can also use web-based brokers like hiveMQ, Adafruit IO and shiftr.io.  For this tutorial, we will be using  shiftr.io.

A typical MQTT connection needs a host name, port, client ID, username and password. Once these are specified, you can subscribe to a topic and start receiving messages on that topic. You can also publish messages on that topic. Unlike HTTP which requires requests to be continually made in order to continually receive a response, the data will continue to go through the MQTT channel until you unsubcribe and disconnect.

The MQTT protocol is used on top of TCP/IP which means you still need an Internet connection. This tutorial uses NodeMCU which relies on the ESP8266 WiFi library. However, you can also use other devices (Arduino UNO, Arduino Yun, Arduino Ethernet) and use the appropriate libraries to create an Internet connection.

Building the NodeMCU MQTT Sketch

You'll be needing the Arduino MQTT library which can be downloaded in 256dpi's repository.  

Once this library is installed on the Arduino IDE, you can now add the <MQQTClient.h> header on your sketch.

The Arduino MQTT library is not complicated and uses only a few functions to establish MQTT connection. The bare minimum are:

We will start with a simple sketch that publishes sensor readings to shiftr.io's neat web interface. Shiftr.io has a "try" channel that you can use without needing to create an account:

Here we see the different subscriber nodes (light grey) connected to the broker (big circle). The name of these nodes are their client ID. The dark grey nodes are the topics. If a subscriber is connected to a topic then it will appear in the diagram as a light grey node. Here a subscriber with client ID javascript is connected to the nodemcu/photocell topic:

The try channel uses “try” as both the username and password. To connect to this channel we use the following function:

For example, if we want to publish a message to the topic photocell, which is under nodemcu, then the following function is used:
You see that the message is shown on the upper left side of the interface.

Here’s a full code that displays sensor readings to the topic nodemcu/photocell on the same try channel:

Upload this sketch to your NodeMCU and open serial monitor. If successful, you should see this message:

Now go to https://shiftr.io/try#terminal to see the dynamic sensor data being displayed.

Another NodeMCU as MQTT Client

How do you read the data you just sent? You can use an MQTT client which can be another NodeMCU, a smartphone or a web browser.

Using another NodeMCU, you can modify the same NodeMCU sketch we used so that it will start accepting messages from the MQTT broker:


We removed the client.publish() part and added a messageReceived() function. The data from the topic you subscribed to will be shown on the serial monitor.

Smartphone MQTT Client

You can use free smartphone apps to get data from a MQTT topic. I used the iOS app, Mqtt which when run, asks you for the hostname, port, username and password:

After that, you have the main interface. You can subscribe to a topic on the upper half and publish a message on the lower half:

Here we see the sensor data being displayed.

Web Browser MQTT Client

To embed the sensor data to a web page, you need to invoke the mqtt.js library. Here’s an example script that you can use:

Save the script above as script.js.

Here’s a very simple HTML for displaying the data:

Save the HTML file and then open it using your web browser. You should now be able to see the data:

Hopefully, this opens the way for you to make greater IoT applications using NodeMCU or Arduino. On my next tutorial, I will show how to create your own MQTT broker with the Raspberry Pi.

Was this tutorial useful? Place a comment below!


Check Also

nodemcu ajax dynamic sensor data

Log Data with NodeMCU and Google Sheets

Most of the time, the data from a sensor in an IoT application needs to …


  1. Hi
    Why messageReceived not show any thing on serial in my code ?

  2. Luciano Damiani

    MessageReceived has not been called! There is a missimg part where to call it. I guess it will be inside the loop.

Leave a Reply

Your email address will not be published. Required fields are marked *