Properties (MQTTv5) are probably one of the most important additions to the MQTT protocol, and are available in most MQTT message types.
The property fields are dependent upon message type, so a CONNECT message will have different property fields than a PUBLISH message.
Here is a list of properties by message type.
The User Property field is part of the properties field and consists of a series of UTF-8 key/value pairs. 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 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.
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.
- MQTT v 5.0 New Features Overview
- MQTT Client and Mosquitto Broker Message Restrictions With Examples
- Understanding And Using MQTT v5 Request Response
- MQTTv5 CONNECT and CONNACK Messages -Overview