2、ESP32 Wi-Fi基础：掌握ESP32的Wi-Fi工作模式（Station、AP、混杂模式）、常用API和事件驱动机制

ESP32 的 Wi-Fi 能力是其作为物联网节点最核心的硬件资源之一。与传统的 MCU 外挂 Wi-Fi 模块（如 ESP8266 或串口转 Wi-Fi 模块）不同，ESP32 将 2.4GHz Wi-Fi 射频、基带处理和协议栈集成在单颗芯片内，通过 ESP-IDF（Espressif IoT Development Framework）提供的原生 API 进行控制。理解其工作模式、API 调用方式和事件驱动机制，是后续实现配网、云端同步和本地优先策略的基石。本章将深入剖析 ESP32 的三种 Wi-Fi 工作模式、核心 API 的调用逻辑以及事件循环（Event Loop）的运作原理，并给出实际工程中的配置建议。

上图展示了 ESP32 Wi-Fi 协议栈与三种工作模式、事件循环以及常用 API 之间的整体关系。在实际开发中，我们通常不会直接操作射频寄存器，而是通过事件驱动的方式感知链路状态变化，并调用相应的 API 进行响应。下面我们将逐一展开。

2.1 三种 Wi-Fi 工作模式的核心原理与适用场景

ESP32 的 Wi-Fi 子系统支持三种基本模式，它们可以独立使用，也可以组合使用（如 STA+AP 共存模式）。理解每种模式的本质是选择正确配网方案的前提。

2.1.1 Station（STA）模式：作为客户端连接路由器

在 STA 模式下，ESP32 扮演一个 Wi-Fi 客户端（Client）的角色。它扫描周围环境中的无线接入点（AP，即路由器），选择一个目标 AP 发起连接，并通过 WPA2/WPA3 等协议完成认证和关联。连接成功后，ESP32 会通过 DHCP 获取 IP 地址，从而获得网络层通信能力。

这是物联网设备最常用的模式。例如，一个智能插座、温湿度传感器或摄像头，都需要以 STA 模式接入家庭或工业路由器，才能与云端服务器或局域网内的手机 App 通信。在配网场景中，设备通常先以其他模式（如 AP 模式）接收配网信息，然后切换为 STA 模式连接目标路由器。

2.1.2 AP（Access Point）模式：创建热点供其他设备接入

AP 模式让 ESP32 自身成为一个无线接入点，广播 SSID（服务集标识），允许最多 4 个（默认配置）外部设备（如手机、电脑）连接。此时 ESP32 通常运行一个 DHCP 服务器，为连接的客户端分配 IP 地址（默认网段为 192.168.4.x）。

AP 模式在配网流程中至关重要。当设备处于未配网状态时，它可以开启一个名为 "ESP32_Config_XXXX" 的热点。用户手机连接该热点后，通过浏览器或 App 访问固定的 IP（如 192.168.4.1），即可发送目标路由器的 SSID 和密码。这种模式也被称为 SoftAP 配网。

2.1.3 混杂模式（Promiscuous）：监听空中数据帧

混杂模式是一种特殊的接收模式。在此模式下，ESP32 的 Wi-Fi 控制器不再过滤目的地址非本机的数据帧，而是将空中捕获的所有 802.11 帧（包括管理帧、控制帧和数据帧）都提交给上层协议栈。该模式常用于 Wi-Fi 信道扫描、RSSI 采集、空中抓包（Sniffer）以及一些基于帧分析的室内定位应用。

在配网场景中，混杂模式较少直接用于传输业务数据，但它可以用于扫描周围 Wi-Fi 环境，帮助设备选择信号最好的信道，或者用于实现一些特殊的“零配置”配网协议（如某些智能家居设备通过监听手机发出的特定 Beacon 帧来获取配网信息）。

2.2 常用 Wi-Fi API 与初始化流程

ESP-IDF 的 Wi-Fi API 基于 C 语言实现，其调用逻辑遵循“初始化 → 配置 → 启动 → 事件处理”的固定流程。掌握这个流程是编写稳定网络应用的基础。

2.2.1 核心 API 清单

以下是在 STA 模式下最常用的 API 函数及其作用：

• esp_wifi_init()：初始化 Wi-Fi 协议栈，分配资源。需要传入一个 wifi_init_config_t 结构体，通常使用宏 WIFI_INIT_CONFIG_DEFAULT() 填充默认值。
• esp_wifi_set_mode()：设置工作模式，参数为 wifi_mode_t 枚举值（WIFI_MODE_STA、WIFI_MODE_AP、WIFI_MODE_APSTA）。
• esp_wifi_set_config()：设置详细配置。对于 STA 模式，需要填充 wifi_config_t 中的 sta 字段，包括 SSID、密码、认证方式等。
• esp_wifi_start()：启动 Wi-Fi 子系统。调用后，协议栈开始工作，并触发相应的事件（如 WIFI_EVENT_STA_START）。
• esp_wifi_connect()：在 STA 模式下发起连接。该函数是异步的，连接结果通过事件通知。
• esp_wifi_scan_start()：启动 Wi-Fi 扫描，用于发现周围的 AP。扫描结果通过事件或回调函数获取。

2.2.2 标准初始化流程（STA 模式）

下面是一个典型的 STA 模式初始化代码片段，展示了 API 的调用顺序：

// 1. 初始化 NVS（非易失性存储），Wi-Fi 驱动依赖 NVS 保存校准数据
esp_err_t ret = nvs_flash_init();
if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
    nvs_flash_erase();
    nvs_flash_init();
}

// 2. 创建默认事件循环
esp_event_loop_create_default();

// 3. 初始化 Wi-Fi 驱动
wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
esp_wifi_init(&cfg);

// 4. 注册事件处理器（详见 2.3 节）
esp_event_handler_instance_register(WIFI_EVENT, ESP_EVENT_ANY_ID, &wifi_event_handler, NULL);
esp_event_handler_instance_register(IP_EVENT, IP_EVENT_STA_GOT_IP, &ip_event_handler, NULL);

// 5. 设置模式为 STA
esp_wifi_set_mode(WIFI_MODE_STA);

// 6. 配置连接参数
wifi_config_t wifi_config = {
    .sta = {
        .ssid = "MyHomeRouter",
        .password = "password123",
        .threshold.authmode = WIFI_AUTH_WPA2_PSK,
    },
};
esp_wifi_set_config(WIFI_IF_STA, &wifi_config);

// 7. 启动 Wi-Fi
esp_wifi_start();

// 8. 发起连接（通常在 WIFI_EVENT_STA_START 事件中调用）
esp_wifi_connect();

2.3 事件驱动机制：系统如何通知你“网络已就绪”

ESP32 的网络协议栈采用事件驱动（Event-Driven）架构。这意味着你不需要轮询检查 Wi-Fi 是否连接成功，而是注册一个回调函数，当特定事件发生时，系统会主动调用你的回调函数。这种机制极大地提高了 CPU 利用率和代码的可维护性。

2.3.1 事件循环与事件源

ESP-IDF 提供了两个核心事件源：WIFI_EVENT 和 IP_EVENT。它们通过默认事件循环（esp_event_loop_create_default()）分发。

• WIFI_EVENT：涵盖 Wi-Fi 协议栈的状态变化。例如：
  • WIFI_EVENT_STA_START：STA 模式启动完成，此时可以安全调用 esp_wifi_connect()。
  • WIFI_EVENT_STA_CONNECTED：ESP32 已与路由器完成关联（Layer 2 连接成功），但尚未获得 IP 地址。
  • WIFI_EVENT_STA_DISCONNECTED：连接断开。此事件携带断开原因码（如 201 表示密码错误，15 表示 AP 未找到）。
• IP_EVENT：涵盖网络层（IP）的状态变化。最重要的一个事件是：
  • IP_EVENT_STA_GOT_IP：ESP32 通过 DHCP 成功获取到 IP 地址。这是“设备真正联网”的标志。事件数据中包含 ip_info 结构体，里面有 IP 地址、子网掩码和网关地址。

2.3.2 事件处理器的注册与实现

事件处理器是一个普通的 C 函数，通过 esp_event_handler_instance_register() 注册。下面是一个处理 Wi-Fi 和 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_CONNECTED:
                ESP_LOGI(TAG, "已连接到路由器，等待获取 IP...");
                break;
            case WIFI_EVENT_STA_DISCONNECTED:
                ESP_LOGI(TAG, "连接断开，尝试重连...");
                esp_wifi_connect(); // 简单重连策略
                break;
            default:
                break;
        }
    }
}

static void ip_event_handler(void* arg, esp_event_base_t event_base,
                             int32_t event_id, void* event_data) {
    if (event_base == IP_EVENT && 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));
        // 在这里可以启动 MQTT、HTTP 客户端等上层应用
        xTaskCreate(mqtt_app_start, "mqtt", 4096, NULL, 5, NULL);
    }
}

2.4 实战案例：基于事件驱动的 Wi-Fi 连接与断线重连

为了将上述理论应用到实际工程中，我们设计一个典型的智能家居设备场景。该设备需要连接家庭 Wi-Fi，并在断线后自动重连，同时将连接状态通过板载 LED 指示。

2.4.1 场景与约束

背景：一款智能灯泡，使用 ESP32-C3 芯片。用户通过手机 App 完成配网后，设备需要稳定连接路由器。由于家庭环境可能存在路由器重启、信号干扰等问题，设备必须具备自动重连能力。

约束：

• 设备功耗敏感，不能使用简单的 while(1) 阻塞重连。
• 需要区分“密码错误”和“路由器重启”两种失败场景，避免无效重连。
• LED 指示状态：快闪（正在连接）、慢闪（连接失败）、常亮（已连接）。

2.4.2 初始现象与问题

初版固件中，开发者在 WIFI_EVENT_STA_DISCONNECTED 回调中直接调用 esp_wifi_connect() 进行重连。结果发现：当路由器密码错误时，设备会陷入“连接-断开-重连”的死循环，导致 LED 快速闪烁，且功耗异常升高。

2.4.3 分析与优化过程

通过查看 WIFI_EVENT_STA_DISCONNECTED 事件中的 reason 字段，我们找到了问题根源。ESP-IDF 定义了详细的断开原因码，其中：

• WIFI_REASON_NO_AP_FOUND (201)：找不到目标 AP（路由器关机或信号太弱）。
• WIFI_REASON_AUTH_FAIL (202)：密码错误。
• WIFI_REASON_ASSOC_FAIL (203)：关联失败。

针对不同原因，我们设计了不同的处理策略：

1. 密码错误（202）：停止重连，进入配置模式（重新开启 AP 热点等待用户重新配网）。
2. 找不到 AP（201）：采用指数退避算法重连。第一次等待 1 秒，第二次 2 秒，第三次 4 秒，最长不超过 30 秒。同时记录连续失败次数，超过 5 次后进入低功耗休眠，等待外部唤醒。
3. 其他原因：等待 5 秒后重连。

2.4.4 关键代码实现

#define MAX_RETRY 5
static int retry_count = 0;

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 && event_id == WIFI_EVENT_STA_DISCONNECTED) {
        wifi_event_sta_disconnected_t* event = (wifi_event_sta_disconnected_t*) event_data;
        
        if (event->reason == WIFI_REASON_AUTH_FAIL) {
            ESP_LOGE(TAG, "密码错误，停止重连，进入配网模式");
            // 关闭 STA，开启 AP 模式等待重新配网
            esp_wifi_set_mode(WIFI_MODE_AP);
            esp_wifi_start();
            // 通知用户 App 配网失败
        } else if (event->reason == WIFI_REASON_NO_AP_FOUND) {
            if (retry_count < MAX_RETRY) {
                retry_count++;
                int delay_ms = (1 << retry_count) * 1000; // 指数退避
                ESP_LOGW(TAG, "未找到 AP，%d 秒后重连 (第 %d 次)", delay_ms/1000, retry_count);
                vTaskDelay(pdMS_TO_TICKS(delay_ms));
                esp_wifi_connect();
            } else {
                ESP_LOGE(TAG, "重连次数过多，进入休眠");
                // 进入深度睡眠，等待 GPIO 唤醒
            }
        } else {
            ESP_LOGW(TAG, "其他原因断开 (reason=%d)，5 秒后重连", event->reason);
            vTaskDelay(pdMS_TO_TICKS(5000));
            esp_wifi_connect();
        }
    }
}

2.4.5 结果与复盘

优化后，设备在密码错误时能立即停止重连，避免无效功耗；在路由器重启时，能自动恢复连接，且重连期间设备仍可响应本地按键操作。通过事件驱动机制，我们将复杂的网络状态管理转化为清晰的状态机逻辑，代码可读性和健壮性显著提升。

2.5 常见误区与工程建议

在 ESP32 Wi-Fi 开发中，初学者容易陷入以下几个误区，需要特别注意：

• 误区一：在事件回调中执行耗时操作。事件回调运行在事件循环任务的上下文中。如果在回调中调用 vTaskDelay() 或进行大块内存拷贝，会阻塞其他事件的处理（如 TCP/IP 栈的事件）。正确的做法是：在回调中只发送通知（如信号量、消息队列），将耗时操作放到独立的任务中执行。
• 误区二：忽略 NVS 初始化。Wi-Fi 驱动需要从 NVS 读取射频校准数据。如果未初始化 NVS，esp_wifi_init() 会返回错误。务必在初始化 Wi-Fi 之前调用 nvs_flash_init()。
• 误区三：混淆“连接成功”和“获取 IP”。WIFI_EVENT_STA_CONNECTED 只代表链路层关联成功，此时设备还没有 IP 地址，无法进行 TCP/IP 通信。必须等待 IP_EVENT_STA_GOT_IP 事件才能启动上层应用。
• 误区四：在 AP 模式下忘记配置 DHCP 服务器。如果使用 AP 模式，需要调用 esp_netif_dhcps_start() 启动 DHCP 服务，否则连接的手机无法获取 IP 地址，无法访问配置页面。

最后，建议在工程中始终使用 esp_netif 组件来管理网络接口。它提供了与底层 Wi-Fi 驱动解耦的 API，使得代码可以同时支持以太网和 Wi-Fi，且便于后续维护和升级。