简介本资源是一套面向物联网初学者与毕业设计学生的完整工程实践资料包聚焦STM32嵌入式开发与云平台协同应用解决从硬件感知、无线通信、云端接入到多端可视化控制的全链路实现难题。压缩包共431个文件约415.72MB涵盖Keil工程源码.c/.h/.uvprojx等、编译中间文件.o/.d/.axf、固件镜像.bin、原理图PDF、配置脚本.bat及平台配置说明.txt结构清晰便于分模块学习与调试。已有649人下载学习适用于课程设计、毕设开发及IoT项目快速原型验证。资源提供本地OLED温湿度显示与LED控制、ESP8266 MQTT固件烧录与联网、ThingsCloud云平台项目创建、STM32端MQTT订阅/发布逻辑、以及Android/iOS/微信小程序/Web App四端联动控制的完整代码与实现路径所有程序均经实测可运行配套原理图与接线说明完备显著降低跨平台开发门槛。 最近在搞一个物联网项目时遇到了一个很有意思的需求想让单片机采集的数据不光能在本地屏上显示还得能在手机、小程序、网页上随时看。传统做法是自建服务器但维护成本太高而且对新手非常不友好。后来我找到了 ThingsCloud 这套物联网云平台配合 STM32 ESP8266 MQTT 这套经典组合把整个链路打通了。整个过程踩了不少坑也积累了一些经验决定完整记录下来。这篇文章会带你从零开始手把手实现一个完整的物联网应用STM32 采集环境数据温湿度、光照等通过 ESP8266 以 MQTT 协议上报到 ThingsCloud 云平台然后再用 Android App、iOS App、微信小程序和 Web App 四种方式远程查看和控制设备。不管你是刚入门物联网的嵌入式开发者还是想快速搭建一套 IoT 演示系统的爱好者这篇文章都能给你一条清晰的路线省掉到处查资料的麻烦。1. 整体架构设计与方案选型1.1 系统架构拆解这套系统说白了就是一条数据链路设备端采集数据云端处理和存储数据客户端展示和控制设备。整个架构可以拆成四层来看第一层是感知层也就是 STM32 主控加上各种传感器。主控负责读取传感器数据比如 DHT11 读温湿度、BH1750 读光照强度然后做简单的数据处理和打包。选 STM32 是因为它的资源丰富、价格便宜而且 HAL 库用起来很方便资料也好找。第二层是网络传输层核心是 ESP8266。STM32 通过串口USART和 ESP8266 通信ESP8266 负责连接 Wi-Fi、建立 TCP 连接、发送和接收 MQTT 报文。ESP8266 在这里实际上是扮演了一个网卡的角色把 STM32 的数据转发到互联网。第三层是云平台层我选的是 ThingsCloud。它本质上是一个物联网接入平台提供了 MQTT Broker、设备管理、数据存储、消息推送这些能力。我们不需要自己搭服务器直接在平台上创建项目、添加设备、定义数据模型就能拿到 MQTT 接入地址和认证信息。第四层是应用层包括 Android App、iOS App、微信小程序和 Web App。这些客户端通过 ThingsCloud 提供的 API 或 MQTT 协议订阅设备数据实现远程监控和控制。先看一张数据流向图传感器数据 - STM32 处理打包 - 串口发送给 ESP8266 - ESP8266 通过 MQTT 上报到 ThingsCloud - 云平台存储数据 - App/小程序/Web 通过 API 拉取或 MQTT 订阅展示反向控制链路由客户端发起指令发布到指定 TopicESP8266 订阅这个 Topic收到指令后通过串口转发给 STM32STM32 解析指令并控制外设比如继电器、LED。1.2 为什么选择这套技术栈先说 MQTT 协议。物联网场景里数据量小、设备可能频繁掉线重连、网络带宽不稳定MQTT 就是专门为这种场景设计的轻量级消息发布/订阅协议。它的协议头很小最小的报文只有 2 个字节非常省流量同时支持 QoS 服务质量分级能保证消息不丢还支持遗嘱消息设备掉线时能自动通知服务端。选择 ThingsCloud 而不是自建 MQTT Broker核心原因是省事。自己搭 Mosquitto 或者 EMQX 不是说不行但接下来的事情会很麻烦设备认证、数据存储、数据可视化、App 对接、消息推送全部要自己实现。ThingsCloud 把设备接入、数据流处理、API 接口这些基础能力都做好了我们只需要关注业务本身。客户端为什么要做四种说实话实际开发中不需要每次都做四个端但掌握多端适配的思路很重要。Android 和 iOS 覆盖了移动端用户群微信小程序解决了不想装 App的问题Web 端方便在 PC 上快速查看。这套方案完整的覆盖了物联网应用的常见展示形态做完之后你对每个平台的开发流程和接入方式都会有一个整体的认识。1.3 硬件准备清单动手之前先把硬件准备好这里列一下我用的东西STM32 开发板我用的是 STM32F103C8T6蓝色Pill板新手推荐这个便宜且教程多。最好是最小系统板带 USB 转串口芯片的那种方便烧录和调试。ESP8266 模块建议用 ESP-01S 或者 NodeMCU。ESP-01S 体积小、便宜但只有两个 GPIO而且需要用 USB 转 TTL 模块给它烧录固件和供电NodeMCU 自带 USB 串口和稳压电路开发调试方便很多。我这次是用 ESP-01S 配合 STM32 使用。传感器模块DHT11 温湿度传感器、BH1750 光照传感器I2C接口、还有继电器模块或者 LED 做控制端演示。杜邦线若干、面包板一个、5V/3.3V 电源。USB 转 TTL 模块用于给 ESP8266 烧录固件。2. 环境搭建与基础准备2.1 STM32 开发环境STM32 开发环境我用的是 STM32CubeIDEST 官方出的免费 IDE基于 Eclipse 开发内置了 CubeMX 配置工具。之所以选它是因为它对 HAL 库的支持最原生图形化配置完引脚和时钟直接生成工程骨架省去手写初始化代码的时间。当然你用 Keil MDK 也可以看个人习惯。安装完 CubeIDE 之后先创建一个新的 STM32 工程选择芯片型号 STM32F103C8。在 Pinout 视图里需要配置以下外设USART1接 ESP8266异步收发模式波特率 115200。注意要把 USART1 的 TXPA9连接到 ESP8266 的 RXRXPA10连接到 ESP8266 的 TX交叉连接。USART2用于调试打印连接板载 ST-Link 或 USB 转串口模块波特率 115200。I2C1接 BH1750 光照传感器默认引脚 PB6SCL、PB7SDA。GPIO 输出接继电器或者 LED比如 PA0、PA1。定时器用于毫秒级延时在 CubeMX 里勾选 SysTick 即可HAL 库自带的 HAL_Delay() 就是基于它实现的。项目的时钟树配置外部晶振用板载的 8MHz通过 PLL 倍频到 72MHz这是 STM32F103 的最高主频。配置好之后生成初始工程后面所有代码都在这个工程基础上添加。2.2 ESP8266 固件准备与烧录ESP8266 出厂时一般自带 AT 固件这个固件的好处是我们不需要自己写芯片的固件直接用 AT 指令控制它联网、发送数据。如果你手上的模块是新的直接上电用 AT 测试如果之前刷过其他固件或者不确定建议重新烧一次官方 AT 固件。我整理一下烧录步骤先下载固件。乐鑫官网上有 AT 固件下载页面选择对应 Flash 大小的版本。ESP-01S 的 Flash 是 1MB需要注意选对版本刷错了会变砖。用 USB 转 TTL 模块连接 ESP-01S。接线方式如下USB转TTLESP-01S3.3VVCCGNDGNDTXRXRXTX3.3V或GNDENCH_PD要接高电平也就是3.3VGNDGPIO0烧录时接地正常运行悬空用下载工具烧录。Windows 下用 ESPFlashDownloadTool把固件 bin 文件放到对应地址一般固件包里有说明比如 eagle.flash.bin 放 0x00000eagle.irom0text.bin 放 0x40000选对串口和波特率点 START 开始烧录。烧录完成后把 GPIO0 悬空或者接高电平重新上电用串口调试助手发 AT如果返回 OK说明固件正常。2.3 ThingsCloud 平台配置ThingsCloud 的接入逻辑很清晰创建项目 - 创建设备 - 拿到 MQTT 接入信息。注册并登录 ThingsCloud 控制台后先创建一个项目名字随意比如环境监测网关。然后在项目里创建一个设备设备类型选择网关设备或直连设备。创建完成后在设备详情页能看到 MQTT 连接参数MQTT Broker 地址类似mqtt://xxx.thingscloud.xyz的地址端口1883TCP或 8883TLSClient ID设备证书生成的唯一标识Username 和 Password设备密钥ThingsCloud 也支持三元组认证方式但控制台生成的设备直接就有现成的 Client ID 和密码用这个就行。关键一步是定义数据模型。在设备的物模型或数据模板里定义属性比如temperature类型 float表示温度humidity类型 float表示湿度light类型 int表示光照强度relay类型 bool表示继电器开关状态每个属性都有对应的标识符上报数据时的 JSON key 名必须和物模型一致否则云平台解析不了。这一步很容易忽略切记先把属性定义好再写固件代码。3. STM32 端核心代码实现3.1 传感器数据采集传感器采集这部分我来说说两个传感器的驱动思路。DHT11 是单总线协议用普通的 GPIO 位操作就能读取。它的数据帧是 40 bit8 bit 湿度整数 8 bit 湿度小数 8 bit 温度整数 8 bit 温度小数 8 bit 校验和。读取流程是主机拉低总线至少 18ms 然后释放DHT11 会拉低响应信号再拉高之后按时序一位一位地输出数据。判断每一位是 0 还是 1看高电平持续的时间26-28us 左右的为 070us 左右的是 1。用 HAL 库实现时特别要注意的是需要禁用中断或者确保延时精度足够。HAL_Delay 的精度只有 1ms但 DHT11 的位读取需要微秒级延时。我写了一个 Delay_us 函数void Delay_us(uint16_t us) { __HAL_TIM_SET_COUNTER(htim1, 0); HAL_TIM_Base_Start(htim1); while(__HAL_TIM_GET_COUNTER(htim1) us); HAL_TIM_Base_Stop(htim1); }定时器配置成 1MHz 计数每个 tick 就是 1us这个函数用起来很方便。你也可以用 Cortex-M 内核自带的 DWT 寄存器做微秒延时但定时器方案更直观不折腾。BH1750 是 I2C 接口用 HAL 库的 I2C 函数直接读就行。上电后先发送一次断电指令0x00再发送连续高分辨率模式指令0x10等 180ms 后读 2 个字节合并成 16 位数据除以 1.2 就得到光照强度单位 lux。代码如下uint8_t bh1750_buf[2]; uint16_t light_raw 0; float light_lux 0.0f; HAL_I2C_Mem_Write(hi2c1, 0x46, 0x00, I2C_MEMADD_SIZE_8BIT, NULL, 0, 100); HAL_I2C_Master_Transmit(hi2c1, 0x46, (uint8_t[]){0x10}, 1, 100); HAL_Delay(180); HAL_I2C_Master_Receive(hi2c1, 0x46, bh1750_buf, 2, 100); light_raw (bh1750_buf[0] 8) | bh1750_buf[1]; light_lux (float)light_raw / 1.2f;注意 BH1750 的器件地址是 0x23 左移一位变成 0x46因为 I2C 是 7 位地址加读写位HAL 库的地址参数需要的是完整 8 位地址。3.2 STM32 与 ESP8266 的串口通信STM32 和 ESP8266 的通信方式我选的是串口 AT 指令。为什么不直接用 ESP8266 跑 MQTT 而是让 STM32 通过 AT 指令转发原因很简单AT 固件把复杂的 TCP/IP 连接和 MQTT 协议栈都封装好了STM32 只需要发送字符串指令比如ATCIPSTARTTCP,xxx.thingscloud.xyz,1883就能建立 TCP 连接大幅降低了单片机端的工作量和固件开发复杂度。但这里有个坑ESP8266 的 AT 固件默认不支持透传 MQTT 报文它只是一个 TCP 通道。所以 MQTT 协议本身的打包和解包逻辑要在 STM32 端自己实现。有人可能会问那为什么不直接用 ESP8266 跑 MQTT 固件或者用官方 MQTT AT 指令实际上乐鑫新的 AT 固件确实带了 MQTT 指令ATMQTTCONN、ATMQTTSUB、ATMQTTPUB但我用下来发现这些指令在 ESP-01S 这种小 Flash 模块上兼容性和稳定性不太好容易出现莫名奇妙的问题。而在 STM32 端自己组装 MQTT 报文虽然代码多一点但是完全可控出了 bug 也好排查。串口通信要解决的一个核心问题是数据的发送和接收如何同步。我的做法是写了一个阻塞式发送函数和一个中断接收的解析队列。STM32 发送 AT 指令给 ESP8266然后等待 ESP8266 的响应比如收到 OK 或者错误提示再执行下一步。这样可以保证每一步都确认成功后再继续避免状态错乱。void ESP8266_SendATCmd(const char* cmd, char* resp, uint16_t resp_len, uint32_t timeout) { // 清空接收缓冲区 memset(esp8266_rx_buf, 0, ESP8266_RX_BUF_SIZE); rx_index 0; // 发送指令 HAL_UART_Transmit(huart1, (uint8_t*)cmd, strlen(cmd), 200); // 等待响应 uint32_t start HAL_GetTick(); while(HAL_GetTick() - start timeout) { if(rx_index 0) { // 检查是否收到 OK / ERROR / 其他关键标记 if(strstr(esp8266_rx_buf, resp) ! NULL) { break; } } } }接收端用串口空闲中断结合 DMA或者简单点用 HAL_UART_Receive_IT 逐字节接收。为了简化逻辑这次用逐字节接收中断在中断回调里把数据存入缓冲区void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) { if(huart-Instance USART1) { esp8266_rx_buf[rx_index] rx_byte; if(rx_index ESP8266_RX_BUF_SIZE) rx_index 0; HAL_UART_Receive_IT(huart1, rx_byte, 1); } }3.3 MQTT 报文手动组装与解析MQTT 报文结构不复杂但第一次手写时要注意细节。我按 MQTT 3.1.1 协议来实现这也是 ThingsCloud 默认支持的版本。MQTT 报文由三部分组成固定报头、可变报头、有效载荷。固定报头第一个字节是报文类型和标志位第二个字节是剩余长度。比如 PUBLISH 报文的第一字节高四位是 3二进制 0011QoS 0 时标志位全为 0所以第一字节就是 0x30。连接报文 CONNECT 是客户端发给服务端的第一个报文需要包含协议名MQTT、协议级别 4、连接标志位用户名密码标志、保活时间、Client ID、用户名和密码。我在 STM32 端构造了一个函数void MQTT_ConnectPacket(uint8_t* buf, uint16_t* len) { uint16_t idx 0; buf[idx] 0x10; // CONNECT 报文QoS 0 // 剩余长度先占位 uint8_t remain_len_pos idx; // 协议名 buf[idx] 0x00; buf[idx] 0x04; buf[idx] M; buf[idx] Q; buf[idx] T; buf[idx] T; // 协议级别 4 (MQTT 3.1.1) buf[idx] 0x04; // 连接标志用户名密码清理会话 buf[idx] 0xC2; // 保活时间 60 秒 buf[idx] 0x00; buf[idx] 0x3C; // Client ID 字符串 // Username 字符串 // Password 字符串 // ... // 回填剩余长度 buf[remain_len_pos] idx - remain_len_pos - 1; *len idx; }剩余长度字段是一个可变字节编码如果报文长度小于 128 字节直接用 1 个字节表示超过 128 字节要用多个字节编码规则是每个字节低 7 位存放有效数据最高位是连续标志。这个细节很容易写错报文一长就会出现解析错误。发送数据用的是 PUBLISH 报文报文格式是固定报头0x30QoS 0或者 0x31/0x32QoS 1可变报头Topic 名称2 字节长度 主题字符串QoS 1 时还要加上 2 字节的报文标识符有效载荷JSON 格式的数据比如上报{temperature: 25.6}最终的报文大致是0x30 0x?? [topic_len_hi] [topic_len_lo] [topic bytes...] {temperature: 25.6}订阅主题用的 SUBSCRIBE 报文固定报头第一字节是 0x82可变报头包含报文标识符2 字节有效载荷是主题和 QoS 级别。心跳报文 PINGREQ 最简单固定两字节0xC0 0x00。ESP8266 每隔一段时间没有数据通信时STM32 要发一个 PINGREQ 维持连接超过保活时间服务端没收到任何包就会断开连接。解析订阅消息同样要在 STM32 端处理。当 ESP8266 收到 TCP 数据后通过串口发给 STM32STM32 需要从数据流中解析出 MQTT 报文判断是 PUBLISH 消息后提取主题和载荷内容。下面是一段简单的解析代码void MQTT_HandlePacket(uint8_t* data, uint16_t len) { uint8_t type data[0] 4; uint16_t idx 1; // 解析剩余长度 uint32_t remain_len 0; uint8_t multiplier 1; uint8_t encoded_byte; do { encoded_byte data[idx]; remain_len (encoded_byte 0x7F) * multiplier; multiplier * 128; } while ((encoded_byte 0x80) idx len); switch(type) { case 3: // PUBLISH // 解析主题 uint16_t topic_len (data[idx] 8) | data[idx1]; idx 2; // 提取消息内容 uint8_t* payload data idx topic_len; uint16_t payload_len remain_len - 2 - topic_len; // 处理业务逻辑 HandleCloudCommand(payload, payload_len); break; case 13: // PINGRESP break; default: break; } }这里我用的是裸指针直接操作缓冲区实际工程中要注意缓冲区越界的问题。另外TCP 粘包的场景一定要考虑。ESP8266 可能一次上报多个 MQTT 报文需要循环解析直到缓冲区的数据全部处理完。4. ESP8266 联网与 MQTT 接入4.1 ESP8266 初始化与 Wi-Fi 连接ESP8266 的初始化顺序是先测试 AT 指令是否正常然后配置 Wi-Fi 模式再连接路由器获取 IP最后建立 TCP 连接。AT 指令的序列如下AT ATE0 // 关闭回显减少串口数据量 ATCWMODE1 // Station 模式 ATCWJAPWiFi名称,WiFi密码 // 连接 Wi-Fi ATCIPSTARTTCP,mqtt.thingscloud.xyz,1883 // 建立 TCP 连接串口输出会被 ESP8266 的大量 IPD 前缀的数据淹没所以关闭回显很重要。同时建议把 Wi-Fi 连接状态查询用起来连接成功后再往下走。判断方式是在发送ATCWJAP后循环发ATCWJAP?查询直到返回CWJAP:3表示连接成功。从实际使用来看ESP-01S 有个共同问题天线信号一般同时供电不足的时候容易掉线。建议线路尽量短或者用外部 3.3V 稳压给它独立供电避免和 STM32 共用 LDO 导致电流不够。TCP 连接成功后STM32 就要通过已有的 TCP 通道发送 MQTT 报文。AT 指令用ATCIPSEND长度然后输入等长的数据返回SEND OK。比如发送 CONNECT 报文时uint8_t mqtt_buf[256]; uint16_t mqtt_len 0; MQTT_ConnectPacket(mqtt_buf, mqtt_len); char cipsend_cmd[32]; sprintf(cipsend_cmd, ATCIPSEND%d\r\n, mqtt_len); ESP8266_SendATCmd(cipsend_cmd, , 2000); HAL_UART_Transmit(huart1, mqtt_buf, mqtt_len, 500); // 等待 SEND OK ESP8266_WaitResp(SEND OK, 2000);注意ATCIPSEND发送后ESP8266 先返回一个提示符然后我们才能发送数据。我遇到过有人直接发数据结果前几个字节被当成指令吞掉的情况。所以一定要等出现再发这个细节要记得。4.2 接收下行数据与自动重连TCP 建立后ESP8266 通过串口主动上报收到的数据格式是IPD,长度:数据内容所以 STM32 串口接收解析时要识别IPD这个前缀。在我的代码里通过串口中断把整个数据存入缓冲区然后在主循环里扫描IPD关键字找到后提取长度字段再从冒号后面取出真正的 MQTT 报文if(strstr(esp8266_rx_buf, IPD) ! NULL) { char* p strstr(esp8266_rx_buf, IPD); int len 0; sscanf(p, IPD,%d:, len); char* payload_start strchr(p, :) 1; MQTT_HandlePacket((uint8_t*)payload_start, len); }IPD后面可能超过一个 TCP 包合并在一起也就是说一段数据里可能有多个IPD头。我的处理方式是解析完一个 MQTT 包后从缓冲区中移除这部分数据然后循环扫描下一个IPD。虽然麻烦点但很稳。断线重连是物联网应用逃不开的坑。我的应对方案是在主循环中维护一个计数器默认 30 秒发一次 PINGREQ。如果连续 3 次没收到 PINGRESP判定 TCP 连接已断开关闭连接。先调ATCIPSTART重新建立 TCP 连接再重新发 CONNECT 报文重新订阅主题。设置一个掉线计数连续重连失败 N 次后重启 ESP8266通过 GPIO 控制 CH_PD 引脚拉低再拉高。用这套逻辑即使路由器重启系统也能在 1 分钟内自动恢复。5. 云平台数据对接与多端应用开发5.1 ThingsCloud 数据流转机制设备上报的数据到了 ThingsCloud 之后平台会做几件事校验设备身份、解析 MQTT 报文、把数据写入数据库、通过规则引擎或 API 供外部调用。ThingsCloud 的消息 Topic 有固定格式。设备发布消息到主题devices/device_id/messages/upload载荷是 JSON比如{ temperature: 25.6, humidity: 60.2, light: 320, relay: false }控制指令是由平台下发到devices/device_id/messages/down主题客户端发布控制消息到这个主题设备端订阅这个主题即可收到。平台上还可以配置数据告警规则比如温度超过 30 度推送报警消息到 App。这些可以在控制台的可视化界面里配置不需要写代码。我把告警规则配在了高温告警和低电量告警两个场景上实测短信和邮件通知都推送得很及时。5.2 Android App 开发要点Android App 我用的是 Kotlin Eclipse Paho MQTT 客户端库。Paho 是 Eclipse 基金会维护的一个 MQTT 客户端库Android 端用org.eclipse.paho.client.mqttv3使用也很简单val client MqttClient(tcp://mqtt.thingscloud.xyz:1883, clientId, MemoryPersistence()) val options MqttConnectOptions().apply { userName device_id password device_password.toCharArray() isCleanSession true connectionTimeout 10 keepAliveInterval 60 } client.setCallback(object : MqttCallback { override fun messageArrived(topic: String?, message: MqttMessage?) { // 处理云端下发的控制指令 } }) client.connect(options) client.subscribe(devices/device_id/messages/down) client.publish(devices/device_id/messages/upload, {\relay\:true}.toByteArray(), 0, false)App 端的 UI 我用的是简单的 LinearLayout RecyclerView 做数据展示。界面主要分三块顶部实时数据卡片显示温度和湿度中间光照强度进度条底部继电器开关按钮。更新数据用 Handler 定时去查或通过 MQTT 订阅实时刷新我选的后者因为 MQTT 实时性好而且省电。Android App 开发中要注意一个关键点网络权限和 Cleartext 流量限制。Android 9 之后默认禁止明文 HTTP 流量如果你的 MQTT 走的是 1883 端口而不是 8883 TLS 端口需要在 AndroidManifest 里加android:usesCleartextTraffictrue否则连不上。5.3 iOS App 开发要点iOS 端我用的是 Swift CocoaMQTT 库通过 CocoaPods 集成。iOS 端接入 MQTT 的思路和 Android 完全一样只是 API 风格不同let client CocoaMQTT(clientID: iOS-Client, host: mqtt.thingscloud.xyz, port: 1883) client.username device_id client.password device_password client.keepAlive 60 client.didReceiveMessage { mqtt, message, id in // 处理订阅的主题消息 } client.connect() client.publish(devices/device_id/messages/upload, withString: {\relay\:false}, qos: .qos0)iOS 开发有一个比较麻烦的点App 退到后台后 MQTT 连接很可能会被系统挂起。如果要保持长时间连接需要配置 Background Mode但 App Store 审核对这个有严格的限制。一般简单方案是 App 退后台时主动断开回前台时重连通过云端缓存最新数据来弥补断线期间的数据空白。5.4 微信小程序开发要点微信小程序端我用的是原生开发MQTT 库选了mqtt.js。小程序和普通网页的 MQTT 接入有个重要的区别小程序运行环境不支持 Node.js 的net模块所以mqtt.js必须使用 WebSocket 方式来连接 MQTT Broker。ThingsCloud 对 WebSocket 接入的支持方式是MQTT over WebSocket默认端口是 8083 或 8084WSS。连接地址要写成const mqtt require(mqtt) const client mqtt.connect(wxs://mqtt.thingscloud.xyz:8084/mqtt, { clientId: wxapp_ Date.now(), username: device_id, password: device_password })注意是wxs://不是ws://。小程序要求所有请求必须是 HTTPS 或 WSS所以不配置 TLS 的话是连不上的。另外在小程序后台管理里要把 ThingsCloud 的域名加到 socket 合法域名列表里否则真机上连接会被拦。小程序页面展示我用了一个简单的数据卡片布局通过onShow生命周期里 connect 和订阅onHide时断开连接避免在后台持续占用资源。5.5 Web App 开发要点Web 端我用了 Vue 3 mqtt.js 实现。Web 端和 WebSocket 的方式类似但浏览器环境对 MQTT over WebSocket 的支持更标准一些import mqtt from mqtt; const client mqtt.connect(ws://xxx.thingscloud.xyz:8083/mqtt, { clientId: web_ Math.random().toString(16).substring(2), username: device_id, password: device_password }); client.on(connect, () { client.subscribe(devices/device_id/messages/down); }); client.on(message, (topic, payload) { const data JSON.parse(payload.toString()); // 更新页面数据 });Web 端我加了一个图表组件用 ECharts 画温湿度的实时曲线效果比纯数据展示直观很多。历史数据用 ThingsCloud 的 REST API 拉取在页面加载时显示最近 24 小时的曲线。不过这需要 API Key 鉴权在控制台创建 API Key 之后用它放在 HTTP header 里请求数据接口。6. 典型问题与排查心得6.1 连接和通信类问题实际调试下来遇到的坑不少这里挑几个典型的说一下。第一个坑是 ESP8266 连不上路由器或者频繁掉线。排查思路是先用串口助手单独测 ESP8266发 ATCWJAP 看返回。如果返回 ERROR看下是不是 Wi-Fi 密码错了或者路由器 5G 频段的问题——ESP 系列只支持 2.4G 频段连 5G 肯定失败。另外电源不稳定也会导致掉线ESP-01S 在发送数据瞬间电流会到 300mA用板载 LDO 供电很容易掉压给它并一个大电容或者独立稳压供电能解决大部分掉线问题。第二个坑是 MQTT 连接建立了但收不到数据。这种情况 90% 是订阅的主题不对或者设备的发布/订阅权限没配好。ThingsCloud 的 Topic 里带设备 ID一定要核对一下设备详情页里的真实 ID别拿示例目录里的占位符去订阅。还有物模型属性标识符要和上报数据的 key 完全一致大小写都不能错否则平台解析失败会直接丢弃消息。第三个坑是 STM32 串口接收乱码或数据错位。常见原因是波特率不匹配或者 ESP8266 回显没关。调试时我是先用电脑串口助手单独测 ESP8266 的收发确认链路通了再接 STM32这样能快速定位问题在哪一端。另外注意 STM32 和 ESP8266 之间电平要匹配——STM32 是 3.3V IOESP8266 也是 3.3V直接连没问题但如果中间加了电平转换芯片一定要检查方向是否正确。6.2 常见问题速查表现象可能原因排查及解决AT 无响应串口接错/波特率不对/固件损坏检查 RX/TX 是否交叉确认波特率 115200重刷固件Wi-Fi 连接 ERROR密码错误/频段不支持/信号弱确认 2.4G 频段检查密码增强供电TCP 连接失败Broker 地址错误/端口被防火墙拦截telnet 测试地址端口确认 1883 端口可达MQTT CONNECT 被拒绝Client ID/账号密码错误核对设备证书注意区分大小写数据上报了但平台看不到Topic 错误/JSON key 与物模型不一致在平台日志里查消息核对属性标识符收不到下行控制指令订阅 Topic 错误/未发送 PINGREQ 维持连接检查订阅主题确认保活机制正常App 连不上 MQTT明文流量被限制/域名未加白名单Android 加 usesCleartextTraffic小程序加 socket 合法域名App 退后台后收不到消息系统挂起 MQTT 连接实现退后台断开、回前台重连逻辑6.3 调试工具和排查方法调试这套系统我常用的工具是 MQTT.fx 和 MQTTX。这两个都是桌面版 MQTT 客户端可以手动连接到 ThingsCloud手动发布和订阅 Topic。这样在排查问题时能快速区分是设备端的问题还是云端/客户端的问题。我的排查习惯是先用 MQTTX 连接 ThingsCloud手动发一条数据看平台能不能收到然后再用 ESP8266 的串口日志看 STM32 发送的报文是否正常最后用手机 App 验证整个数据链路。一层层排查问题定位很快。串口调试助手我用的是 SSCOM 和 XCOM一个偏工程风格、一个界面友好一些看个人习惯。另外有条件的话在 MQTT Broker 侧抓包分析用 Wireshark 过滤 MQTT 协议就能看到完整的报文交换过程。有一次我排查一个报文错乱的问题就是靠看抓包里每个字节的十六进制值才找到原因的——STM32 端构造的报文长度字段算错了导致服务端解析出了异常。7. 多端数据同步与状态管理7.1 设备影子与数据一致性物联网应用里除了设备实时上报数据还有一类数据需要处理设备的状态比如继电器是开还是关。如果只是简单地把状态存到 App 本地那么手机 A 打开了继电器手机 B 上显示的还是关闭状态这就出现了数据不一致。ThingsCloud 提供了一个设备影子的机制简单说就是云端保存一个设备状态的 JSON 快照。设备上报数据后影子会自动更新客户端读取状态时优先从影子拿而不是等设备应答。这样即使设备离线也能知道它最后的状态。实际开发中我的做法是继电器状态单独放到一个属性里上报控制指令发送后不管设备是否立即应答App 端都先把本地 UI 更新成目标状态再等待设备上报的新状态来确认。如果 3 秒内没收到确认就提示指令已发送等待设备响应。同步的思路就是每次设备状态变化都完整地发布一次包含所有属性的 JSON。这样任何一端收到消息都能用最新的数据整体覆盖本地的旧数据不会出现只更新了温度没更新湿度的不一致问题。7.2 离线消息与 QoS 选择MQTT 的 QoS 分 3 级QoS 0 最多发送一次可能丢QoS 1 保证至少到达一次但可能重复QoS 2 保证只到达一次但开销最大。在物联网场景里对于传感器周期上报的数据我建议用 QoS 0因为即使丢掉一次下一秒又会重新上报问题不大。但对于控制指令比如开继电器如果丢了用户就发现设备没响应所以至少用 QoS 1。ThingsCloud 默认支持 QoS 0 和 QoS 1够用了。另外要注意的是 MQTT 协议中客户端订阅 Topic 时可以设置 QoS服务端发布消息时也有自己的 QoS最终消息实际到达的 QoS 取两者中的最小值。所以如果订阅时设了 QoS 2但服务端发布用的是 QoS 0实际消息还是 QoS 0不会变成 QoS 2。不用纠结这个细节做到控制指令用 QoS 1数据上报用 QoS 0就够了。7.3 多端并发控制在实践中如何处理到了多端并发场景一个设备对应四个客户端每个客户端都能发控制指令就可能出现A 发开、B 发关这种竞争。我的解法是在云平台上增加一个指令序号字段每次下发指令时带上一个自增的编号设备端只处理比当前序号大的指令把旧的指令丢弃。这个方案实现很简单却很好地避免了并发控制时的指令乱序问题。当然如果你有更复杂的业务逻辑比如需要按用户权限控制设备那就需要在云端做一层授权处理。ThingsCloud 的 API 也支持按设备设置访问权限这些后续可以根据需求扩展。对于入门级的项目来说序号去重就够了。8. 项目总结与扩展思路8.1 开发流程复盘整个项目走下来我最大的感受是物联网项目的核心不是某个单独的技术点而是数据链路的贯通。从传感器读数到云端存储再到多端展示一整条链路里每一个环节都不能断。我刚开始做的时候在 MQTT 报文组装上卡了两天后来发现是剩余长度字段的编码算错了导致云端一直解析失败。所以我的建议是千万别跳过协议理解这一步哪怕手边有现成的库也要懂底层的工作原理出了问题才能快速定位。8.2 项目扩展方向这套系统的基础架构搭好之后后续扩展就很方便了。你可以增加更多传感器比如 PM2.5、土壤湿度、烟雾报警只需要在 STM32 端加驱动代码云平台上加几个属性客户端加几个 UI 组件。增加执行器控制比如智能插座、窗帘电机通过继电器驱动逻辑和继电器控制完全一样。数据告警与联动在 ThingsCloud 上配置规则引擎温度过高自动发通知或者触发另一个设备的动作。设备固件 OTA 升级通过云平台下发固件STM32 通过 ESP8266 接收升级包这个稍微复杂一些要自己实现升级协议。接入语音助手比如小爱同学、天猫精灵通过云平台做协议转换实现语音控制设备。8.3 最后分享一点个人经验最后再分享一个小技巧开发过程中我给整个系统加了一个心跳逻辑不只是 MQTT 的 PINGREQ而是在应用层也在客户端和服务端之间定时互相打点。客户端每 30 秒发布一条包含客户端类型和在线状态的心跳消息设备端收到的传感器数据在云平台也标记一个时间戳。这样在 App 上能看到设备上次在线时间和客户端连接状态排查问题时非常有用。另外一个经验是关于工程管理的把这个项目做成一个工程资料包形式来管理是很明智的选择。因为四个端加一个单片机工程代码量不小如果你把开发环境、依赖库版本、引脚定义、云平台配置这些信息都整理成文档放在工程目录里隔几个月再回来看还能快速上手。我这里推荐在工程里加一个 README.md把上面提到的硬件接线表、AT 指令序列、MQTT Topic 定义、ThingsCloud 账号相关配置但注意不要提交真实密钥全部写清楚。你以后维护这个项目或者分享给别人都会省很多事。硬件开发有意思的地方就在于它能打破虚拟世界和现实世界的边界。当你在手机 App 上按下开关远处的继电器真的咔哒一声响了的时候那种成就感是纯写代码体会不到的。希望这篇文章能帮你把这条路走通少踩一些坑。本文还有配套的精品资源点击获取 
长河君 · 2026/8/31 21:42:57 · 阅读 1.2k STM32+ESP8266+MQTT+云平台：多端物联网监测与控制实战
简介本资源是一套面向物联网初学者与毕业设计学生的完整工程实践资料包聚焦STM32嵌入式开发与云平台协同应用解决从硬件感知、无线通信、云端接入到多端可视化控制的全链路实现难题。压缩包共431个文件约415.72MB涵盖Keil工程源码.c/.h/.uvprojx等、编译中间文件.o/.d/.axf、固件镜像.bin、原理图PDF、配置脚本.bat及平台配置说明.txt结构清晰便于分模块学习与调试。已有649人下载学习适用于课程设计、毕设开发及IoT项目快速原型验证。资源提供本地OLED温湿度显示与LED控制、ESP8266 MQTT固件烧录与联网、ThingsCloud云平台项目创建、STM32端MQTT订阅/发布逻辑、以及Android/iOS/微信小程序/Web App四端联动控制的完整代码与实现路径所有程序均经实测可运行配套原理图与接线说明完备显著降低跨平台开发门槛。 最近在搞一个物联网项目时遇到了一个很有意思的需求想让单片机采集的数据不光能在本地屏上显示还得能在手机、小程序、网页上随时看。传统做法是自建服务器但维护成本太高而且对新手非常不友好。后来我找到了 ThingsCloud 这套物联网云平台配合 STM32 ESP8266 MQTT 这套经典组合把整个链路打通了。整个过程踩了不少坑也积累了一些经验决定完整记录下来。这篇文章会带你从零开始手把手实现一个完整的物联网应用STM32 采集环境数据温湿度、光照等通过 ESP8266 以 MQTT 协议上报到 ThingsCloud 云平台然后再用 Android App、iOS App、微信小程序和 Web App 四种方式远程查看和控制设备。不管你是刚入门物联网的嵌入式开发者还是想快速搭建一套 IoT 演示系统的爱好者这篇文章都能给你一条清晰的路线省掉到处查资料的麻烦。1. 整体架构设计与方案选型1.1 系统架构拆解这套系统说白了就是一条数据链路设备端采集数据云端处理和存储数据客户端展示和控制设备。整个架构可以拆成四层来看第一层是感知层也就是 STM32 主控加上各种传感器。主控负责读取传感器数据比如 DHT11 读温湿度、BH1750 读光照强度然后做简单的数据处理和打包。选 STM32 是因为它的资源丰富、价格便宜而且 HAL 库用起来很方便资料也好找。第二层是网络传输层核心是 ESP8266。STM32 通过串口USART和 ESP8266 通信ESP8266 负责连接 Wi-Fi、建立 TCP 连接、发送和接收 MQTT 报文。ESP8266 在这里实际上是扮演了一个网卡的角色把 STM32 的数据转发到互联网。第三层是云平台层我选的是 ThingsCloud。它本质上是一个物联网接入平台提供了 MQTT Broker、设备管理、数据存储、消息推送这些能力。我们不需要自己搭服务器直接在平台上创建项目、添加设备、定义数据模型就能拿到 MQTT 接入地址和认证信息。第四层是应用层包括 Android App、iOS App、微信小程序和 Web App。这些客户端通过 ThingsCloud 提供的 API 或 MQTT 协议订阅设备数据实现远程监控和控制。先看一张数据流向图传感器数据 - STM32 处理打包 - 串口发送给 ESP8266 - ESP8266 通过 MQTT 上报到 ThingsCloud - 云平台存储数据 - App/小程序/Web 通过 API 拉取或 MQTT 订阅展示反向控制链路由客户端发起指令发布到指定 TopicESP8266 订阅这个 Topic收到指令后通过串口转发给 STM32STM32 解析指令并控制外设比如继电器、LED。1.2 为什么选择这套技术栈先说 MQTT 协议。物联网场景里数据量小、设备可能频繁掉线重连、网络带宽不稳定MQTT 就是专门为这种场景设计的轻量级消息发布/订阅协议。它的协议头很小最小的报文只有 2 个字节非常省流量同时支持 QoS 服务质量分级能保证消息不丢还支持遗嘱消息设备掉线时能自动通知服务端。选择 ThingsCloud 而不是自建 MQTT Broker核心原因是省事。自己搭 Mosquitto 或者 EMQX 不是说不行但接下来的事情会很麻烦设备认证、数据存储、数据可视化、App 对接、消息推送全部要自己实现。ThingsCloud 把设备接入、数据流处理、API 接口这些基础能力都做好了我们只需要关注业务本身。客户端为什么要做四种说实话实际开发中不需要每次都做四个端但掌握多端适配的思路很重要。Android 和 iOS 覆盖了移动端用户群微信小程序解决了不想装 App的问题Web 端方便在 PC 上快速查看。这套方案完整的覆盖了物联网应用的常见展示形态做完之后你对每个平台的开发流程和接入方式都会有一个整体的认识。1.3 硬件准备清单动手之前先把硬件准备好这里列一下我用的东西STM32 开发板我用的是 STM32F103C8T6蓝色Pill板新手推荐这个便宜且教程多。最好是最小系统板带 USB 转串口芯片的那种方便烧录和调试。ESP8266 模块建议用 ESP-01S 或者 NodeMCU。ESP-01S 体积小、便宜但只有两个 GPIO而且需要用 USB 转 TTL 模块给它烧录固件和供电NodeMCU 自带 USB 串口和稳压电路开发调试方便很多。我这次是用 ESP-01S 配合 STM32 使用。传感器模块DHT11 温湿度传感器、BH1750 光照传感器I2C接口、还有继电器模块或者 LED 做控制端演示。杜邦线若干、面包板一个、5V/3.3V 电源。USB 转 TTL 模块用于给 ESP8266 烧录固件。2. 环境搭建与基础准备2.1 STM32 开发环境STM32 开发环境我用的是 STM32CubeIDEST 官方出的免费 IDE基于 Eclipse 开发内置了 CubeMX 配置工具。之所以选它是因为它对 HAL 库的支持最原生图形化配置完引脚和时钟直接生成工程骨架省去手写初始化代码的时间。当然你用 Keil MDK 也可以看个人习惯。安装完 CubeIDE 之后先创建一个新的 STM32 工程选择芯片型号 STM32F103C8。在 Pinout 视图里需要配置以下外设USART1接 ESP8266异步收发模式波特率 115200。注意要把 USART1 的 TXPA9连接到 ESP8266 的 RXRXPA10连接到 ESP8266 的 TX交叉连接。USART2用于调试打印连接板载 ST-Link 或 USB 转串口模块波特率 115200。I2C1接 BH1750 光照传感器默认引脚 PB6SCL、PB7SDA。GPIO 输出接继电器或者 LED比如 PA0、PA1。定时器用于毫秒级延时在 CubeMX 里勾选 SysTick 即可HAL 库自带的 HAL_Delay() 就是基于它实现的。项目的时钟树配置外部晶振用板载的 8MHz通过 PLL 倍频到 72MHz这是 STM32F103 的最高主频。配置好之后生成初始工程后面所有代码都在这个工程基础上添加。2.2 ESP8266 固件准备与烧录ESP8266 出厂时一般自带 AT 固件这个固件的好处是我们不需要自己写芯片的固件直接用 AT 指令控制它联网、发送数据。如果你手上的模块是新的直接上电用 AT 测试如果之前刷过其他固件或者不确定建议重新烧一次官方 AT 固件。我整理一下烧录步骤先下载固件。乐鑫官网上有 AT 固件下载页面选择对应 Flash 大小的版本。ESP-01S 的 Flash 是 1MB需要注意选对版本刷错了会变砖。用 USB 转 TTL 模块连接 ESP-01S。接线方式如下USB转TTLESP-01S3.3VVCCGNDGNDTXRXRXTX3.3V或GNDENCH_PD要接高电平也就是3.3VGNDGPIO0烧录时接地正常运行悬空用下载工具烧录。Windows 下用 ESPFlashDownloadTool把固件 bin 文件放到对应地址一般固件包里有说明比如 eagle.flash.bin 放 0x00000eagle.irom0text.bin 放 0x40000选对串口和波特率点 START 开始烧录。烧录完成后把 GPIO0 悬空或者接高电平重新上电用串口调试助手发 AT如果返回 OK说明固件正常。2.3 ThingsCloud 平台配置ThingsCloud 的接入逻辑很清晰创建项目 - 创建设备 - 拿到 MQTT 接入信息。注册并登录 ThingsCloud 控制台后先创建一个项目名字随意比如环境监测网关。然后在项目里创建一个设备设备类型选择网关设备或直连设备。创建完成后在设备详情页能看到 MQTT 连接参数MQTT Broker 地址类似mqtt://xxx.thingscloud.xyz的地址端口1883TCP或 8883TLSClient ID设备证书生成的唯一标识Username 和 Password设备密钥ThingsCloud 也支持三元组认证方式但控制台生成的设备直接就有现成的 Client ID 和密码用这个就行。关键一步是定义数据模型。在设备的物模型或数据模板里定义属性比如temperature类型 float表示温度humidity类型 float表示湿度light类型 int表示光照强度relay类型 bool表示继电器开关状态每个属性都有对应的标识符上报数据时的 JSON key 名必须和物模型一致否则云平台解析不了。这一步很容易忽略切记先把属性定义好再写固件代码。3. STM32 端核心代码实现3.1 传感器数据采集传感器采集这部分我来说说两个传感器的驱动思路。DHT11 是单总线协议用普通的 GPIO 位操作就能读取。它的数据帧是 40 bit8 bit 湿度整数 8 bit 湿度小数 8 bit 温度整数 8 bit 温度小数 8 bit 校验和。读取流程是主机拉低总线至少 18ms 然后释放DHT11 会拉低响应信号再拉高之后按时序一位一位地输出数据。判断每一位是 0 还是 1看高电平持续的时间26-28us 左右的为 070us 左右的是 1。用 HAL 库实现时特别要注意的是需要禁用中断或者确保延时精度足够。HAL_Delay 的精度只有 1ms但 DHT11 的位读取需要微秒级延时。我写了一个 Delay_us 函数void Delay_us(uint16_t us) { __HAL_TIM_SET_COUNTER(htim1, 0); HAL_TIM_Base_Start(htim1); while(__HAL_TIM_GET_COUNTER(htim1) us); HAL_TIM_Base_Stop(htim1); }定时器配置成 1MHz 计数每个 tick 就是 1us这个函数用起来很方便。你也可以用 Cortex-M 内核自带的 DWT 寄存器做微秒延时但定时器方案更直观不折腾。BH1750 是 I2C 接口用 HAL 库的 I2C 函数直接读就行。上电后先发送一次断电指令0x00再发送连续高分辨率模式指令0x10等 180ms 后读 2 个字节合并成 16 位数据除以 1.2 就得到光照强度单位 lux。代码如下uint8_t bh1750_buf[2]; uint16_t light_raw 0; float light_lux 0.0f; HAL_I2C_Mem_Write(hi2c1, 0x46, 0x00, I2C_MEMADD_SIZE_8BIT, NULL, 0, 100); HAL_I2C_Master_Transmit(hi2c1, 0x46, (uint8_t[]){0x10}, 1, 100); HAL_Delay(180); HAL_I2C_Master_Receive(hi2c1, 0x46, bh1750_buf, 2, 100); light_raw (bh1750_buf[0] 8) | bh1750_buf[1]; light_lux (float)light_raw / 1.2f;注意 BH1750 的器件地址是 0x23 左移一位变成 0x46因为 I2C 是 7 位地址加读写位HAL 库的地址参数需要的是完整 8 位地址。3.2 STM32 与 ESP8266 的串口通信STM32 和 ESP8266 的通信方式我选的是串口 AT 指令。为什么不直接用 ESP8266 跑 MQTT 而是让 STM32 通过 AT 指令转发原因很简单AT 固件把复杂的 TCP/IP 连接和 MQTT 协议栈都封装好了STM32 只需要发送字符串指令比如ATCIPSTARTTCP,xxx.thingscloud.xyz,1883就能建立 TCP 连接大幅降低了单片机端的工作量和固件开发复杂度。但这里有个坑ESP8266 的 AT 固件默认不支持透传 MQTT 报文它只是一个 TCP 通道。所以 MQTT 协议本身的打包和解包逻辑要在 STM32 端自己实现。有人可能会问那为什么不直接用 ESP8266 跑 MQTT 固件或者用官方 MQTT AT 指令实际上乐鑫新的 AT 固件确实带了 MQTT 指令ATMQTTCONN、ATMQTTSUB、ATMQTTPUB但我用下来发现这些指令在 ESP-01S 这种小 Flash 模块上兼容性和稳定性不太好容易出现莫名奇妙的问题。而在 STM32 端自己组装 MQTT 报文虽然代码多一点但是完全可控出了 bug 也好排查。串口通信要解决的一个核心问题是数据的发送和接收如何同步。我的做法是写了一个阻塞式发送函数和一个中断接收的解析队列。STM32 发送 AT 指令给 ESP8266然后等待 ESP8266 的响应比如收到 OK 或者错误提示再执行下一步。这样可以保证每一步都确认成功后再继续避免状态错乱。void ESP8266_SendATCmd(const char* cmd, char* resp, uint16_t resp_len, uint32_t timeout) { // 清空接收缓冲区 memset(esp8266_rx_buf, 0, ESP8266_RX_BUF_SIZE); rx_index 0; // 发送指令 HAL_UART_Transmit(huart1, (uint8_t*)cmd, strlen(cmd), 200); // 等待响应 uint32_t start HAL_GetTick(); while(HAL_GetTick() - start timeout) { if(rx_index 0) { // 检查是否收到 OK / ERROR / 其他关键标记 if(strstr(esp8266_rx_buf, resp) ! NULL) { break; } } } }接收端用串口空闲中断结合 DMA或者简单点用 HAL_UART_Receive_IT 逐字节接收。为了简化逻辑这次用逐字节接收中断在中断回调里把数据存入缓冲区void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) { if(huart-Instance USART1) { esp8266_rx_buf[rx_index] rx_byte; if(rx_index ESP8266_RX_BUF_SIZE) rx_index 0; HAL_UART_Receive_IT(huart1, rx_byte, 1); } }3.3 MQTT 报文手动组装与解析MQTT 报文结构不复杂但第一次手写时要注意细节。我按 MQTT 3.1.1 协议来实现这也是 ThingsCloud 默认支持的版本。MQTT 报文由三部分组成固定报头、可变报头、有效载荷。固定报头第一个字节是报文类型和标志位第二个字节是剩余长度。比如 PUBLISH 报文的第一字节高四位是 3二进制 0011QoS 0 时标志位全为 0所以第一字节就是 0x30。连接报文 CONNECT 是客户端发给服务端的第一个报文需要包含协议名MQTT、协议级别 4、连接标志位用户名密码标志、保活时间、Client ID、用户名和密码。我在 STM32 端构造了一个函数void MQTT_ConnectPacket(uint8_t* buf, uint16_t* len) { uint16_t idx 0; buf[idx] 0x10; // CONNECT 报文QoS 0 // 剩余长度先占位 uint8_t remain_len_pos idx; // 协议名 buf[idx] 0x00; buf[idx] 0x04; buf[idx] M; buf[idx] Q; buf[idx] T; buf[idx] T; // 协议级别 4 (MQTT 3.1.1) buf[idx] 0x04; // 连接标志用户名密码清理会话 buf[idx] 0xC2; // 保活时间 60 秒 buf[idx] 0x00; buf[idx] 0x3C; // Client ID 字符串 // Username 字符串 // Password 字符串 // ... // 回填剩余长度 buf[remain_len_pos] idx - remain_len_pos - 1; *len idx; }剩余长度字段是一个可变字节编码如果报文长度小于 128 字节直接用 1 个字节表示超过 128 字节要用多个字节编码规则是每个字节低 7 位存放有效数据最高位是连续标志。这个细节很容易写错报文一长就会出现解析错误。发送数据用的是 PUBLISH 报文报文格式是固定报头0x30QoS 0或者 0x31/0x32QoS 1可变报头Topic 名称2 字节长度 主题字符串QoS 1 时还要加上 2 字节的报文标识符有效载荷JSON 格式的数据比如上报{temperature: 25.6}最终的报文大致是0x30 0x?? [topic_len_hi] [topic_len_lo] [topic bytes...] {temperature: 25.6}订阅主题用的 SUBSCRIBE 报文固定报头第一字节是 0x82可变报头包含报文标识符2 字节有效载荷是主题和 QoS 级别。心跳报文 PINGREQ 最简单固定两字节0xC0 0x00。ESP8266 每隔一段时间没有数据通信时STM32 要发一个 PINGREQ 维持连接超过保活时间服务端没收到任何包就会断开连接。解析订阅消息同样要在 STM32 端处理。当 ESP8266 收到 TCP 数据后通过串口发给 STM32STM32 需要从数据流中解析出 MQTT 报文判断是 PUBLISH 消息后提取主题和载荷内容。下面是一段简单的解析代码void MQTT_HandlePacket(uint8_t* data, uint16_t len) { uint8_t type data[0] 4; uint16_t idx 1; // 解析剩余长度 uint32_t remain_len 0; uint8_t multiplier 1; uint8_t encoded_byte; do { encoded_byte data[idx]; remain_len (encoded_byte 0x7F) * multiplier; multiplier * 128; } while ((encoded_byte 0x80) idx len); switch(type) { case 3: // PUBLISH // 解析主题 uint16_t topic_len (data[idx] 8) | data[idx1]; idx 2; // 提取消息内容 uint8_t* payload data idx topic_len; uint16_t payload_len remain_len - 2 - topic_len; // 处理业务逻辑 HandleCloudCommand(payload, payload_len); break; case 13: // PINGRESP break; default: break; } }这里我用的是裸指针直接操作缓冲区实际工程中要注意缓冲区越界的问题。另外TCP 粘包的场景一定要考虑。ESP8266 可能一次上报多个 MQTT 报文需要循环解析直到缓冲区的数据全部处理完。4. ESP8266 联网与 MQTT 接入4.1 ESP8266 初始化与 Wi-Fi 连接ESP8266 的初始化顺序是先测试 AT 指令是否正常然后配置 Wi-Fi 模式再连接路由器获取 IP最后建立 TCP 连接。AT 指令的序列如下AT ATE0 // 关闭回显减少串口数据量 ATCWMODE1 // Station 模式 ATCWJAPWiFi名称,WiFi密码 // 连接 Wi-Fi ATCIPSTARTTCP,mqtt.thingscloud.xyz,1883 // 建立 TCP 连接串口输出会被 ESP8266 的大量 IPD 前缀的数据淹没所以关闭回显很重要。同时建议把 Wi-Fi 连接状态查询用起来连接成功后再往下走。判断方式是在发送ATCWJAP后循环发ATCWJAP?查询直到返回CWJAP:3表示连接成功。从实际使用来看ESP-01S 有个共同问题天线信号一般同时供电不足的时候容易掉线。建议线路尽量短或者用外部 3.3V 稳压给它独立供电避免和 STM32 共用 LDO 导致电流不够。TCP 连接成功后STM32 就要通过已有的 TCP 通道发送 MQTT 报文。AT 指令用ATCIPSEND长度然后输入等长的数据返回SEND OK。比如发送 CONNECT 报文时uint8_t mqtt_buf[256]; uint16_t mqtt_len 0; MQTT_ConnectPacket(mqtt_buf, mqtt_len); char cipsend_cmd[32]; sprintf(cipsend_cmd, ATCIPSEND%d\r\n, mqtt_len); ESP8266_SendATCmd(cipsend_cmd, , 2000); HAL_UART_Transmit(huart1, mqtt_buf, mqtt_len, 500); // 等待 SEND OK ESP8266_WaitResp(SEND OK, 2000);注意ATCIPSEND发送后ESP8266 先返回一个提示符然后我们才能发送数据。我遇到过有人直接发数据结果前几个字节被当成指令吞掉的情况。所以一定要等出现再发这个细节要记得。4.2 接收下行数据与自动重连TCP 建立后ESP8266 通过串口主动上报收到的数据格式是IPD,长度:数据内容所以 STM32 串口接收解析时要识别IPD这个前缀。在我的代码里通过串口中断把整个数据存入缓冲区然后在主循环里扫描IPD关键字找到后提取长度字段再从冒号后面取出真正的 MQTT 报文if(strstr(esp8266_rx_buf, IPD) ! NULL) { char* p strstr(esp8266_rx_buf, IPD); int len 0; sscanf(p, IPD,%d:, len); char* payload_start strchr(p, :) 1; MQTT_HandlePacket((uint8_t*)payload_start, len); }IPD后面可能超过一个 TCP 包合并在一起也就是说一段数据里可能有多个IPD头。我的处理方式是解析完一个 MQTT 包后从缓冲区中移除这部分数据然后循环扫描下一个IPD。虽然麻烦点但很稳。断线重连是物联网应用逃不开的坑。我的应对方案是在主循环中维护一个计数器默认 30 秒发一次 PINGREQ。如果连续 3 次没收到 PINGRESP判定 TCP 连接已断开关闭连接。先调ATCIPSTART重新建立 TCP 连接再重新发 CONNECT 报文重新订阅主题。设置一个掉线计数连续重连失败 N 次后重启 ESP8266通过 GPIO 控制 CH_PD 引脚拉低再拉高。用这套逻辑即使路由器重启系统也能在 1 分钟内自动恢复。5. 云平台数据对接与多端应用开发5.1 ThingsCloud 数据流转机制设备上报的数据到了 ThingsCloud 之后平台会做几件事校验设备身份、解析 MQTT 报文、把数据写入数据库、通过规则引擎或 API 供外部调用。ThingsCloud 的消息 Topic 有固定格式。设备发布消息到主题devices/device_id/messages/upload载荷是 JSON比如{ temperature: 25.6, humidity: 60.2, light: 320, relay: false }控制指令是由平台下发到devices/device_id/messages/down主题客户端发布控制消息到这个主题设备端订阅这个主题即可收到。平台上还可以配置数据告警规则比如温度超过 30 度推送报警消息到 App。这些可以在控制台的可视化界面里配置不需要写代码。我把告警规则配在了高温告警和低电量告警两个场景上实测短信和邮件通知都推送得很及时。5.2 Android App 开发要点Android App 我用的是 Kotlin Eclipse Paho MQTT 客户端库。Paho 是 Eclipse 基金会维护的一个 MQTT 客户端库Android 端用org.eclipse.paho.client.mqttv3使用也很简单val client MqttClient(tcp://mqtt.thingscloud.xyz:1883, clientId, MemoryPersistence()) val options MqttConnectOptions().apply { userName device_id password device_password.toCharArray() isCleanSession true connectionTimeout 10 keepAliveInterval 60 } client.setCallback(object : MqttCallback { override fun messageArrived(topic: String?, message: MqttMessage?) { // 处理云端下发的控制指令 } }) client.connect(options) client.subscribe(devices/device_id/messages/down) client.publish(devices/device_id/messages/upload, {\relay\:true}.toByteArray(), 0, false)App 端的 UI 我用的是简单的 LinearLayout RecyclerView 做数据展示。界面主要分三块顶部实时数据卡片显示温度和湿度中间光照强度进度条底部继电器开关按钮。更新数据用 Handler 定时去查或通过 MQTT 订阅实时刷新我选的后者因为 MQTT 实时性好而且省电。Android App 开发中要注意一个关键点网络权限和 Cleartext 流量限制。Android 9 之后默认禁止明文 HTTP 流量如果你的 MQTT 走的是 1883 端口而不是 8883 TLS 端口需要在 AndroidManifest 里加android:usesCleartextTraffictrue否则连不上。5.3 iOS App 开发要点iOS 端我用的是 Swift CocoaMQTT 库通过 CocoaPods 集成。iOS 端接入 MQTT 的思路和 Android 完全一样只是 API 风格不同let client CocoaMQTT(clientID: iOS-Client, host: mqtt.thingscloud.xyz, port: 1883) client.username device_id client.password device_password client.keepAlive 60 client.didReceiveMessage { mqtt, message, id in // 处理订阅的主题消息 } client.connect() client.publish(devices/device_id/messages/upload, withString: {\relay\:false}, qos: .qos0)iOS 开发有一个比较麻烦的点App 退到后台后 MQTT 连接很可能会被系统挂起。如果要保持长时间连接需要配置 Background Mode但 App Store 审核对这个有严格的限制。一般简单方案是 App 退后台时主动断开回前台时重连通过云端缓存最新数据来弥补断线期间的数据空白。5.4 微信小程序开发要点微信小程序端我用的是原生开发MQTT 库选了mqtt.js。小程序和普通网页的 MQTT 接入有个重要的区别小程序运行环境不支持 Node.js 的net模块所以mqtt.js必须使用 WebSocket 方式来连接 MQTT Broker。ThingsCloud 对 WebSocket 接入的支持方式是MQTT over WebSocket默认端口是 8083 或 8084WSS。连接地址要写成const mqtt require(mqtt) const client mqtt.connect(wxs://mqtt.thingscloud.xyz:8084/mqtt, { clientId: wxapp_ Date.now(), username: device_id, password: device_password })注意是wxs://不是ws://。小程序要求所有请求必须是 HTTPS 或 WSS所以不配置 TLS 的话是连不上的。另外在小程序后台管理里要把 ThingsCloud 的域名加到 socket 合法域名列表里否则真机上连接会被拦。小程序页面展示我用了一个简单的数据卡片布局通过onShow生命周期里 connect 和订阅onHide时断开连接避免在后台持续占用资源。5.5 Web App 开发要点Web 端我用了 Vue 3 mqtt.js 实现。Web 端和 WebSocket 的方式类似但浏览器环境对 MQTT over WebSocket 的支持更标准一些import mqtt from mqtt; const client mqtt.connect(ws://xxx.thingscloud.xyz:8083/mqtt, { clientId: web_ Math.random().toString(16).substring(2), username: device_id, password: device_password }); client.on(connect, () { client.subscribe(devices/device_id/messages/down); }); client.on(message, (topic, payload) { const data JSON.parse(payload.toString()); // 更新页面数据 });Web 端我加了一个图表组件用 ECharts 画温湿度的实时曲线效果比纯数据展示直观很多。历史数据用 ThingsCloud 的 REST API 拉取在页面加载时显示最近 24 小时的曲线。不过这需要 API Key 鉴权在控制台创建 API Key 之后用它放在 HTTP header 里请求数据接口。6. 典型问题与排查心得6.1 连接和通信类问题实际调试下来遇到的坑不少这里挑几个典型的说一下。第一个坑是 ESP8266 连不上路由器或者频繁掉线。排查思路是先用串口助手单独测 ESP8266发 ATCWJAP 看返回。如果返回 ERROR看下是不是 Wi-Fi 密码错了或者路由器 5G 频段的问题——ESP 系列只支持 2.4G 频段连 5G 肯定失败。另外电源不稳定也会导致掉线ESP-01S 在发送数据瞬间电流会到 300mA用板载 LDO 供电很容易掉压给它并一个大电容或者独立稳压供电能解决大部分掉线问题。第二个坑是 MQTT 连接建立了但收不到数据。这种情况 90% 是订阅的主题不对或者设备的发布/订阅权限没配好。ThingsCloud 的 Topic 里带设备 ID一定要核对一下设备详情页里的真实 ID别拿示例目录里的占位符去订阅。还有物模型属性标识符要和上报数据的 key 完全一致大小写都不能错否则平台解析失败会直接丢弃消息。第三个坑是 STM32 串口接收乱码或数据错位。常见原因是波特率不匹配或者 ESP8266 回显没关。调试时我是先用电脑串口助手单独测 ESP8266 的收发确认链路通了再接 STM32这样能快速定位问题在哪一端。另外注意 STM32 和 ESP8266 之间电平要匹配——STM32 是 3.3V IOESP8266 也是 3.3V直接连没问题但如果中间加了电平转换芯片一定要检查方向是否正确。6.2 常见问题速查表现象可能原因排查及解决AT 无响应串口接错/波特率不对/固件损坏检查 RX/TX 是否交叉确认波特率 115200重刷固件Wi-Fi 连接 ERROR密码错误/频段不支持/信号弱确认 2.4G 频段检查密码增强供电TCP 连接失败Broker 地址错误/端口被防火墙拦截telnet 测试地址端口确认 1883 端口可达MQTT CONNECT 被拒绝Client ID/账号密码错误核对设备证书注意区分大小写数据上报了但平台看不到Topic 错误/JSON key 与物模型不一致在平台日志里查消息核对属性标识符收不到下行控制指令订阅 Topic 错误/未发送 PINGREQ 维持连接检查订阅主题确认保活机制正常App 连不上 MQTT明文流量被限制/域名未加白名单Android 加 usesCleartextTraffic小程序加 socket 合法域名App 退后台后收不到消息系统挂起 MQTT 连接实现退后台断开、回前台重连逻辑6.3 调试工具和排查方法调试这套系统我常用的工具是 MQTT.fx 和 MQTTX。这两个都是桌面版 MQTT 客户端可以手动连接到 ThingsCloud手动发布和订阅 Topic。这样在排查问题时能快速区分是设备端的问题还是云端/客户端的问题。我的排查习惯是先用 MQTTX 连接 ThingsCloud手动发一条数据看平台能不能收到然后再用 ESP8266 的串口日志看 STM32 发送的报文是否正常最后用手机 App 验证整个数据链路。一层层排查问题定位很快。串口调试助手我用的是 SSCOM 和 XCOM一个偏工程风格、一个界面友好一些看个人习惯。另外有条件的话在 MQTT Broker 侧抓包分析用 Wireshark 过滤 MQTT 协议就能看到完整的报文交换过程。有一次我排查一个报文错乱的问题就是靠看抓包里每个字节的十六进制值才找到原因的——STM32 端构造的报文长度字段算错了导致服务端解析出了异常。7. 多端数据同步与状态管理7.1 设备影子与数据一致性物联网应用里除了设备实时上报数据还有一类数据需要处理设备的状态比如继电器是开还是关。如果只是简单地把状态存到 App 本地那么手机 A 打开了继电器手机 B 上显示的还是关闭状态这就出现了数据不一致。ThingsCloud 提供了一个设备影子的机制简单说就是云端保存一个设备状态的 JSON 快照。设备上报数据后影子会自动更新客户端读取状态时优先从影子拿而不是等设备应答。这样即使设备离线也能知道它最后的状态。实际开发中我的做法是继电器状态单独放到一个属性里上报控制指令发送后不管设备是否立即应答App 端都先把本地 UI 更新成目标状态再等待设备上报的新状态来确认。如果 3 秒内没收到确认就提示指令已发送等待设备响应。同步的思路就是每次设备状态变化都完整地发布一次包含所有属性的 JSON。这样任何一端收到消息都能用最新的数据整体覆盖本地的旧数据不会出现只更新了温度没更新湿度的不一致问题。7.2 离线消息与 QoS 选择MQTT 的 QoS 分 3 级QoS 0 最多发送一次可能丢QoS 1 保证至少到达一次但可能重复QoS 2 保证只到达一次但开销最大。在物联网场景里对于传感器周期上报的数据我建议用 QoS 0因为即使丢掉一次下一秒又会重新上报问题不大。但对于控制指令比如开继电器如果丢了用户就发现设备没响应所以至少用 QoS 1。ThingsCloud 默认支持 QoS 0 和 QoS 1够用了。另外要注意的是 MQTT 协议中客户端订阅 Topic 时可以设置 QoS服务端发布消息时也有自己的 QoS最终消息实际到达的 QoS 取两者中的最小值。所以如果订阅时设了 QoS 2但服务端发布用的是 QoS 0实际消息还是 QoS 0不会变成 QoS 2。不用纠结这个细节做到控制指令用 QoS 1数据上报用 QoS 0就够了。7.3 多端并发控制在实践中如何处理到了多端并发场景一个设备对应四个客户端每个客户端都能发控制指令就可能出现A 发开、B 发关这种竞争。我的解法是在云平台上增加一个指令序号字段每次下发指令时带上一个自增的编号设备端只处理比当前序号大的指令把旧的指令丢弃。这个方案实现很简单却很好地避免了并发控制时的指令乱序问题。当然如果你有更复杂的业务逻辑比如需要按用户权限控制设备那就需要在云端做一层授权处理。ThingsCloud 的 API 也支持按设备设置访问权限这些后续可以根据需求扩展。对于入门级的项目来说序号去重就够了。8. 项目总结与扩展思路8.1 开发流程复盘整个项目走下来我最大的感受是物联网项目的核心不是某个单独的技术点而是数据链路的贯通。从传感器读数到云端存储再到多端展示一整条链路里每一个环节都不能断。我刚开始做的时候在 MQTT 报文组装上卡了两天后来发现是剩余长度字段的编码算错了导致云端一直解析失败。所以我的建议是千万别跳过协议理解这一步哪怕手边有现成的库也要懂底层的工作原理出了问题才能快速定位。8.2 项目扩展方向这套系统的基础架构搭好之后后续扩展就很方便了。你可以增加更多传感器比如 PM2.5、土壤湿度、烟雾报警只需要在 STM32 端加驱动代码云平台上加几个属性客户端加几个 UI 组件。增加执行器控制比如智能插座、窗帘电机通过继电器驱动逻辑和继电器控制完全一样。数据告警与联动在 ThingsCloud 上配置规则引擎温度过高自动发通知或者触发另一个设备的动作。设备固件 OTA 升级通过云平台下发固件STM32 通过 ESP8266 接收升级包这个稍微复杂一些要自己实现升级协议。接入语音助手比如小爱同学、天猫精灵通过云平台做协议转换实现语音控制设备。8.3 最后分享一点个人经验最后再分享一个小技巧开发过程中我给整个系统加了一个心跳逻辑不只是 MQTT 的 PINGREQ而是在应用层也在客户端和服务端之间定时互相打点。客户端每 30 秒发布一条包含客户端类型和在线状态的心跳消息设备端收到的传感器数据在云平台也标记一个时间戳。这样在 App 上能看到设备上次在线时间和客户端连接状态排查问题时非常有用。另外一个经验是关于工程管理的把这个项目做成一个工程资料包形式来管理是很明智的选择。因为四个端加一个单片机工程代码量不小如果你把开发环境、依赖库版本、引脚定义、云平台配置这些信息都整理成文档放在工程目录里隔几个月再回来看还能快速上手。我这里推荐在工程里加一个 README.md把上面提到的硬件接线表、AT 指令序列、MQTT Topic 定义、ThingsCloud 账号相关配置但注意不要提交真实密钥全部写清楚。你以后维护这个项目或者分享给别人都会省很多事。硬件开发有意思的地方就在于它能打破虚拟世界和现实世界的边界。当你在手机 App 上按下开关远处的继电器真的咔哒一声响了的时候那种成就感是纯写代码体会不到的。希望这篇文章能帮你把这条路走通少踩一些坑。本文还有配套的精品资源点击获取