Did you know that the MQTT broker can store new messages & subscription for a client after it goes offline? It will then send the messages as soon as the client reconnects. This feature in MQTT is called persistent session. In this post, I will explain how it works.
See Also:
Fundamentals of MQTT
MQTT Python With Paho-MQTT Client

Persistent Session or Clean Session

Lets say you have 2 clients connected to a broker. One client is publishing to a topic and the other client is suscribed to that topic. If the client that has subscribed suddenly disconnects from the broker, it will not recieve any of the messages published to that topic, until it reconnects.

To solve this problem we use a Persistent Session or a Clean Session. When a client connects to the broker it can request the broker for a persistent session. The broker will store the client information and the topics it has subscribed to. When the client reconnects after a disconnection, the broker will send all undelivered messages to the client. The broker stores these undelivered messages in a message queue.

How to use a Persistent Session?

A persistent session can be started by the client by setting the cleanSession flag to False when the client connects to the broker. By default this value is set to True.

For a persistent session to work you must note:

  • The broker uses the client ID to recognize clients for a persistent session. So make sure you use a set and use a unique client ID for each client.
  • You need to subscribe to the topics with a QoS level of 1 or 2. Only then the broker will publish the undelivered messages.
    See: MQTT QoS Levels Explained
  • The messages also must be published to that topic with QoS Level 1 or 2. The broker will not deliver messages if a client publishes messages with QoS Level 0.
  • If the retain flag is set to True when publishing a message, the client who has a persistent session will still get all the messages.

When to use a Persistent Session?

It is important to use a Persistent Session when:

  • The client has to recieve all the messages from a topic that it has subscribed to.
  • When internet of the client that has subscribed to a topic is bad.

Do not use Persistent Session for a client that is only publishing!


How many messages can be queued by the broker?

The broker stores the messages in the primary memory. So the maximum number of messages that can be stored by a broker depends on th primary memory.

Mosquitto by default stores upto 100 messages. This setting can be changed.

How do I set a client that is already connected to a broker to have a Persistent Session?

You will need to disconnect the client and reconnect it with the cleanSession flag set to True.