Retained Messages

Overview

Retained messages are a powerful MQTT feature that allows the broker to store the last message published to a topic and automatically deliver it to new subscribers. This ensures subscribers immediately receive the latest value without waiting for the next publish.

Only one retained message is stored per topic. Publishing a new retained message overwrites the previous one.

How Retained Messages Work

Key Characteristics

Persistence: Retained messages persist on the broker until replaced or cleared
Immediate delivery: New subscribers receive retained messages instantly
One per topic: Each topic stores at most one retained message
Flag indication: Subscribers can detect retained messages via the retain flag
QoS preserved: Retained messages maintain their QoS level

Publishing Retained Messages

Python Examples

import paho.mqtt.client as mqtt

client = mqtt.Client("retained_publisher")
client.connect("localhost", 1883)

# Publish with retain flag
client.publish(
    "devices/device001/status",
    "online",
    qos=1,
    retain=True  # Enable message retention
)

print("Retained message published")
client.disconnect()

JavaScript Examples

const mqtt = require('mqtt');
const client = mqtt.connect('mqtt://localhost:1883');

client.on('connect', () => {
  // Publish retained message
  client.publish(
    'home/livingroom/temperature',
    '22.5',
    { qos: 1, retain: true },
    (err) => {
      if (!err) {
        console.log('Retained message published');
      }
      client.end();
    }
  );
});

Java Examples

import com.hivemq.client.mqtt.mqtt5.Mqtt5BlockingClient;
import com.hivemq.client.mqtt.mqtt5.Mqtt5Client;
import com.hivemq.client.mqtt.datatypes.MqttQos;

public class RetainedPublisher {
    public static void main(String[] args) {
        Mqtt5BlockingClient client = Mqtt5Client.builder()
                .identifier("retained_publisher")
                .serverHost("localhost")
                .buildBlocking();
        
        client.connect();
        
        // Publish with retain flag
        client.publishWith()
                .topic("devices/status")
                .payload("online".getBytes())
                .qos(MqttQos.AT_LEAST_ONCE)
                .retain(true)  // Enable retention
                .send();
        
        System.out.println("Retained message published");
        client.disconnect();
    }
}

Receiving Retained Messages

Detecting Retained Messages

import paho.mqtt.client as mqtt

def on_connect(client, userdata, flags, rc):
    print("Connected, subscribing to topics")
    client.subscribe("devices/+/status", qos=1)

def on_message(client, userdata, msg):
    # Check if message is retained
    if msg.retain:
        print(f"[RETAINED] {msg.topic}: {msg.payload.decode()}")
    else:
        print(f"[LIVE] {msg.topic}: {msg.payload.decode()}")

client = mqtt.Client("retained_subscriber")
client.on_connect = on_connect
client.on_message = on_message

client.connect("localhost", 1883)
client.loop_forever()

Clearing Retained Messages

To remove a retained message, publish an empty payload with the retain flag set.

import paho.mqtt.client as mqtt

client = mqtt.Client("clear_retained")
client.connect("localhost", 1883)

# Clear retained message by publishing empty payload
client.publish(
    "devices/device001/status",
    payload="",  # Empty payload
    qos=1,
    retain=True  # Retain flag must be true
)

print("Retained message cleared")
client.disconnect()

Bulk Clear Retained Messages

import paho.mqtt.client as mqtt

retained_topics = []

def on_connect(client, userdata, flags, rc):
    # Subscribe to all topics to discover retained messages
    client.subscribe("#")

def on_message(client, userdata, msg):
    if msg.retain:
        retained_topics.append(msg.topic)
        print(f"Found retained message: {msg.topic}")

def clear_all_retained():
    client = mqtt.Client("bulk_clear")
    client.on_connect = on_connect
    client.on_message = on_message
    
    client.connect("localhost", 1883)
    client.loop_start()
    
    # Wait to collect all retained messages
    time.sleep(2)
    client.loop_stop()
    client.disconnect()
    
    # Clear each retained message
    client.connect("localhost", 1883)
    for topic in retained_topics:
        client.publish(topic, "", retain=True)
        print(f"Cleared: {topic}")
    
    client.disconnect()
    print(f"Cleared {len(retained_topics)} retained messages")

clear_all_retained()

Common Use Cases

Device Status
Configuration
Last Known Value
System State

Track online/offline status of devices:

# Device publishes status on connect
client.publish("devices/sensor001/status", "online", retain=True)

# Set Last Will Testament (LWT) to update on disconnect
client.will_set("devices/sensor001/status", "offline", retain=True)

# Monitoring dashboard always sees latest status

Distribute configuration to devices:

# Publish configuration once
config = json.dumps({"interval": 60, "threshold": 25})
client.publish("config/sensors", config, qos=2, retain=True)

# New devices get config immediately on subscribe
# No need to republish for every new device

Store last known sensor reading:

# Sensor publishes readings
client.publish(
    "sensors/temperature/current",
    "22.5",
    qos=1,
    retain=True
)

# Dashboard shows last value immediately
# Even if sensor hasn't published recently

Track system operating modes:

# Publish system mode
modes = ["NORMAL", "MAINTENANCE", "EMERGENCY"]
current_mode = "NORMAL"

client.publish(
    "system/mode",
    current_mode,
    qos=2,
    retain=True
)

# All components see current mode on startup