Welcome to the eighth part of MQTT Essentials. A ten-part blog series on the core features and concepts of the MQTT protocol. This post introduces retained messages. At the end of this blog post you will find a video on the same topic.

In MQTT, the client that publishes a message has no guarantee that a subscribing client actually receives the message. The publishing client can only make sure that the message gets delivered safely to the broker. Basically, the same is true for a subscribing client. The client that connects and subscribes to topics has no guarantee on when the publishing client will publish a message in one of their topics of interest. It can take a few seconds, minutes, or hours for the publisher to send a new message in one of the subscribed topics. Until the next message is published, the subscribing client is totally in the dark about the current status of the topic. This situation is where retained messages come into play.

Get the MQTT Essentials eBook

72 pages of MQTT education and learning for beginners and experts alike.

Get eBook

Retained Messages

A retained message is a normal MQTT message with the retained flag set to true. The broker stores the last retained message and the corresponding QoS for that topic. Each client that subscribes to a topic pattern that matches the topic of the retained message receives the retained message immediately after they subscribe. The broker stores only one retained message per topic.

If the subscribing client includes wildcards in the topic pattern they subscribe to, it receives a retained message even if the topic of the retained message is not an exact match. Here’s an example: Client A publishes a retained message to myhome/livingroom/temperature. Sometime later, client B subscribes to myhome/#. Client B receives the myhome/livingroom/temperature retained message directly after subscribing to myhome/#. Client B (the subscribing client) can see that the message is a retained message because the broker sends retained messages with the retained flag set to true. The client can decide how it wants to process the retained messages.

Retained messages help newly-subscribed clients get a status update immediately after they subscribe to a topic. The retained message eliminates the wait for the publishing clients to send the next update.

In other words, a retained message on a topic is the last known good value. The retained message doesn’t have to be the last value, but it must be the last message with the retained flag set to true.

It is important to understand that a retained message has nothing to do with persistent sessions (a subject that we covered last week). Once a retained message is stored by the broker, there’s only one way to remove it. Keep reading to find out how.

Send a retained message

From the perspective of a developer, sending a retained message is quite simple and straight-forward. You just set the retained flag of an MQTT publish message to true. Typically, your client library provides an easy way to set this flag.

Delete a retained message

There is also a very simple way to delete the retained message of a topic: send a retained message with a zero-byte payload on the topic where you want to delete the previous retained message. The broker deletes the retained message and new subscribers no longer get a retained message for that topic. Often, it is not even necessary to delete, because each new retained message overwrites the previous one.

Why and when should you use Retained Messages?

A retained message makes sense when you want newly-connected subscribers to receive messages immediately (without waiting until a publishing client sends the next message). This is extremely helpful for status updates of components or devices on individual topics. For example, the status of device1 is on the topic myhome/devices/device1/status. When retained messages are used, new subscribers to the topic get the status (online/offline) of the device immediately after they subscribe. The same is true for clients that send data in intervals, temperature, GPS coordinates, and other data. Without retained messages, new subscribers are kept in the dark between publish intervals. Using retained messages helps provide the last good value to a connecting client immediately.

That’s the end of part eight in our MQTT Essentials series. We hope you enjoyed it. In the next post, we talk about a feature called Last Will and Testament. This feature makes it possible to send a last message when a client disconnects abruptly.

If you would like to get notified about each new post as soon as it is available, use the subscription form to sign up for our newsletter. If you prefer RSS, you can subscribe to our RSS feed here. Do check out MQTT Glossary to know all the key MQTT terminologies.

About The HiveMQ Team

We love writing about MQTT, IoT protocols and architecture in general. Our experts are here to help, so reach out to us if we can help!
Contact us