个人开发技术分享 ESP Dev Center

开始前适用开发板：ESP32-S3 Korvo · 开发框架：ESP-IDF

适用开发板：Korvo S3 · 工程 02.beginner.mqtt_tcp · target esp32s3
前置：Wi-Fi Station
概念：MQTT 教程
学习时长：约 25 分钟 · 难度：★★☆☆☆

学习目标

完成本节后，你将能够：

理解 MQTT 协议的 发布/订阅 模型
掌握 esp_mqtt_client 的事件驱动编程方式
学会使用 MQTTX 等工具验证通信
了解 QoS 等级对消息可靠性的影响

1. 这个例子在干嘛

连接 Wi-Fi 后，创建一个 MQTT 客户端，连接到 Broker（服务器），然后进行发布（Publish）和订阅（Subscribe）操作。

MQTT 三分钟速通：

MQTT 是一种"邮局"模型的通信协议：

  设备 A（发布者）                  设备 B（订阅者）
      │                                │
      │  publish "温度=25"             │  subscribe "温度"
      │  到 topic: /home/temp          │  到 topic: /home/temp
      │          │                     │
      └──────→ Broker（邮局）────────→ │
               转发消息给所有
               订阅了该 topic 的人

关键概念：
  Topic（主题）：消息的"地址"，如 /home/temp
  Publish（发布）：往某个 topic 发消息
  Subscribe（订阅）：声明我想收某个 topic 的消息
  Broker（代理）：转发消息的服务器

本例的完整数据流：

┌──────────┐   Wi-Fi   ┌──────────┐   TCP/MQTT   ┌──────────┐
│ Korvo S3 │──────────→│  路由器   │─────────────→│  Broker  │
│          │           │          │              │ (云/本地) │
│ 发布/订阅 │           └──────────┘              │ 转发消息  │
│ 屏幕状态  │                                     └──────────┘
└──────────┘                                          ↕
                                                 ┌──────────┐
                                                 │  MQTTX   │
                                                 │ PC 客户端 │
                                                 └──────────┘

2. 编译烧录

cd Korvo_Firmware\02.beginner.mqtt_tcp
idf.py set-target esp32s3
idf.py menuconfig    # 必须配置 Wi-Fi 和 Broker
idf.py build flash monitor

3. menuconfig 配置

3.1 Wi-Fi 配置

Example Connection Configuration → WiFi SSID / Password

3.2 MQTT Broker 配置

Example Configuration → Broker URL

选项	默认值（以源码为准）	说明
Broker URL	`mqtt://mqtt.eclipseprojects.io`	公共测试 Broker

Broker 选择建议：

入门测试：公共 Broker（mqtt.eclipseprojects.io），免费但不稳定

稳定测试：自建 Mosquitto（PC 上安装，同局域网）

生产环境：阿里云 IoT / EMQX Cloud / AWS IoT

Topic 名称在 main/app_main.c 源码中定义（常见 /topic/qos0、/topic/qos1），以代码为准。

4. 运行现象

阶段	屏幕显示	串口输出
连接 Wi-Fi	SSID + 状态	`wifi:connected`
连接 Broker	Broker URL + `connected`	`MQTT_EVENT_CONNECTED`
发布消息	`publish ok`	`sent publish successful, msg_id=...`
订阅成功	`subscribed`	`MQTT_EVENT_SUBSCRIBED`
收到消息	最近 Topic/Data	`TOPIC=/topic/qos0 DATA=...`
断开	状态更新	`MQTT_EVENT_DISCONNECTED`（自动重连）

5. 事件驱动模型详解

MQTT 客户端的所有行为都由 事件回调 驱动：

mqtt_event_handler(event) {
    switch (event->event_id) {

        case MQTT_EVENT_CONNECTED:
            // Broker 连接成功！
            // → 发布欢迎消息
            // → 订阅感兴趣的 topic
            esp_mqtt_client_publish(client, "/topic/qos0", "hello", 0, 0, 0);
            esp_mqtt_client_subscribe(client, "/topic/qos1", 1);
            break;

        case MQTT_EVENT_SUBSCRIBED:
            // 订阅确认
            // → 可以再发一条测试消息
            break;

        case MQTT_EVENT_DATA:
            // 收到订阅的消息！
            // event->topic / event->topic_len
            // event->data  / event->data_len
            // → 更新屏幕显示
            // → 执行业务逻辑
            break;

        case MQTT_EVENT_DISCONNECTED:
            // 断开连接（库会自动重连，无需手动处理）
            break;

        case MQTT_EVENT_ERROR:
            // 错误处理
            break;
    }
}

重要原则：不要在回调里做耗时操作！如果需要长时间处理（如写 Flash、HTTP 请求），应通过队列发送消息到另一个任务处理。

6. MQTTX 验证（必做！）

MQTTX 是一款免费的 MQTT 桌面客户端，用来验证板子的通信是否正常。

6.1 下载安装

从 mqttx.app 下载安装。

6.2 验证步骤

确认板子已 CONNECTED（串口看到 MQTT_EVENT_CONNECTED）
MQTTX 新建连接 → 填入同一个 Broker URL
测试下行（PC → 板子）：
- MQTTX 发布消息到板子订阅的 topic（如 /topic/qos1）
- 板子屏幕/串口应显示收到的消息
测试上行（板子 → PC）：
- MQTTX 订阅板子 publish 的 topic（如 /topic/qos0）
- 应看到板子发送的数据

7. 关键文件与代码解析

文件	作用	重点关注
`main/app_main.c`	Wi-Fi 初始化、MQTT 客户端创建、事件处理	`mqtt_event_handler`
`main/Kconfig.projbuild`	menuconfig 选项定义	Broker URL
display 组件	屏幕 UI 更新	状态显示

核心代码流程

app_main()
  ├── Wi-Fi 连接（GOT_IP 后继续）
  ├── esp_mqtt_client_config_t { .broker.address.uri = Broker URL }
  ├── esp_mqtt_client_init(&config)
  ├── esp_mqtt_client_register_event(client, handler)
  └── esp_mqtt_client_start(client)
        → CONNECTED 事件触发 → publish + subscribe

8. QoS 等级

QoS	名称	可靠性	适用场景
0	At most once	可能丢失	传感器周期上报（丢一两条无所谓）
1	At least once	至少送达一次	控制命令（推荐）
2	Exactly once	恰好一次	支付/计费（ESP 上少用）

9. 常见问题与排查

现象	可能原因	解决方案
`MQTT_EVENT_ERROR`	Broker 地址错误	确认 URL 格式：`mqtt://host:1883`
`MQTT_EVENT_ERROR`	Broker 需要账号密码	添加 `username` / `password`
收不到消息	Topic 不匹配	MQTTX 和源码中的 topic 必须完全一致
收不到消息	QoS 不匹配	发布和订阅都用 QoS 1
公共 Broker 不稳定	服务器负载高	换自建 Mosquitto 或付费 Broker
Wi-Fi 连接失败	同 wifi_station	见 Wi-Fi 排查
断开后不重连	一般库会自动重连	检查 `keepalive` 和 `reconnect_timeout`

10. 动手改造建议

温度上报：每 5 秒 publish ADC 读数到 /sensor/temp topic
远程控制：订阅 /led/ctrl，收到 on 点亮 LED，收到 off 关灯
JSON 数据：发布 {"temp":25,"hum":60} 格式数据，MQTTX 验证解析
换自建 Broker：PC 安装 Mosquitto，修改 Broker URL 为 PC 的 IP
Last Will 遗嘱：设置遗嘱消息，板子掉线时 Broker 自动通知其他设备

11. 知识延伸

MQTT vs HTTP：HTTP 是"请求-响应"（你问一次才回答一次），MQTT 是"订阅推送"（有新消息主动推给你），更适合物联网
Keep Alive：客户端定期发心跳包给 Broker，超过 keepalive 时间没心跳则认为掉线
Retained Message：Broker 可以保留每个 topic 的最后一条消息，新订阅者连接后立即收到
ESP-IDF MQTT 库：基于 esp-mqtt，支持 TCP、TLS、WebSocket 多种传输方式

12. 下一步

方向	推荐例程	说明
OTA 升级	OTA	MQTT 报新版本 → OTA 下载
HTTP 服务器	HTTP Server	另一种网络交互方式
P4C5 版 MQTT	P4C5 MQTT	C5 协处理器下的同功能
通用 MQTT 教程	MQTT 教程	深入协议细节

酷世DIY · Kevincoooool

在 Web Flasher 中打开选择对应固件并烧录 打开 Web Serial查看运行日志 查看示例工程来源打开 GitHub 文档版本

开始前适用开发板：ESP32-S3 Korvo · 开发框架：ESP-IDF

适用开发板：Korvo S3 · 工程 02.beginner.mqtt_tcp · target esp32s3
前置：Wi-Fi Station
概念：MQTT 教程
学习时长：约 25 分钟 · 难度：★★☆☆☆

学习目标

完成本节后，你将能够：

理解 MQTT 协议的 发布/订阅 模型
掌握 esp_mqtt_client 的事件驱动编程方式
学会使用 MQTTX 等工具验证通信
了解 QoS 等级对消息可靠性的影响

1. 这个例子在干嘛

连接 Wi-Fi 后，创建一个 MQTT 客户端，连接到 Broker（服务器），然后进行发布（Publish）和订阅（Subscribe）操作。

MQTT 三分钟速通：

MQTT 是一种"邮局"模型的通信协议：

  设备 A（发布者）                  设备 B（订阅者）
      │                                │
      │  publish "温度=25"             │  subscribe "温度"
      │  到 topic: /home/temp          │  到 topic: /home/temp
      │          │                     │
      └──────→ Broker（邮局）────────→ │
               转发消息给所有
               订阅了该 topic 的人

关键概念：
  Topic（主题）：消息的"地址"，如 /home/temp
  Publish（发布）：往某个 topic 发消息
  Subscribe（订阅）：声明我想收某个 topic 的消息
  Broker（代理）：转发消息的服务器

本例的完整数据流：

┌──────────┐   Wi-Fi   ┌──────────┐   TCP/MQTT   ┌──────────┐
│ Korvo S3 │──────────→│  路由器   │─────────────→│  Broker  │
│          │           │          │              │ (云/本地) │
│ 发布/订阅 │           └──────────┘              │ 转发消息  │
│ 屏幕状态  │                                     └──────────┘
└──────────┘                                          ↕
                                                 ┌──────────┐
                                                 │  MQTTX   │
                                                 │ PC 客户端 │
                                                 └──────────┘

2. 编译烧录

cd Korvo_Firmware\02.beginner.mqtt_tcp
idf.py set-target esp32s3
idf.py menuconfig    # 必须配置 Wi-Fi 和 Broker
idf.py build flash monitor

3. menuconfig 配置

3.1 Wi-Fi 配置

Example Connection Configuration → WiFi SSID / Password

3.2 MQTT Broker 配置

Example Configuration → Broker URL

选项	默认值（以源码为准）	说明
Broker URL	`mqtt://mqtt.eclipseprojects.io`	公共测试 Broker

Broker 选择建议：

入门测试：公共 Broker（mqtt.eclipseprojects.io），免费但不稳定

稳定测试：自建 Mosquitto（PC 上安装，同局域网）

生产环境：阿里云 IoT / EMQX Cloud / AWS IoT

Topic 名称在 main/app_main.c 源码中定义（常见 /topic/qos0、/topic/qos1），以代码为准。

4. 运行现象

阶段	屏幕显示	串口输出
连接 Wi-Fi	SSID + 状态	`wifi:connected`
连接 Broker	Broker URL + `connected`	`MQTT_EVENT_CONNECTED`
发布消息	`publish ok`	`sent publish successful, msg_id=...`
订阅成功	`subscribed`	`MQTT_EVENT_SUBSCRIBED`
收到消息	最近 Topic/Data	`TOPIC=/topic/qos0 DATA=...`
断开	状态更新	`MQTT_EVENT_DISCONNECTED`（自动重连）

5. 事件驱动模型详解

MQTT 客户端的所有行为都由 事件回调 驱动：

mqtt_event_handler(event) {
    switch (event->event_id) {

        case MQTT_EVENT_CONNECTED:
            // Broker 连接成功！
            // → 发布欢迎消息
            // → 订阅感兴趣的 topic
            esp_mqtt_client_publish(client, "/topic/qos0", "hello", 0, 0, 0);
            esp_mqtt_client_subscribe(client, "/topic/qos1", 1);
            break;

        case MQTT_EVENT_SUBSCRIBED:
            // 订阅确认
            // → 可以再发一条测试消息
            break;

        case MQTT_EVENT_DATA:
            // 收到订阅的消息！
            // event->topic / event->topic_len
            // event->data  / event->data_len
            // → 更新屏幕显示
            // → 执行业务逻辑
            break;

        case MQTT_EVENT_DISCONNECTED:
            // 断开连接（库会自动重连，无需手动处理）
            break;

        case MQTT_EVENT_ERROR:
            // 错误处理
            break;
    }
}

重要原则：不要在回调里做耗时操作！如果需要长时间处理（如写 Flash、HTTP 请求），应通过队列发送消息到另一个任务处理。

6. MQTTX 验证（必做！）

MQTTX 是一款免费的 MQTT 桌面客户端，用来验证板子的通信是否正常。

6.1 下载安装

从 mqttx.app 下载安装。

6.2 验证步骤

确认板子已 CONNECTED（串口看到 MQTT_EVENT_CONNECTED）
MQTTX 新建连接 → 填入同一个 Broker URL
测试下行（PC → 板子）：
- MQTTX 发布消息到板子订阅的 topic（如 /topic/qos1）
- 板子屏幕/串口应显示收到的消息
测试上行（板子 → PC）：
- MQTTX 订阅板子 publish 的 topic（如 /topic/qos0）
- 应看到板子发送的数据

7. 关键文件与代码解析

文件	作用	重点关注
`main/app_main.c`	Wi-Fi 初始化、MQTT 客户端创建、事件处理	`mqtt_event_handler`
`main/Kconfig.projbuild`	menuconfig 选项定义	Broker URL
display 组件	屏幕 UI 更新	状态显示

核心代码流程

app_main()
  ├── Wi-Fi 连接（GOT_IP 后继续）
  ├── esp_mqtt_client_config_t { .broker.address.uri = Broker URL }
  ├── esp_mqtt_client_init(&config)
  ├── esp_mqtt_client_register_event(client, handler)
  └── esp_mqtt_client_start(client)
        → CONNECTED 事件触发 → publish + subscribe

8. QoS 等级

QoS	名称	可靠性	适用场景
0	At most once	可能丢失	传感器周期上报（丢一两条无所谓）
1	At least once	至少送达一次	控制命令（推荐）
2	Exactly once	恰好一次	支付/计费（ESP 上少用）

9. 常见问题与排查

现象	可能原因	解决方案
`MQTT_EVENT_ERROR`	Broker 地址错误	确认 URL 格式：`mqtt://host:1883`
`MQTT_EVENT_ERROR`	Broker 需要账号密码	添加 `username` / `password`
收不到消息	Topic 不匹配	MQTTX 和源码中的 topic 必须完全一致
收不到消息	QoS 不匹配	发布和订阅都用 QoS 1
公共 Broker 不稳定	服务器负载高	换自建 Mosquitto 或付费 Broker
Wi-Fi 连接失败	同 wifi_station	见 Wi-Fi 排查
断开后不重连	一般库会自动重连	检查 `keepalive` 和 `reconnect_timeout`

10. 动手改造建议

温度上报：每 5 秒 publish ADC 读数到 /sensor/temp topic
远程控制：订阅 /led/ctrl，收到 on 点亮 LED，收到 off 关灯
JSON 数据：发布 {"temp":25,"hum":60} 格式数据，MQTTX 验证解析
换自建 Broker：PC 安装 Mosquitto，修改 Broker URL 为 PC 的 IP
Last Will 遗嘱：设置遗嘱消息，板子掉线时 Broker 自动通知其他设备

11. 知识延伸

MQTT vs HTTP：HTTP 是"请求-响应"（你问一次才回答一次），MQTT 是"订阅推送"（有新消息主动推给你），更适合物联网
Keep Alive：客户端定期发心跳包给 Broker，超过 keepalive 时间没心跳则认为掉线
Retained Message：Broker 可以保留每个 topic 的最后一条消息，新订阅者连接后立即收到
ESP-IDF MQTT 库：基于 esp-mqtt，支持 TCP、TLS、WebSocket 多种传输方式

12. 下一步

方向	推荐例程	说明
OTA 升级	OTA	MQTT 报新版本 → OTA 下载
HTTP 服务器	HTTP Server	另一种网络交互方式
P4C5 版 MQTT	P4C5 MQTT	C5 协处理器下的同功能
通用 MQTT 教程	MQTT 教程	深入协议细节

酷世DIY · Kevincoooool

在 Web Flasher 中打开选择对应固件并烧录 打开 Web Serial查看运行日志 查看示例工程来源打开 GitHub 文档版本

Korvo · MQTT 客户端

学习目标

1. 这个例子在干嘛

2. 编译烧录

3. menuconfig 配置

3.1 Wi-Fi 配置

3.2 MQTT Broker 配置

4. 运行现象

5. 事件驱动模型详解

6. MQTTX 验证（必做！）

6.1 下载安装

6.2 验证步骤

7. 关键文件与代码解析

核心代码流程

8. QoS 等级

9. 常见问题与排查

10. 动手改造建议

11. 知识延伸

12. 下一步

Korvo · MQTT 客户端

学习目标

1. 这个例子在干嘛

2. 编译烧录

3. menuconfig 配置

3.1 Wi-Fi 配置

3.2 MQTT Broker 配置

4. 运行现象

5. 事件驱动模型详解

6. MQTTX 验证（必做！）

6.1 下载安装

6.2 验证步骤

7. 关键文件与代码解析

核心代码流程

8. QoS 等级

9. 常见问题与排查

10. 动手改造建议

11. 知识延伸

12. 下一步