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 订阅展示

反向控制链路由客户端发起指令，发布到指定 Topic，ESP8266 订阅这个 Topic，收到指令后通过串口转发给 STM32，STM32 解析指令并控制外设（比如继电器、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 开发环境我用的是 STM32CubeIDE，ST 官方出的免费 IDE，基于 Eclipse 开发，内置了 CubeMX 配置工具。之所以选它，是因为它对 HAL 库的支持最原生，图形化配置完引脚和时钟，直接生成工程骨架，省去手写初始化代码的时间。当然你用 Keil MDK 也可以，看个人习惯。

安装完 CubeIDE 之后，先创建一个新的 STM32 工程，选择芯片型号 STM32F103C8。在 Pinout 视图里需要配置以下外设：

• USART1：接 ESP8266，异步收发模式，波特率 115200。注意要把 USART1 的 TX（PA9）连接到 ESP8266 的 RX，RX（PA10）连接到 ESP8266 的 TX，交叉连接。
• USART2：用于调试打印，连接板载 ST-Link 或 USB 转串口模块，波特率 115200。
• I2C1：接 BH1750 光照传感器，默认引脚 PB6（SCL）、PB7（SDA）。
• 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。接线方式如下：

用下载工具烧录。Windows 下用 ESPFlashDownloadTool，把固件 bin 文件放到对应地址（一般固件包里有说明，比如 eagle.flash.bin 放 0x00000，eagle.irom0text.bin 放 0x40000），选对串口和波特率，点 START 开始烧录。

烧录完成后把 GPIO0 悬空或者接高电平，重新上电，用串口调试助手发 AT，如果返回 OK，说明固件正常。

2.3 ThingsCloud 平台配置

ThingsCloud 的接入逻辑很清晰：创建项目 -> 创建设备 -> 拿到 MQTT 接入信息。

注册并登录 ThingsCloud 控制台后，先创建一个项目，名字随意，比如"环境监测网关"。然后在项目里创建一个设备，设备类型选择"网关设备"或"直连设备"。创建完成后，在设备详情页能看到 MQTT 连接参数：

• MQTT Broker 地址：类似mqtt://xxx.thingscloud.xyz的地址
• 端口：1883（TCP）或 8883（TLS）
• Client ID：设备证书生成的唯一标识
• Username 和 Password：设备密钥

ThingsCloud 也支持三元组认证方式，但控制台生成的设备直接就有现成的 Client ID 和密码，用这个就行。

关键一步是定义数据模型。在设备的"物模型"或"数据模板"里定义属性，比如：

• temperature，类型 float，表示温度
• humidity，类型 float，表示湿度
• light，类型 int，表示光照强度
• relay，类型 bool，表示继电器开关状态

每个属性都有对应的标识符，上报数据时的 JSON key 名必须和物模型一致，否则云平台解析不了。这一步很容易忽略，切记先把属性定义好再写固件代码。

3. STM32 端核心代码实现

3.1 传感器数据采集

传感器采集这部分，我来说说两个传感器的驱动思路。

DHT11 是单总线协议，用普通的 GPIO 位操作就能读取。它的数据帧是 40 bit：8 bit 湿度整数 + 8 bit 湿度小数 + 8 bit 温度整数 + 8 bit 温度小数 + 8 bit 校验和。读取流程是：主机拉低总线至少 18ms 然后释放，DHT11 会拉低响应信号再拉高，之后按时序一位一位地输出数据。判断每一位是 0 还是 1，看高电平持续的时间，26-28us 左右的为 0，70us 左右的是 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 只需要发送字符串指令，比如AT+CIPSTART="TCP","xxx.thingscloud.xyz",1883，就能建立 TCP 连接，大幅降低了单片机端的工作量和固件开发复杂度。

但这里有个坑：ESP8266 的 AT 固件默认不支持透传 MQTT 报文，它只是一个 TCP 通道。所以 MQTT 协议本身的打包和解包逻辑要在 STM32 端自己实现。

有人可能会问：那为什么不直接用 ESP8266 跑 MQTT 固件，或者用官方 MQTT AT 指令？实际上乐鑫新的 AT 固件确实带了 MQTT 指令（AT+MQTTCONN、AT+MQTTSUB、AT+MQTTPUB），但我用下来发现，这些指令在 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（二进制 0011），QoS 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 报文，报文格式是：

• 固定报头：0x30（QoS 0）或者 0x31/0x32（QoS 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 数据后通过串口发给 STM32，STM32 需要从数据流中解析出 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[idx+1]; 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 // 关闭回显，减少串口数据量 AT+CWMODE=1 // Station 模式 AT+CWJAP="WiFi名称","WiFi密码" // 连接 Wi-Fi AT+CIPSTART="TCP","mqtt.thingscloud.xyz",1883 // 建立 TCP 连接

串口输出会被 ESP8266 的大量 +IPD 前缀的数据淹没，所以关闭回显很重要。同时建议把 Wi-Fi 连接状态查询用起来，连接成功后再往下走。判断方式是在发送AT+CWJAP后，循环发AT+CWJAP?查询，直到返回+CWJAP:3表示连接成功。

从实际使用来看，ESP-01S 有个共同问题：天线信号一般同时供电不足的时候容易掉线。建议线路尽量短，或者用外部 3.3V 稳压给它独立供电，避免和 STM32 共用 LDO 导致电流不够。

TCP 连接成功后，STM32 就要通过已有的 TCP 通道发送 MQTT 报文。AT 指令用AT+CIPSEND=<长度>，然后输入等长的数据，返回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, "AT+CIPSEND=%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);

注意AT+CIPSEND发送后，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。虽然麻烦点，但很稳。

断线重连是物联网应用逃不开的坑。我的应对方案是：

1. 在主循环中维护一个计数器，默认 30 秒发一次 PINGREQ。
2. 如果连续 3 次没收到 PINGRESP，判定 TCP 连接已断开，关闭连接。
3. 先调AT+CIPSTART重新建立 TCP 连接，再重新发 CONNECT 报文，重新订阅主题。
4. 设置一个掉线计数，连续重连失败 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:usesCleartextTraffic="true"，否则连不上。

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 或 8084（WSS）。连接地址要写成：

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，发 AT+CWJAP 看返回。如果返回 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 IO，ESP8266 也是 3.3V，直接连没问题，但如果中间加了电平转换芯片，一定要检查方向是否正确。

6.2 常见问题速查表

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 上按下开关，远处的继电器真的"咔哒"一声响了的时候，那种成就感是纯写代码体会不到的。希望这篇文章能帮你把这条路走通，少踩一些坑。

本文还有配套的精品资源，点击获取