STM32+ESP-01S基于AT指令实现MQTT联网

1. STM32+ESP-01S实现MQTT联网的工程实践

在嵌入式物联网开发中，让资源受限的MCU接入云平台是常见需求。直接在STM32上移植完整MQTT协议栈（如Eclipse Paho）会显著增加Flash和RAM占用，尤其对STM32F103C8T6这类64KB Flash、20KB RAM的主流入门型号而言，往往超出资源预算。更工程化的方案是采用“MCU+Wi-Fi模组”协同架构：由MCU专注业务逻辑与外设控制，Wi-Fi模组承担TCP/IP协议栈、TLS加密及MQTT协议解析等重负载任务。本方案选用ESP-01S模组——其内置ESP8266EX芯片，出厂已烧录AT固件，仅需串口指令即可完成网络连接与MQTT通信，大幅降低开发门槛。本文将完整呈现从硬件连接、AT指令调试到STM32固件开发的全链路实现，所有代码均基于HAL库，可直接用于量产项目。

1.1 硬件连接与电平匹配

ESP-01S模组工作电压为3.3V，IO电平亦为3.3V，而多数STM32F1系列开发板（如最小系统板）的串口引脚默认兼容5V TTL电平。若直接连接，存在烧毁ESP-01S的风险。必须进行电平转换：

• TX线路（ESP-01S → STM32） ：ESP-01S的TX引脚输出3.3V逻辑电平，可被STM32的UART_RX引脚（容忍5V输入）直接识别，此线路无需额外电路。
• RX线路（STM32 → ESP-01S） ：STM32的UART_TX引脚输出5V逻辑电平，会击穿ESP-01S的RX引脚。必须采用分压电路或专用电平转换芯片。最简方案为电阻分压：在STM32 TX与ESP-01S RX之间串联一个1kΩ电阻，再从ESP-01S RX引脚并联一个2kΩ电阻至GND。该组合将5V降至约3.3V（5V × 2kΩ / (1kΩ + 2kΩ) ≈ 3.33V），满足ESP-01S输入高电平要求（VIH ≥ 2.5V）。

标准连接如下：
- ESP-01S VCC → STM32 3.3V电源（需确保电源能提供至少300mA峰值电流）
- ESP-01S GND → STM32 GND（ 必须共地 ）
- ESP-01S TX → STM32 USART1_RX（PA10）
- ESP-01S RX → STM32 USART1_TX（PA9） 经1kΩ/2kΩ分压网络
- ESP-01S CH_PD → STM32 3.3V（保持高电平使能模组）
- ESP-01S GPIO0 → STM32 GND（确保模组处于运行模式，非下载模式）

经验提示 ：首次上电时，若ESP-01S无响应，优先检查CH_PD是否悬空或接地。曾因CH_PD未接3.3V导致模组始终处于复位状态，串口无任何回显。

1.2 AT固件版本确认与透传模式管理

ESP-01S出厂固件版本直接影响AT指令集的完备性与稳定性。使用USB转TTL模块（如CH340）将其连接PC，在串口调试助手（如XCOM、SSCOM）中设置波特率115200、8N1，发送 AT 指令。若返回 OK ，表明基础通信正常。紧接着发送 AT+GMR 查询固件版本。 强烈建议升级至乐鑫官方最新AT固件（v2.2.1或更高） ，原因在于旧版固件（如v1.5.4）存在MQTT连接后无法退出透传模式、心跳包异常等已知缺陷。

透传模式（Transparent Transmission Mode）是ESP-01S的核心工作模式。在此模式下，模组将串口收到的所有字节原样转发至TCP连接，反之亦然。但该模式与AT指令模式互斥：一旦进入透传模式，模组将不再响应任何AT指令，直至硬复位。因此，完整的初始化流程必须严格遵循：
1. 退出透传模式 ：发送 +++ （无换行，且前后需有1s静默期）强制退出。成功后返回 OK 。
2. 配置Wi-Fi参数 ： AT+CWMODE=1 （Station模式）→ AT+CWJAP="SSID","PASSWORD" （连接路由器）。
3. 建立TCP连接 ： AT+CIPSTART="TCP","broker.emqx.io",1883 （以EMQX Cloud为例）。
4. 启用透传模式 ： AT+CIPMODE=1 → AT+CIPSEND （此后所有串口数据直通网络）。

若跳过第1步直接尝试配置，串口将无响应，这是初学者最常见的卡点。

1.3 MQTT服务器选型与网络性能实测

MQTT服务器（Broker）的选择对系统可靠性至关重要。测试中对比了两类主流服务：

公共Mosquitto服务器因资源受限，常出现高延迟与连接抖动，不适用于实时性要求较高的场景（如设备远程控制）。EMQX Cloud提供免费层（10连接/100消息/分钟），其低延迟与高稳定性使其成为原型验证与小规模部署的优选。 关键配置项 ：
- broker.emqx.io ：域名，需确保ESP-01S已正确解析DNS（ AT+CIPDOMAIN 可验证）。
- 端口1883：标准MQTT非加密端口。若需TLS加密，应使用8883端口并加载证书，但会显著增加模组负担，本文暂不涉及。

踩坑记录 ：曾因误用 test.mosquitto.org ，设备在订阅主题后频繁掉线，日志显示 CLOSED 。切换至 broker.emqx.io 后问题彻底解决。务必在项目初期进行网络质量摸底。

2. MQTT协议帧结构解析与手动构造

ESP-01S的AT固件不提供高级MQTT API（如 AT+MQTTPUB ），需MCU手动构造符合MQTT 3.1.1协议规范的二进制报文并通过串口发送。理解报文结构是可靠通信的基础。

2.1 CONNECT报文：建立会话的握手

CONNECT报文是客户端向Broker发起连接请求的唯一方式，其结构分为固定头、可变头与有效载荷三部分：

构造要点 ：
- 客户端ID（Client Identifier）是全局唯一标识 。若两台设备使用相同ID（如”HJT”）连接同一Broker，后上线者将强制踢出先上线者。生产环境中ID应包含设备MAC或序列号哈希值，例如 HJT_2A3F 。
- CLEAN SESSION = 1 表示每次连接均为新会话，Broker不保存历史消息与订阅关系。此模式最简单，适合资源受限设备。
- 保活时间（Keep Alive） 必须大于0。Broker会在该时间间隔内未收到任何报文时主动断开连接。120秒是平衡功耗与可靠性的常用值。

2.2 SUBSCRIBE报文：订阅主题的声明

SUBSCRIBE报文用于向Broker声明客户端希望接收哪些主题的消息。其结构同样含固定头、可变头与有效载荷：

构造要点 ：
- 报文标识符（Packet Identifier） 是SUBSCRIBE与SUBACK报文的关联键。Broker返回的SUBACK报文中会携带相同ID，MCU需校验此ID以确认订阅成功。
- QoS等级 在SUBSCRIBE中指明客户端期望的QoS，而非发布者使用的QoS。QoS 0（最多一次）对LED开关等非关键控制足够，且开销最小。

2.3 PINGREQ与PUBLISH报文：维持连接与接收消息

• PINGREQ（心跳包） ：当连接建立后，MCU必须每 Keep Alive 秒（120秒）发送一次 0xC0 0x00 （固定头类型0xC0，剩余长度0）以告知Broker“我还活着”。若Broker在 1.5 × Keep Alive 时间内未收到PINGREQ，将主动断开连接。
• PUBLISH（发布消息） ：当Broker向客户端推送其订阅的主题消息时，会发送PUBLISH报文。其固定头类型为 0x30 ，剩余长度包含主题名长度、主题名、报文标识符（QoS>0时）、以及消息负载。对于QoS 0的发布，报文结构最简： 0x30 + 剩余长度 + 主题长度 + 主题名 + 消息负载 。

关键洞察 ：ESP-01S在透传模式下，不会解析或修改任何MQTT报文。它仅是一个透明的数据管道。这意味着MCU发送的每一个字节都必须100%符合协议规范，否则Broker将拒绝连接或返回错误码。

3. STM32 HAL库驱动开发详解

基于STM32CubeMX生成的初始化代码，核心开发围绕USART1中断接收与定时器心跳管理展开。以下为关键模块实现。

3.1 串口接收中断处理：字节流解析

ESP-01S在透传模式下，所有网络数据（包括CONNECT响应、SUBACK、PUBLISH消息）均通过串口以原始字节流形式送达。MCU需在中断中高效捕获并解析这些字节。由于MQTT报文无明确结束符，不能依赖 \n 或 \r ，必须依据协议长度字段动态解析。

// 全局缓冲区与状态机
#define RX_BUFFER_SIZE 64
uint8_t rx_buffer[RX_BUFFER_SIZE];
volatile uint16_t rx_head = 0;
volatile uint16_t rx_tail = 0;
volatile uint8_t in_mqtt_frame = 0; // 标记是否正在接收一个完整MQTT报文
volatile uint8_t mqtt_remaining_length = 0; // 当前报文剩余长度
volatile uint8_t mqtt_header_bytes = 0; // 已接收的固定头字节数

void USART1_IRQHandler(void)
{
    uint32_t isrflags = __HAL_USART_GET_FLAG(&huart1, USART_FLAG_RXNE);
    uint32_t cr1its = __HAL_USART_GET_IT_SOURCE(&huart1, USART_IT_RXNE);

    if (isrflags && cr1its) {
        uint8_t data = (uint8_t)(huart1.Instance->DR & 0xFF);

        // 将字节存入环形缓冲区
        rx_buffer[rx_head] = data;
        rx_head = (rx_head + 1) % RX_BUFFER_SIZE;

        // 解析固定头：首字节为类型，后续1-4字节为剩余长度（变长编码）
        if (!in_mqtt_frame) {
            if ((data & 0xF0) == 0x10) { // CONNECT响应：0x20
                in_mqtt_frame = 1;
                mqtt_remaining_length = 0;
                mqtt_header_bytes = 1;
            } else if ((data & 0xF0) == 0x20) { // CONNACK：0x20
                in_mqtt_frame = 1;
                mqtt_remaining_length = 0;
                mqtt_header_bytes = 1;
            } else if ((data & 0xF0) == 0x90) { // SUBACK：0x90
                in_mqtt_frame = 1;
                mqtt_remaining_length = 0;
                mqtt_header_bytes = 1;
            } else if ((data & 0xF0) == 0x30) { // PUBLISH：0x30
                in_mqtt_frame = 1;
                mqtt_remaining_length = 0;
                mqtt_header_bytes = 1;
            }
        } else if (mqtt_header_bytes == 1) {
            // 第二个字节是剩余长度的第一字节
            mqtt_remaining_length = data & 0x7F;
            if (data & 0x80) {
                // 需要更多字节，此处简化，实际需循环读取
                mqtt_header_bytes++;
            } else {
                // 固定头结束，准备接收有效载荷
                mqtt_header_bytes = 0;
                in_mqtt_frame = 0;
                // 此处触发完整报文处理函数 process_mqtt_packet()
            }
        }
    }
}

设计哲学 ：避免在中断中做复杂解析。中断仅负责高速存入环形缓冲区，主循环或专用解析任务（如FreeRTOS任务）再从缓冲区提取完整报文进行处理。这保证了中断响应的实时性。

3.2 MQTT状态机与连接管理

连接过程是典型的事件驱动状态机。定义以下状态：

typedef enum {
    MQTT_DISCONNECTED,
    MQTT_CONNECTING,
    MQTT_CONNECTED,
    MQTT_SUBSCRIBING,
    MQTT_SUBSCRIBED,
    MQTT_ERROR
} mqtt_state_t;

mqtt_state_t mqtt_state = MQTT_DISCONNECTED;
uint32_t last_connect_time = 0;
uint32_t keep_alive_timer = 0;

void mqtt_task(void const * argument)
{
    for(;;) {
        switch(mqtt_state) {
            case MQTT_DISCONNECTED:
                if (HAL_GetTick() - last_connect_time > 5000) { // 5秒后重试
                    send_connect_packet(); // 发送CONNECT报文
                    mqtt_state = MQTT_CONNECTING;
                    last_connect_time = HAL_GetTick();
                }
                break;

            case MQTT_CONNECTING:
                // 检查环形缓冲区是否有CONNACK (0x20)
                if (check_for_connack()) {
                    mqtt_state = MQTT_CONNECTED;
                    keep_alive_timer = HAL_GetTick();
                } else if (HAL_GetTick() - last_connect_time > 10000) {
                    mqtt_state = MQTT_ERROR;
                }
                break;

            case MQTT_CONNECTED:
                // 发送SUBSCRIBE
                if (mqtt_state == MQTT_CONNECTED) {
                    send_subscribe_packet();
                    mqtt_state = MQTT_SUBSCRIBING;
                }
                break;

            case MQTT_SUBSCRIBING:
                // 检查SUBACK
                if (check_for_suback()) {
                    mqtt_state = MQTT_SUBSCRIBED;
                }
                break;

            case MQTT_SUBSCRIBED:
                // 维持心跳
                if (HAL_GetTick() - keep_alive_timer > 120000) { // 120秒
                    send_pingreq_packet();
                    keep_alive_timer = HAL_GetTick();
                }
                break;

            case MQTT_ERROR:
                // 清理资源，延时后重置状态机
                HAL_Delay(2000);
                mqtt_state = MQTT_DISCONNECTED;
                break;
        }
        osDelay(10); // 任务调度
    }
}

健壮性设计 ：
- 所有网络操作均带超时机制，避免无限等待。
- last_connect_time 与 keep_alive_timer 均使用 HAL_GetTick() ，确保与系统滴答同步。
- 错误状态 MQTT_ERROR 触发软复位流程，而非死锁。

3.3 LED控制逻辑：从MQTT消息到物理动作

PUBLISH报文的有效载荷即为用户数据。在本例中，Broker向主题 HJT 发布的消息内容为单字节ASCII码： '1' （0x31）表示开灯， '2' （0x32）表示关灯。解析逻辑嵌入在PUBLISH报文处理函数中：

void process_publish_packet(uint8_t* payload, uint16_t len) {
    if (len == 1) {
        switch(payload[0]) {
            case '1': // ASCII 0x31
                HAL_GPIO_WritePin(GPIOB, GPIO_PIN_5, GPIO_PIN_RESET); // PB5低电平点亮LED（共阳接法）
                break;
            case '2': // ASCII 0x32
                HAL_GPIO_WritePin(GPIOB, GPIO_PIN_5, GPIO_PIN_SET); // PB5高电平熄灭LED
                break;
            default:
                // 未知命令，可记录日志或忽略
                break;
        }
    }
}

硬件细节 ：LED通常采用共阳极接法，即LED阳极接VCC，阴极通过限流电阻（220Ω）接MCU GPIO。此时GPIO输出低电平（ GPIO_PIN_RESET ）形成回路，LED点亮；输出高电平（ GPIO_PIN_SET ）则截止，LED熄灭。务必在 MX_GPIO_Init() 中将PB5配置为推挽输出模式（ GPIO_MODE_OUTPUT_PP ）。

4. 调试技巧与常见故障排除

在真实项目中，网络通信问题往往比纯MCU逻辑更难定位。以下是经过实战验证的调试方法论。

4.1 串口抓包：16进制视角下的真相

当现象与预期不符（如LED不响应），首要动作是开启串口调试助手的“16进制显示”与“16进制发送”功能。观察ESP-01S返回的原始字节：

• CONNECT成功 ：应看到 0x20 0x02 0x00 0x00 。其中 0x20 是CONNACK固定头， 0x02 表示剩余长度2字节， 0x00 0x00 是返回码0（连接接受）。
• SUBSCRIBE成功 ：应看到 0x90 0x03 0x00 0x01 0x00 。 0x90 是SUBACK， 0x03 是剩余长度， 0x00 0x01 是报文ID， 0x00 是授予的QoS（0）。
• PUBLISH到达 ：应看到 0x30 开头的报文，紧随其后是主题名 0x48 0x4A 0x54 （”HJT”），最后是有效载荷 0x31 或 0x32 。

若看到 0x20 0x02 0x00 0x01 ，则返回码为1（连接被拒绝），原因通常是客户端ID冲突或Broker认证失败。

4.2 分阶段验证：隔离问题域

遵循“自底向上”原则，逐层验证：

1. 物理层 ：用万用表测量ESP-01S的VCC与GND间电压是否稳定3.3V；用示波器观察TX/RX波形是否干净。
2. AT指令层 ：脱离STM32，用USB-TTL直接与ESP-01S对话，确保 AT+CWMODE? 、 AT+CWJAP? 、 AT+CIPSTART? 均返回预期值。
3. 透传层 ：在透传模式下，PC串口发送任意字节（如 0x01 0x02 0x03 ），观察ESP-01S是否原样回传（需开启回显 AT+CIPMODE=1 后 AT+CIPSEND ）。
4. MQTT层 ：仅发送CONNECT报文，确认收到CONNACK；再发送SUBSCRIBE，确认收到SUBACK；最后用MQTT.fx等工具向主题发消息，观察STM32是否收到PUBLISH。

黄金法则 ：永远假设上一层是错的，先验证它。曾因PC端串口助手缓存未清，误判ESP-01S固件异常，耗费数小时。

4.3 资源监控：防止内存溢出

在 while(1) 主循环中添加简易资源监控：

void check_system_health(void) {
    static uint32_t last_check = 0;
    if (HAL_GetTick() - last_check > 5000) {
        last_check = HAL_GetTick();

        // 检查环形缓冲区水位
        uint16_t used = (rx_head >= rx_tail) ? (rx_head - rx_tail) : (RX_BUFFER_SIZE - rx_tail + rx_head);
        if (used > RX_BUFFER_SIZE * 0.8) {
            // 缓冲区过载警告，可能解析逻辑阻塞
            HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_0); // 闪烁PA0指示灯
        }

        // 检查堆栈使用量（需启用CMSIS-RTOS）
        osThreadStackInfo_t stack_info;
        osThreadGetStackSpace(osThreadGetId(), &stack_info);
        if (stack_info.free < 128) {
            // 任务堆栈不足
            HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_1);
        }
    }
}

当缓冲区持续高位或堆栈告急时，系统行为将变得不可预测，这是许多“偶发性”通信故障的根源。

5. 生产环境增强建议

本方案已通过原型验证，若需投入量产，建议在以下维度增强：

5.1 安全加固

• TLS加密 ：使用 AT+CIPSTART="SSL","broker.emqx.io",8883 建立加密连接。需提前通过 AT+CERT 指令烧录服务器根证书。
• 客户端认证 ：在CONNECT报文中设置用户名与密码字段（连接标志位相应置1），避免未授权接入。
• 固件签名 ：对STM32固件进行数字签名，启动时校验，防止恶意固件注入。

5.2 可靠性提升

• 看门狗协同 ：配置独立看门狗（IWDG），在 mqtt_task 主循环末尾喂狗。若MQTT状态机卡死，IWDG将强制复位。
• 断网自动重连 ：在 MQTT_ERROR 状态中，不仅重试连接，还应记录失败次数。连续3次失败后，尝试切换备用Broker地址或进入低功耗休眠。
• OTA升级通道 ：预留一个特殊MQTT主题（如 firmware/update/HJT ），当收到新固件URL时，由MCU下载并写入Flash指定区域，重启后加载。

5.3 日志与诊断

• 分级日志 ：定义 LOG_LEVEL_DEBUG 、 LOG_LEVEL_INFO 、 LOG_LEVEL_ERROR 宏。调试阶段开启DEBUG，量产时仅保留ERROR。
• 环形日志缓冲区 ：开辟一块SRAM作为日志环形缓冲区，记录关键事件（如 CONNECT_SENT , CONNACK_RECEIVED , SUBACK_FAILED ）。当设备异常时，可通过特定AT指令（如 AT+LOGDUMP ）导出日志。

我的实践 ：在一款智能灌溉控制器中，正是依靠环形日志缓冲区，捕获到一次罕见的ESP-01S在高温（>60℃）下TCP连接超时的BUG。没有日志，这个问题将永远无法复现与定位。