Skip to main content

​
Overview

The MQTT Manager module provides a simple interface for publishing and subscribing to MQTT topics. It handles connection management, automatic reconnection, and message callbacks.

​
Basic MQTT Connection

This example demonstrates connecting to an MQTT broker and publishing/subscribing to topics.
1

Include required libraries

Enable MQTT support and include platform-specific WiFi:
#include <Arduino.h>
#if defined(ESP8266)
  #include <ESP8266WiFi.h>
#elif defined(ESP32)
  #include <WiFi.h>
#endif

#define ENABLE_MODULE_MQTT_MANAGER
#include "Kinematrix.h"
2

Configure WiFi and MQTT

Set your WiFi credentials and MQTT broker:
const char* WIFI_SSID = "YourWiFiSSID";
const char* WIFI_PASSWORD = "YourWiFiPassword";

const char* MQTT_BROKER = "broker.hivemq.com";
const int MQTT_PORT = 1883;

const char* TOPIC_PUBLISH = "esp/test/data";
const char* TOPIC_SUBSCRIBE = "esp/test/command";
3

Create MQTT instance

Initialize the MQTT manager:
MQTTManager mqtt;
4

Define message callback

Handle incoming messages:
void onMessageReceived(char* topic, byte* payload, unsigned int length) {
  char message[length + 1];
  memcpy(message, payload, length);
  message[length] = '\0';
  
  Serial.print("Message on ");
  Serial.print(topic);
  Serial.print(": ");
  Serial.println(message);
}
5

Connect to WiFi and MQTT

Set up connections in setup():
void setup() {
  Serial.begin(115200);
  
  // Connect to WiFi
  WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.println(" connected!");
  
  // Setup MQTT
  mqtt.beginMQTT(MQTT_BROKER, MQTT_PORT);
  
  // Set unique client ID
  String clientId = "ESP_Basic_" + String(ESP.getChipId(), HEX);
  mqtt.setClientId(clientId.c_str());
  
  mqtt.setCallback(onMessageReceived);
  
  if (mqtt.connect()) {
    mqtt.subscribe(TOPIC_SUBSCRIBE);
    mqtt.publish(TOPIC_PUBLISH, "Device connected!");
  }
}
6

Maintain connection in loop

Keep MQTT alive and publish periodically:
void loop() {
  mqtt.loop();  // Must be called regularly
  
  // Publish every 5 seconds
  if (millis() - lastPublishTime >= 5000) {
    lastPublishTime = millis();
    mqtt.publish(TOPIC_PUBLISH, "Hello from ESP!");
  }
}

​
Complete Basic Example

#include <Arduino.h>
#if defined(ESP8266)
  #include <ESP8266WiFi.h>
#elif defined(ESP32)
  #include <WiFi.h>
#endif

#define ENABLE_MODULE_MQTT_MANAGER
#include "Kinematrix.h"

const char* WIFI_SSID = "YourWiFiSSID";
const char* WIFI_PASSWORD = "YourWiFiPassword";
const char* MQTT_BROKER = "broker.hivemq.com";
const int MQTT_PORT = 1883;
const char* TOPIC_PUBLISH = "esp/test/data";
const char* TOPIC_SUBSCRIBE = "esp/test/command";

MQTTManager mqtt;
unsigned long lastPublishTime = 0;

void onMessageReceived(char* topic, byte* payload, unsigned int length) {
  char message[length + 1];
  memcpy(message, payload, length);
  message[length] = '\0';
  Serial.print("Received: ");
  Serial.println(message);
}

void setup() {
  Serial.begin(115200);
  
  WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.println(" WiFi connected!");
  
  mqtt.beginMQTT(MQTT_BROKER, MQTT_PORT);
  
  String clientId = "ESP_" + String(ESP.getChipId(), HEX);
  mqtt.setClientId(clientId.c_str());
  mqtt.setCallback(onMessageReceived);
  
  if (mqtt.connect()) {
    mqtt.subscribe(TOPIC_SUBSCRIBE);
    mqtt.publish(TOPIC_PUBLISH, "Connected!");
  }
}

void loop() {
  mqtt.loop();
  
  if (millis() - lastPublishTime >= 5000) {
    lastPublishTime = millis();
    String msg = "Uptime: " + String(millis() / 1000) + "s";
    mqtt.publish(TOPIC_PUBLISH, msg.c_str());
  }
}

​
Structured Topics

Organize MQTT topics hierarchically for complex systems.

​
Topic Structure

Use a consistent naming scheme: 
home/livingroom/temperature      (sensor data)
home/livingroom/humidity         (sensor data)
home/livingroom/lights/state     (device state)
home/livingroom/lights/set       (device command)

​
Publishing to Structured Topics

Use the publishToTopic helper method: 
const char* TOPIC_BASE = "home/livingroom";

// Publish temperature
mqtt.publishToTopic(TOPIC_BASE, "temperature", String(temp).c_str());

// Publish with retained flag
mqtt.publishToTopic(TOPIC_BASE, "lights/state", "ON", true);

​
Subscribing to Multiple Topics

void setup() {
  // ... WiFi and MQTT setup ...
  
  if (mqtt.connect()) {
    // Subscribe to multiple control topics
    mqtt.subscribe("home/livingroom/lights/set");
    mqtt.subscribe("home/livingroom/brightness/set");
    mqtt.subscribe("home/livingroom/temperature/set");
  }
}

​
Handling Different Topics

void onMessageReceived(char* topic, byte* payload, unsigned int length) {
  char message[length + 1];
  memcpy(message, payload, length);
  message[length] = '\0';
  
  if (strstr(topic, "/lights/set") != NULL) {
    bool lightsOn = (strcmp(message, "ON") == 0);
    digitalWrite(LIGHT_PIN, lightsOn);
    
    // Publish new state
    mqtt.publishToTopic(TOPIC_BASE, "lights/state", 
                        lightsOn ? "ON" : "OFF", true);
  }
  else if (strstr(topic, "/brightness/set") != NULL) {
    int brightness = atoi(message);
    analogWrite(LED_PIN, brightness);
    
    mqtt.publishToTopic(TOPIC_BASE, "brightness/state", 
                        String(brightness).c_str(), true);
  }
}

​
Smart Home Example

Complete IoT sensor and control system: 
float temperature = 21.5;
int humidity = 55;
bool lights = false;
int brightness = 0;

void publishEnvironmentData() {
  if (!mqtt.isConnected()) return;
  
  mqtt.publishToTopic(TOPIC_BASE, "temperature", String(temperature).c_str());
  mqtt.publishToTopic(TOPIC_BASE, "humidity", String(humidity).c_str());
}

void loop() {
  mqtt.loop();
  
  if (millis() - lastPublishTime >= 5000) {
    lastPublishTime = millis();
    
    // Read sensors
    temperature = 21.0 + random(-10, 10) / 10.0;
    humidity = 55 + random(-5, 5);
    
    // Publish data
    publishEnvironmentData();
  }
}

​
Advanced Features

​
Last Will and Testament (LWT)

Set a message to publish when device disconnects: 
mqtt.setWill("device/status", "offline", true, 1);
See mqtt-manager_mqtt-lwt-example.ino for details.

​
QoS Levels

Control message delivery guarantees: 
mqtt.publish(topic, message, false, 0);  // QoS 0 - At most once
mqtt.publish(topic, message, false, 1);  // QoS 1 - At least once
mqtt.publish(topic, message, false, 2);  // QoS 2 - Exactly once

​
Connection Status

Check and monitor connection state: 
if (mqtt.isConnected()) {
  // Safe to publish
  mqtt.publish(topic, message);
} else {
  Serial.println("Not connected: " + mqtt.getStateString());
}

​
Key Methods

MethodDescription
beginMQTT(broker, port)Initialize MQTT connection
setClientId(id)Set unique client identifier
setCallback(function)Set message handler
connect()Connect to broker
loop()Maintain connection (call in loop)
publish(topic, message)Publish message
publishToTopic(base, subtopic, msg)Structured topic publish
subscribe(topic)Subscribe to topic
isConnected()Check connection status
getStateString()Get connection state

​
Hardware Requirements

  • ESP32 or ESP8266
  • WiFi connection
  • MQTT broker (local or cloud)
  • Public: broker.hivemq.com, test.mosquitto.org
  • Self-hosted: Mosquitto, HiveMQ
  • Cloud: AWS IoT, Azure IoT Hub, Google Cloud IoT

​
Source Files

Example files located at:
  • Basic: example/modules/wifi/EXAMPLE-mqtt-manager/mqtt-manager_mqtt-basic-example/
  • Topics: example/modules/wifi/EXAMPLE-mqtt-manager/mqtt-manager_mqtt-topics-example/

Build docs developers (and LLMs) love

Get started for freeTalk to us