arduino-mqtt: An MQTT 3.1.1 Client for Arduino

The problem arduino-mqtt solves

arduino-mqtt is described as an MQTT library for Arduino. It bundles the lwmqtt MQTT 3.1.1 client and adds a thin wrapper to provide an Arduino-like API. The audience is developers building IoT devices on Arduino-compatible hardware who need MQTT messaging. Compatibility examples cover Arduino Yun and Yun-Shield, Arduino Ethernet Shield, Arduino WiFi Shield, Adafruit HUZZAH ESP8266, Arduino WiFi101 Shield, Arduino MKR GSM 1400, Arduino MKR NB 1500 and ESP32 and ESP8266 development boards, with secure variants for several of them. Other shields and boards should also work if they provide a Client based network implementation. The README points to the wiki for more examples. The project is not archived and its last push was on 2026-04-16.

How the wrapper and buffers work

The library wraps lwmqtt, so the underlying protocol handling is the lwmqtt MQTT 3.1.1 client. The Arduino side exposes an MQTTClient object with two buffers, one for read and one for write, defaulting to 128 bytes each. A single constructor argument sets both buffer sizes, while two arguments set them separately. Beginning with version 2.5.2, the message payload is sent directly during publishing, so the write buffer is only needed to encode the packet header and topic, for which the default 128 bytes should be enough. Receiving messages is still fully constrained by the read buffer, which may be increased if necessary. The maximum packet size default of 128 bytes can therefore be raised with MQTTClient client(256) or MQTTClient client(256, 512). The API also provides begin overloads for hostname and IPAddress, with and without a port, defaulting to 1883, and onMessage for registering a callback.

Installing and a first connection

The README offers several install routes. Download the latest release, search for lwmqtt in the Arduino IDE Library Manager, run pio lib install "256dpi/MQTT" for PlatformIO, or add it to idf_component.yml for the IDF component manager.

arduino_mqtt:
  git: "https://github.com/256dpi/arduino-mqtt.git"
  version: # tag, branch, or commit hash

A basic sketch creates a WiFiClient and an MQTTClient, begins the client with a broker hostname, subscribes in connect, and calls client.loop in loop.

#include <SPI.h>
#include <WiFi101.h>
#include <MQTT.h>

const char ssid[] = "ssid";
const char pass[] = "pass";

WiFiClient net;
MQTTClient client;

unsigned long lastMillis = 0;

void connect() {
  Serial.print("checking wifi...");
  while (WiFi.status() != WL_CONNECTED) {
    Serial.print(".");
    delay(1000);
  }

  Serial.print("\nconnecting...");
  while (!client.connect("arduino", "public", "public")) {
    Serial.print(".");
    delay(1000);
  }

  Serial.println("\nconnected!");
  client.subscribe("/hello");
}

void messageReceived(String &topic, String &payload) {
  Serial.println("incoming: " + topic + " - " + payload);
}

void setup() {
  Serial.begin(115200);
  WiFi.begin(ssid, pass);
  client.begin("public.cloud.shiftr.io", net);
  client.onMessage(messageReceived);
  connect();
}

void loop() {
  client.loop();
  if (!client.connected()) {
    connect();
  }
  if (millis() - lastMillis > 1000) {
    lastMillis = millis();
    client.publish("/hello", "world");
  }
}

For shiftr.io, provide the instance name and token secret as the second and third arguments to client.connect. Port 8883 should be specified for secure clients.

Known limitations and failure modes

The default 128 byte read buffer limits received message size unless increased. Local domain names such as Computer.local are not supported by Arduino, so IP addresses must be set directly. On ESP8266, an additional delay(10) after client.loop() reportedly fixes many WiFi stability issues. The message callback must not use the client to publish, subscribe or unsubscribe, as it may cause deadlocks; instead change a global variable or push to a queue and handle it after client.loop. The README does not document reconnection backoff or TLS certificate provisioning details. The last push was on 2026-04-16 and releases span from 2023 to 2026, so maintenance cadence is uneven and adopters should check the wiki for more examples.

Alternatives and how they differ

The README does not name a competing library, so the comparison is structural. A raw lwmqtt integration gives the same protocol client without the Arduino-style wrapper, requiring more boilerplate for connection and callback handling. Conversely, a heavier Arduino MQTT library might hide the buffer sizing that arduino-mqtt exposes, which matters on memory constrained boards. arduino-mqtt's approach is to keep the wrapper thin and make buffer sizes explicit, leaving transport to any Client implementation. The examples directory includes per-board sketches, including secure variants, which serve as the primary learning resource.

Maintenance and upgrade cost

The repository is not archived and the last push was on 2026-04-16. Recent releases are v2.5.3 on 2026-04-16, v2.5.2 on 2024-02-10 and v2.5.1 on 2023-02-04. The license is MIT, which permits commercial use, modification and distribution with the copyright notice retained; this is not legal advice. The Makefile includes an update target that clones lwmqtt v0.9.1 and copies sources into src/lwmqtt, indicating the bundled dependency version. The library supports clang-format with Google style and arduino-cli based testing.

Editorial conclusion

Adopt arduino-mqtt if you need MQTT 3.1.1 on Arduino-compatible boards and can follow the per-board examples. Skip it if you need a buffer larger than the default 128 bytes without reconfiguring MQTTClient. Verify the buffer sizing notes and the board-specific example before deploying.

Frequently asked questions

Official sources

1. 256dpi/arduino-mqtt on GitHub
2. Issues
3. License: MIT
4. README
5. Releases