Retained messages is used to store the “Last Good Message” on a topic. Usually, If an MQTT client subscribes to a topic on a broker it will not see any of the old messages published on it. If a client publishes to a topic with the retain flag set to True then the broker will save the last message published with that flag.
How MQTT Retained Messages work
Lets take 4 MQTT clients, 3 that subscribe and the other that publishes with retained message flag. You can follow these flow of events in order:
- Client 1 publishes the message “Online” to a topic “device1/status” with retain flag set to True.
- Broker stores that message on the topic “device1/status” for any client who subscribes.
- Client 2 subscribes to the topic “device1/status”. As soon as it subscribes it will receive the message “Online”.
- Client 1 publishes the message “Offline” to the same topic with retain flag set to True. Client 2 receives the message as its already subscribed.
- Client 3 subscribes to the same topic and receives the message “Offline” as soon as it subscribes.
- Client 1 publishes the message “Online” to the same topic but this time with retain flag set to False. Client 2 & 3 recieves the message as its already subscribed.
- Client 4 subscribes to the topic. This time client 4 will receive the message “Online” as it was the last message sent with retain flag set to True.
I hope you get from this flow of events how Retained messages work. This is part of a series explaining different concepts of MQTT. If you are new to MQTT, please read the Fundaments of MQTT first.
How does QoS affect Retained Messages?
Short answer: it doesn’t. A client can publish or subscribe with any QoS level, the retained message will only get printed if the message is published with retain flag set to true.
If a client publishes with QoS 1 or 2 and a client has subscibed with QoS 1 or 2, then all the messages will be saved including the retained messages
How to delete a retained message?
To delete a retained message from a topic, a client must either replace it with another message with retain flag set to True OR a client must publish a blank message with retain flag set to True on that topic. This is the only way to delete a retained message.
When to use Retained messages?
Use retained message to update the status of a device on a topic. For example:
“device1/status” can be Offline/Online
“kitchenlights/status” can be “On/Off”.
Retained messages can be combined with the Last Will & Testament feature in MQTT. See more about that here:
MQTT Last Will And Testament (Explained with Example)
Example Using Paho-MQTT Python Client
This example assumes you know the basics of Paho-MQTT. If not see this post:
MQTT Python With Paho-MQTT Client (Step-by-Step Guide With Examples)
To publish a retained message on Paho simply set the retain flag to True while publishing:
publish(topic, payload=None, qos=0, retain=True)
To test this make sure the client subscribes AFTER the retained message is published.