API Reference¶

`chumicro_mqtt`¶

The error types every call can raise, and topic_matches for checking a topic against a wildcard filter.

`chumicro_mqtt` ¶

Non-blocking MQTT 3.1.1 client for CircuitPython, MicroPython, and CPython.

`MQTTBackpressureError` ¶

Bases: MQTTError

The outbound queue is full, so the caller must back off.

`MQTTConnectError` ¶

Bases: MQTTError

CONNACK arrived with a non-zero return code.

`MQTTError` ¶

Bases: Exception

Base class for every chumicro-mqtt failure.

`MQTTProtocolError` ¶

Bases: MQTTError

The broker sent something the spec doesn't allow.

`UnsupportedQoSError` ¶

Bases: MQTTError

User requested QoS 2, which is not implemented.

`topic_matches(topic, pattern)` ¶

Return True when topic matches the wildcard pattern.

`chumicro_mqtt.client`¶

MQTTClient itself, the ProtocolState values it moves through, the InboundPublish record handed to your message callback, the WhenOversized policy, and default_client_id. from chumicro_mqtt import MQTTClient gives you the same class.

`chumicro_mqtt.client` ¶

MQTT 3.1.1 client built on chumicro-sockets + chumicro-timing.

:class:MQTTClient is the public entry point.

`ProtocolState` ¶

Connection lifecycle states.

`InboundPublish` ¶

One inbound PUBLISH returned by :meth:MQTTClient.next_message.

`InFlightPublish` ¶

One outstanding QoS 1 PUBLISH awaiting a PUBACK.

`PendingResponse` ¶

A non-publish response we're waiting for (CONNACK / SUBACK / UNSUBACK / PINGRESP).

`WhenOversized` ¶

Policy for inbound PUBLISH whose total wire size exceeds rx_buffer_size.

`MQTTClient` ¶

Non-blocking MQTT 3.1.1 client (QoS 0 + 1).

`io_socket` `property` ¶

The MQTT socket-ish object while connected, connecting, or bringing up transport, else None.

`from_config(config, *, radio=None, ssl_context=None, socket=None, transport_factory=None, ticks=None)` `classmethod` ¶

Build an :class:MQTTClient from runtime config.

Raises:

Type	Description
`ValueError`	config is not a mapping-like object.
`MissingConfigKey`	A required broker key is missing.

`init(socket=None, *, transport_factory=None, client_id, keep_alive_seconds=60, ack_timeout_seconds=5.0, publish_retry_max=3, username=None, password=None, clean_session=True, will_topic=None, will_message=None, will_qos=0, will_retain=False, rx_buffer_size=None, when_oversized=WhenOversized.DROP_WITH_EVENT, when_disconnected='queue', pre_connect_queue_size=8, recv_budget_per_tick=1024, max_tx_queue_size=20, send_timeout_seconds=None, ticks=None)` ¶

Wire up the client.

Parameters:

Name	Type	Description	Default
`socket`	`object \| None`	Already-connected non-blocking socket; `None` when transport_factory is given.	`None`
`transport_factory`	`object \| None`	Zero-arg `SocketConnector` factory; used when socket is `None`.	`None`
`client_id`	`str`	MQTT client identifier, unique per broker.	required
`keep_alive_seconds`	`int`	Broker idle timeout; PINGREQ runs at half this interval.	`60`
`ack_timeout_seconds`	`float`	Per-ack deadline, also bounding each transport attempt.	`5.0`
`publish_retry_max`	`int`	Max QoS 1 PUBLISH retries before FAILED.	`3`
`username`	`str \| None`	Optional auth username.	`None`
`password`	`str \| None`	Optional auth password.	`None`
`clean_session`	`bool`	`False` resumes persistent broker session state across reconnects.	`True`
`will_topic`	`str \| None`	Last-will topic; `None` disables the will.	`None`
`will_message`	`bytes \| None`	Last-will payload.	`None`
`will_qos`	`int`	Will QoS (0 or 1).	`0`
`will_retain`	`bool`	`True` retains the will on the broker.	`False`
`rx_buffer_size`	`int \| None`	Steady-state RX buffer (default 256); larger PUBLISHes use the oversized tier.	`None`
`when_oversized`	`WhenOversized`	Policy for inbound messages larger than `rx_buffer_size`.	`DROP_WITH_EVENT`
`when_disconnected`	`str`	:meth:`publish` policy before CONNECTED, `"queue"` (default) or `"raise"`.	`'queue'`
`pre_connect_queue_size`	`int`	Bound on the pre-connect publish queue (default 8).	`8`
`recv_budget_per_tick`	`int`	Cap on bytes pulled per tick (default 1024).	`1024`
`max_tx_queue_size`	`int`	Maximum pending outbound packets (default 20).	`20`
`send_timeout_seconds`	`float \| None`	Max unsent time before FAILED; `None` inherits ack_timeout_seconds.	`None`
`ticks`	`object \| None`	Optional tick source (`chumicro_timing.ticks` shape); defaults to the real clock.	`None`

`connect()` ¶

Express the intent "be connected", acting on it now.

`hold()` ¶

Suspend timer-driven reconnection until the next :meth:connect.

`disconnect()` ¶

Queue a DISCONNECT packet, close the socket, mark DISCONNECTED.

`set_will(topic, message=None, *, qos=0, retain=False)` ¶

Update the Last Will + Testament, taking effect on the next CONNECT.

Parameters:

Name	Type	Description	Default
`topic`	`str \| None`	Will topic; `None` disables the will.	required
`message`	`bytes \| None`	Will payload; `None` becomes empty bytes.	`None`
`qos`	`int`	Will QoS (0 or 1).	`0`
`retain`	`bool`	`True` retains the will on the broker.	`False`

Raises:

Type	Description
`UnsupportedQoSError`	`qos > 1`.

`publish(topic, payload, *, qos=0, retain=False, on_publish=None)` ¶

Queue a PUBLISH packet for topic.

Parameters:

Name	Type	Description	Default
`topic`	`str`	Publish topic, sent on the wire as written.	required
`payload`	`bytes \| str`	`bytes` or `str` (`str` is auto-encoded as UTF-8).	required
`qos`	`int`	0 or 1; QoS 2 raises :class:`UnsupportedQoSError`.	`0`
`retain`	`bool`	`True` for retained messages.	`False`
`on_publish`	`object \| None`	Callback `(topic, payload_bytes)` fired on delivery.	`None`

Raises:

Type	Description
`MQTTError`	`when_disconnected="raise"` and not yet CONNECTED.
`MQTTBackpressureError`	The tx queue or pre-connect queue is full.

`subscribe(topic, qos=0, *, on_subscribe=None)` ¶

Declare a subscription for topic, valid in any state.

Parameters:

Name	Type	Description	Default
`topic`	`str`	Topic filter (`+` / `#` wildcards ok), sent as written.	required
`qos`	`int`	0 or 1.	`0`
`on_subscribe`	`object \| None`	One-shot `(topic, granted_qos)` fired on the first SUBACK granting topic.	`None`

Raises:

Type	Description
`MQTTBackpressureError`	Already CONNECTED and the tx queue is full.

`unsubscribe(topic, *, on_unsubscribe=None)` ¶

Retract a subscription for topic, valid in any state.

`next_message()` ¶

Suspend until the next inbound PUBLISH; return it, or None when parked.

`check(now_ms)` ¶

Return True when the client wants a handle() this tick.

`io_interest(now_ms)` ¶

Poll-interest bitmask (_IO_READ / _IO_WRITE) for Runner.wait.

`io_error(now_ms, eventmask)` ¶

Runner hook: POLLERR / POLLHUP surfaced on the registered socket.

`next_deadline(now_ms)` ¶

Earliest tick at which handle() must run even on a quiet socket.

`handle(now_ms)` ¶

One tick of progress.

`default_client_id(prefix='chumicro')` ¶

Return a stable per-device MQTT client id <prefix>-<uid-hex>.

Unique across devices, stable across reboots (so a persistent session resumes rather than colliding on a shared broker). The UID comes from microcontroller.cpu.uid (CircuitPython), machine.unique_id() (MicroPython), or the host MAC via uuid.getnode() (CPython); each is guarded, and if none works the historical <prefix>-mqtt is returned.

API Reference¶

chumicro_mqtt¶

chumicro_mqtt ¶

MQTTBackpressureError ¶

MQTTConnectError ¶

MQTTError ¶

MQTTProtocolError ¶

UnsupportedQoSError ¶

topic_matches(topic, pattern) ¶

chumicro_mqtt.client¶

chumicro_mqtt.client ¶

ProtocolState ¶

InboundPublish ¶

InFlightPublish ¶

PendingResponse ¶

WhenOversized ¶

MQTTClient ¶

io_socket property ¶

from_config(config, *, radio=None, ssl_context=None, socket=None, transport_factory=None, ticks=None) classmethod ¶

connect() ¶

hold() ¶

disconnect() ¶

set_will(topic, message=None, *, qos=0, retain=False) ¶

publish(topic, payload, *, qos=0, retain=False, on_publish=None) ¶

subscribe(topic, qos=0, *, on_subscribe=None) ¶

unsubscribe(topic, *, on_unsubscribe=None) ¶

next_message() ¶

check(now_ms) ¶

io_interest(now_ms) ¶

io_error(now_ms, eventmask) ¶

next_deadline(now_ms) ¶

handle(now_ms) ¶

default_client_id(prefix='chumicro') ¶

`chumicro_mqtt`¶

`chumicro_mqtt` ¶

`MQTTBackpressureError` ¶

`MQTTConnectError` ¶

`MQTTError` ¶

`MQTTProtocolError` ¶

`UnsupportedQoSError` ¶

`topic_matches(topic, pattern)` ¶

`chumicro_mqtt.client`¶

`chumicro_mqtt.client` ¶

`ProtocolState` ¶

`InboundPublish` ¶

`InFlightPublish` ¶

`PendingResponse` ¶

`WhenOversized` ¶

`MQTTClient` ¶

`io_socket` `property` ¶

`from_config(config, *, radio=None, ssl_context=None, socket=None, transport_factory=None, ticks=None)` `classmethod` ¶

`connect()` ¶

`hold()` ¶

`disconnect()` ¶

`set_will(topic, message=None, *, qos=0, retain=False)` ¶

`publish(topic, payload, *, qos=0, retain=False, on_publish=None)` ¶

`subscribe(topic, qos=0, *, on_subscribe=None)` ¶

`unsubscribe(topic, *, on_unsubscribe=None)` ¶

`next_message()` ¶

`check(now_ms)` ¶

`io_interest(now_ms)` ¶

`io_error(now_ms, eventmask)` ¶

`next_deadline(now_ms)` ¶

`handle(now_ms)` ¶

`default_client_id(prefix='chumicro')` ¶