adafruit_minimqtt

A minimal MQTT Library for CircuitPython.

  • Author(s): Brent Rubell

Implementation Notes

Adapted from https://github.com/micropython/micropython-lib/tree/master/umqtt.simple/umqtt

Software and Dependencies:

exception adafruit_minimqtt.adafruit_minimqtt.MMQTTException(error, code=None)

MiniMQTT Exception class.

Raised for various mostly protocol or network/system level errors. In general, the robust way to recover is to call reconnect().

exception adafruit_minimqtt.adafruit_minimqtt.MMQTTStateError(error, code=None)

MiniMQTT invalid state error.

Raised e.g. if a function is called in unexpected state.

class adafruit_minimqtt.adafruit_minimqtt.MQTT(*, broker: str, port: int | None = None, username: str | None = None, password: str | None = None, client_id: str | None = None, is_ssl: bool | None = None, keep_alive: int = 60, recv_timeout: int = 10, socket_pool=None, ssl_context=None, use_binary_mode: bool = False, socket_timeout: int = 1, connect_retries: int = 5, user_data=None)

MQTT Client for CircuitPython.

Parameters:

  • broker (str) – MQTT Broker URL or IP Address.

  • port (int) – Optional port definition, defaults to MQTT_TLS_PORT if is_ssl is True, MQTT_TCP_PORT otherwise.

  • username (str) – Username for broker authentication.

  • password (str) – Password for broker authentication.

  • client_id (str) – Optional client identifier, defaults to a unique, generated string.

  • is_ssl (bool) – Sets a secure or insecure connection with the broker.

  • keep_alive (int) – KeepAlive interval between the broker and the MiniMQTT client.

  • recv_timeout (int) – receive timeout, in seconds.

  • socket_pool (socket) – A pool of socket resources available for the given radio.

  • ssl_context – SSL context for long-lived SSL connections.

  • use_binary_mode (bool) – Messages are passed as bytearray instead of string to callbacks.

  • socket_timeout (int) – How often to check socket state for read/write/connect operations, in seconds.

  • connect_retries (int) – How many times to try to connect to the broker before giving up on connect or reconnect. Exponential backoff will be used for the retries.

  • user_data (class) – arbitrary data to pass as a second argument to most of the callbacks. This works with all callbacks but the “on_message” and those added via add_topic_callback(); for those, to get access to the user_data use the ‘user_data’ member of the MQTT object passed as 1st argument.

add_topic_callback(mqtt_topic: str, callback_method) → None

Registers a callback_method for a specific MQTT topic.

Parameters:

  • mqtt_topic (str) – MQTT topic identifier.

  • callback_method (function) – The callback method.

Expected method signature is on_message(client, topic, message) To get access to the user_data, use the client argument.

If a callback is called for the topic, then any “on_message” callback will not be called.

connect(clean_session: bool = True, host: str | None = None, port: int | None = None, keep_alive: int | None = None, session_id: str | None = None) → int

Initiates connection with the MQTT Broker. Will perform exponential back-off on connect failures.

Parameters:

  • clean_session (bool) – Establishes a persistent session.

  • host (str) – Hostname or IP address of the remote broker.

  • port (int) – Network port of the remote broker.

  • keep_alive (int) – Maximum period allowed for communication within single connection attempt, in seconds.

  • session_id (str) – unique session ID, used for multiple simultaneous connections to the same host

deinit() → None

De-initializes the MQTT client and disconnects from the mqtt broker.

disable_logger() → None

Disables logging.

disconnect() → None

Disconnects the MiniMQTT client from the MQTT broker.

enable_logger(log_pkg, log_level: int = 20, logger_name: str = 'log')

Enables library logging by getting logger from the specified logging package and setting its log level.

Parameters:

  • log_pkg – A Python logging package.

  • log_level – Numeric value of a logging level, defaults to INFO.

  • logger_name – name of the logger, defaults to “log”.

:return logger object

is_connected() → bool

Returns MQTT client session status as True if connected, False if not.

logger

An optional logging attribute that can be set with with a Logger to enable debug logging.

loop(timeout: float = 1.0) → list[int] | None

Non-blocking message loop. Use this method to check for incoming messages. Returns list of packet types of any messages received or None.

Parameters:

timeout (float) – return after this timeout, in seconds.

property mqtt_msg: Tuple[int, int]

Returns maximum MQTT payload and topic size.

property on_message

Called when a new message has been received on a subscribed topic.

Expected method signature is on_message(client, topic, message) To get access to the user_data, use the client argument.

ping() → list[int]

Pings the MQTT Broker to confirm if the broker is alive or if there is an active network connection. Returns packet types of any messages received while waiting for PINGRESP.

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

Publishes a message to a topic provided.

Parameters:

  • topic (str) – Unique topic identifier.

  • msg (str|int|float|bytes) – Data to send to the broker.

  • retain (bool) – Whether the message is saved by the broker.

  • qos (int) – Quality of Service level for the message, defaults to zero.

reconnect(resub_topics: bool = True) → int

Attempts to reconnect to the MQTT broker. Return the value from connect() if successful. Will disconnect first if already connected. Will perform exponential back-off on connect failures.

Parameters:

resub_topics (bool) – Whether to resubscribe to previously subscribed topics.

remove_topic_callback(mqtt_topic: str) → None

Removes a registered callback method.

Parameters:

mqtt_topic (str) – MQTT topic identifier string.

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

Subscribes to a topic on the MQTT Broker. This method can subscribe to one topic or multiple topics.

Parameters:

  • topic (str|tuple|list) – Unique MQTT topic identifier string. If this is a tuple, then the tuple should contain topic identifier string and qos level integer. If this is a list, then each list element should be a tuple containing a topic identifier string and qos level integer.

  • qos (int) – Quality of Service level for the topic, defaults to zero. Conventional options are 0 (send at most once), 1 (send at least once), or 2 (send exactly once).

unsubscribe(topic: str | list | None) → None

Unsubscribes from a MQTT topic.

Parameters:

topic (str|list) – Unique MQTT topic identifier string or list.

username_pw_set(username: str, password: str | None = None) → None

Set client’s username and an optional password.

Parameters:

  • username (str) – Username to use with your MQTT broker.

  • password (str) – Password to use with your MQTT broker.

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

Sets the last will and testament properties. MUST be called before connect().

Parameters:

  • topic (str) – MQTT Broker topic.

  • msg (str|int|float|bytes) – Last will disconnection msg. msgs of type int & float are converted to a string. msgs of type byetes are left unchanged, as it is in the publish function.

  • qos (int) – Quality of Service level, defaults to zero. Conventional options are 0 (send at most once), 1 (send at least once), or 2 (send exactly once). .. note:: Only options 1 or 0 are QoS levels supported by this library.

  • retain (bool) – Specifies if the msg is to be retained when it is published.

class adafruit_minimqtt.adafruit_minimqtt.NullLogger

Fake logger class that does not do anything

nothing(msg: str, *args) → None

no action