Detailed Explanation of MQTT Message Structure and Python Reading Methods

Introduction

In the field of the Internet of Things (IoT), the MQTT (Message Queuing Telemetry Transport) protocol is favored for its lightweight and efficient nature. This article will provide a detailed analysis of the composition of MQTT messages and introduce how to read MQTT message content using Python. Through specific examples, it aims to help readers gain a deeper understanding of how MQTT works and its applications in real projects.

MQTT Message Structure

The MQTT message consists of three parts: Fixed Header, Variable Header, and Payload. This compact design makes it very suitable for low-bandwidth, high-latency network environments.

1. Fixed Header

• Length: The fixed header is always present, with a length of 2 to 4 bytes.
• Composition:

• Control Field: 1 byte. The first 4 bits represent the message type (e.g., CONNECT is 0x10, PUBLISH is 0x30), and the last 4 bits are control flags (e.g., DUP, QoS, RETAIN).
• Remaining Length: 1-4 bytes. The length is represented using 7 bits, with the 8th bit as a continuation flag indicating whether more bytes are needed.

• Characteristics: Designed to be compact and efficient, suitable for resource-constrained devices.

2. Variable Header

• Existence: Not all message types have a variable header; the content varies by message type.
• Examples:

• CONNECT message: includes protocol name (e.g., “MQTT”), protocol version, connection flags, and keep-alive time.
• PUBLISH message: includes topic name and packet identifier (for QoS 1 or QoS 2).

3. Payload

• Existence: Not all message types have a payload; the content is binary data, and the format is defined by the application.
• Examples:

• CONNECT message: contains client ID.
• PUBLISH message: can be sensor data, text messages, etc.

Reading MQTT Messages with Python

Python can easily connect to an MQTT broker, subscribe to topics, and read message content using the Paho MQTT client library.

1. Install Paho MQTT Library

Run the following command in the terminal to install:

pip install paho-mqtt

2. Connect to the MQTT Broker

You can use a public MQTT broker, such as broker.emqx.io, with the default port of 1883 (TCP).

3. Subscribe to Topics and Handle Messages

• Use client.subscribe("topic_name") to subscribe to the specified topic.
• Handle received messages through the on_message callback function, accessing msg.topic (topic) and msg.payload.decode() (decoded message content).

Specific Example

The following is a simple Python script to connect to an MQTT broker, subscribe to a topic, and print the received messages:

import paho.mqtt.client as mqtt

def on_connect(client, userdata, flags, rc):
    print("Connected with result code: " + str(rc))
    client.subscribe("python/mqtt/test")

def on_message(client, userdata, msg):
    print(f"Message received: '{msg.payload.decode()}', from topic '{msg.topic}', QoS {msg.qos}")

client = mqtt.Client()
client.on_connect = on_connect
client.on_message = on_message
client.connect("broker.emqx.io", 1883, 60)
client.loop_forever()

After running this script, it will connect to broker.emqx.io, subscribe to the topic "python/mqtt/test", and print the topic and content when a message is received.

Latest Version of Python Syntax

In the latest version of Paho MQTT, it is recommended to use the API supported by MQTT 5.0, adding the callback_api_version parameter when creating the client to ensure future compatibility:

client = mqtt.Client(callback_api_version=mqtt.CallbackAPIVersion.VERSION2)

Simply replace the line client = mqtt.Client() in the above example with this line of code to support the new features of MQTT 5.0.

Conclusion

This article provides a detailed overview of the structure of MQTT messages and how to read them in Python. The MQTT protocol, with its lightweight and efficient nature, has broad application prospects in the field of IoT. By combining Python and the Paho MQTT library, developers can quickly implement MQTT client functionality. It is hoped that this article will provide practical guidance for readers in applying MQTT in real projects.

References

• Steve’s Internet Guide: MQTT Protocol Messages Overview
• EMQ: How to Use MQTT in Python
• MQTT V3.1.1 Specification PDF
• Paho MQTT Migration Guide