MQTT Communication Experiment

1. MQTT Overview

MQTT (Message Queuing Telemetry Transport) is the most mainstream lightweight publish/subscribe messaging protocol in the IoT field. It is based on TCP and uses the publish/subscribe (Pub/Sub) mode instead of the traditional client-server direct connection mode, achieving temporal and spatial decoupling between producers and consumers.

In this experiment the ESP32-S3 connects to the public Broker broker.emqx.io, publishes messages to the test/esp32/send topic, and subscribes to the test/esp32/recv topic.

Typical application scenarios:

This experiment depends on the umqtt.simple library (built into MicroPython or uploaded separately). Using a public Broker requires no self-built server.

2. Core Concepts

2.1 Publish/Subscribe Model

​x
​
┌──────────┐ publish("test/topic", msg)   ┌──────────┐  
│ ESP32-S3 │ ───────────────────────────→ │  Broker  │
│          │ ←─────────────────────────── │ (EMQX)   │
│          │  subscribe("test/topic")     └────┬─────┘
└──────────┘                                   │
                                    pushed to all subscribers on publish
                                          ┌────┴───────┐
                                          │ Phone APP  │
                                          └────────────┘

• Broker: the message relay station, responsible for receiving publishes and pushing to subscribers
• Topic: the message topic, e.g. home/livingroom/temperature
• Publish: publish a message to a specified topic
• Subscribe: subscribe to a topic; the Broker pushes messages on that topic to you

2.2 Configuration Parameters

2.3 Core API

xxxxxxxxxx
from umqtt.simple import MQTTClient
​
# create
client = MQTTClient("client_id", "broker.emqx.io", port=1883)
client.set_callback(on_message)          # set callback
client.connect()                         # connect Broker
client.subscribe("topic/sub")            # subscribe
client.publish("topic/pub", "hello")     # publish
client.check_msg()              # check for subscribed messages

2.4 Topics and Messages

This experiment defines two topics; the ESP32 uses them to interact with external clients (such as MQTTX):

QoS 0 (At most once): the message is delivered at most once and delivery is not guaranteed. Suitable for lightweight periodic sensor reporting.

Message flow:

xxxxxxxxxx
ESP32-S3  --publish("test/esp32/send", "Hello ESP32 MQTT")-->  Broker  --forward-->  MQTTX (subscriber)
ESP32-S3  <--subscribe("test/esp32/recv")----------------  Broker  <--publish--  MQTTX (publisher)

The ESP32 publishes and subscribes to separate topics to avoid receiving its own messages. If you want a self-send/self-receive loopback test, set TOPIC_PUB and TOPIC_SUB to the same topic.

3. Hardware Dependencies

The ESP32-S3 has built-in WiFi and needs access to the public Broker (broker.emqx.io). No PC or self-built server is required.

4. Project Architecture and Flow

xxxxxxxxxx
Script execution (single-file .py)
  |
  |- wifi_init(): connect to WiFi (STA mode)
  |- create MQTTClient -> connect() -> subscribe()
  |
  `- while True:
       |- publish(TOPIC_PUB, "Hello ESP32 MQTT")   // publish
       |- check_msg()                               // check subscription
       `- sleep(3s)

5. Source Code Explained

Full source code: Source Code -> MicroPython -> 4.Network Protocols -> MQTT -> MQTT.py

5.1 Creating the MQTT Client

Use the umqtt.simple library to connect to the public Broker broker.emqx.io:1883, set the callback, and subscribe to the target topic.

xxxxxxxxxx
from umqtt.simple import MQTTClient
​
BROKER     = "broker.emqx.io"           # public broker
TOPIC_PUB  = "test/esp32/send"          # publish topic
TOPIC_SUB  = "test/esp32/recv"          # subscribe topic
CLIENT_ID  = "esp32s3_mqtt"             # unique client ID
​
client = MQTTClient(CLIENT_ID, BROKER, port=1883)
client.set_callback(on_message)         # callback on message
client.connect()
client.subscribe(TOPIC_SUB)

5.2 Message Callback

Automatically called when the Broker pushes a subscribed message; the parameters are topic and msg (both bytes).

xxxxxxxxxx
def on_message(topic, msg):
    """received subscribed message"""
    print(f"[Received] {topic.decode()} -> {msg.decode()}")

5.3 Main Loop

Publishes one message every 3s -> check_msg() checks whether any subscribed message has arrived.

xxxxxxxxxx
while True:
    msg = "Hello ESP32 MQTT"
    client.publish(TOPIC_PUB, msg)       # publish
    print(f"[Sent] {msg}")
​
    client.check_msg()                   # check for messages
    time.sleep(3)

6. Operating Procedures

6.1 Flashing and Running

Thonny IDE steps: See MicroPython -> 1. Before Development -> 3.Thonny IDE.

1. Modify WIFI_SSID / WIFI_PASS

   

2. Run MQTT.py

3. (Optional) Install an MQTT debugging tool (such as MQTTX) on the PC

   • Create a new connection with broker.emqx.io:1883 (the public Broker requires no username/password),
   • Subscribe to test/esp32/send to see the messages published by the ESP32,
   • Publish a message to test/esp32/recv and the ESP32 will receive it.

   

   

6.2 Serial Output Example

xxxxxxxxxx
========== MQTT CLIENT ==========
[WiFi] Connecting to 'Yahboom2' ...
[WiFi] Connected! IP: 192.168.11.229
[MQTT] Connected to broker.emqx.io
[MQTT] Subscribed: test/esp32/recv
[Sent] Hello ESP32 MQTT
[Sent] Hello ESP32 MQTT
[Recv] test/esp32/recv -> "msg": "hello"
​
[Recv] test/esp32/recv -> "msg": "hello"
​
[Recv] test/esp32/recv -> "msg": "hello"
​
[Sent] Hello ESP32 MQTT
[Sent] Hello ESP32 MQTT

6.3 Verification Methods

7. Common Problems