MQTT Retained Message Workbench

See how an MQTT broker stores the latest retained message per topic and sends current state to new subscribers.

Learner-ready MQTT retained message workbench with retained store animation, overwrite and clear behavior, wildcard topic-filter matching, MQTT 5 retain handling, QoS cap feedback, source links, and local desktop/mobile visual verification.

MQTT Retained Messages Initial State

MQTT Retained Message Workbench

A retained message is the broker's latest saved state for one exact topic. Publish with the retain flag to store or overwrite it, subscribe later to receive matching retained state immediately, and clear stale state with an empty retained publish.

Current scenario Device state startup

Broker action Store retained state

New subscriber Receives one retained message

Best use Current state, not events

1. Store state

The broker keeps the latest retained application message for each exact topic name. A new retained publish replaces the previous one.

2. Start subscribers fast

A dashboard can subscribe after the device published and still receive current state immediately, subject to the subscription filter.

3. Clear stale values

A retained publish with a zero-byte payload removes the retained message for that topic. This prevents old devices from appearing alive.

4. Avoid event traps

Retained messages are poor event history. Use them for "pump is running" rather than "button was pressed at 09:10".

1Prepare PUBLISH

2Route through broker

3Update retained slot

4New subscriber joins

5Send initial state

6Check design fit

Prepare the publish

Choose whether this message should be stored as current state, sent as a live event, or used to clear a stale retained value.

RETAIN

P

Publisher

Publishes a topic, payload, QoS, and retain flag.

Topic
devices/pump-7/status Payload
online Publish QoS
QoS 1

B

Broker

Routes live messages and keeps retained slots by exact topic name.

Retained store after publish

S

New subscriber

Subscribes with a topic filter and maximum QoS.

Filter
devices/pump-7/status Maximum QoS
QoS 1

Initial retained delivery

Scenario presets

Publish action Retained publish: store current state Normal publish: live only Clear retained: empty retained payload

Topic devices/pump-7/status home/lab/temperature factory/door-3/event fleet/truck-42/location plant/line-a/pump-7/status devices/node-12/status

Publish QoS QoS 0 QoS 1 QoS 2

Payload

Subscriber topic filter

Subscriber maximum QoS QoS 0 QoS 1 QoS 2

Subscription action New subscription Existing subscription changes

MQTT 5 retain handling Send retained messages on subscribe Send only if the subscription is new Do not send retained messages

Broker action Stores retained state

The topic will have one saved retained message.

Subscription match 1 retained topic matches

The filter matches the exact topic.

Delivery QoS Delivered at QoS 1

Delivery is capped by the subscriber maximum QoS.

Design diagnosis Good retained use

This represents current state and helps late subscribers.

Quick Reference

Use these cards to decide when retained messages are appropriate before using them in a system design.

What is stored?

The broker stores the latest retained application message for an exact topic name. It is a current-state snapshot, not a log.

What does a subscriber get?

When a subscription is established, the broker sends retained messages whose topic names match the subscription filter, unless MQTT 5 retain handling suppresses them.

How is it cleared?

Publish a retained message with a zero-byte payload to the exact topic. That removes the retained value for that topic.

Learning Support: How to read the animation

• Watch the packet label. Orange means a retained publish, teal means a normal live-only publish, and red means a retained clear.
• Look at the broker store. A retained publish creates or overwrites one slot. A normal publish leaves the store unchanged.
• Change the subscriber topic filter to test exact matches, single-level wildcards with +, and multi-level wildcards with #.
• Use the MQTT 5 retain-handling control to see why some subscribers intentionally skip retained messages.

Design Checks

These common decisions separate useful retained state from confusing stale events.

Use retained for state

Good examples are device status, latest sensor reading, current configuration, or last known location. Late subscribers need these values immediately.

Avoid retained for events

Commands, alerts, button presses, and door-open events can become misleading when replayed later. Use event topics, logs, or command acknowledgement patterns instead.

Pair with presence carefully

A common pattern is retained birth message "online" plus a retained Last Will "offline". Clear retained state when a device is permanently removed.

Technical Notes And Source Links

• MQTT stores one retained message per topic. A later retained publish to the same topic replaces the earlier retained message.
• The retained message keeps its stored QoS, but delivery to a subscriber is limited by the subscriber's maximum QoS for that subscription.
• MQTT 5 adds retain-handling subscription options: send retained on subscribe, send only for a new subscription, or do not send retained messages.
• Retained messages are independent from persistent sessions. Persistent sessions store subscriptions and queued messages for a client; retained messages are per-topic broker state.

OASIS MQTT 5.0 specification OASIS MQTT 3.1.1 specification

Practice Prompts

Try these short checks without leaving the page.

Cold-start dashboard

Set the scenario to Device state startup, press Step until the subscriber joins, then change the filter so it no longer matches. What disappears and why?

Stale event warning

Set the scenario to Event without retain, then switch the publish action to retained. Why does the diagnosis warn against this design?