Adafruit_MQTT_Library is a small MQTT client for Arduino boards

A client that borrows Arduino's transport abstraction

The library is described in one line: an Arduino library for MQTT support, including access to Adafruit IO. The important second half is the platform list. It works with the Adafruit FONA, the Arduino Yun, the ESP8266 Arduino platforms, and anything that supports Arduino's Client interface, with the Ethernet shield given as the example of that last case.

That last item is the design. Rather than bundling a socket implementation, the library speaks to whatever transport the board already provides through the Client interface, which is the interface an Ethernet shield, a WiFi client or a cellular modem all expose. The consequence is that the same MQTT code compiles for a wired shield board and for an ESP8266 without a transport abstraction written by the library author.

The transport-specific parts live in separate files, which the repository listing makes visible. There is Adafruit_MQTT.cpp with its header, Adafruit_MQTT_Client.cpp with its header for the Client-based path, and a separate Adafruit_MQTT_FONA.h for the cellular board. Alongside them sit keywords.txt and library.properties, the two files the Arduino library manager uses to index the library and its keywords.

The library is MIT licensed and its default branch is master. It is not archived, and the last push was on 2026-07-07, which is also the date of the most recent release, 2.6.6, with 2.6.5 on 2026-06-30 and 2.6.4 on 2026-04-21. A CI badge for the Arduino Library CI workflow is present in the README, so the build is checked automatically on every push.

It implements part of the MQTT spec, on purpose

The README is direct about this: the library does not support the full MQTT spec but is intended to support enough for QoS 0 and 1 publishing.

That sentence defines the boundaries of the project. A full MQTT client handles a wide range of acknowledgement modes, retained message semantics, session persistence, wildcards in subscriptions, and the will and testament messages. None of that is claimed here. What is claimed is the subset a small board needs to send telemetry and receive commands, with the two lowest quality of service levels.

The capabilities the README does describe are publishing and subscribing to feeds, plus access to Adafruit IO, the hosted service built around the same feed model. The README directs you to the included examples to see how to use the library to access an MQTT service to publish and subscribe to feeds.

The open question about how complete the subscription side is appears in the future todos:

   - Subscription callbacks

and a second entry on the list is to remove the watchdog:

   - remove watchdog

The first of those tells you something concrete about the current state. Subscribing to a topic is supported, since there are examples named for subscribing, but callback driven delivery is still on the todo list, so a subscription example is likely to be driven by polling or by a single message read rather than by a per-message callback. The second todo says the watchdog dependency exists today and the maintainer intends to remove it, which means the library currently pulls in a watchdog for reliability on the FONA path.

Both entries are worth reading before you design around them.

The compatibility table marks everything as not tested

The README carries a generated compatibility table with four columns: tested works, doesn't work, not tested and notes. Every row in the visible part of that table has an X in the not tested column and nothing in the other two.

The listed parts are Atmega328 at 16 and 12 MHz, Atmega32u4 at 16 and 8 MHz, ESP8266, Atmega2560 at 16 MHz, ATSAM3X8E, ATSAM21D, ATSAMD51J20, ATtiny85 at 16 and 8 MHz, Intel Curie at 32 MHz and STM32F2. So on the strength of the table alone, no board is confirmed working and none is confirmed broken.

What the table does provide is the board to product mapping underneath it, which is the part that tells you which physical devices the rows refer to:

  * ESP8266 : Adafruit Huzzah

The other entries map Atmega328 at 16 MHz to Arduino UNO, Pro Trinket 5V, Metro 328 and Metro Mini, Atmega32u4 at 16 MHz to Arduino Leonardo, Arduino Micro, Arduino Yun and Teensy 2.0, Atmega32u4 at 8 MHz to Flora and Bluefruit Micro, Atmega2560 to Arduino Mega, ATSAM3X8E to Arduino Due, ATSAM21D to Arduino Zero and M0 Pro, ATSAMD51J20 to the PyPortal, ATtiny85 at 16 MHz to the Trinket 5V, and ATtiny85 at 8 MHz to Gemma, Arduino Gemma and Trinket 3V.

The board list is broader than the ESP8266 and FONA boards named in the feature description, which is a hint that the transport abstraction is doing real work. But an untested row is a promise nobody has made, so if your product is one of these boards you should expect to debug the first connection yourself, and the examples directory is where you would start.

The examples directory is the actual documentation

There is no usage guide in this repository. The README is short, and the examples are the documentation, and the directory listing shows a set that is effectively a catalogue of features and transports.

The Adafruit IO examples come first. There is adafruitio_anon_time_esp8266, adafruitio_time_esp8266, adafruitio_errors_esp8266, adafruitio_secure_esp8266, adafruitio_secure_esp32, adafruitio_secure_airlift, with the naming pattern telling you the shape of each one: whether the session is anonymous or authenticated, whether the connection is secure, and which board it targets.

The plain MQTT examples cover the protocol features one at a time. mqtt_esp8266 is the baseline. mqtt_2subs_esp8266 is about two simultaneous subscriptions. mqtt_esp8266_callback is the example that shows message delivery by callback, which is worth reading next to the subscription callbacks todo entry, since it suggests the callback path exists in some form. mqtt_retain covers retained messages. mqtt_arbitrary_data covers publishing payloads that are not simple strings. mqtt_airlift_subscribe_time_keepalive is a single example combining a subscription, a time feed and the keepalive setting.

The transport examples are the other axis: mqtt_ethernet for the Ethernet shield, mqtt_winc1500 for the WINC1500 WiFi shield, mqtt_fona for the cellular board, mqtt_yun for the Arduino Yun, and mqtt_esp8266 for the ESP8266.

Read as a set, the examples show that the library's surface is small and mostly about configuration, because the MQTT operations themselves are a handful of calls. If you are evaluating whether this library can do what you need, the fastest check is to find the example closest to your case and read it.

Two optional dependencies, both tied to the FONA path

The dependency list is short and specific, and both entries are conditional on the target platform rather than required by the core library.

The first is the Adafruit SleepyDog watchdog library, described as the watchdog library used by the FONA code for reliability. The second is the Adafruit FONA library itself, required for the FONA hardware. The README frames them as dependencies depending on the target platform, which is the important part: an ESP8266 project does not need either of them.

The watchdog in particular deserves a note. A watchdog on a microcontroller resets the board if it stops responding, which is the right behaviour for a cellular device on a flaky link that must recover on its own. It also means the library has a background thread or timer that periodically pets the dog, and on a device where the application already has its own reliability strategy that is one more thing running. The todo entry to remove the watchdog suggests the maintainer agrees it is not universally wanted.

Since the FONA hardware requires a cellular module, the second dependency drags in a modem stack, and the FONA path is therefore the heaviest configuration the library supports. The presence of Adafruit_MQTT_FONA.h as a separate header from the Client-based implementation confirms that the two paths are separated at the source level.

The rest of the dependency situation is the Arduino ecosystem itself, which is what makes the library portable: any board with a working Arduino core and a Client implementation can use it.

Maintenance, and the gap between releases

The project is a small, focused C++ library with a clear scope, and the release record shows steady maintenance rather than bursts.

The published versions are 2.6.6 on 2026-07-07, 2.6.5 on 2026-06-30 and 2.6.4 on 2026-04-21. Patch releases spaced a week or two apart are the pattern, which is what you would expect from a library that tracks a family of boards and a hosted service at the same time.

The last push was on 2026-07-07, the same day as release 2.6.6, so the tree is in a released state rather than mid-change. The repository is not archived, the default branch is master, and the licence is MIT, which is the least restrictive of the common choices and means you can vendor the source files into a closed product without obligations beyond keeping the notice.

Two things to weigh before you depend on it. The compatibility table marks every board as not tested, so the library's real support surface is whatever the examples cover, which in practice means ESP8266, Ethernet, WINC1500, FONA and the Yun. And the two open todos mean the feature set is still moving in both directions, one addition and one removal, so a pin to a specific version is sensible if your product has a release schedule.

The Arduino Library CI badge in the README means builds are checked automatically, which is the main practical reassurance for a library that must compile across a dozen board cores.

Editorial conclusion

Adafruit_MQTT_Library fits a project on a microcontroller with an Arduino core that needs to publish telemetry or control messages and cannot carry a full MQTT stack, and it does not fit an application that needs the complete MQTT specification, because the README states that support is limited to what QoS 0 and 1 publishing requires. Before adopting it, check the compatibility table for your board, since every listed part is marked as not tested, and read the examples for your transport, because the examples directory is where the actual usage patterns live. The library is MIT licensed, release 2.6.6 was published on 2026-07-07, and the last push was on 2026-07-07.

Frequently asked questions

Official sources

1. adafruit/Adafruit_MQTT_Library on GitHub
2. Issues
3. License: MIT
4. README
5. Releases