micropython-mqtt: an asynchronous MQTT driver for MicroPython

The problem is the outage, not the protocol

The repository describes itself as a resilient asynchronous MQTT driver that recovers from WiFi and broker outages, and the README sets out why the official driver is not enough for that job. Six limitations are listed. It is unable reliably to resume operation after a temporary WiFi outage. It uses blocking sockets, which can pause execution for arbitrary periods when accessing a slow broker, and can block forever on a qos 1 publication while waiting for an acknowledgement that never arrives, which can happen on WiFi if the outage occurs at that point in the sequence. That blocking behaviour limits compatibility with asynchronous applications, since pending coroutines are not scheduled for the duration. The support for qos 1 is partial, with no retransmission when a publication acknowledgement is lost. The combination of those two facts puts a limit on the usable WiFi range, because reliable operation requires staying well within range of the access point. And as a synchronous solution it has no mechanism to support the MQTT keepalive, which prevents the last will system from working and makes subscribe-only clients problematic. The design here is a direct answer to each of those points.

The protocol assumptions this driver makes

MQTT itself is described in the README as an easily used networking protocol designed for IoT applications, well suited to controlling hardware devices and reading sensors across a local network or the internet. The model is publish and subscribe between multiple clients, with a single server, also known as a broker, managing the network. Clients may include ESP8266, ESP32 and Pyboard D modules and other networked computers, while typical server hardware is a Raspberry Pi or another small Linux machine that may be left running continuously, with mosquitto named as an effective PC server. Packets consist of a topic and a message string, and a client subscribing to a topic receives all packets published under it. The quality of service levels are described precisely, and one absence is stated up front: level 0 offers no guarantees, level 1 ensures the packet is communicated but duplication can occur, and level 2 avoids duplication but is not supported by the official driver or by this module, with duplicates handled at the application level instead. That last point is a design decision you inherit rather than a bug.

Which files the package ships

The top level of the repository is a small set of files with an unusual shape. There is a `gateway/` directory, a `mqtt_as/` package, an `mqtt_as_eth/` variant, a `mqtt_local_example.py` example, a `pubtest` and a `pubtest_v5` script, plus `GATEWAY.md` and `FUTURE_DEVELOPMENT.md` as separate documents. The `mqtt_as` name is the MicroPython convention for an asynchronous module, and the package metadata in package.json lists the individual files that can be fetched directly, which is how the library is installed on a board that has no package manager in the usual sense:

  "urls": [
    ["mqtt_as/__init__.py", "github:peterhinch/micropython-mqtt/mqtt_as/__init__.py"],
    ["mqtt_as/mqtt_v5_properties.py", "github:peterhinch/micropython-mqtt/mqtt_as/mqtt_v5_properties.py"],
    ["mqtt_as/range.py", "github:peterhinch/micropython-mqtt/mqtt_as/range.py"],
    ["mqtt_as/range_ex.py", "github:peterhinch/micropython-mqtt/mqtt_as/range_ex.py"],
    ["mqtt_as/clean.py", "github:peterhinch/micropython-mqtt/mqtt_as/clean.py"],
    ["mqtt_local_example.py", "github:peterhinch/micropython-mqtt/mqtt_local_example.py"]
  ],
  "version": "0.1"

The `mqtt_v5_properties.py` file is the MQTTv5 support, `range.py` and `range_ex.py` handle the retry and backoff behaviour that the recovery story depends on, and `clean.py` presumably deals with session state. The separate `mqtt_as_eth/` directory is for the non-WiFi case, matching the section on non-WiFi platforms covering a Unix build or wired Ethernet hardware.

The API surface and its two styles

The README's table of contents shows the API in detail, and the shape of it is informative. The `MQTTClient` class takes a configuration dictionary in its constructor and exposes `connect`, `publish`, `subscribe`, `unsubscribe`, `isconnected`, `disconnect` and `close`, plus three diagnostic methods: `broker_up`, `wan_ok` and `dprint`. The presence of `broker_up` and `wan_ok` as first class methods tells you the driver treats network reachability and broker reachability as separate facts, which is exactly the distinction needed to decide whether to retry the connection or give up. There are two usage styles. One is the event based interface, where the client is configured with callbacks and the application reacts to events, and the other is a callback style, and the example usage section is titled for the event interface. The documentation also has a dedicated section on class variables and on a module attribute, and a section on MQTTv5 support covering configuration and migration from MQTTv3.1.1, the MQTTv5 properties, and a list of unsupported features.

Notes that only appear in a real deployment

The Notes section is where the operational reality shows. There is a subsection on connectivity, and separate ones on client publications with qos 1 and client subscriptions with qos 1, which is where the retry semantics live. Application design gets its own subsections covering publication timeouts, behaviour on power up, and optimisations for RAM use and large incoming messages. The behaviour on power up subsection matters more than it sounds, because a device that reboots after a deep sleep has to decide what to do about a session it left behind, and the README is telling you that this is a decision the application designer makes. There is also a section on an alternative design approach, described as continuing the MQTT paradigm into the application, and a section of non standard applications covering usage in specialist and micropower applications. The whole document closes with reference material: connect error codes, a note on Hive MQ as a secure and free broker, a section on the `ssl_params` dictionary with user notes on SSL and TLS, instructions for running a mosquitto broker including changes since Mosquitto V2, and the non-WiFi platform instructions.

Low power operation is a first class case

The non standard applications section is where this driver separates itself from a general purpose client. There is a `deepsleep` subsection, a `lightsleep and disconnect` subsection, and a section on ultra low power consumption for the ESP8266 and ESP32. Deep sleep is where the device powers down between readings, which is a fundamentally different lifecycle from a machine that stays connected, and it is also where the MQTT keepalive problem bites, since a sleeping device cannot respond to a ping and the broker will declare it dead. A sleep and disconnect pattern sidesteps that by closing the connection before sleeping. The alternative design approach section is the conceptual companion, arguing for carrying the publish and subscribe model into the application layer rather than treating the network layer as a separate concern. The Optimisations subsection on RAM use and large incoming messages is the third leg, since a MicroPython board has very little memory and a large message has to be received without exhausting it.

The firmware warning, and the cost of switching

Two practical constraints are worth stating before you commit. The first is the firmware warning at the top of the README. Version V1.22.0 included a changed IDF version 5.0.4, and the instruction is that if you upgrade the firmware on an ESP board, the MQTT package should also be updated to the latest version, otherwise recovery from an outage may not occur. That is a hard coupling between the library version and the firmware version, and it means the upgrade path for a device is not just a pip step. The second is that this is not the official driver and does not behave identically to it. The README documents the differences in detail, and the QoS 2 gap and the deliberately partial handling of QoS 1 duplicates are the two you are most likely to trip over when porting an application. There is also a per-platform section on ESP8266 limitations and another on ESP32 issues, so a specific board may have its own caveats, and the Pyboard D, Arduino Nano RP2040 Connect and RP2 Pico W are each called out with their own notes. The project publishes no GitHub releases, so the only version marker in the repository is the one in package.json.

Editorial conclusion

micropython-mqtt is the right choice for a MicroPython device on unreliable WiFi, particularly one that sleeps, wakes and must reconnect without a manual reset, and for anyone who needs MQTTv5 properties the official driver does not offer. It is the wrong choice if you want a drop-in replacement for the official MicroPython MQTT client, because the README is explicit about the behavioural differences, and the wrong choice if your device is on a wired network with a stable link. Before you adopt it, read the Limitations section, which the README marks as required reading, and note the firmware warning that firmware at or above V1.22.0 needs the latest version of this package for outage recovery to work. The last push was on 2026-10-18 and the repository publishes no GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. peterhinch/micropython-mqtt on GitHub
4. README