Arduino MQTT Primer: ESP32 Wiring, Broker Setup, and Pub/Sub Code

MQTT (Message Queuing Telemetry Transport) is an OASIS-standard publish/subscribe messaging protocol running over TCP/IP. Unlike raw serial buses (I2C/SPI), Arduino MQTT implementations rely on a network physical layer (WiFi or Ethernet) and a central broker to route payloads. The direct answer for most makers: use an ESP32 with the PubSubClient library, connect to a local Mosquitto broker on port 1883, and publish JSON payloads to hierarchical topics.

Because MQTT operates at Layer 7 (Application) of the OSI model, it doesn't have a "bus" in the traditional hardware sense. However, understanding how the physical network layer maps to the MQTT logical layer is critical for preventing dropped connections and latency spikes. Below is the mechanical breakdown of the stack.

Physical Layer & Network Mechanics

Before writing a single line of pub/sub code, you must provision the physical transport. The ESP32-WROOM-32 uses an integrated 802.11 b/g/n WiFi radio, while wired setups typically use a W5500 Ethernet module over SPI. Here is how the physical constraints map to MQTT application behavior.

Protocol Showdown: Which Transport Fits?

MQTT is not the only way to move data from a microcontroller to a server. Choosing between MQTT, HTTP, CoAP, and raw TCP depends entirely on your device count, payload size, and network reliability. According to the HiveMQ MQTT Essentials guide, MQTT's persistent TCP connection and 2-byte fixed header make it vastly superior for battery-constrained IoT nodes.

The Verdict: Choose MQTT when you need bidirectional communication (publishing sensor data and subscribing to relay commands) over standard WiFi/Ethernet. Choose HTTP only for infrequent, heavy payloads like pushing a compiled log file to an S3 bucket. Choose CoAP if you are routing over UDP-based mesh networks where TCP handshakes would timeout.

Minimal Working Exchange: ESP32 to Mosquitto

Below is a production-ready baseline for the ESP32 using the PubSubClient library. This code includes a critical fix for ESP32 WiFi modem sleep, which is the #1 cause of "random" MQTT disconnects on the bench.

#include <WiFi.h>
#include <PubSubClient.h>

// Hardware & Network Config
const char* ssid = "YourNetworkSSID";
const char* password = "YourNetworkPassword";
const char* mqtt_server = "192.168.1.50"; // Local Mosquitto Broker IP
const int mqtt_port = 1883;

// Unique Client ID (CRITICAL: Never hardcode the same ID for multiple nodes)
String clientId = "ESP32_Node_" + String(random(0xffff), HEX);

WiFiClient espClient;
PubSubClient client(espClient);

void setup_wifi() {
  delay(10);
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  // EXPERT FIX: Disable WiFi modem sleep to prevent TCP socket drops
  WiFi.setSleep(false); 
  Serial.println("\nWiFi connected. IP: " + WiFi.localIP().toString());
}

void callback(char* topic, byte* payload, unsigned int length) {
  Serial.print("Message arrived [" + String(topic) + "] ");
  for (int i = 0; i < length; i++) {
    Serial.print((char)payload[i]);
  }
  Serial.println();
  
  // Example: Toggle GPIO 2 based on payload
  if ((char)payload[0] == '1') {
    digitalWrite(2, HIGH);
  } else {
    digitalWrite(2, LOW);
  }
}

void reconnect() {
  while (!client.connected()) {
    Serial.print("Attempting MQTT connection...");
    // Connect with Last Will and Testament (LWT)
    if (client.connect(clientId.c_str(), "home/status/esp32", 1, true, "offline")) {
      Serial.println("connected");
      client.publish("home/status/esp32", "online", true);
      client.subscribe("home/commands/esp32/relay");
    } else {
      Serial.print("failed, rc=");
      Serial.print(client.state());
      delay(5000);
    }
  }
}

void setup() {
  Serial.begin(115200);
  pinMode(2, OUTPUT);
  setup_wifi();
  client.setServer(mqtt_server, mqtt_port);
  client.setCallback(callback);
  client.setKeepAlive(60); // 60-second ping interval
}

void loop() {
  if (!client.connected()) {
    reconnect();
  }
  client.loop();
  
  // Publish telemetry every 5 seconds (non-blocking timer logic omitted for brevity)
  // client.publish("home/sensors/temp", "22.5");
}

Debugging the "Bus": Classic Failures & Sniffing

When an MQTT node goes dark, the issue is rarely the broker. It is almost always a physical layer timeout, a logical address clash, or a payload formatting error. Here is how to diagnose the three most common failures.

1. The Client ID Clash (The Ping-Pong Effect)

Symptom: Your ESP32 connects, immediately drops, reconnects, and drops again in a 2-second loop. The broker logs show Socket error on client X, disconnecting.

The Cause: MQTT requires every connected device to have a strictly unique Client ID. If you flash the same firmware to two ESP32s with clientId = "esp32_sensor", the broker will accept the second connection and forcibly sever the first. The first node reconnects, severing the second. This creates an infinite disconnect loop.

The Fix: Always append a unique hardware identifier to the Client ID. Use the ESP32's MAC address: String clientId = "ESP32_" + WiFi.macAddress();

2. ESP32 WiFi Modem Sleep Drops

Symptom: The node works perfectly for 10 minutes, then silently stops publishing. The broker eventually marks it offline after the KeepAlive timeout.

The Cause: By default, the ESP32 Arduino core enables WiFi modem sleep to save power. This puts the RF radio to sleep between DTIM beacons, which frequently drops the underlying TCP socket without cleanly closing the MQTT session. The Espressif WiFi API documentation details how power-save modes interact with TCP keep-alives.

The Fix: Add WiFi.setSleep(false); immediately after WiFi.begin() succeeds, as shown in the code block above. For battery nodes where sleep is mandatory, switch to AsyncMqttClient and implement deep-sleep wake cycles rather than modem sleep.

3. Sniffing the Traffic

Because MQTT runs over standard TCP, you can inspect the raw bytes on the wire. You don't need specialized hardware logic analyzers like you would for SPI or I2C.

• Wireshark: Run Wireshark on your PC and apply the display filter tcp.port == 1883. You will see the CONNECT, CONNACK, PUBLISH, and PINGREQ packets in plain text (if unencrypted). This is invaluable for proving whether the ESP32 is actually sending the payload or if the broker is rejecting it.
• MQTT Explorer: For application-level debugging, download the open-source tool MQTT Explorer. It connects to your broker and visualizes the topic tree in real-time, allowing you to verify QoS levels, retained flags, and payload formatting without writing a custom subscriber script.