简介STM32F103 结合 ESP8266 接入阿里云 IoT 的 MQTT 实践工程基于 HAL 库开发以 AT 指令方式完成通信面向物联网入门及嵌入式联网开发人群。资源共 996 个文件压缩包约 13.45MB核心代码以 C 源码和头文件为主563 个 .c、250 个 .h另有启动汇编、STM32CubeMX 的 .ioc 配置、IAR/Keil 工程与链接脚本以及编译生成的 hex/axf覆盖从源码阅读、重新生成工程到烧录验证的完整链路。整体配置思路简洁将阿里云设备三元组填入配置在 main.c 中修改对应宏定义即可完成连接并按物模型格式上传数据。工程内还涉及 DHT11 温湿度采集和 OLED 显示等外设应用可帮助理解从传感器读取、数据格式化到 MQTT 发布、云端交互的完整流程同时为扩展其他传感器或自定义物模型提供参考。已有 1599 人学习下载适合希望快速实现 STM32 设备上云并在实际项目中落地的开发者。 做嵌入式开发的兄弟应该都有体会调一个传感器很容易把数据稳定送到云端是另一回事。我最近在做的环境监测项目就撞上了这个需求——STM32F103要采集温湿度数据要送到阿里云IoT平台上做可视化监控还要能接收手机端下发的控制指令。最终落地方案是STM32F103通过HAL库工程与ESP8266通信ESP8266连接WiFi并以MQTT协议接入阿里云IoT。这篇就是整个实践的完整复盘从硬件连接、平台配置、AT指令调试到STM32端串口DMA和状态机实现再到联调中那些让人头大的坑全部记录下来。如果你正准备做类似项目或者想搞懂“STM32 ESP8266 阿里云MQTT”这条链路里到底有哪些关键环节、哪些地方最容易翻车这篇文章应该能帮你少走不少弯路。1. 项目全貌STM32 ESP8266 阿里云IoT的通信链路与选型逻辑1.1 硬件连接与任务分配先说硬件。我用的是最常见的STM32F103C8T6最小系统板配一个ESP8266-01S模块或者ESP-12F本质一样都是串口转WiFi。两者之间就是一组UARTSTM32F103的PA9USART1_TX接ESP8266的RXDPA10USART1_RX接ESP8266的TXDGND必须共地ESP8266的EN脚接3.3V使能GPIO0悬空或者上拉到VCC保证进入运行模式有一个特别容易被忽略的点ESP8266的峰值电流能达到300-400mA如果直接从STM32开发板的3.3V引脚取电WiFi建链瞬间电压会被拉垮模块轻则重启重则完全连不上网。我后来的做法是给ESP8266用独立的AMS1117-3.3从5V电源转换供电STM32和ESP8266只共地不要共用3.3V电源轨。任务分配很明确STM32F103负责业务逻辑读传感器、控制输出、解析协议、处理云端指令ESP8266当作一个“串口转MQTT网关”它内部跑AT固件自带TCP/IP协议栈和MQTT客户端MCU只需要通过串口下发AT指令即可。这样STM32端不用去实现完整的MQTT报文组装和状态机开发量小很多。1.2 为什么选AT指令方案而不是ESP8266 SDK方案做类似项目时还有另一条路给ESP8266刷NodeMCU固件或者直接用ESP8266 RTOS SDK让MCU和ESP8266之间走自定义串口协议。这条路的好处是可以把更复杂的逻辑放到ESP8266上。但对大多数以STM32为主控的项目来说我仍然推荐AT指令方案。原因有三个。第一AT指令方案把协议栈职责完全隔离了ESP8266固件自己维护MQTT连接、心跳、重连STM32端的代码逻辑非常简单串口发指令、收结果、解析结果就完事。第二AT固件是官方维护的稳定性有保障不需要自己折腾WiFi芯片的内部状态。第三出问题时调试面小——判断“链路通不通”只需要在串口调试助手里面敲几条指令就行不用上调试器去查RTOS任务状态。这也解释了为什么本文的工程代码都是基于HAL库的串口、DMA和定时器来写而不再单独去碰MQTT协议本身。用一个状态机把AT指令串起来就是最合理的做法。2. 阿里云IoT平台侧配置产品创建、设备三元组与签名参数计算2.1 产品与设备创建流程在写代码之前先去阿里云IoT控制台把平台侧的东西准备好。在“公共实例”下创建一个产品节点类型选“设备”连网方式选WiFi数据格式选“ICA标准数据格式Alink JSON”。建好产品之后要做的就是定义物模型例如温度temperature、湿度humidity类型选float或int读写类型根据需求来。物模型定好后云端会自动生成对应的功能Topic这是后面所有的上行下行数据的基础。然后在这个产品下添加一个设备。添加完会拿到三个关键参数也就是常说的三元组ProductKey产品唯一标识DeviceName设备名称在同一产品内唯一DeviceSecret设备密钥这三个参数后面都要用到尤其是DeviceSecret创建完成后只完整显示一次建议第一时间存好。我在项目中途换设备调试时就因为没存DeviceSecret不得不重新创建一个设备平白多花了几分钟。2.2 MQTT连接参数与HMAC签名原理阿里云IoT的MQTT接入不是拿三元组直接做密码而是要求客户端按固定规则生成连接参数。这个规则如果不搞清楚后面连不上都不知道是哪一步的问题。MQTT Broker地址是{ProductKey}.iot-as-mqtt.cn-shanghai.aliyuncs.com端口1883TCP如果做TLS则是8883。ClientId、Username、Password三者的构造规则如下ClientId: {DeviceName}|securemode3,signmethodhmacsha1,timestamp789| Username: {DeviceName}{ProductKey} Password: HMAC_SHA1(signContent, DeviceSecret)其中signContent的拼接格式是固定套路clientId{ClientId完整值}deviceName{DeviceName}productKey{ProductKey}timestamp{timestamp}签名算法可以选hmacsha1也可以选hmacmd5。STM32F103的算力跑HMAC-SHA1完全没问题但如果你不想引入mbedtls库可以选hmacmd5自己写一个几十行的MD5HMAC实现就够了。开发效率优先的话我建议直接选hmacmd5然后记得把签名摘要转成十六进制小写字符串填到Password字段里。参数项取值示例生成规则Broker地址a1xxxxx.iot-as-mqtt.cn-shanghai.aliyuncs.comProductKey 固定域名端口1883TCP直连ClientIdtestdevice|securemode3,signmethodhmacmd5,timestamp1633000000000|DeviceName 参数段Usernametestdevicea1xxxxxDeviceName ProductKeyPassworda1b2c3d4...十六进制HMAC签名结果2.3 Topic规划上报、下发与通配符使用阿里云IoT的使用方式是基于Topic的订阅发布模型。常用的两个官方Topic属性上报/sys/{ProductKey}/{DeviceName}/thing/event/property/post属性设置云端下发/sys/{ProductKey}/{DeviceName}/thing/service/property/set前者是设备主动PUBLISH把当前属性值上报到云端后者是设备SUBSCRIBE接收云端或App下发的属性设置指令。在物模型定义里属性和事件都会自动生成对应的Topic也可以在Topic列表里手动创建自定义Topic。这里提醒一句Topic字符串里的ProductKey和DeviceName必须和实际值完全一致区分大小写。很多人最后连不上排查半天发现是复制的时候把DeviceName多了一个空格。另外一个不错的习惯是先用PC端的MQTT客户端比如MQTT X配合上面算好的签名参数把连接和Topic收发验证通过再跑到单片机上写代码调试这样问题面会小很多。3. ESP8266端AT指令实战从WiFi联网到MQTT连接建立3.1 确认固件版本支持MQTT指令这一步是很多人忽略的坑。老版本的ESP8266 AT固件只支持TCP/UDP透传不支持MQTT指令。必须使用较新的AT固件ATGMR输出在2.2.0.0及以上部分定制固件也可以才会有ATMQTTUSERCFG、ATMQTTCONN这一串指令。如果不确定手上模块的固件版本上电后先发一条ATGMR正常会返回类似AT version:2.2.0.0 SDK version:3.0.4如果返回的是AT version:1.2.0这种老版本网上搜一下对应模组型号的MQTT固件重新烧录。这一步不值得省固件版本不对的话后面所有MQTT指令都会返回ERROR。3.2 完整的指令序列与应答特征ESP8266接入WiFi并连接阿里云MQTT核心指令序列大概是这样的ATCWMODE1 ATCWJAP你的WiFi名,你的WiFi密码 ATMQTTUSERCFG0,1,clientId的值,username的值,password的值,0,0, ATMQTTCONN0,ProductKey.iot-as-mqtt.cn-shanghai.aliyuncs.com,1883,1 ATMQTTTOPIC0,1,/sys/ProductKey/DeviceName/thing/service/property/set ATMQTTSUB0,1 ATMQTTPUB0,/sys/ProductKey/DeviceName/thing/event/property/post,{\id\:1,\params\:{\temperature\:25.5,\humidity\:60}},0,0ATMQTTUSERCFG的参数含义第一个0是链路ID固定为0第二个1表示使用MQTT协议并启用clientId/username/password认证后面依次是clientId、username、password然后是证书相关参数非加密场景填0,0,即可。执行完ATMQTTCONN后模块会先返回OK过一会儿如果有MQTT连接成功的信息会在后续输出类似MQTTSTATE:0这里的0表示连接建立成功。如果返回的值不是0基本可以按下面的表格定位返回状态码含义排查方向0连接正常无需处理1连接被服务器断开检查签名、设备是否被删除2网络异常检查WiFi、信号强度4域名解析失败确认Broker地址是否正确5认证失败重点检查Password签名结果3.3 AT应答不匹配与异常状态的排查思路AT指令调试最常见的现象是指令发出去了模块好像没反应或者回复的不是预期的OK。这里我的建议是先用串口调试助手手工敲一遍指令不要直接上STM32代码。手工确认可以通再写MCU端逻辑这样问题定位快很多。几个高频问题指令没有以\r\n结尾模块直接忽略。串口调试助手默认一般会带但自己写代码时千万别只发\n或什么都不发。发送速度太快上一句还没执行完下一句就进来了。稳妥做法是等上一条返回OK再发下一条。ATMQTTCONN执行后不返回OK而是隔几秒返回ERROR。先用ATCWJAP?确认WiFi还连着再用ATMQTTCONN?查看当前的MQTT状态码。返回MQTTDISCONNECTED:3之类的状态码一般是连接异常后被服务端断开。先看WiFi链路再看密码签名再看Topic权限。记住一个原则AT调试的时候任何一条指令的结果都要看“返回了什么”而不是“屏幕上有没有东西蹦出来”。MQTT连接是异步的默认的串口CRLF不回显很容易让人误判。4. STM32 HAL库工程实现串口DMA、空闲中断与AT指令状态机4.1 CubeMX配置与串口资源分配STM32端的工程我用STM32CubeMX生成基于HAL库。串口资源分配上USART1接ESP8266波特率1152008N1USART2留作调试日志输出这样ESP8266的AT返回和程序日志分开看排查问题会清楚很多。CubeMX里USART1的NVIC配置要打开全局中断DMA配置里分别添加USART1_TX和USART1_RX两个DMA通道模式选Normal不是Circular因为我们需要在空闲中断后手动重启接收。生成工程后首先要做的一件事是确认时钟树配置正确别因为HSE起振失败导致串口波特率全部偏掉。这类问题最隐蔽表现是串口收到大量乱码但程序逻辑完全正常。4.2 串口空闲中断DMA的高效接收设计ESP8266返回的数据是变长的有的是OK有的是几十字节的MQTTSUBRECV下行数据。如果用逐字节接收MCU负载高且容易丢如果固定长度接收又没法适应变长回复。推荐的做法是空闲中断DMA。思路是这样DMA把USART1接收到的数据源源不断搬进缓冲区不需要CPU参与当一帧数据结束后串口总线进入空闲状态触发IDLE中断此时看一下DMA计数器就能算出这一帧数据的实际长度然后处理缓冲区再重新开启一轮接收。IRQHandler中大致这样写void USART1_IRQHandler(void) { HAL_UART_IRQHandler(huart1); if (__HAL_UART_GET_FLAG(huart1, UART_FLAG_IDLE)) { __HAL_UART_CLEAR_IDLEFLAG(huart1); HAL_UART_DMAStop(huart1); uint16_t len RX_BUF_SIZE - __HAL_DMA_GET_COUNTER(hdma_usart1_rx); if (len 0) { at_parse(rx_buf, len); } HAL_UART_Receive_DMA(huart1, rx_buf, RX_BUF_SIZE); } }注意一个细节__HAL_UART_CLEAR_IDLEFLAG必须在清DMA计数器之前执行否则可能因为DMA停止时机导致长度计算错误。另外HAL_UART_IRQHandler会处理所有UART中断标志如果IDLE中断在它里面被清了外面就检测不到了实际工程里我习惯把IDLE判断放在它之后。有了这个接收框架MCU就可以非阻塞地拿到ESP8266返回的完整数据帧整个系统的主循环也不会卡在串口等待上。4.3 AT指令状态机的完整逻辑MCU发AT指令是“发送一条、等一条回复”但回复并不是立即到达的可能先回OK再回MQTTSTATE之类的异步消息。所以不能用简单的延时死等最好用一个轻量状态机。我通常这样设计typedef enum { AT_ST_IDLE, AT_ST_WAIT_RESP, AT_ST_RESP_OK, AT_ST_RESP_ERROR, AT_ST_TIMEOUT } AT_State; typedef struct { AT_State state; uint16_t timeout_cnt; uint8_t expect_str[32]; } AT_Handler;发送一条指令后把状态置为AT_ST_WAIT_RESP同时启动超时计数在at_parse拿到新数据时把当前帧和期望的关键字做匹配。匹配到OK就进入AT_ST_RESP_OK匹配到ERROR就进入AT_ST_RESP_ERROR如果超时还没匹配到就按失败处理。主循环里再根据当前状态推进下一步操作if (at_handler.state AT_ST_RESP_OK) { at_handler.state AT_ST_IDLE; send_next_at_command(); /* 推进到连接流程的下一步 */ }这个状态机的好处是整个流程可以被拆解成“发指令、等结果、推进”三个环节不管是连WiFi、配MQTT还是订阅Topic都能复用同一套逻辑。实测下来串口数据即使在偶发丢字节的情况下状态机也能通过超时机制兜底不会死锁在某个等待状态。5. 属性上报与云端指令下发的代码落地5.1 构造MQTT PUBLISH报文上报属性在AT指令方案下属性上报最终落在一条ATMQTTPUB指令上。上报阿里云属性时payload要符合Alink JSON格式{id:1,version:1.0,method:thing.event.property.post,params:{temperature:25.5,humidity:60}}在C字符串里拼这个JSON的时候双引号都要加反斜杠转义命令行里payload中的引号同样要转义。拼接时建议用snprintf一次格式化char payload[256]; snprintf(payload, sizeof(payload), {\id\:\%d\,\version\:\1.0\,\method\:\thing.event.property.post\, \params\:{\temperature\:%.1f,\humidity\:%.1f}}, msg_id, temp, humi); char cmd[320]; snprintf(cmd, sizeof(cmd), ATMQTTPUB0,\/sys/%s/%s/thing/event/property/post\,\%s\,0,0, product_key, device_name, payload);这里最容易踩的坑是转义层级。C源码字符串一层转义传给ESP8266的AT指令还有一层转义两层叠加很容易看花眼。我的自查办法是先在串口调试助手里手工拼并执行一次能收到云端数据再把同样内容的转义形式写进代码里。另外上报频率不要太猛一般几秒一包就够否则云端也会限流。5.2 订阅Topic与下行指令的解析处理下行指令走的是ATMQTTTOPICATMQTTSUB订阅成功后当云端下发属性设置时ESP8266会主动推一帧数据上来格式类似MQTTSUBRECV:0,/sys/ProductKey/DeviceName/thing/service/property/set,len,{method:thing.service.property.set,id:123,params:{switch:1},version:1.0}STM32端要做的就是从这帧字符串里找到MQTTSUBRECV:0,这个关键字再跳过Topic字符串和长度字段拿到后面的JSON body然后从JSON里提取params里的字段值。解析JSON有两个选择一是引入cJSON库简单可靠二是用手写字符串查找函数处理适合字段很少且格式固定的场景。如果只是控制一路开关手写查找就够了如果字段多、业务复杂老老实实用cJSON别自己造轮子。我这次项目因为只处理一个switch字段就用手写查找提取数字十几行代码搞定也没有引入额外的内存开销。5.3 心跳保活与断线重连策略MQTT的连接不是建一次就一劳永逸。WiFi信号波动、网络抖动、服务端空闲超时都可能导致连接断开。ESP8266固件内部会维护MQTT心跳ATMQTTCONN最后一个参数就是keepalive秒数我一般设120秒这个值和云端不产生冲突。关键问题是异常断开后如何恢复。ESP8266在断开时会主动上报MQTTDISCONNECTED:0STM32收到这条消息后不能直接重发ATMQTTCONN了事而是要先确认WiFi状态ATCWJAP?如果返回CWJAP:0说明WiFi在线直接重新走一遍MQTT连接流程如果返回的是ERROR或者CWJAP:1之类说明WiFi已经断了得先从ATCWJAP重新连。市面不少demo代码只做了MQTT重连却漏了WiFi状态判断结果越重连越乱这里值得多写几行。最后再分享一个调测小技巧在阿里云IoT控制台的“日志服务”里可以看到每条上下行消息的记录和时间戳。STM32端上报的数据有没有到云端、云端下发的指令有没有发出在这个日志页面一查便知比在串口里反复翻日志高效得多。很多看起来“设备连上了但数据没上来”的问题都是在这里找到原因的。本文还有配套的精品资源点击获取