How to Set Up MQTT With ESP8266?

Question

Hello, I'm Ganesh. I'm building git-lrc, an AI code reviewer that runs on every commit. It is free, unlimited, and source-available on Github. Star Us to help devs discover the project. Do give it a try and share your feedback for improving the product.

In this article, I will be demonstrating how to use MQTT with a NodeMCUv2 (ESP8266) board.

What is MQTT?

MQTT is a lightweight messaging protocol for IoT devices.

It is a publish-subscribe protocol, which means that devices can publish messages to a topic and other devices can subscribe to that topic to receive messages.

Why is MQTT needed?

As the ESP8266 is a low-cost WiFi microcontroller, it can connect to a WiFi network, and it can transmit data wirelessly.

For sending data from the ESP8266 to the cloud, we need to use the MQTT protocol.

Integrate MQTT with ESP8266

Let's start with setting up mqtt with esp8266.

We use PubSubClient library for mqtt with esp8266.

Add this in platformio.ini file.

[env:nodemcuv2]
platform = espressif8266
board = nodemcuv2
framework = arduino
upload_speed = 115200
monitor_speed = 115200
lib_deps = 
    knolleary/PubSubClient @ ^2.8

Here is the simple example of MQTT with ESP8266.

#include <Arduino.h>
#include <WiFi.h>
#include <PubSubClient.h> // <-- Added MQTT library

// --- 1. WiFi Credentials ---
const char* ssid = "Add your wifi name"; 
// !! YOU MUST CHANGE THIS to your WiFi password !!
const char* password = "Add your wifi password"; 

// --- 2. MQTT Credentials ---
const char* mqtt_server = "Add your mqtt server";
const int   mqtt_port = 1883;
const char* mqtt_user = "Add your mqtt username";
const char* mqtt_pass = "Add your mqtt password";
// This is the topic we will listen to
const char* mqtt_topic_to_subscribe = "nodemcu/messages";

// --- 3. MQTT Client Objects ---
WiFiClient espClient;
PubSubClient client(espClient);


// --- 4. Function to handle incoming MQTT messages ---
void callback(char* topic, byte* payload, unsigned int length) {
    Serial.print("Message arrived [");
    Serial.print(topic);
    Serial.print("] ");

    // Print the message payload
    for (int i = 0; i < length; i++) {
        Serial.print((char)payload[i]);
    }
    Serial.println();
}

// --- 5. Function to connect to MQTT ---
void reconnect() {
    // Loop until we're reconnected
    while (!client.connected()) {
        Serial.print("Attempting MQTT connection...");
        // Attempt to connect
        if (client.connect("esp32-client-123", mqtt_user, mqtt_pass)) {
            Serial.println("connected");
            // Subscribe to the topic
            client.subscribe(mqtt_topic_to_subscribe);
            Serial.print("Subscribed to topic: ");
            Serial.println(mqtt_topic_to_subscribe);
        } else {
            Serial.print("failed, rc=");
            Serial.print(client.state());
            Serial.println(" try again in 5 seconds");
            // Wait 5 seconds before retrying
            delay(5000);
        }
    }
}

// --- 6. setup() ---
// This runs once at the beginning
void setup() {
    Serial.begin(115200);
    delay(10);

    Serial.println();
    Serial.print("Connecting to: ");
    Serial.println(ssid);

    // Start connecting to WiFi
    WiFi.begin(ssid, password);

    // Wait for the connection to complete
    while (WiFi.status() != WL_CONNECTED) {
        delay(500);
        Serial.print(".");
    }

    // If we get here, we are connected!
    Serial.println(""); // New line
    Serial.println("WiFi connected!");
    Serial.print("IP address: ");
    Serial.println(WiFi.localIP());

    // --- Add MQTT setup ---
    client.setServer(mqtt_server, mqtt_port);
    client.setCallback(callback); // Set the function to run when a message arrives
}


// --- 7. loop() ---
// This runs over and over, forever
void loop() {
    // Check if connected to MQTT, if not, reconnect
    if (!client.connected()) {
        reconnect();
    }
    // This function processes MQTT messages
    client.loop(); 

    // Small delay to keep things stable
    delay(10); 
}

Output:

Conclusion

Finally, we could set up MQTT with ESP8266.

In the next article, we will use MQTT with PainlessMesh. To send data from one ESP8266 to another ESP8266.

Any feedback or contributors are welcome! It’s online, source-available, and ready for anyone to use.
⭐ Star it on GitHub: https://github.com/HexmosTech/git-lrc