mqtt – Simple MQTT client

The mqtt module provides a minimal MQTT v3.1.1 client implementation suitable for use on memory-constrained devices. It supports connecting to a broker (with optional TLS), publishing messages, subscribing to topics, last-will configuration and keep-alive pings.

Example:

from mqtt import MQTTClient

def callback(topic, msg):
    print(topic, msg)

client = MQTTClient("openmv", "broker.example.com", 1883)
client.set_callback(callback)
client.connect()
client.subscribe(b"openmv/in")
client.publish(b"openmv/out", b"hello")
while True:
    client.check_msg()

Exceptions

exception mqtt.MQTTException

Raised when the broker rejects the CONNECT request or when a SUBSCRIBE request is refused. The single argument is the broker-supplied numeric return code.

Classes

class mqtt.MQTTClient(client_id: bytes | str, server: str, port: int, ssl_params: dict | None = None, user: bytes | str | None = None, password: bytes | str | None = None, keepalive: int = 0, callback: callable | None = None)

Construct an MQTT client.

Arguments:

  • client_id – unique client identifier sent to the broker.

  • server – broker hostname or IP address (resolved with socket.getaddrinfo()).

  • port – broker TCP port (typically 1883 plain or 8883 for TLS).

  • ssl_params – if not None, the socket is wrapped with ssl.wrap_socket() and ssl_params is forwarded as keyword arguments. Pass {} to enable TLS with defaults.

  • user – optional username for broker authentication. If given, password must also be supplied.

  • password – optional password used together with user.

  • keepalive – keep-alive interval in seconds (0 disables). Must be less than 65536.

  • callback – callable invoked as callback(topic, msg) for each PUBLISH delivered from the broker. May also be set later with set_callback().

Methods

set_callback(f: callable) → None

Set the callback invoked by wait_msg() and check_msg() when a PUBLISH message is received. The callback is called as f(topic, msg) with both arguments as bytes.

set_last_will(topic: bytes | str, msg: bytes | str, retain: bool = False, qos: int = 0) → None

Configure the MQTT Last Will and Testament. The broker publishes msg on topic if the client disconnects ungracefully. Must be called before connect().

Arguments:

  • topic – last-will topic (must be non-empty).

  • msg – last-will payload.

  • retain – if True, broker stores the will message as a retained message.

  • qos – last-will QoS level. Must be 0, 1 or 2.

connect(clean_session: bool = True, timeout: float = 5.0) → int

Open a TCP (and optionally TLS) connection to the broker and send a CONNECT packet.

Arguments:

  • clean_session – if True, request a clean session; otherwise the broker resumes any prior session state.

  • timeout – socket timeout in seconds applied to the underlying socket.

Returns the broker’s session present flag (0 or 1). Raises MQTTException if the broker returns a non-zero CONNACK return code.

disconnect() → None

Send a DISCONNECT packet and close the underlying socket.

ping() → None

Send a PINGREQ packet to the broker. Should be called periodically if keepalive is non-zero so the broker does not drop the connection.

publish(topic: bytes | str, msg: bytes | str, retain: bool = False, qos: int = 0) → None

Publish msg to topic.

Arguments:

  • topic – topic name to publish to.

  • msg – payload bytes.

  • retain – if True, instruct the broker to retain the message for new subscribers.

  • qos – quality-of-service level. 0 (fire and forget) and 1 (acknowledged) are supported. 2 is not implemented and will raise AssertionError.

For qos 1, the call blocks until the matching PUBACK is received. The total packet size must be less than 2097152 bytes.

subscribe(topic: bytes | str, qos: int = 0) → None

Subscribe to topic at the given qos level. A callback must have been registered via set_callback() or supplied to the constructor; otherwise AssertionError is raised.

Blocks until the matching SUBACK is received. Raises MQTTException if the broker refuses the subscription (return code 0x80).

wait_msg() → int | None

Block waiting for a single incoming MQTT packet and process it. PUBLISH packets are delivered to the registered callback. PINGRESP packets are consumed silently. For other control packets the raw first byte is returned. Returns None if no data is available or if a PINGRESP was processed.

check_msg() → int | None

Non-blocking variant of wait_msg(). Polls the socket for at most ~50 ms using select.select(); if data is pending it performs the same processing as wait_msg(), otherwise returns None.