Micropython MQTT Retain: A Comprehensive Guide

MQTT (Message Queuing Telemetry Transport) is a lightweight publish - subscribe messaging protocol widely used in Internet of Things (IoT) applications. Micropython, a lean and efficient implementation of Python 3 for microcontrollers and constrained systems, allows developers to use MQTT easily on resource - constrained devices. One of the important features in MQTT is the retain flag. When a message is published with the retain flag set to True, the MQTT broker stores the message and its payload on the specified topic. New subscribers to that topic will immediately receive the last retained message, which can be very useful in scenarios where devices need to get the latest state information as soon as they subscribe. In this blog, we will explore the fundamental concepts of Micropython MQTT retain, how to use it, common practices, and best practices.

Table of Contents#

  1. Fundamental Concepts of Micropython MQTT Retain
  2. Usage Methods
  3. Common Practices
  4. Best Practices
  5. Conclusion
  6. References

Fundamental Concepts of Micropython MQTT Retain#

MQTT Basics#

MQTT is a client - server protocol. Clients can publish messages to topics and subscribe to topics to receive messages. A topic is a hierarchical string that acts as a channel for message distribution.

The Retain Flag#

When a client publishes a message with the retain flag set to True, the MQTT broker will store this message as the retained message for the specified topic. When a new client subscribes to that topic, the broker will send the last retained message to the new subscriber. If a client publishes a message with the retain flag set to True and an empty payload, the broker will delete the retained message for that topic.

Usage Methods#

Prerequisites#

  • A MicroPython - enabled device (e.g., ESP8266, ESP32).
  • An MQTT broker (e.g., Mosquitto).
  • Internet connection for the device.

Installing the MQTT Library#

In Micropython, the umqtt.simple library can be used to interact with MQTT brokers. Here is an example of publishing a retained message:

import time
from umqtt.simple import MQTTClient
 
# MQTT broker configuration
BROKER_ADDRESS = "your_broker_address"
CLIENT_ID = "micropython_client"
TOPIC = "test_topic"
USERNAME = "your_username"
PASSWORD = "your_password"
 
# Create an MQTT client instance
client = MQTTClient(CLIENT_ID, BROKER_ADDRESS, user=USERNAME, password=PASSWORD)
 
# Connect to the MQTT broker
client.connect()
 
# Publish a retained message
message = "This is a retained message"
client.publish(TOPIC, message, retain=True)
 
# Disconnect from the MQTT broker
client.disconnect()

Subscribing to a Topic with Retained Messages#

import time
from umqtt.simple import MQTTClient
 
# MQTT broker configuration
BROKER_ADDRESS = "your_broker_address"
CLIENT_ID = "micropython_client_sub"
TOPIC = "test_topic"
USERNAME = "your_username"
PASSWORD = "your_password"
 
# Callback function to handle received messages
def sub_cb(topic, msg):
    print((topic, msg))
 
# Create an MQTT client instance
client = MQTTClient(CLIENT_ID, BROKER_ADDRESS, user=USERNAME, password=PASSWORD)
client.set_callback(sub_cb)
 
# Connect to the MQTT broker
client.connect()
 
# Subscribe to the topic
client.subscribe(TOPIC)
 
# Check for incoming messages
while True:
    client.check_msg()
    time.sleep(1)
 
# Disconnect from the MQTT broker
client.disconnect()

Common Practices#

Using Retained Messages for Device State#

Retained messages are commonly used to represent the current state of a device. For example, in a smart home system, a light bulb can publish its on/off state as a retained message. When a new client (e.g., a mobile app) subscribes to the light bulb's topic, it will immediately get the current state of the light bulb.

Initialization of New Devices#

New devices can use retained messages to get the initial configuration or state information from the broker. For example, a sensor device can subscribe to a configuration topic with retained messages to get the sampling rate, calibration parameters, etc.

Best Practices#

Use Appropriate Topics#

Organize your topics in a hierarchical and meaningful way. For example, use topics like home/room1/light to represent a light in a specific room. This makes it easier to manage retained messages and understand the data flow.

Clean Up Retained Messages#

When a device is no longer in use or a state is no longer relevant, publish an empty message with the retain flag set to True to delete the retained message from the broker. This helps to keep the broker clean and reduces unnecessary message traffic.

Error Handling#

Implement proper error handling in your code. For example, handle connection errors to the MQTT broker and retry mechanisms in case of network failures.

Conclusion#

The retain flag in Micropython MQTT is a powerful feature that can greatly enhance the functionality of IoT applications. It allows devices to get the latest state information immediately when they subscribe to a topic, which is useful for device initialization, state representation, and more. By understanding the fundamental concepts, usage methods, common practices, and best practices, developers can use the retain flag effectively in their Micropython - based MQTT applications.

References#

2025-10