The Paho Python client version 1.5.1 included support for MQTTv5. Because of the new capabilities of MQTTv5 there have been changes to many of the common functions like connect,subscribe and publish etc.
The aim of this tutorial is to point out the main changes, and what you need to do in your code to use the new features.
MQTT Protocol Version
If you want to use the new MQTTv5 capabilities then is important to specify the protocol version you want to use. Supported versions are:
- MQTTv31 = 3
- MQTTv311 = 4
- MQTTv5 = 5
Therefore when creating the client for MQTTv5 use:
client = mqtt.Client("mqtt5_client",protocol=MQTTv5)
connect(host, port=1883, keepalive=60, bind_address="")
connect(self, host, port=1883, keepalive=60, bind_address="", bind_port=0, clean_start=MQTT_CLEAN_START_FIRST_ONLY, properties=None)
The most important addition is the properties object.
The properties object is present in other function calls, and so it is important to understand how to use it and we cover this next.
The properties object varies according to what function you will use it in.
To use it in the connection function you first need to import the properties class and then create a properties object using the following syntax:
The following are the available packet types (taken from the code:
CONNECT, CONNACK, PUBLISH, PUBACK, PUBREC, PUBREL,
PUBCOMP, SUBSCRIBE, SUBACK, UNSUBSCRIBE, UNSUBACK,
PINGREQ, PINGRESP, DISCONNECT, AUTH
In addition you will need to set property attributes. In the example code below we set the maximum packet size the client can receive.
Because this is done in the connection message we use the Connect packet type:
Once we have the properites object we set the attributes as shown in the code below:
from paho.mqtt.properties import Properties from paho.mqtt.packettypes import PacketTypes properties=Properties(PacketTypes.CONNECT) properties.MaximumPacketSize=20 client.connect(host,port,properties=properties)
To make your code work with both MQTTv5 and MQTTv3.1.1 you need to set the properties object to None when using MQTTv3.1.1
So Instead of
you would use
Note: MQTTv5 Properties by Message Type has list of property fields that are available in the connection message and other message types.
Connect Acknowledge Callback Function
The server can return lots of information in the properties field of the CONNACK message and so the callback function must include it. Below shows CONNACK callbacks for v3.1.1 and v5 as defined in the latest client code..
Old signature for MQTT v3.1 and v3.1.1 is: on_connect(client, userdata, flags, rc) signature for MQTT v5.0 client: on_connect(client, userdata, flags, reasonCode, properties=None)
Notice the extra properties field.
However existing code written for v3.1.1 used the following callback signature:
connect(client, userdata, flags, rc)
This will still work with MQTTv3.1.1 but you will get an error with MQTTv5
To make the callback work with v3.1.1 and v5 connections use:
on_connect(client, userdata, flags, rc, properties=None)
The following functions have also changed and you need to use the same logic as described above.
Subscribe and Subscribe Callback
MQTT v3.1.1 and v3.1
and for MQTT v5.0:
subscribe(self, topic, qos=0, options=None, properties=None)
Old signature for MQTT v3.1.1 and v3.1 is: on_ subscribe(client, userdata, mid, granted_qos) and for the MQTT v5.0 client: on_subscribe(client, userdata, mid, granted_qos, properties=None)
Old signature for MQTT v3.1.1 and v3.1 is: unsubscribe_callback(client, userdata, mid) and for the MQTT v5.0 client: unsubscribe_callback(client, userdata, mid)
Old signature for MQTT v3.1.1 and v3.1 is: publish(self, topic, payload=None, qos=0, retain=False) and for the MQTT v5.0 client: publish(self, topic, payload=None, qos=0, retain=False, properties=None)
Changes in the MQTTv5 protocol mean that you will need to make script changes if you want your old code to work with both protocols.
Resources and Related Tutorials
- MQTTv5 Properties by Message Type
- MQTTv5 Shared Subscriptions
- MQTTv5 Topics and Topic Aliases
- Examining MQTTv5 User Properties
- MQTTv5 CONNECT and CONNACK Messages -Overview
- Understanding And Using MQTT v5 Request Response
- MQTT v 5.0 New Features Overview
- MQTTv5 Clean Start (Clean Sessions) and Session Expiry
- MQTTv5 Last Will and Testament