Communicate over MQTT topics
Use the Python Link software development kit (SDK) to subscribe to topics, publish messages, and unsubscribe from topics on IoT Platform over MQTT. This topic covers the full request-and-confirm flow for each operation.
Topic format
A topic is a communication channel between a device and IoT Platform. Devices use topics to send and receive messages.
Topics use forward slashes (/) to define a hierarchy and separate categories. The first three levels of a custom topic are predefined:
|
Level |
Value |
Description |
|
1 |
ProductKey |
Identifies the product |
|
2 |
|
Wildcard for the DeviceName |
|
3 |
user |
Identifies the custom topic category |
For more information, see What is a topic?.
Receive messages from the cloud
Call subscribe_topic() to subscribe to a topic:
rc, mid = lk.subscribe_topic(topic, qos=1) In the mqtt_sub_pub_on.py demo, call lk.to_full_topic("user/test") to generate a topic string. The to_full_topic API uses the ProductKey and DeviceName you specified and returns a string equivalent to /YourProductKey/YourDeviceName/user/test.
The subscription result is returned in the on_subscribe_topic callback:
lk.on_subscribe_topic = on_subscribe_topic
def on_subscribe_topic(mid, granted_qos, userdata):
print("on_subscribe_topic mid:%d, granted_qos:%s" %
(mid, str(','.join('%s' % it for it in granted_qos))))
pass
granted_qos is the Quality of Service (QoS) level granted for the subscribed topic:
|
Value |
Meaning |
|
|
Subscription succeeded. |
|
|
Subscription failed. |
Receive and process messages from the cloud
Incoming messages trigger the on_topic_message() callback:
lk.on_topic_message = on_topic_message
def on_topic_message(topic, payload, qos, userdata):
print("on_topic_message:" + topic + " payload:" + str(payload) + " qos:" + str(qos))
pass
Send messages to the cloud
In Python Link SDK versions 1.0.0 to 1.2.11, if the device disconnects from IoT Platform, calling the publish API throws an exception that you must handle. In versions 1.2.12 and later, the API returns a non-zero error value instead of throwing an exception.
Send a message
Call publish_topic() to publish a message to the cloud:
rc, mid = lk.publish_topic(topic, payload) Publish result notification
The on_publish_topic callback confirms whether the cloud received the message:
lk.on_publish_topic = on_publish_topic
def on_publish_topic(mid, userdata):
print("on_publish_topic mid:%d" % mid)
An rc value of 0 from publish_topic means the request was written to the send buffer. A successful on_publish_topic callback then confirms the publish succeeded.
Unsubscribe from a topic
In Python Link SDK versions 1.0.0 to 1.2.11, if the device disconnects from IoT Platform, calling the unsubscribe API throws an exception that you must handle. In versions 1.2.12 and later, the API returns a non-zero error value instead of throwing an exception.
Call unsubscribe_topic() to unsubscribe from a specific topic:
rc, mid = lk.unsubscribe_topic(topic) The unsubscribe result is returned in the on_unsubscribe_topic callback:
lk.on_unsubscribe_topic = on_unsubscribe_topic
def on_unsubscribe_topic(mid, userdata):
print("on_unsubscribe_topic mid:%d" % mid)
pass
An rc value of 0 from unsubscribe_topic means the request was written to the cache buffer. Any other value indicates a failure. A successful on_unsubscribe_topic callback then confirms the unsubscribe succeeded.