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:
Adafruit CircuitPython firmware for the supported boards: https://github.com/adafruit/circuitpython/releases
Adafruit’s Connection Manager library: https://github.com/adafruit/Adafruit_CircuitPython_ConnectionManager
- exception adafruit_minimqtt.adafruit_minimqtt.MMQTTException¶
MiniMQTT Exception class.
- 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, use_imprecise_time: bool | None = 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.
use_imprecise_time (bool) – on boards without time.monotonic_ns() one has to set this to True in order to operate correctly over more than 24 days or so
- 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) int ¶
Initiates connection with the MQTT Broker. Will perform exponential back-off on connect failures.
- 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
- get_monotonic_time() float ¶
Provide monotonic time in seconds. Based on underlying implementation this might result in imprecise time, that will result in the library not being able to operate if running contiguously for more than 24 days or so.
- logger¶
An optional logging attribute that can be set with with a Logger to enable debug logging.
- loop(timeout: float = 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 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.
- 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 alist
, 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), or2
(send exactly once).
- username_pw_set(username: str, password: str | None = None) None ¶
Set client’s username and an optional password.
- will_set(topic: str | None = None, payload: int | float | str | None = None, qos: int = 0, retain: bool = False) None ¶
Sets the last will and testament properties. MUST be called before
connect()
.- Parameters:
topic (str) – MQTT Broker topic.
payload (int|float|str) – Last will disconnection payload. payloads of type int & float are converted to a string.
qos (int) –
Quality of Service level, defaults to zero. Conventional options are
0
(send at most once),1
(send at least once), or2
(send exactly once).Note
Only options
1
or0
are QoS levels supported by this library.retain (bool) – Specifies if the payload is to be retained when it is published.