ESP32 Wi-Fi STA + Light-sleep 下 MQTT 心跳丢包的定位与参数调优实战

一、问题现象与背景

在电池供电的 ESP32 项目中,为降低功耗常启用 esp_wifi_set_ps(WIFI_PS_MIN_MODEM) 或 Light-sleep。典型现象是:

  • 设备运行数分钟后被 MQTT Broker 判定超时并断开(keepalive 60s,实际 90s 未收到 PINGREQ)。
  • 日志中偶见 MQTT_EVENT_DISCONNECTED,重连后短时间正常,随后复现。
  • 关闭省电模式后问题消失,但功耗从 mA 级升到上百 mA。

根因通常不是 MQTT 库本身,而是 Wi-Fi 省电机制与 TCP 重传时序叠加 导致心跳包在空口被延迟或丢弃。

二、原理:Light-sleep 与 DTIM 如何影响心跳

1. Modem-sleep 与 Light-sleep 的区别

  • Modem-sleep:CPU 正常运行,Wi-Fi 射频按 DTIM 周期休眠,AP 缓存下行帧,醒来后取回。
  • Light-sleep:CPU 暂停、外设时钟门控,仅 RTC 与 Wi-Fi 唤醒源工作,唤醒延迟更大(数百微秒到数毫秒)。

2. DTIM 与心跳的耦合

AP 在 Beacon 中携带 DTIM 周期(常见 1~3)。STA 在每个 DTIM 窗口醒来接收缓存帧。若 MQTT keepalive 恰好落在睡眠窗口内,PINGREQ 会排队等待下一次唤醒,实际发送时间被拉长。当 Broker 的 keepalive * 1.5 超时先到,连接即被断开。

3. TCP 重传放大问题

心跳包丢失后触发 TCP RTO 重传(初始约 1s,指数退避)。若此时射频处于睡眠,重传被进一步推迟,形成“丢包→重传延迟→超时断开”的恶性循环。

三、定位步骤

  1. 确认省电模式:打印 esp_wifi_get_ps() 返回值,确认当前为 WIFI_PS_MIN_MODEM 还是 WIFI_PS_MAX_MODEM。
  2. 抓包验证:用另一台设备做 AP 镜像或串口打印 esp_timer_get_time() 记录 PINGREQ 实际发出时刻,与预期周期对比。
  3. 观察断开间隔:若断开时间接近 keepalive * 1.5,基本可判定为心跳延迟而非网络中断。
  4. 对照实验:临时 esp_wifi_set_ps(WIFI_PS_NONE),若问题消失即确认省电相关。

四、参数调优方案

1. 调整 DTIM 与 listen interval

在 menuconfig 中增大 listen interval,或让 AP 侧 DTIM 保持 1。STA 侧可通过 esp_wifi_set_config 的 listen_interval 控制唤醒频率,但过大会增加下行延迟。

2. 缩短 MQTT keepalive 并留足余量

将 keepalive 设为 30s,Broker 超时按 1.5 倍即 45s,给睡眠唤醒留出余量。避免 keepalive 与 DTIM 周期形成整数倍共振。

3. 心跳前主动唤醒射频

在发送 PINGREQ 前调用 esp_wifi_set_ps(WIFI_PS_NONE),发送完成后再恢复省电模式,可显著降低丢包率。

4. 关闭 Light-sleep 的自动进入

若使用 esp_light_sleep_start() 手动控制,确保在 MQTT 活跃期不进入睡眠;或用 esp_sleep_enable_timer_wakeup 与心跳周期对齐。

五、完整代码示例

#include "esp_wifi.h"
#include "esp_sleep.h"
#include "mqtt_client.h"
#include "esp_log.h"

static const char *TAG = "MQTT_PS";
static esp_mqtt_client_handle_t s_client;

/* 心跳发送前临时关闭省电,发送后恢复 */
static void mqtt_ping_with_wakeup(void)
{
    wifi_ps_type_t old_ps;
    esp_wifi_get_ps(&old_ps);
    esp_wifi_set_ps(WIFI_PS_NONE);          // 唤醒射频
    vTaskDelay(pdMS_TO_TICKS(20));           // 等待射频稳定

    esp_mqtt_client_publish(s_client, "$sys/heartbeat", "1", 1, 0, 0);

    esp_wifi_set_ps(old_ps);                // 恢复原省电模式
}

static void mqtt_event_handler(void *arg, esp_event_base_t base,
                               int32_t id, void *data)
{
    esp_mqtt_event_handle_t event = data;
    switch ((esp_mqtt_event_id_t)id) {
    case MQTT_EVENT_CONNECTED:
        ESP_LOGI(TAG, "MQTT connected");
        break;
    case MQTT_EVENT_DISCONNECTED:
        ESP_LOGW(TAG, "MQTT disconnected, will reconnect");
        break;
    default:
        break;
    }
}

void app_main(void)
{
    esp_netif_init();
    esp_event_loop_create_default();

    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
    esp_wifi_init(&cfg);

    wifi_config_t wifi_cfg = {
        .sta = {
            .ssid = "YOUR_SSID",
            .password = "YOUR_PASS",
            .listen_interval = 3,           // 与 DTIM 配合,勿过大
        },
    };
    esp_wifi_set_mode(WIFI_MODE_STA);
    esp_wifi_set_config(WIFI_IF_STA, &wifi_cfg);
    esp_wifi_start();
    esp_wifi_connect();

    esp_wifi_set_ps(WIFI_PS_MIN_MODEM);     // 初始省电模式

    esp_mqtt_client_config_t mqtt_cfg = {
        .broker.address.uri = "mqtt://broker.example.com",
        .session.keepalive = 30,            // 缩短心跳周期
    };
    s_client = esp_mqtt_client_init(&mqtt_cfg);
    esp_mqtt_client_register_event(s_client, ESP_EVENT_ANY_ID,
                                   mqtt_event_handler, NULL);
    esp_mqtt_client_start(s_client);

    /* 周期任务:每 20s 主动唤醒发送心跳 */
    while (1) {
        mqtt_ping_with_wakeup();
        vTaskDelay(pdMS_TO_TICKS(20000));
    }
}

六、注意事项

  • 不要盲目调大 listen_interval:会拉长下行数据延迟,影响 OTA 与命令响应。
  • keepalive 与 DTIM 避免整数倍关系:例如 DTIM=3、keepalive=30 易形成共振,可改为 25 或 35。
  • Light-sleep 唤醒源要配置完整:仅靠 Wi-Fi 唤醒可能漏掉定时器事件,建议同时启用 esp_sleep_enable_timer_wakeup。
  • 重连策略要有退避:断线后指数退避重连,避免频繁重连加剧功耗与 Broker 压力。
  • 实测功耗再定参数:用电流探头对比 WIFI_PS_NONE 与 MIN_MODEM 的实际均值,确认调优收益。

通过“定位—调参—验证”的闭环,可在保持低功耗的同时将 MQTT 心跳丢包率降到可接受范围。核心思路是:让心跳发送时刻与射频唤醒窗口对齐,并给 Broker 超时留足余量。