PubSubClient MQTT Arduino: IoT Messaging Tutorial for Embedded Systems

After designing dozens of IoT devices and PCB boards that communicate over networks, I’ve come to rely heavily on the PubSubClient MQTT Arduino library. Whether you’re building smart home sensors, industrial monitoring systems, or remote control devices, MQTT provides the lightweight, reliable messaging protocol that constrained microcontrollers desperately need. This tutorial covers everything you need to implement production-grade MQTT communication in your Arduino projects.

Understanding MQTT and Why It Matters for IoT Hardware

MQTT (Message Queuing Telemetry Transport) is a publish-subscribe messaging protocol designed specifically for resource-constrained devices and low-bandwidth networks. As a PCB engineer, I appreciate MQTT’s efficiency—it uses minimal packet overhead compared to HTTP, making it perfect for battery-powered devices where every byte transmitted consumes precious power.

The PubSubClient MQTT Arduino library brings this protocol to Arduino-compatible microcontrollers, enabling bidirectional communication between your embedded devices and cloud services, home automation platforms, or custom applications. Unlike REST APIs that require constant polling, MQTT establishes persistent connections where devices receive messages instantly when published.

Key advantages for embedded hardware designers:

Low bandwidth consumption: MQTT headers are just 2 bytes, compared to HTTP’s hundreds of bytes Persistent connections: Eliminates connection overhead from repeated requests Quality of Service levels: Guarantees message delivery when network conditions vary Bidirectional communication: Devices can both send data and receive commands Last Will and Testament: Automatically notifies when devices disconnect unexpectedly

PubSubClient Library Overview and Limitations

The PubSubClient MQTT Arduino library, developed by Nick O’Leary, has been the standard for Arduino MQTT implementations since 2009. Understanding its capabilities and constraints is critical for successful hardware deployment.

Feature	Specification	Impact on Design
Protocol Version	MQTT 3.1.1 (default)	Configurable to MQTT 3.1
Publish QoS	QoS 0 only	Fire-and-forget, no delivery guarantee
Subscribe QoS	QoS 0 or QoS 1	Can receive acknowledged messages
Keepalive Interval	15 seconds	Configurable via code or header
Memory Footprint	Minimal	Suitable for ATmega328
Platform Support	Universal	Works with any Client implementation

Engineering insight: The 256-byte buffer limitation often catches developers by surprise. When designing message formats, account for topic strings (which count toward this limit) plus your payload. For a topic like sensors/temperature/room1/current (32 bytes), you have only 224 bytes remaining for payload data.

Installing PubSubClient MQTT Arduino Library

Installation methods vary based on your development environment:

Arduino IDE Installation

1. Open Arduino IDE
2. Navigate to Sketch → Include Library → Manage Libraries
3. Search for “PubSubClient”
4. Install the library by Nick O’Leary
5. Verify installation by checking File → Examples → PubSubClient

PlatformIO Installation

Add to your platformio.ini file:

lib_deps =

    knolleary/PubSubClient@^2.8

Manual Installation from GitHub

cd ~/Arduino/libraries

git clone https://github.com/knolleary/pubsubclient.git

Hardware Requirements and Network Compatibility

The PubSubClient MQTT Arduino library works with any Arduino board that provides a network Client implementation. Here’s how different hardware configurations map to this library:

Hardware Platform	Network Interface	Client Type	Notes
Arduino Uno + Ethernet Shield	Wired Ethernet	EthernetClient	Most stable, recommended for prototyping
ESP8266	WiFi	WiFiClient	Built-in WiFi, very popular
ESP32	WiFi + Bluetooth	WiFiClient	Dual-core, excellent performance
Arduino Mega + W5500	Ethernet	EthernetClient	More RAM than Uno
Arduino + SIM800L	Cellular GPRS	Client	Requires custom implementation
STM32 + Ethernet	Wired Ethernet	EthernetClient	ARM Cortex performance

PCB design consideration: When specifying microcontrollers for MQTT projects, I always ensure at least 8KB RAM. The ATmega328 (2KB) works but leaves very little headroom for complex applications.

Basic PubSubClient MQTT Arduino Implementation

Let’s build a complete, production-ready MQTT client from scratch. This example demonstrates proper connection handling, publishing, and subscribing.

Complete Working Example

#include <ESP8266WiFi.h>

#include <PubSubClient.h>

// Network credentials

const char* ssid = “YOUR_WIFI_SSID”;

const char* password = “YOUR_WIFI_PASSWORD”;

// MQTT Broker settings

const char* mqtt_server = “broker.hivemq.com”;

const int mqtt_port = 1883;

const char* mqtt_client_id = “ESP8266_Device_001”;

// Topics

const char* topic_publish = “home/sensor/temperature”;

const char* topic_subscribe = “home/control/relay”;

WiFiClient espClient;

PubSubClient client(espClient);

unsigned long lastMsg = 0;

float temperature = 20.0;

void setup_wifi() {

  delay(10);

  Serial.println(“Connecting to WiFi…”);

  WiFi.begin(ssid, password);

  while (WiFi.status() != WL_CONNECTED) {

    delay(500);

    Serial.print(“.”);

  }

  Serial.println(“\nWiFi connected”);

  Serial.print(“IP address: “);

  Serial.println(WiFi.localIP());

}

void callback(char* topic, byte* payload, unsigned int length) {

  Serial.print(“Message arrived [“);

  Serial.print(topic);

  Serial.print(“]: “);

  // Convert payload to string

  String message;

  for (int i = 0; i < length; i++) {

    message += (char)payload[i];

  }

  Serial.println(message);

  // Act on received message

  if (String(topic) == topic_subscribe) {

    if (message == “ON”) {

      digitalWrite(LED_BUILTIN, HIGH);

      Serial.println(“LED turned ON”);

    } else if (message == “OFF”) {

      digitalWrite(LED_BUILTIN, LOW);

      Serial.println(“LED turned OFF”);

    }

  }

}

void reconnect() {

  while (!client.connected()) {

    Serial.print(“Attempting MQTT connection…”);

    if (client.connect(mqtt_client_id)) {

      Serial.println(“connected”);

      // Subscribe to control topic

      client.subscribe(topic_subscribe);

      Serial.print(“Subscribed to: “);

      Serial.println(topic_subscribe);

      // Publish connection announcement

      client.publish(topic_publish, “Device connected”);

    } else {

      Serial.print(“failed, rc=”);

      Serial.print(client.state());

      Serial.println(” retry in 5 seconds”);

      delay(5000);

    }

  }

}

void setup() {

  pinMode(LED_BUILTIN, OUTPUT);

  Serial.begin(115200);

  setup_wifi();

  client.setServer(mqtt_server, mqtt_port);

  client.setCallback(callback);

}

void loop() {

  if (!client.connected()) {

    reconnect();

  }

  client.loop();

  // Publish temperature every 10 seconds

  unsigned long now = millis();

  if (now – lastMsg > 10000) {

    lastMsg = now;

    // Simulate temperature reading

    temperature += random(-10, 11) / 10.0;

    char tempString[8];

    dtostrf(temperature, 1, 2, tempString);

    Serial.print(“Publishing temperature: “);

    Serial.println(tempString);

    client.publish(topic_publish, tempString);

  }

}

Engineering notes on this implementation:

• Client ID must be unique across all devices connecting to same broker
• client.loop() must be called frequently to process incoming messages and maintain connection
• Non-blocking reconnection prevents system lockup during network issues
• Temperature converted to string using dtostrf() for MQTT transmission

Advanced Configuration for Production Systems

Increasing Buffer Size for Larger Messages

The default 256-byte limit is insufficient for many applications. Modify before connecting:

void setup() {

  client.setBufferSize(512);  // Set to 512 bytes

  client.setServer(mqtt_server, mqtt_port);

  // Continue setup…

}

Memory trade-off: Every byte added to buffer size reduces available RAM for other variables. On ATmega328, carefully balance buffer size against total memory usage.

Configuring Keepalive Interval

Keepalive determines how often the client sends PING packets to maintain connection:

void setup() {

  client.setKeepAlive(60);  // 60 seconds instead of default 15

  // Continue setup…

}

Network consideration: Longer keepalive intervals reduce bandwidth consumption but increase time before detecting disconnections. For battery-powered devices, I typically use 30-60 seconds. For critical real-time systems, stick with 15 seconds.

Authentication and Secure Connections

Many production brokers require authentication:

void reconnect() {

  const char* username = “device_user”;

  const char* password = “secure_password”;

  if (client.connect(mqtt_client_id, username, password)) {

    Serial.println(“Authenticated successfully”);

  }

}

For TLS/SSL encryption (MQTTS), use WiFiClientSecure on ESP8266/ESP32:

#include <WiFiClientSecure.h>

WiFiClientSecure espClient;

PubSubClient client(espClient);

void setup() {

  espClient.setInsecure();  // Skip certificate verification (development only)

  // For production, load CA certificate:

  // espClient.setCACert(root_ca);

}

Understanding Callback Functions and Message Processing

The callback function in PubSubClient MQTT Arduino executes when subscribed messages arrive. Understanding its limitations prevents common bugs.

Callback Function Constraints

void callback(char* topic, byte* payload, unsigned int length) {

  // IMPORTANT: payload is NOT null-terminated

  // Must process within callback or copy to global variable

  // WRONG: This fails because payload isn’t a proper string

  // String message = (char*)payload;

  // CORRECT: Build string from bytes

  String message = “”;

  for (int i = 0; i < length; i++) {

    message += (char)payload[i];

  }

  // Process message

  if (message == “RESET”) {

    // Trigger device reset

  }

}

Copying Payload for Later Processing

If you need to use payload data outside the callback:

char payloadBuffer[256];

bool newMessageAvailable = false;

void callback(char* topic, byte* payload, unsigned int length) {

  if (length < sizeof(payloadBuffer)) {

    memcpy(payloadBuffer, payload, length);

    payloadBuffer[length] = ‘\0’;  // Null-terminate

    newMessageAvailable = true;

  }

}

void loop() {

  client.loop();

  if (newMessageAvailable) {

    processMessage(payloadBuffer);

    newMessageAvailable = false;

  }

}

Robust Reconnection Strategies

Network reliability varies dramatically across installation environments. Implementing proper reconnection logic separates hobby projects from production devices.

Non-Blocking Reconnection

The blocking while loop in basic examples freezes your entire program during reconnection attempts. Use this pattern instead:

unsigned long lastReconnectAttempt = 0;

void loop() {

  if (!client.connected()) {

    unsigned long now = millis();

    if (now – lastReconnectAttempt > 5000) {

      lastReconnectAttempt = now;

      if (client.connect(mqtt_client_id)) {

        lastReconnectAttempt = 0;

        client.subscribe(topic_subscribe);

      }

    }

  } else {

    client.loop();

    // Normal operation code here

  }

}

Production consideration: This allows other critical code (sensor readings, safety checks) to continue running even during extended network outages.

Connection State Monitoring

void checkConnectionState() {

  int state = client.state();

  switch(state) {

    case -4: Serial.println(“Connection timeout”); break;

    case -3: Serial.println(“Connection lost”); break;

    case -2: Serial.println(“Connect failed”); break;

    case -1: Serial.println(“Disconnected”); break;

    case 0: Serial.println(“Connected”); break;

    case 1: Serial.println(“Bad protocol”); break;

    case 2: Serial.println(“Bad client ID”); break;

    case 3: Serial.println(“Unavailable”); break;

    case 4: Serial.println(“Bad credentials”); break;

    case 5: Serial.println(“Unauthorized”); break;

  }

}

Troubleshooting Common PubSubClient Issues

After deploying hundreds of MQTT devices, these are the problems I encounter repeatedly:

Issue: Client Connects But Doesn’t Receive Messages

Cause: Forgetting to call client.loop() frequently enough.

Solution: Ensure client.loop() executes at least every few hundred milliseconds. Long delay() calls prevent message processing.

// WRONG

void loop() {

  client.loop();

  delay(10000);  // 10-second delay blocks message processing

}

// CORRECT

void loop() {

  client.loop();

  if (millis() – lastCheck > 10000) {

    // Perform periodic task

    lastCheck = millis();

  }

}

Issue: Messages Truncated or Corrupted

Cause: Buffer size too small for message length.

Solution: Calculate required buffer size: topic_length + payload_length + ~10 bytes header overhead.

// For topic “sensors/building/floor2/room5/temperature” (40 bytes)

// Plus 100-byte JSON payload

// Need minimum: 40 + 100 + 10 = 150 bytes

client.setBufferSize(200);  // Add safety margin

Issue: Frequent Disconnections

Cause: Keepalive timeout or WiFi power saving interference.

Solution: Adjust keepalive and disable WiFi sleep mode on ESP8266/ESP32:

void setup() {

  WiFi.setSleepMode(WIFI_NONE_SLEEP);  // Disable WiFi power saving

  client.setKeepAlive(30);

}

Issue: “Failed, rc=-2” Error

Cause: DNS resolution failure or incorrect broker address.

Solution: Use IP address instead of hostname, or implement better DNS handling:

IPAddress broker_ip(192, 168, 1, 100);

client.setServer(broker_ip, 1883);

Best Practices for Production PCB Designs

From years of deploying IoT devices, these practices improve reliability:

Power Supply Decoupling: Place 10μF and 0.1μF capacitors near WiFi modules. MQTT transmission causes current spikes that can reset microcontrollers if power supply is poorly decoupled.

Watchdog Timer Implementation: Use hardware watchdog timers to recover from network stack hangs. ESP8266 includes automatic WDT; configure appropriately.

Status LED Indicators: Design PCBs with LEDs indicating: Power, WiFi connected, MQTT connected, Message activity. Simplifies field troubleshooting.

Over-the-Air Updates: Plan for OTA firmware updates. MQTT-triggered updates allow fixing bugs without physical access to deployed devices.

Persistent Configuration: Store WiFi credentials and broker settings in EEPROM/Flash. Allows configuration without recompiling firmware.

Essential Resources for PubSubClient MQTT Arduino

Official Documentation and Libraries

Resource	Description	URL
PubSubClient GitHub	Source code and issue tracking	https://github.com/knolleary/pubsubclient
API Documentation	Complete function reference	https://pubsubclient.knolleary.net/api
Arduino Library Manager	Direct installation	Search “PubSubClient” in IDE
MQTT.org	Protocol specification	https://mqtt.org/

MQTT Broker Options

Free Public Brokers (testing only, no reliability guarantee):

• broker.hivemq.com (port 1883)
• test.mosquitto.org (port 1883)
• broker.emqx.io (port 1883)

Self-Hosted Brokers:

• Mosquitto: Lightweight, open-source, runs on Raspberry Pi
• EMQ X: Scalable, supports millions of connections
• HiveMQ: Commercial-grade with cloud options

Cloud MQTT Services:

• AWS IoT Core: Enterprise scalability
• Azure IoT Hub: Microsoft ecosystem integration
• CloudMQTT: Managed Mosquitto instances

Example Code Downloads

Download complete working examples:

• Basic Publish/Subscribe: Included with PubSubClient library
• Non-blocking Reconnection: mqtt_reconnect_nonblocking.ino
• ESP8266 with WiFi: mqtt_esp8266.ino
• Authentication Example: Check library examples folder

Frequently Asked Questions (FAQs)

1. Can I use PubSubClient MQTT Arduino with multiple brokers simultaneously?

Yes, create multiple PubSubClient instances with separate network clients. Each requires its own Client object (WiFiClient, EthernetClient, etc.). This configuration is useful for redundancy or connecting to different services simultaneously. However, memory constraints on smaller Arduinos may limit practical implementation to ESP32 or similar platforms with adequate RAM.

2. Why can’t PubSubClient publish messages with QoS 1 or QoS 2?

The library intentionally omits QoS 1/2 publishing to minimize memory footprint and code complexity. QoS 1 requires storing unacknowledged messages and handling PUBACK responses. QoS 2 needs even more complex four-way handshake management. For resource-constrained microcontrollers, these features consume too much RAM. If you absolutely need guaranteed delivery, implement application-level acknowledgments or consider AsyncMQTTClient library for ESP8266/ESP32.

3. How do I send binary data or large payloads via PubSubClient?

For binary data, use the publish(topic, payload, length) variant that accepts byte arrays. For payloads exceeding buffer size, either: (1) Increase buffer with setBufferSize() before connecting, (2) Fragment large payloads into multiple messages with sequence numbers, or (3) Compress data before transmission. Remember that buffer size impacts available RAM—on Arduino Uno with 2KB RAM, staying under 512 bytes total buffer is advisable.

4. What causes “Attempting MQTT connection…failed, rc=-4” errors?

Error code -4 (MQTT_CONNECTION_TIMEOUT) indicates the client couldn’t complete the connection handshake within the timeout period. Common causes include: network congestion, broker overload, firewall blocking port 1883, or incorrect broker address. Verify broker reachability with ping tests. Increase timeout with client.setSocketTimeout(). Check if firewall rules allow outbound TCP port 1883 connections.

5. How can I reduce power consumption for battery-powered MQTT devices?

Implement deep sleep between transmissions using ESP8266/ESP32 sleep modes. Increase keepalive interval to 60+ seconds to reduce ping traffic. Use QoS 0 to avoid acknowledgment overhead. Disable WiFi between transmissions and reconnect only when needed. Consider MQTT-SN (MQTT for Sensor Networks) for extremely low-power applications. Design PCBs with efficient voltage regulators (LDO or buck converters depending on current requirements) and measure actual power consumption to optimize sleep/wake cycles.

Conclusion

The PubSubClient MQTT Arduino library provides embedded developers with reliable, efficient IoT messaging capabilities. From basic sensor reporting to complex bidirectional control systems, MQTT’s publish-subscribe architecture simplifies network communication while consuming minimal resources.

As a PCB engineer, I’ve found that successful MQTT implementations require understanding both the protocol’s strengths and the library’s limitations. Proper buffer sizing, robust reconnection logic, and careful memory management separate prototypes from production-ready devices.

Whether you’re building smart home devices, industrial sensors, or agricultural monitoring systems, mastering PubSubClient MQTT Arduino enables your embedded hardware to participate in IoT ecosystems professionally. The library’s broad platform support means your investment in learning transfers across Arduino Uno, ESP8266, ESP32, and numerous other compatible boards.

Start with the basic examples provided, gradually add authentication and reconnection logic, then optimize for your specific hardware constraints. With proper implementation, MQTT provides the reliable, scalable messaging infrastructure your IoT products demand.

---

Suggested Meta Description:

“Complete PubSubClient MQTT Arduino tutorial for IoT devices. Learn message publishing, subscribing, buffer configuration, reconnection strategies, and troubleshooting from a PCB engineer’s perspective with practical examples.”