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:

  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” for any client who subscribes.
  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. 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 “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
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.