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, socket_pool=None, ssl_context=None)

MQTT Client for CircuitPython. :param str broker: MQTT Broker URL or IP Address. :param int port: Optional port definition, defaults to 8883. :param str username: Username for broker authentication. :param str password: Password for broker authentication. :param network_manager: NetworkManager object, such as WiFiManager from ESPSPI_WiFiManager. :param str client_id: Optional client identifier, defaults to a unique, generated string. :param bool is_ssl: Sets a secure or insecure connection with the broker. :param int keep_alive: KeepAlive interval between the broker and the MiniMQTT client. :param socket socket_pool: A pool of socket resources available for the given radio. :param ssl_context: SSL context for long-lived SSL connections.

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) – Name of callback method.
connect(clean_session=True, host=None, port=None, keep_alive=None)

Initiates connection with the MQTT Broker. :param bool clean_session: Establishes a persistent session. :param str host: Hostname or IP address of the remote broker. :param int port: Network port of the remote broker. :param int keep_alive: 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(logger, log_level=20)

Enables library logging provided a logger object. :param logger: A python logger pacakge. :param log_level: Numeric value of a logging level, defaults to INFO.

is_connected()

Returns MQTT client session status as True if connected, raises a MMQTTException if False.

loop(timeout=1)

Non-blocking message loop. Use this method to check incoming subscription messages. Returns response codes of any messages received. :param int timeout: Socket timeout, in seconds.

mqtt_msg

Returns maximum MQTT payload and topic size.

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. :param str topic: Unique topic identifier. :param str,int,float,bytes msg: Data to send to the broker. :param bool retain: Whether the message is saved by the broker. :param int qos: Quality of Service level for the message, defaults to zero.

reconnect(resub_topics=True)

Attempts to reconnect to the MQTT broker. :param bool resub_topics: 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. :param str,list topic: Unique MQTT topic identifier string or list.

username_pw_set(username, password=None)

Set client’s username and an optional password. :param str username: Username to use with your MQTT broker. :param str password: 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. :param sock: socket object. :param iface: internet interface object