MQTT 上云验收：ESP32-S3 从局域网控灯到远程网页控制

文章目录

[MQTT 上云验收：ESP32-S3 从局域网控灯到远程网页控制](#MQTT 上云验收：ESP32-S3 从局域网控灯到远程网页控制)
- [一、先分清两件事：局域网页 vs 上云](#一、先分清两件事：局域网页 vs 上云)
- [二、通俗原理：MQTT 在这条链里干什么](#二、通俗原理：MQTT 在这条链里干什么)
- 三、验收前置条件
- 四、验收目标（同时满足才过）
- 五、确认板子已在网上
- [六、看 MQTT 是否起来](#六、看 MQTT 是否起来)
- 七、打开演示页看在线
- [八、远程开 / 关各一次](#八、远程开 / 关各一次)
- [九、对照与排查（串口 ↔ 演示页）](#九、对照与排查（串口 ↔ 演示页）)
- 十、验收自检清单
- 十一、小结
- 系列博文

MQTT 上云验收：ESP32-S3 从局域网控灯到远程网页控制

级别： 实战篇（免费·思路级）

适合谁读： 已按本系列完成 SoftAP、局域网网页控灯、NVS 掉电回连，想试「离开同一 Wi‑Fi 还能不能看一眼设备」的读者。

适用环境： Windows 10/11；ESP-IDF v6.1 （与本系列一致）；乐鑫 ESP32-S3-DevKitC-1 ；演示工程文中称 wifi_led。

说明： 本文是现象验收，不展开 v6.1 相对旧版的 MQTT API 差分；客户端连 Broker、上报/收命令的思路在常见版本里同类。

目标： 分清局域网 HTTP 与 MQTT 上云；用公开演示页做一次「在线 + 远程开/关灯」验收。

前置阅读（建议先过）：

文 04 SoftAP 配网 ·

文 05 局域网网页控灯 ·

文 06 NVS 掉电记 Wi‑Fi ·

文 00 环境安装

本文只做 MQTT 上云思路 + 演示页现象验收。

摘要： 局域网控灯要设备和手机同 Wi‑Fi；MQTT 上云后，ESP32 把状态报到 Broker，公网演示页可远程开关灯。本文只做现象验收。

演示工程： 文中称 wifi_led。实机需固件已能「连上家里 Wi‑Fi → 接入演示用 MQTT → 与公开演示页联动」。若当前只有局域网页能力，可先读思路，实机步骤稍后再做。

公开演示入口： https://linkeverything.top/tools/iot/

（以现网为准；维护时可能暂时打不开，属正常。）

一、先分清两件事：局域网页 vs 上云

	文 05 局域网网页	本文 MQTT 上云
手机要不要和板同一 Wi‑Fi	要	不必（板要能上网即可）
典型入口	`http://<STA局域网IP>/`	公网演示页
板子角色	自己当 HTTP 小服务器	MQTT 客户端，连云端 Broker
适合什么	家里调试、同网验收	外出看一眼、远程开关演示
本文深度	已写过	思路 + 现象，部署从略

记两句话就够：

局域网页：手机 → 家里路由器 → 板子 HTTP → 灯
上云演示 ：手机/电脑 → 公网演示页 → 中转服务 → MQTT → 板子 → 灯

（中转服务：接 MQTT、给演示页用的那一层；不是阿里云 / 腾讯云那种商用 IoT 平台。）

补充（看完对比再读）： 上了云，不必删掉局域网网页。就算固件同时开着 HTTP 和 MQTT，两条路一般也不打架------同网仍可走文 05，外出再走演示页。

二、通俗原理：MQTT 在这条链里干什么

MQTT 跑在 TCP 上，常见端口 1883 （明文）或 8883 （TLS）。嵌入式多用轻量长连接做「上报 + 收命令」。

风险提示： 公网严禁把 Broker 用 1883 明文 对外；1883 只适合本机或隔离内网调试。公网应使用 8883 + TLS （或等价加密）。本演示环境走 8883。

说法	意思
MQTT	轻量消息协议，适合「上报状态、接收命令」
Broker	消息中转站；设备和云都连它
上报（state）	板子说：我在线、灯开/关（还可带其它只读字段，后续篇章再讲）
命令（cmd）	演示页 / 中转服务说：请开灯 / 请关灯
中转服务	演示用小后端：接 MQTT、喂演示页；不是完整运营后台

板子侧常见流程（现象级）：

已按文 04～文 06：能连家里 2.4GHz Wi‑Fi，掉电后能自动回连
固件当 MQTT 客户端连上演示用 Broker（公网侧 TLS）
周期性或按事件上报「在线 + 灯状态」
收到开/关命令后改灯，并再报一次状态
演示页看到最新状态，并可下发开/关

板子只管 MQTT 收发；演示页怎么从中转服务取数，不影响本篇验收。

官方文档（跟做不强制，与本系列 v6.1 环境对应）：

https://docs.espressif.com/projects/esp-idf/zh_CN/v6.1/esp32s3/api-reference/protocols/esp_mqtt.html

演示页只做现象验收，别当生产控制台；截图与评论请打码，别贴账号口令。

三、验收前置条件

文 04～文 06 已过：能自动拿 STA got IP，局域网网页能控灯。
板子所连 Wi‑Fi 能访问公网（访客网禁外网会挂）。公司网 / 校园网常拦外网或 MQTT 端口，不行就换能上公网的网络。
串口监视可用（波特率常见 115200）。
浏览器能打开：https://linkeverything.top/tools/iot/
固件已按演示环境配好 MQTT。只有纯局域网固件 → 先读思路即可。

可选监视（COM3 换成你的口；Espressif / 工程路径按本机实际修改）：

powershell 复制代码

. 'C:\Espressif\tools\Microsoft.v6.1.PowerShell_profile.ps1'
cd F:\esp\projects\wifi_led
idf.py -p COM3 monitor

退出监视：Ctrl + ]。

四、验收目标（同时满足才过）

板子已连家里 Wi‑Fi（串口有 STA got IP）。
串口有 MQTT 连接成功 / 状态上报类关键字（敏感字段打码后再截图）。
演示页显示该设备在线，灯状态与实物大致一致（见图1、图2）。
演示页点开灯 → RGB 亮；点关灯 → 灯灭（见图3）。
点完后页面状态与实物一致（允许数秒延迟）。

说明：演示页维护或暂时无在线设备，不等于你局域网控灯失败。

页面显示离线时，先确认串口确实有过 MQTT 成功日志，再分设备问题还是演示环境问题。

发布时请在图1～图3位置插入真实截图 （不要只留文字占位）。下列图注可直接用作说明；截图须打码（账号、完整设备密钥、可识别的完整设备 ID 等），文中图注已按「已打码示例」书写。

五、确认板子已在网上

上电，打开串口监视。
应看到 STA got IP:192.168.x.x 一类日志。
（可选）按文 05 用局域网页控一次灯，确认灯硬件正常。

过不了：先回文 04 / 文 05 / 文 06，不要先怀疑 MQTT。

六、看 MQTT 是否起来

继续看串口：正常会出现「MQTT 已连接」「已 publish / 已上报」一类日志（以你的固件文案为准）。
若上电后约 30 秒内仍只有 Wi‑Fi、没有 MQTT 成功字样：查外网、系统时间、固件是否编进上云（评论区只写现象，敏感信息请打码）。
查完仍不通：先回文 04 / 文 05 确认配网与局域控灯正常，再回到本节。还是不行 → 可先回到局域网验收（文 05），等网络 / 固件就绪后再做上云。

图1　串口：已有 STA IP，且出现 MQTT 相关成功关键字（已打码示例）

七、打开演示页看在线

打开：https://linkeverything.top/tools/iot/
确认是网页（不是本地文件）。
看演示设备是否在线、灯状态是否对得上。
很慢或超时：稍等刷新；也可能是演示环境繁忙。

图2　演示页显示设备在线，灯状态与实物一致（已打码示例）

八、远程开 / 关各一次

可用手机 4G / 非家庭 Wi‑Fi 打开演示页------换的是看页面那台手机/电脑 的网络，不是把板子切到 4G。板子仍须连着能上公网的家里 Wi‑Fi。
点开灯 → 看 RGB 是否亮。
点关灯 → 看是否灭。
刷新或稍等，页面状态应跟上。

图3　演示页远程开关后，板载灯同步亮灭

能完成第七、八节 → 本篇现象验收通过。

九、对照与排查（串口 ↔ 演示页）

一张表看完：左边是现象，右边是你怎么做。

现象	含义 / 你怎么做
有 `STA got IP`，演示页在线且能控灯	上云链路通 → 本篇通过
有 STA IP，但从无 MQTT 成功日志	多半没连上 Broker 或未编进上云 → 查外网与固件；出口见第六节第 3 步
MQTT 已连接，演示页一直离线	上报没到，或设备 ID 与演示页不一致 → 确认是否演示固件、ID 是否对得上
演示页能控，局域网页不能控	两套入口独立 → 局域网问题回文 05
Wi‑Fi 都连不上	回文 04 / 文 06；确认 2.4GHz、非访客隔离
能连 MQTT，灯不动	先用文 05 网页确认灯硬件是否正常
演示页打不开 / 很慢 / 一直转圈	DNS、维护、本机网络或演示负载 → 换网络、稍后重试
开关有明显延迟	等几秒；以实物灯为准

十、验收自检清单

快速勾选；细则见第四节。

□ 串口有 STA got IP
□ 串口有 MQTT 连接/上报成功类关键字（截图已打码）
□ 演示页显示在线，灯状态与实物一致
□ 演示页开灯 → RGB 亮；关灯 → RGB 灭
□ （加分）用非家庭 Wi‑Fi（如 4G）打开演示页仍能控

十一、小结

局域网网页 = 同网调试；MQTT 上云 = 经中转服务用演示页远程看一眼、控一下。
板子是 MQTT 客户端；演示页属云侧入口。
过关：演示页见在线，且远程开/关与板载灯一致。
补充：上云不必拆掉局域网 HTTP，两套可并存。
下一篇预告：板端温湿度进状态（SHT30 现象级）。

欢迎对照实践；评论区请写板型、现象与已打码的日志关键字。

串口与配网卡住时，也可寻求线上远程排障（先说清板型与现象）。

系列博文

文 00 Windows 搭 ESP-IDF / 选板
文 01 Flash 配错导致重启
文 02 COM 口与 hello_world 烧录
文 03 工程路径、set-target、sdkconfig
文 04 SoftAP 配网（现象级）
文 05 局域网网页控灯（现象级）
文 06 NVS 掉电记 Wi‑Fi（现象级）
文 07（本文） MQTT 上云验收（思路级）
文 08 SHT30 温湿度进状态（现象级）（待发）