micropython-mqtt

Async MQTT client library with auto reconnect for MicroPython devices such as the ESP32 or Pycom devices

Installation

Download the mqtt.py file and add it to your /libs folder

Features

The MQTTClient class is a simple lightweight MQTT client for basic MQTT pub / sub functionality. It has the following features:

Auto reconnect to the broker when the connection is lost
Supports QOS 0 and 1 for publish and subscribe
Publish, subscribe and receipt of published messages are all async
Automatically handles ping requests if no messages are sent for a period of time

Usage

See the basic-example.py file in the examples folder for a simple example of using the MQTTClient class

`from libs.mqtt import MQTTClient`

Import the MQTTClient class

`client = MQTTClient('192.168.1.1', port=1883)`

Construct a new instance of the MQTTClient class

Parameter: server - the address of the MQTT broker
- Type: string
Parameter: port - the TCP/IP port to connect to
- Type: number
Optional Parameter: reconnect_retry_time - the time in seconds between reconnect retry attempts
- Type: number
- Default: 10
Optional Parameter: keep_alive - the time in seconds of no activity before a ping is sent to the broker
- Type: number
- Default: 15
Optional Parameter: ssl - set True to use SSL
- Type: boolean
- Default: False
Optional Parameter: ssl_params - the SSL parameters to use if using SSL
- Type: object

`set_connected_callback(cb)`

Set the callback method which is fired when the connected status changes. This callback is optional

Parameter: cb - the callback method
- Type: method name
- Callback Signature: def connected_cb(status) where status is True if the client is connected or False if disconnected

`set_message_callback(cb)`

Set the callback method which is fired when a new MQTT message arrives. This callback is optional

Parameter: cb - the callback method
- Type: method name
- Callback Signature: def message_cb(topic, payload) where topic is the message topic and payload is the message payload

`set_puback_callback(cb)`

Set the callback method which is fired when a publish command succeeds. This callback is optional

Parameter: cb - the callback method
- Type: method name
- Callback Signature: def puback_cb(msg_id) where msg_id is a message ID. This can be matched with a message ID returned from the publish method to confirm that a publish has succeeded

`set_suback_callback(cb)`

Set the callback method which is fired when a subscribe command succeeds. This callback is optional

Parameter: cb - the callback method
- Type: method name
- Callback Signature: def suback_cb(msg_id) where msg_id is a message ID. This can be matched with a message ID returned from the subscribe method to confirm that a subscribe has succeeded

`set_unsuback_callback(cb)`

Set the callback method which is fired when an ubsubscribe command succeeds. This callback is optional

Parameter: cb - the callback method
- Type: method name
- Callback Signature: def unsuback_cb(msg_id) where msg_id is a message ID. This can be matched with a message ID returned from the unsubscribe method to confirm that an unsubscribe has succeeded

`connect(client_id, user=None, password=None, clean_session=True, will_topic=None, will_qos=0, will_retain=False, will_payload=None)`

Connect the MQTT client to the broker. This method is non-blocking and returns before the connection has completed.

Parameter: client_id - the ID of this MQTT client
- Type: string
Optional Parameter: user - the username used to authenticate with the broker
- Type: string
- Default: None
Optional Parameter: password - the password used to authenticate with the broker
- Type: string
- Default: None
Optional Parameter: clean_session - set true to start a clean session with the broker
- Type: boolean
- Default: True
Optional Parameter: will_topic - the last will and testament topic.
- Type: string
- Default: None
Optional Parameter: will_qos - the last will and testament QOS level. QOS values of 0, 1 and 2 are valid
- Type: number
- Default: 0
Optional Parameter: will_retain - the last will and testament message retain flag
- Type: boolean
- Default: False
Optional Parameter: will_payload - the last will and testament message payload
- Type: string
- Default: None

`disconnect()`

Disconnect the MQTT client from the broker

`isconnected()`

Get the status of the connection between the MQTT client and broker

Returns: True if the client is connected, else False

`publish(topic, payload, retain=False, qos=0)`

Publish an MQTT message to the broker

Parameter: topic - the message topic
- Type: string
Parameter: payload - the message payload
- Type: string
Optional Parameter: retain - the message retain flag
- Type: boolean
- Default: False
Optional Parameter: qos - the message QOS level. QOS values of 0 and 1 are valid. This library does not currently support QOS 2
- Type: number
- Default: 0
Returns: QOS = 0, None. QOS = 1, the publish message ID. This can be used with the set_puback_callback to verify that a message has been published
Raises: MQTTException if the message cannot be published

`subscribe(topic, qos=0)`

Subscribe to an MQTT topic

Parameter: topic - the topic to subscribe to. MQTT wildcards can be used
- Type: string
Optional Parameter: qos - the subscription QOS level. QOS values of 0 and 1 are valid. This library does not currently support QOS 2
- Type: boolean
- Default: False
Returns: the subscribe message ID. This can be used with the set_suback_callback to verify that a subscription was successful
Raises: MQTTException if the subscribe message cannot be sent

`unsubscribe(topic)`

Unsubscribe from an MQTT topic

Parameter: topic - the topic to unsubscribe from. MQTT wildcards can be used
- Type: string
Returns: the unsubscribe message ID. This can be used with the set_unsuback_callback to verify that an unsubscription was successful
Raises: MQTTException if the unsubscribe message cannot be sent

chrismoorhouse / micropython-mqtt