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
- exception adafruit_minimqtt.adafruit_minimqtt.MMQTTException¶
MiniMQTT Exception class.
- class adafruit_minimqtt.adafruit_minimqtt.MQTT(*, broker, port=None, username=None, password=None, client_id=None, is_ssl=True, keep_alive=60, recv_timeout=10, socket_pool=None, ssl_context=None, use_binary_mode=False, socket_timeout=1, connect_retries=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 broker before giving up.
user_data (class) – arbitrary data to pass as a second argument to the callbacks.
- add_topic_callback(mqtt_topic, callback_method)¶
Registers a callback_method for a specific MQTT topic.
- Parameters:
mqtt_topic (str) – MQTT topic identifier.
callback_method (function) – The callback method.
- connect(clean_session=True, host=None, port=None, keep_alive=None)¶
Initiates connection with the MQTT Broker.
- deinit()¶
De-initializes the MQTT client and disconnects from the mqtt broker.
- disable_logger()¶
Disables logging.
- disconnect()¶
Disconnects the MiniMQTT client from the MQTT broker.
- enable_logger(log_pkg, log_level=20, logger_name='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()¶
Returns MQTT client session status as True if connected, False if not.
- loop(timeout=0)¶
Non-blocking message loop. Use this method to check incoming subscription messages. Returns response codes of any messages received.
- Parameters:
timeout (int) – Socket timeout, in seconds.
- property mqtt_msg¶
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)
- ping()¶
Pings the MQTT Broker to confirm if the broker is alive or if there is an active network connection. Returns response codes of any messages received while waiting for PINGRESP.
- publish(topic, msg, retain=False, qos=0)¶
Publishes a message to a topic provided.
- reconnect(resub_topics=True)¶
Attempts to reconnect to the MQTT broker.
- Parameters:
resub_topics (bool) – Resubscribe to previously subscribed topics.
- remove_topic_callback(mqtt_topic)¶
Removes a registered callback method.
- Parameters:
mqtt_topic (str) – MQTT topic identifier string.
- subscribe(topic, qos=0)¶
Subscribes to a topic on the MQTT Broker. This method can subscribe to one topics 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).
- unsubscribe(topic)¶
Unsubscribes from a MQTT topic.
- username_pw_set(username, password=None)¶
Set client’s username and an optional password.
- will_set(topic=None, payload=None, qos=0, retain=False)¶
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.
- adafruit_minimqtt.adafruit_minimqtt.set_socket(sock, iface=None)¶
Legacy API for setting the socket and network interface.
- Parameters:
sock – socket object.
iface – internet interface object