Examining MQTTv5 User Properties

user-propertiesProperties (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

If you are familiar with http it looks very similar to how http headers work.

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
  • Timestamp
  • 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.


Related Tutorials:

Please rate? And use Comments to let me know more
[Total: 0   Average: 0/5]

One comment

  1. Great documentation, thank you very much.
    I’d like to add the following creation code concering the user property to work:
    publish_properties = mqtt.Properties(PacketTypes.PUBLISH)
    publish_properties.UserProperty = (“MessageType”, “DeviceCreationRequest”)
    self.mqttClient.publish(topic,payload=payload, qos=0, retain=False, properties=publish_properties)

    Hope it might help others

Leave a Reply

Your email address will not be published. Required fields are marked *