MQTT Retained Message

EMQX implements the retained message feature of MQTT. You can flag one message published under a certain topic as Retained and save it as a persistent message on the EMQX. When any new subscribers subscribe to a topic that matches the topic of the retained message, they immediately receive that message, even if it was published before they subscribed to the topic.

You can use client tools to connect to EMQX and try this messaging service. This section introduces how to use the MQTTX Desktop and MQTTX CLI to simulate clients and see how a retained message is published and received.

Prerequisites

• Knowledge about MQTT Retained Message
• Basic publishing and subscribing operations using MQTTX

Publish Retained Message with MQTTX Desktop

1. Start EMQX and MQTTX Desktop. Click the New Connection to create a client connection as a publisher.

   • Enter Demo in the Name field.
   • Enter the localhost 127.0.0.1 in Host to use as an example in this demonstration.
   • Leave other settings as default and click Connect.

   TIP

   More detailed instructions on creating an MQTT connection are introduced in MQTTX Desktop.

   

2. After the successful connection, type the topic heading sensor/t1 in the text box and compose the message payload as shown in the screenshot. Click the send button. A message to the topic sensor/t1 appears in the message dialogue.

   

3. Publish two retained messages with the topic sensor/t2.

   • Enter 1 as the first message. Select Retain. Click the send button.
   • Enter 2 as the second message. Click the send button.
   

4. Click the + -> New Connection in the Connections pane to create a subscription Subscriber as a client that receives messages.

5. Click + New Subscription to subscribe to the topic sensor/+. Click the Confirm button.

   TIP

   With the topic set to sensor/+, both sensor/t1 and sensor/t2 are subscribed. For more information on topics and wildcards, see Understanding MQTT Topics & Wildcards by Case.

   You will see that the client Subscriber only receives the last retained message but not the first message with the topic sensor/t1 and the first retained message with the topic sensor/t2, because EMQX only stores the latest retained message of each topic.

   

Now you have tried using the MQTTX Client to send a retained message. You can also check the latest retained message stored in the EMQX through the Dashboard, see View Retained Message in Dashboard.

Publish Retained Message with MQTTX CLI

1. Initiate a connection request with one client.

2. Use the following command to publish a retained message. Set the topic to t/1, payload to A retained message from MQTTX CLI, and retain = true：

   mqttx pub -t 't/1' -m 'A retained message from MQTTX CLI' --retain true -h 'localhost' -p 1883

3. Initiate another new client connection request to the same broker. Subscribe to the topic t/1 with the new client. It will receive the retained message.

   If you continuously create new clients and let them subscribe to the topic t/1, all new clients you created will receive the retained message.

   $ mqttx sub -t 't/1' -h 'localhost' -p 1883 -v
   topic:  t/1
   payload:  A retained message from MQTTX CLI
   retain: true

4. Publish an empty message to clear the retained message:

   mqttx pub -t 't/1' -m '' --retain true -h 'localhost' -p 1883

5. Initiate a new client connection and subscribe to the topic t/1. No retained messages are received, indicating the retained message is cleared.

View Retained Message in Dashboard

When you publish a retained message, EMQX will save this message in the system. you can view this message on the Retained Messages list page. When you subscribe to the topic of this retained message, EMQX will publish this message to the topic, and you can receive this message immediately by subscribing to the topic.

The default expiration time of the retained message is never expired unless you manually delete this message.

Retained Messages List

In the Monitoring -> Retained Messages page, you can view all the retained messages in the system, including the topic, QoS, publish time, and client ID. The search box allows for filtering through search, and it supports topic wildcards.

The page also provides options to view the payload of a retained message and delete it using the Show Payload and Delete buttons respectively. You can refresh the list using the Refresh button and access the retained message settings page using the Settings button.

You can see the following 3 types of retained messages from system topics by default:

• $SYS/brokers/+/sysdescr: System description of the current EMQX node
• $SYS/brokers/+/version: Version number of the current EMQX node
• $SYS/brokers - Number and name of all nodes of the current EMQX

Delete Retained Message

To delete a retained message in EMQX, you can either publish an empty message to the topic of the retained message in the client or use the EMQX Dashboard. In the Dashboard, you can click the Delete button for a specific retained message to remove it. You can also delete all retained messages on the cluster by using the Clear All button. Additionally, you can also set the expiration time for retained messages on the Retained Messages configuration page, allowing EMQX to automatically delete them when they expire.