Developer interface#

Client#

class aiomqtt.Client(hostname: str, port: int = 1883, *, username: str | None = None, password: str | None = None, logger: logging.Logger | None = None, identifier: str | None = None, queue_type: type[asyncio.Queue[Message]] | None = None, protocol: ProtocolVersion | None = None, will: Will | None = None, clean_session: bool | None = None, transport: Literal['tcp', 'websockets'] = 'tcp', timeout: float | None = None, keepalive: int = 60, bind_address: str = '', bind_port: int = 0, clean_start: mqtt.CleanStartOption = 3, max_queued_incoming_messages: int | None = None, max_queued_outgoing_messages: int | None = None, max_inflight_messages: int | None = None, max_concurrent_outgoing_calls: int | None = None, properties: Properties | None = None, tls_context: ssl.SSLContext | None = None, tls_params: TLSParameters | None = None, tls_insecure: bool | None = None, proxy: ProxySettings | None = None, socket_options: Iterable[SocketOption] | None = None, websocket_path: str | None = None, websocket_headers: WebSocketHeaders | None = None)

The async context manager that manages the connection to the broker.

Parameters:

hostname – The hostname or IP address of the remote broker.
port – The network port of the remote broker.
username – The username to authenticate with.
password – The password to authenticate with.
logger – Custom logger instance.
identifier – The client identifier. Generated automatically if None.
queue_type – The class to use for the queue. The default is asyncio.Queue, which stores messages in FIFO order. For LIFO order, you can use asyncio.LifoQueue; For priority order you can subclass asyncio.PriorityQueue.
protocol – The version of the MQTT protocol.
will – The will message to publish if the client disconnects unexpectedly.
clean_session – If True, the broker will remove all information about this client when it disconnects. If False, the client is a persistent client and subscription information and queued messages will be retained when the client disconnects.
transport – The transport protocol to use. Either "tcp" or "websockets".
timeout – The default timeout for all communication with the broker in seconds.
keepalive – The keepalive timeout for the client in seconds.
bind_address – The IP address of a local network interface to bind this client to.
bind_port – The network port to bind this client to.
clean_start – (MQTT v5.0 only) Set the clean start flag always, never, or only on the first successful connection to the broker.
max_queued_incoming_messages – Restricts the incoming message queue size. If the queue is full, further incoming messages are discarded. 0 or less means unlimited (the default).
max_queued_outgoing_messages – Resticts the outgoing message queue size. If the queue is full, further outgoing messages are discarded. 0 means unlimited (the default).
max_inflight_messages – The maximum number of messages with QoS > 0 that can be part way through their network flow at once.
max_concurrent_outgoing_calls – The maximum number of concurrent outgoing calls.
properties – (MQTT v5.0 only) The properties associated with the client.
tls_context – The SSL/TLS context.
tls_params – The SSL/TLS configuration to use.
tls_insecure – Enable/disable server hostname verification when using SSL/TLS.
proxy – Configure a proxy for the connection.
socket_options – Options to pass to the underlying socket.
websocket_path – The path to use for websockets.
websocket_headers – The headers to use for websockets.

messages

Async generator that yields messages from the underlying message queue.

Type:: AsyncGenerator[aiomqtt.client.Message, None]

identifier

The client identifier.

Type:: str

async subscribe(topic: str | tuple[str, paho.mqtt.subscribeoptions.SubscribeOptions] | list[tuple[str, paho.mqtt.subscribeoptions.SubscribeOptions]] | list[tuple[str, int]], qos: int = 0, options: paho.mqtt.subscribeoptions.SubscribeOptions | None = None, properties: paho.mqtt.properties.Properties | None = None, *args: Any, timeout: float | None = None, **kwargs: Any) → tuple[int, ...] | list[paho.mqtt.reasoncodes.ReasonCode]

Subscribe to a topic or wildcard.

Parameters:

topic – The topic or wildcard to subscribe to.
qos – The requested QoS level for the subscription.
options – (MQTT v5.0 only) Optional paho-mqtt subscription options.
properties – (MQTT v5.0 only) Optional paho-mqtt properties.
*args – Additional positional arguments to pass to paho-mqtt’s subscribe method.
timeout – The maximum time in seconds to wait for the subscription to complete. Use math.inf to wait indefinitely.
**kwargs – Additional keyword arguments to pass to paho-mqtt’s subscribe method.

async unsubscribe(topic: str | list[str], properties: paho.mqtt.properties.Properties | None = None, *args: Any, timeout: float | None = None, **kwargs: Any) → None

Unsubscribe from a topic or wildcard.

Parameters:

topic – The topic or wildcard to unsubscribe from.
properties – (MQTT v5.0 only) Optional paho-mqtt properties.
*args – Additional positional arguments to pass to paho-mqtt’s unsubscribe method.
timeout – The maximum time in seconds to wait for the unsubscription to complete. Use math.inf to wait indefinitely.
**kwargs – Additional keyword arguments to pass to paho-mqtt’s unsubscribe method.

Publish a message to the broker.

Parameters:

topic – The topic to publish to.
payload – The message payload.
qos – The QoS level to use for publication.
retain – If set to True, the message will be retained by the broker.
properties – (MQTT v5.0 only) Optional paho-mqtt properties.
*args – Additional positional arguments to pass to paho-mqtt’s publish method.
timeout – The maximum time in seconds to wait for publication to complete. Use math.inf to wait indefinitely.
**kwargs – Additional keyword arguments to pass to paho-mqtt’s publish method.

async __aenter__() → Self: Connect to the broker.

async __aexit__(exc_type: type[BaseException] | None, exc: BaseException | None, tb: types.TracebackType | None) → None: Disconnect from the broker.

Message#

Wraps the paho-mqtt message class to allow using our own matching logic.

This class is not meant to be instantiated by the user. Instead, it is yielded by the async generator Client.messages.

Parameters:

topic – The topic the message was published to.
payload – The message payload.
qos – The quality of service level of the subscription that matched the message.
retain – Whether the message is a retained message.
mid – The message ID.
properties – (MQTT v5.0 only) The properties associated with the message.

topic

The topic the message was published to.

Type:: aiomqtt.client.Topic

payload

The message payload.

Type:: str | bytes | bytearray | int | float | None

qos

The quality of service level of the subscription that matched the message.

Type:: int

retain

Whether the message is a retained message.

Type:: bool

mid

The message ID.

Type:: int

properties

(MQTT v5.0 only) The properties associated with the message.

Type:: paho.mqtt.properties.Properties | None

Topic#

class aiomqtt.Topic(value: str)

MQTT topic that can be published and subscribed to.

Parameters:: value – The topic string.

value

The topic string.

Type:: str

matches(wildcard: str | aiomqtt.topic.Wildcard) → bool

Check if the topic matches a given wildcard.

Parameters:: wildcard – The wildcard to match against.
Returns:: True if the topic matches the wildcard, False otherwise.

Wildcard#

class aiomqtt.Wildcard(value: str)

MQTT wildcard that can be subscribed to, but not published to.

A wildcard is similar to a topic, but can optionally contain + and # placeholders. You can access the value attribute directly to perform str operations on a wildcard.

Parameters:: value – The wildcard string.

value

The wildcard string.

Type:: str