4、WiFi连接实战：STA模式、AP模式、WiFi事件处理与重连机制

ESP32 作为物联网终端，其网络连接的稳定性直接决定了上层应用（MQTT、HTTP、WebSocket）的可用性。本章聚焦于 ESP32 的 WiFi 基础连接能力，深入剖析 STA（Station）与 AP（Access Point）两种工作模式的核心差异、事件驱动架构以及工程中至关重要的断线重连机制。我们将从底层原理出发，结合代码实践与故障排查案例，帮助您构建一个健壮、可自愈的 WiFi 连接管理层，为后续的协议实战打下坚实基础。

4.1 核心原理：ESP32 网络协议栈与 WiFi 模式

ESP32 的网络功能基于乐鑫自研的 WiFi 协议栈（IEEE 802.11 b/g/n）与 LwIP 轻量级 TCP/IP 协议栈。在系统层面，WiFi 驱动与 LwIP 通过 esp_netif 抽象层进行交互，这为开发者提供了统一的网络接口管理方式。理解这一分层结构是掌握后续所有网络操作的前提。

ESP32 支持三种基础 WiFi 工作模式，它们决定了设备在网络中的角色：

模式	角色定义	IP 获取方式	典型应用场景
STA 模式	作为客户端连接外部 AP（如家用路由器）	DHCP 客户端（动态）或静态 IP	传感器数据上报、云端通信、远程控制
AP 模式	自身作为热点，允许其他设备接入	内置 DHCP 服务器，分配 192.168.4.x 网段	设备配网（SoftAP 配网）、点对点直连调试
APSTA 模式	同时开启 AP 与 STA，两者独立工作	AP 接口固定 IP，STA 接口 DHCP	中继器、配网后自动切换、局域网控制

在代码层面，esp_wifi.h 提供了底层驱动接口，而 esp_netif.h 负责网络接口的创建与配置。一个常见的初始化流程是：先创建默认的 STA 或 AP 网络接口，再初始化 WiFi 驱动，最后设置模式并启动。值得注意的是，事件循环（Event Loop） 是连接底层驱动与上层应用的桥梁，所有 WiFi 状态变化（如连接成功、断开、获取 IP）都会以事件的形式异步通知，这要求我们必须采用事件驱动编程模型，而非简单的轮询。

4.2 操作流程：STA 模式连接与事件处理实战

STA 模式是物联网设备最常用的工作模式。一个健壮的 STA 连接流程不应只是简单地调用 esp_wifi_connect()，而应包含完整的生命周期管理。以下是推荐的五步操作流程：

1. 初始化网络接口与事件循环：调用 esp_netif_init() 创建 LwIP 任务，并创建默认 STA 接口。
2. 注册事件处理器：使用 esp_event_loop_create() 创建事件循环，并注册 WIFI_EVENT 和 IP_EVENT 的处理函数。
3. 配置并启动 WiFi：设置 wifi_config_t 结构体（SSID、密码、认证方式），调用 esp_wifi_set_mode(WIFI_MODE_STA) 和 esp_wifi_start()。
4. 触发连接：在 WIFI_EVENT_STA_START 事件回调中调用 esp_wifi_connect()，确保驱动已就绪。
5. 等待 IP 获取：在 IP_EVENT_STA_GOT_IP 事件回调中，通过 esp_netif_get_ip_info() 获取 IP 地址，此时网络层才真正可用。

下面是一个精简但完整的事件处理框架，展示了如何通过事件驱动管理连接状态：

static void wifi_event_handler(void* arg, esp_event_base_t event_base,
                               int32_t event_id, void* event_data) {
    if (event_base == WIFI_EVENT) {
        switch (event_id) {
            case WIFI_EVENT_STA_START:
                ESP_LOGI(TAG, "STA 启动，开始连接...");
                esp_wifi_connect();  // 首次连接
                break;
            case WIFI_EVENT_STA_DISCONNECTED:
                ESP_LOGW(TAG, "连接断开，准备重连...");
                // 注意：不要在此处直接调用 esp_wifi_connect()
                // 应通过定时器或任务延迟重试，避免频繁重连
                s_retry_count++;
                if (s_retry_count < MAX_RETRY) {
                    vTaskDelay(pdMS_TO_TICKS(2000 * s_retry_count)); // 简单退避
                    esp_wifi_connect();
                }
                break;
            default:
                break;
        }
    } else if (event_base == IP_EVENT) {
        if (event_id == IP_EVENT_STA_GOT_IP) {
            ip_event_got_ip_t* event = (ip_event_got_ip_t*) event_data;
            ESP_LOGI(TAG, "获取到 IP: " IPSTR, IP2STR(&event->ip_info.ip));
            s_retry_count = 0;  // 连接成功，重置重试计数
            // 此处可触发 MQTT/HTTP 等上层应用
        }
    }
}

4.3 案例拆解：AP 模式配网与 APSTA 无缝切换

AP 模式最常见的工程应用是 SmartConfig 配网 和 SoftAP 配网。我们以一个典型的“手机 App 配网”场景为例，拆解其完整链路。

场景背景：设备首次上电，无任何 WiFi 凭据。用户需通过手机 App 将家庭路由器 SSID/密码写入设备。

实施步骤：

• 步骤 1：启动 AP 热点。设备开机后检测到 NVS 中无有效凭据，自动进入 AP 模式，热点名称为 ESP32_Config_XXXX，IP 固定为 192.168.4.1。
• 步骤 2：手机连接热点。手机连接该热点后，通过 HTTP（端口 80）访问设备的配网页面或发送 JSON 请求。
• 步骤 3：接收并存储凭据。设备解析 JSON 中的 SSID 和密码，写入 NVS 分区，并设置一个“已配置”标志位。
• 步骤 4：模式切换。调用 esp_wifi_set_mode(WIFI_MODE_STA) 并重启 WiFi 接口，自动连接目标路由器。

在更复杂的场景中，我们希望设备在配网后仍保留 AP 功能用于本地调试，此时应使用 APSTA 模式。关键配置如下：

wifi_config_t ap_config = {
    .ap = {
        .ssid = "ESP32_Local",
        .ssid_len = 0,
        .password = "12345678",
        .max_connection = 4,
        .authmode = WIFI_AUTH_WPA2_PSK
    },
};
wifi_config_t sta_config = {
    .sta = {
        .ssid = "Home_Router",
        .password = "router_password",
        .threshold.authmode = WIFI_AUTH_WPA2_PSK,
    },
};
// 先设置 AP 配置，再设置 STA 配置，最后启动
esp_wifi_set_mode(WIFI_MODE_APSTA);
esp_wifi_set_config(WIFI_IF_AP, &ap_config);
esp_wifi_set_config(WIFI_IF_STA, &sta_config);
esp_wifi_start();

在 APSTA 模式下，两个接口的事件是独立触发的。例如，手机断开 AP 连接会触发 WIFI_EVENT_AP_STADISCONNECTED，而路由器断开 STA 连接会触发 WIFI_EVENT_STA_DISCONNECTED。开发者需要分别处理，避免逻辑混淆。

4.4 重连机制深度优化与常见误区

WiFi 连接的不确定性（信号衰减、路由器重启、信道拥挤）要求我们必须设计一套健壮的重连机制。简单的 while(1) { esp_wifi_connect(); } 是不可取的。一个工程级的重连策略应包含以下要素：

策略维度	推荐实现	原因说明
退避算法	指数退避 + 随机抖动（1s, 2s, 4s, 8s... 上限 60s）	避免多设备同时重连造成网络风暴，降低路由器压力
重试上限	连续失败 10 次后，进入深度休眠或重启	防止设备在无信号区域空转耗电，延长电池寿命
状态监控	定期检查 esp_wifi_is_connected() 或监听事件	事件驱动为主，轮询为辅，确保状态同步
快速恢复	保存上次连接的 BSSID 和信道，重连时优先使用	跳过扫描阶段，将重连时间从 3-5 秒缩短至 1 秒以内

以下是一个改进后的重连任务示例，它使用 FreeRTOS 任务而非事件回调，以避免阻塞事件循环：

void wifi_reconnect_task(void *pvParameters) {
    uint8_t retries = 0;
    while (1) {
        if (gl_wifi_connected) {
            vTaskDelay(pdMS_TO_TICKS(10000)); // 已连接，每 10 秒检查一次
            continue;
        }
        if (retries >= MAX_RETRIES) {
            ESP_LOGE(TAG, "重连失败次数过多，系统重启");
            esp_restart();
        }
        // 指数退避：1s, 2s, 4s, 8s, 16s, 32s, 60s...
        uint32_t delay_ms = (1 << retries) * 1000;
        if (delay_ms > 60000) delay_ms = 60000;
        // 添加随机抖动 ±20%
        delay_ms += (esp_random() % (delay_ms / 5));
        ESP_LOGW(TAG, "第 %d 次重连，等待 %d ms", retries + 1, delay_ms);
        vTaskDelay(pdMS_TO_TICKS(delay_ms));
        esp_wifi_connect();
        retries++;
    }
}

常见误区总结：

• 误区一：忽略 WIFI_EVENT_STA_START 事件。在 esp_wifi_start() 后立即调用 esp_wifi_connect() 可能因驱动未就绪而失败，应等待 START 事件。
• 误区二：在事件回调中执行耗时操作。事件回调运行在优先级较高的任务中，若执行 DNS 查询或 MQTT 连接，会阻塞其他事件处理。应使用队列或任务通知将耗时操作移交至低优先级任务。
• 误区三：未处理 WIFI_EVENT_STA_STOP。当调用 esp_wifi_stop() 后，STA 会停止，此时应清理相关资源并更新状态标志。
• 误区四：静态 IP 配置错误。若使用静态 IP，需确保网关、子网掩码、DNS 均正确，否则会出现“已连接但无法上网”的假象。