User properties allow you to add your own meta data to MQTT messages.
User properties consist of an array of user defined UTF-8 key/value pairs and are carried in the message property field.
This means if you want to include numbers they need to be converted to strings.
User Properties effectively allow the user to extend the MQTT protocol, and can be present in all messages and responses.
Because user properties are user defined they only have meaning to that user implementation.
User properties can be sent between client and server and client to client depending on the message type used to send them.
User properties can be sent in various message types. User Properties set in the connection message for example aren’t passed on to the receiving client, whereas user properties set in the publish message are sent to the receiving client.
Connection User Properties
Connection message user defined properties are sent from client to server, and they are not transmitted on to the receiving client.
They are used to send connection related information to the server.
The server must be able to use these properties, and so these properties would be defined by the server, and so are server dependent.
Publish User Properties
These are probably the most useful as they are transmitted to the receiving client.
They will be most probably be used for sending meta data between clients. e.g
- Message numbering
- Routing information
To illustrate I have a simple publish and subscribe script that use a client to publish and another client to receive the message.
User properties are set as an array of key/value pairs as you can clearly see in the code below.
The publisher sets user properties using the code below
print("sending message user properties set") client_pub.publish("test/mqtt","test message",\ user_property=[('sfilename', 'test.txt'),('dfilename', 'test.txt')])
It could be used for example for file transfer where the file names are sent in the user properties and the file contents in the payload.
The screen shot below shows what is received.
This tutorial show you how to Send a File Using MQTTv3.1.1 and Python without user properties.
User Properties Python Code
Here is the code that creates the user properties
print("sending message user properties set") properties=Properties(PacketTypes.PUBLISH) count="1" properties.UserProperty=[("filename","test.txt"),("count",count)] client_pub.publish("test/mqtt","test message",properties=properties)
Decoding Received User Properties
below is the on_message callback were we extract the user properties for the incoming message. You should notice that the user properties are part of the message properties.
def on_message(client, userdata, message): msg=str(message.payload.decode("utf-8")) messages.append(msg) print("correlation=",message.properties) print('RECV Topic = ',message.topic) print('RECV MSG =', msg) print("properties received= ",message.properties) user_properties=message.properties.UserProperty print("user properties received= ",user_properties)
Here is a screen shot of the output.
The addition of properties field was probably the most significant change in the MQTT protocol, and allowed much more control information to be exchanged, and importantly user defined control information using user properties.
Download Scripts Used in MQTTV5 Tutorials
- MQTT v 5.0 New Features Overview
- Paho Python MQTT Client Changes for MQTTv5 Support
- MQTT Client and Mosquitto Broker Message Restrictions With Examples
- Understanding And Using MQTT v5 Request Response
- MQTTv5 CONNECT and CONNACK Messages -Overview