MQTT Retained Messages Animation

Interactive Visualization of Message Persistence and Initial State Delivery

animation

mqtt

protocols

persistence

In 60 Seconds

MQTT retained messages allow the broker to store the last message published to a topic with the retain flag set, then automatically deliver it to any new subscriber. This ensures new clients immediately receive the current device state without waiting for the next publish, which is essential for IoT dashboards and monitoring.

MQTT Retained Messages

This interactive animation demonstrates how MQTT retained messages provide initial state to new subscribers. Watch how the broker stores retained messages and delivers them immediately when new clients subscribe.

Animation Overview

This animation shows the MQTT retained message mechanism:

Publisher (left): IoT device publishing messages with retain flag
Broker (center): Stores retained messages by topic
Subscribers (right): Clients that receive retained messages upon subscribing
Immediate Delivery: New subscribers receive last retained message instantly

How to Use This Animation

Click “Publish Retained” to publish a message with the retain flag set
Use “Add Subscriber” to see new subscribers receive the retained message immediately
Use “Publish Normal” to see a message without retention (not stored)
Click “Clear Retained” to remove the retained message from the broker
Watch how the broker persists and delivers retained messages to new subscribers

Understanding Retained Messages

The animation above demonstrates MQTT’s retained message mechanism for providing initial state to new subscribers:

Scenario	What Happens	New Subscriber Gets
Retained message exists	Broker stores last message with retain=true	Immediate delivery of stored message
No retained message	Normal messages only delivered to connected clients	Nothing (waits for next publish)
Clear retained	Publish with retain=true and empty payload	Nothing (retained cleared)

How Retained Messages Work

Publisher sends with retain=true: Message flagged for persistence
Broker stores: Keeps ONE retained message per topic (overwrites previous)
Normal subscribers: Receive message like any other publish
New subscriber joins: Immediately receives the stored retained message
Initial state available: New clients know current state without waiting

Retained Message Use Cases

Retained messages solve the “cold start problem” - when a new subscriber needs to know the current state immediately:

Use Case	Topic	Retained Value
Temperature sensor	`home/livingroom/temp`	`"22.5"`
Device status	`devices/sensor-01/status`	`"online"`
Configuration	`config/update-interval`	`"60"`
Last known position	`fleet/truck-42/location`	`{"lat":51.5,"lon":-0.1}`

Best Practices for Retained Messages

Use for state topics: Sensor readings, device status, configuration
Don’t use for events: Commands, notifications, alerts (use normal messages)
Pair with LWT: Device publishes "online" retained on connect; LWT publishes "offline" retained
Clear when removing devices: Publish empty payload to remove stale retained messages
Keep payloads small: Retained messages consume broker memory

Retain Flag Behavior

# Python example using paho-mqtt

# Publish retained message (stored by broker)
client.publish(
    topic="sensors/temperature",
    payload="22.5",
    qos=1,
    retain=True  # <-- Broker stores this
)

# Publish normal message (NOT stored)
client.publish(
    topic="sensors/temperature",
    payload="23.0",
    qos=1,
    retain=False  # <-- Only delivered to current subscribers
)

# Clear retained message (empty payload)
client.publish(
    topic="sensors/temperature",
    payload="",   # <-- Empty payload
    qos=1,
    retain=True   # <-- With retain=True clears the stored message
)

Retain Flag	Payload	Broker Action
`true`	Non-empty	Store/overwrite retained message
`true`	Empty (`""`)	Clear retained message for topic
`false`	Any	Do not store (deliver to connected only)

Important Limitations

One per topic: Broker stores only ONE retained message per topic (new overwrites old)
Memory usage: Many retained topics increase broker memory footprint
Not a database: Use for current state only, not historical data
QoS applies: Retained messages respect QoS for delivery guarantees
Session handling: Clean session may affect retained message delivery timing

Retained vs Non-Retained Comparison

Aspect	Retained Message	Normal Message
Storage	Broker stores last message	No storage
New subscribers	Receive immediately	Wait for next publish
Use case	Current state, status	Events, commands
Memory	Uses broker memory	No memory overhead
Clear mechanism	Empty payload with retain=true	N/A

What’s Next

MQTT Pub/Sub Animation - Topic-based message routing
MQTT LWT Animation - Device presence monitoring
MQTT QoS Levels - Delivery guarantees
Simulations Hub - More interactive visualizations

Animation Technical Details

This animation demonstrates:

Retained flag visualization: Orange packets with “R” badge indicate retain=true
Broker storage: Visual indicator shows retained message stored at broker
Immediate delivery: New subscribers receive retained message right after SUBACK
Normal vs retained: Teal packets for normal, orange for retained
Clear mechanism: Red packet shows clearing retained with empty payload
State persistence: Retained value persists across subscriber additions

The implementation uses D3.js transitions for smooth animations and follows the IEEE color palette for consistency with the textbook.

Common Pitfalls

Pitfall 1: Using Retained Messages for Events or Commands Retained messages store the LAST message only. If you use retained for door open/close events, a new subscriber might see “door opened” even though the door closed afterward and the system is now idle. Use retained for current state, not historical events.

Pitfall 2: Forgetting to Clear Retained Messages When Removing Devices When a sensor is decommissioned, its last retained message persists indefinitely. New subscribers receive stale data like “22.5C” from a sensor that no longer exists. Always publish an empty payload with retain=true to clear the message when removing devices.

Pitfall 3: Confusing Retained Flag with Persistent Sessions Retained messages and persistent sessions are independent features. A retained message is stored by the broker per-topic. A persistent session stores subscriptions and queued messages per-client. You might need both, one, or neither depending on your use case.

Pitfall 4: Expecting Multiple Retained Messages Per Topic The broker stores exactly ONE retained message per topic (the most recent). Publishing a new retained message overwrites the previous one. If you need history, use a database or time-series store, not MQTT retained messages.