Clearing Retained Messages from a Topic

This article will go over the process of clearing retained messages from a specific topic on a MQTT broker. Retained messages are MQTT messages, configured with a retained flag on publish, that the broker stores and delivers to new subscribers immediately upon subscription. Clearing them can be necessary when the information is no longer relevant or accurate.

For example, many Ignition MQTT module clients utilize retained messages to provide their current status to subscribers. When this status changes, it needs to be updated by the client to provide relevant status details.

The standard MQTT way to clear a retained message is to publish a message with:

1. An empty payload.

2. The RETAIN flag set to true (or 1).

When the broker receives such a message, it replaces the existing retained message for that topic with an empty one, effectively clearing it. Any new subscribers to that topic will no longer receive the old retained message.

Next, we’ll provide some suggestions for usage with some common MQTT clients.

Using MQTT.fx

MQTT.fx is a popular desktop MQTT client, and can be a great tool to utilize for exploring and testing within an MQTT environment. This can also be used to publish specific messages, in which case this will be very useful for our task.

1. Connect to your HiveMQ Broker:

   • Open MQTT.fx and establish a connection to your HiveMQ broker by configuring the connection profile with the broker address, port, and any necessary credentials.

2. Navigate to the "Publish" Tab:

   • Once connected, click on the "Publish" tab.

3. Configure the Message:

   • Topic: Enter the exact topic name you wish to clear, for example, my/sensor/status.

   • Payload: Leave this field completely empty. Do not enter any spaces or characters. This is important, as any information contained within the payload will instead update the retained message to this payload data, instead of clearing it.

   • QoS: For our purposes, any of the available options will function, though QoS 0 or 1 is typically a better choice to improve performance.

   • Retain: Crucially, check the "Retain" checkbox. This sets the RETAIN flag to true, and is necessary to clear the retained message from this topic.

4. Publish the Message:

   • Click the "Publish" button.

Using HiveMQ MQTT CLI (Command Line Client)

1. Open your terminal or command prompt.

2. Construct the mqtt publish command: You'll use the mqtt publish command and specify your broker's address, port, the topic, and crucially, the retain flag and an empty message.

   The basic command structure is:

   mqtt publish \ -h <broker_address> \ -p <port> \ -t <topic> \ -r \ -m ""

   • -h <broker_address> or --host <broker_address>: Specifies the hostname or IP address of your HiveMQ broker (e.g., broker.hivemq.com or localhost).

   • -p <port> or --port <port>: Specifies the port your broker is listening on (default MQTT is 1883, default MQTT over TLS is 8883).

   • -t <topic> or --topic <topic>: The topic name you want to clear (e.g., home/sensors/status).

   • -r or --retain: This flag sets the retain flag to true.

   • -m "": This sets the message payload to an empty string, which is required when clearing a retained message.

   • -q <qos> or --qos <qos>: (Optional) Set the Quality of Service (e.g., -q 0 or -q 1). If not specified, it defaults to QoS 0.

3. Example Command:

   To clear a retained message on the topic my/device/status on a HiveMQ broker running at mqtt.example.com on port 1883:

   mqtt publish -h mqtt.example.com -p 1883 -t my/device/status -r -m ""

4. For Brokers Requiring Authentication:

   If your HiveMQ broker requires a username and password, use the -u and -pw flags:

   mqtt publish -h mqtt.example.com -p 1883 -t my/device/status -r -m "" -u <username> -pw <password>

5. For TLS/SSL Connections:

   If you are connecting over TLS/SSL (usually port 8883), you'll need to include the --tls flag. For trusted CAs, this might be enough. For self-signed certificates, you might need to provide a server CA file with --cafile or cite the session as insecure with --insecure:

   mqtt publish -h mqtt.example.com -p 8883 -t my/device/status -r -m "" --tls

   If your broker uses a self-signed certificate, you might need to specify the CA file:

   mqtt publish -h mqtt.example.com -p 8883 -t my/device/status -r -m "" --tls --cafile /path/to/your/ca.crt

   Or, if you accept insecure connections (not recommended for production):

   mqtt publish -h mqtt.example.com -p 8883 -t my/device/status -r -m "" --tls --insecure