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 recieve any of the messages published on it before subscription. If a client publishes a message to a topic with the retain flag set to True then the broker will save that message as the “Last Good Message” on that topic. This message will be received by any client who subscribes to that topic.

This is a part of a series explaining the different concepts of MQTT. If you are new to MQTT, please read the Fundaments of MQTT first. 

How MQTT Retained Messages work

Lets take 4 MQTT clients, 3 that subscribe and the 4th that publishes with retained message flag. You can follow these flow of events in order:

  1. Client 1 publishes the message “Online” to a topic “device1/status” with retain flag set to True.
  2. Broker stores that message on the topic “device1/status” as the Last Good Message.
  3. Client 2 subscribes to the topic “device1/status”. As soon as it subscribes it will receive the message “Online”.
  4. Client 1 publishes the message “Offline” to the same topic with retain flag set to True.The broker replaces the message “Online” with “Offline” as the Last Good Message. Client 2 receives the message as its already subscribed.
  5. Client 3 subscribes to the same topic and receives the message “Offline” as soon as it subscribes. 
  6. 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.
  7. Client 4 subscribes to the topic. This time client 4 will receive the message “Offline” as it was the last message sent with retain flag set to True. It will not recieve the message “Online” as the broker did not store it.

I hope this flow of events helps you understand Retained Messages in MQTT.

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
or
“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.