chumicro-mqtt

A non-blocking MQTT 3.1.1 client (QoS 0 + 1) that fits inside your runner tick. MQTT is the lightweight publish/subscribe protocol most IoT brokers speak.

Publish and subscribe at QoS 0 or QoS 1, set a last will, retain messages, and match wildcard topics. Messages published before the broker connection is up wait in a bounded queue and go out on connect, and inbound size limits keep one huge payload from exhausting a small heap. No threads, no async: the client does a bounded slice of work per tick, so a slow broker or a large message never stalls the rest of your loop. Built on chumicro-sockets (TCP + TLS) and chumicro-timing (ticks).

Part of the ChuMicro family: small, focused Python libraries for microcontrollers and laptops. Browse all libraries.

Install

# CircuitPython (after `circup bundle-add ChuMicro/ChuMicro-Bundle-Experimental`)
circup install chumicro_mqtt

# MicroPython
mpremote mip install github:ChuMicro/ChuMicro-Bundle-Experimental/chumicro_mqtt

# CPython
pip install chumicro-mqtt-experimental

For bundle setup, pre-compiled .mpy bundles, the experimental channel, and details on PyPI naming, see the chumicro INSTALL guide.

Quick example

from chumicro_timing import ticks_ms
from chumicro_mqtt import MQTTClient
from chumicro_wifi import WifiConfig, WifiService

wifi = WifiService(WifiConfig(ssid="home-wifi", password="s3cret"))

# On CircuitPython pass radio=wifi.adapter.radio (the WifiService's board
# radio); the kwarg is ignored on MP / CPython.  from_config builds the
# transport factory: the client dials the broker non-blocking (one connect
# phase per tick) and self-heals after drops.
client = MQTTClient.from_config(
    {"mqtt.broker.host": "broker.example.com", "mqtt.broker.port": 1883},
    radio=wifi.adapter.radio,
)

client.on_message = lambda topic, payload: print(topic, payload)
client.connect()

# Drive from a tick loop.
while True:
    now = ticks_ms()
    if client.check(now):
        client.handle(now)

QoS 0 + QoS 1 are implemented; QoS 2 raises UnsupportedQoSError. Last-will, retained messages, wildcard topic matching (topic_matches), and a structured oversized-message policy are all built in.

What's included

Tuning for tick-latency vs throughput

handle() does one recv_into and one packet send per tick (plus, on ticks that dispatched inbound QoS-1 publishes, a single coalesced PUBACK batch), so each call yields back to the runner after a bounded slice of socket work. Three MQTTClient(...) constructor knobs let you trade tick fairness for throughput:

Where this fits

Depends on chumicro-sockets (TCP + TLS) and chumicro-timing for ticks. Used directly in app code; no other ChuMicro library depends on it.

Platform support

Works on CPython, MicroPython, and CircuitPython.

Examples

Wiring wifi and broker config for the examples

The hardware-facing examples need wifi credentials and a broker host and port. The telemetry example reads [wifi] for credentials and [telemetry] for the broker host, port, and topic, from a runtime_config.msgpack (chumicro-workspace) with a constants fallback in the file. The library itself never reads TOML. It takes a chumicro-sockets socket and goes, so config wiring stays in the application layer.

Memory and leak testing

A host-side suite uses tracemalloc to verify the client doesn't leak across its hot paths: QoS 0 and QoS 1 publish, inbound recv, and subscribe/unsubscribe cycles.

Contributing

Issues, bug reports, and pull requests are welcome, and so is "I ran it on this board and here's what happened", some of the most useful feedback a hardware project can get. Development happens in the ChuMicro repository, whose contributing guide covers setup and the test workflow.

Docs

📖 Stable docs · Experimental docs

Find this library

• PyPI: chumicro-mqtt
• Bundle: ChuMicro-Bundle (CircuitPython & MicroPython)
• Experimental bundle: ChuMicro-Bundle-Experimental
• Source: libraries/mqtt

License

MIT