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

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.

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, in seconds.

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.

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=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 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)

Unsubscribes from a MQTT topic.

Parameters:

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

username_pw_set(username, password=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=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), or 2 (send exactly once).

    Note

    Only options 1 or 0 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