mqtt

network Module

Class mqtt

MQTT stands for MQ Telemetry Transport. It is a publish/subscribe, extremely simple and lightweight messaging protocol, designed for constrained devices and low-bandwidth, high-latency or unreliable networks. The design principles are to minimise network bandwidth and device resource requirements whilst also attempting to ensure reliability and some degree of assurance of delivery. These principles also turn out to make the protocol ideal of the emerging “machine-to-machine” (M2M) or “Internet of Things” world of connected devices, and for mobile applications where bandwidth and battery power are at a premium.

mqtt runs in separate thread (FreeRTOS task).

Note: When using secure connection more memory is required. If not using psRAM, you may need to lower the MicroPython heap.

---

Methods

Create mqtt instance object:

mqtt = network.mqtt(name, server [, user, password, port, autoreconnect, clientid, cleansession, keepalive, qos, retain, secure, connected_cb, disconnected_cb, subscribed_cb, unsubscribed_cb, published_cb, data_cb])

Creates the mqtt object and starts the mqtt client task.

Only the two first arguments are mandatory:

Argument	Function
name	string, mqtt identifier, used to identify the mqtt client object, for example in collback functions
server	string, mqtt server (broker) ip address or domain name

Other arguments are optional, if entered they must be entered as kw arguments (arg=value):

Argument	Function
user	string, user name if requred by mqtt server, default: ""
password	string, user password if requred by mqtt server, default: ""
clientid	string, mqtt client id, it is recomended to enter some unique ID, default: "mpy_mqtt_client"
secure	bool, if True, use secure connection, default: False
port	int, server's mqtt port, default: 1883 if secure=False, 8883 if secure=True
autoreconnect	bool, if True, reconnect to server if disconnected for some reason, default: False
cleansession	bool, if True, do not use mqtt persistent session feature, default: False
keepalive	int, Keep Alive interval in seconds, default: 120
qos	int, mqtt QoS level, default: 0
retain	bool, mqtt retain flag, default 0
connected_cb	callback function executed when mqtt is connected to the server; arguments: mqtt_name
disconnected_cb	callback function executed when mqtt is disconnected to the server; arguments: mqtt_name
subscribed_cb	callback function executed on succesful topic subscription; arguments: (mqtt_name, topic)
unsubscribed_cb	callback function executed when the topic is unsubscribed; arguments: (mqtt_name, topic)
published_cb	callback function executed when the topic is published; arguments: (mqtt_name, publish_result)
data_cb	callback function executed when new subscribed topic data arrives; arguments: (mqtt_name, topic_data_length, topic_data)

mqtt.config([clientid, autoreconnect, cleansession, keepalive, qos, retain, secure, connected_cb, disconnected_cb, subscribed_cb, unsubscribed_cb, published_cb, data_cb])

Reconfigure the mqtt client object.
All arguments are optional, if entered they must be entered as kw arguments (arg=value):

mqtt.status()

Returns the status of mqtt client task.

The status is returned as tuple: (num_stat, description).
Possible values are:
(0, "Disconnected")
(1, "Connected")
(2, "Stopping")
(3, "Stopped")

Note: Before issuing any other mqtt command it is recommended to check the mqtt status.

mqtt.subscribe(topic)

Subscribe to the topic, wait max 2 seconds.
Argument topic is string, the topic name.

Returns True if successfully subscribed, False if not.

mqtt.unsubscribe(topic)

Unsubscribe from the topic, wait max 2 seconds.
Argument topic is string, the topic name.

Returns True if successfully subscribed, False if not.

mqtt.publish(topic, msg)

Publish message to the topic.
Argument topic is string, thetopic name; msg is string, the topic message

Returns True if successfully subscribed, False if not.

mqtt.stop()

Stop the mqtt client task. Used resources are freed.

Returns True if successfully subscribed, False if not.

mqtt.start()

Start the stopped mqtt client task.

mqtt.free()

Stop the mqtt client task. Free resources and destroy the mqtt object

Returns True if successfully subscribed, False if not.

Example

def conncb(task):
    print("[{}] Connected".format(task))

def disconncb(task):
    print("[{}] Disconnected".format(task))

def subscb(task):
    print("[{}] Subscribed".format(task))

def pubcb(pub):
    print("[{}] Published: {}".format(pub[0], pub[1]))

def datacb(msg):
    print("[{}] Data arrived from topic: {}, Message:\n".format(msg[0], msg[1]), msg[2])

mqtt = network.mqtt("loboris", "loboris.eu", user="wifimcu", password="wifimculobo", cleansession=True, connected_cb=conncb, disconnected_cb=disconncb, subscribed_cb=subscb, published_cb=pubcb, data_cb=datacb)

# secure connection requires more memory and may not work
# mqtts = network.mqtt("eclipse", "iot.eclipse.org", secure=True, cleansession=True, connected_cb=conncb, disconnected_cb=disconncb, subscribed_cb=subscb, published_cb=pubcb, data_cb=datacb)

'''
# Wait until status is: (1, 'Connected')

mqtt.subscribe('test')
mqtt.publish('test', 'Hi from Micropython')

'''