通用步骤

[English]

本文档总结了 ESP-IDF 中 Wi-Fi 各工作模式的公共实现流程，涵盖关键的系统和网络初始化、Wi-Fi 配置与启动、事件管理及相关功能模块的通用操作。文档列出各阶段的主要任务、涉及的 API 及调用顺序，为不同示例提供统一的实现参考。

掌握该文档内容有助于快速理解各模式的核心流程、在不同 Wi-Fi 应用中复用公共代码，并结合示例文档高效定位模式差异与特有实现。

Wi-Fi 运行步骤

Wi-Fi 不同模式下的运行流程图可参考 ESP32 Wi-Fi station 一般情况 和 ESP32 Wi-Fi AP 一般情况。

初始化阶段

1. 创建/初始化 LwIP：初始化底层的 TCP/IP 协议栈（LwIP）以及其之上的网络接口管理模块（esp-netif），为设备的 IP 地址管理和网络数据收发搭建起必要的软硬件环境。

• TCP/IP 协议栈是实现网络通信的核心软件模块，负责按照标准协议完成数据的封装、路由、传输和接收，启动网络通信必须先初始化 TCP/IP 协议栈。

• ESP32 使用 LwIP 作为其网络协议栈实现，LwIP 是专为资源有限的嵌入式系统设计的轻量级 TCP/IP 协议栈，支持包括 IP、TCP、UDP、DHCP 等在内的常见网络协议。有关 LwIP 的进一步说明请参考 LwIP。

• 在 LwIP 协议栈之上，esp-netif 作为网络接口管理模块，负责统一管理多个网络接口（如 Wi-Fi STA、AP 和以太网）及其生命周期，提供事件处理机制以响应网络状态和 IP 地址变化，保障通信稳定灵活。初始化 esp-netif 后，系统能有效创建和管理具体接口，实现协议栈与物理设备的连接。有关 esp-netif 的进一步说明请参考 ESP-NETIF。

• 该步骤通过调用 esp_netif_init() 完成。

2. 创建/初始化事件：搭建系统的事件驱动框架，创建一个默认的事件循环环境。

• 事件是一种高层次的软件信号，代表系统或模块状态的变化，程序可根据不同事件执行相应任务。Wi-Fi 相关事件可参考 ESP32 Wi-Fi 事件描述。

• 事件循环是一种循环监听和处理事件的机制或程序结构，持续检查是否有新事件产生，并将事件分发给对应的处理函数或模块。

• 在 Wi-Fi 中，通过事件机制可以让程序及时知道连接和通信过程中的状态变化，方便做出响应和处理，保证网络运行稳定。

• 该步骤通过调用 esp_event_loop_create_default() 完成。更多参数说明可参考 事件循环库 API。

3. 创建/初始化网络接口：创建一个默认的网络接口，并将该接口与 esp-netif 网络接口管理模块关联，实现协议栈与 Wi-Fi 硬件的连接。

• 接口对象封装了网络参数（如 IP 地址、子网掩码等），并作为桥梁连接 Wi-Fi 驱动与 LwIP 协议栈。完成该步骤后，系统即可进行 Wi-Fi 扫描、连接和数据传输等操作。

• 对于 Wi-Fi STA 模式，调用 esp_netif_create_default_wifi_sta() 完成该步骤。更多参数说明可参考 NETIF API。

• 对于 Wi-Fi AP 模式，调用 esp_netif_create_default_wifi_ap() 完成该步骤。更多参数说明可参考 NETIF API。

4. 创建/初始化 Wi-Fi：配置并初始化 Wi-Fi 驱动，启动相关内部任务，确保无线硬件和协议栈正常运行。

• Wi-Fi 驱动是 Wi-Fi 功能的核心，实现无线通信的底层协议和硬件控制。

• Wi-Fi 驱动参数通过 wifi_init_config_t 结构体进行配置，通常使用 WIFI_INIT_CONFIG_DEFAULT() 快速加载默认配置。

• 配置内容涵盖硬件资源分配、任务优先级、缓冲区大小和功耗管理等，保证驱动初始化的性能和稳定性。具体结构体成员可参考 Wi-Fi 库。

• 调用 esp_wifi_init() 完成 Wi-Fi 驱动初始化，启动必要的内部任务和资源，需传入配置结构体指针。更多参数说明可参考 Wi-Fi 库。

配置阶段

该阶段的其他注意事项请参考 Wi-Fi 配置阶段。

1. 配置连接参数：Wi-Fi 网络连接参数通过 wifi_config_t 结构体进行配置，配置内容涵盖目标连接网络的 SSID、密码、认证方式、加密类型等，以保证连接的网络的有效性和安全性。具体结构体成员可参考 station 模式结构体 或 AP 模式结构体。

2. 配置 Wi-Fi 模式：明确设备的角色，设定正确的工作模式。不同模式说明可参考 Wi-Fi 模式。调用 esp_wifi_set_mode() 并传入需要设定的模式。更多参数说明可参考 Wi-Fi 库。

3. 应用 Wi-Fi 配置：将连接参数应用到指定接口，确保系统能够识别和使用正确配置。

• 只有完成配置，才能发起连接和认证流程。

• 调用 esp_wifi_set_config() 完成该步骤，根据 Wi-Fi 模式指定接口，并传入配置结构体指针。更多参数说明可参考 Wi-Fi 库。

启动阶段

1. 启动 Wi-Fi：

• 调用 esp_wifi_start() 启动已初始化并完成配置的 Wi-Fi 驱动。相关参数说明可参考 Wi-Fi 库。

• 函数根据当前设定的模式创建对应的内部任务、分配必要资源，并使驱动进入工作状态。

• 调用成功后，设备将进入就绪状态，可以执行后续连接、扫描或监听等操作。

2. 等待事件：

• Wi-Fi 启动过程是异步的，即调用启动 API 后会立即返回，不会等到启动完成。

• 驱动在后台完成初始化和任务创建，结果通过事件机制上报，程序应依靠事件来判断连接状态。

• 启动完成后，相关事件会触发事件回调函数接收事件并执行相应的处理任务。

连接阶段

1. 连接 Wi-Fi：

• 调用 esp_wifi_connect() 启动连接流程。相关参数说明可参考 Wi-Fi 库。

• 函数根据当前设定的接口和连接参数，执行内部扫描、认证与关联操作。

2. 等待事件：

• Wi-Fi 连接过程是异步的，连接动作在后台任务中完成，连接结果通过事件机制上报，程序应依靠事件判断连接状态并做出响应。

• 连接完成后，相关事件会触发事件回调函数接收事件并执行相应的处理任务。

获取 IP 阶段

在该阶段，Wi-Fi 驱动会向 DHCP 服务器请求分配 IP 地址，并返回对应的事件状态。此过程由系统自动完成，无需用户干预。详情请参考 Wi-Fi 获取 IP 阶段。

备注

DHCP 服务器是一种自动分配 IP 地址的服务。在日常网络中，路由器通常充当 DHCP 服务器，为连接的设备分配可用 IP 地址。在 ESP32 的 SoftAP 模式下，设备自身也会启动 DHCP 服务器，为连接到它的客户端自动分配 IP 地址，使客户端能够顺利加入网络，无需手动设置 IP。

事件回调机制

Wi-Fi 及网络操作过程中的状态变化（如启动完成、连接成功、断开、获取 IP 等）均以事件形式通知应用程序。通过注册事件回调函数，应用程序可以及时接收并处理这些异步事件，实现动态响应和状态管理。事件回调机制保证程序能够在事件发生时执行相应操作，而无需主动轮询状态，提高效率和实时性。有关事件回调的进一步内容请参考 事件循环库。

注册事件回调函数

在 ESP-IDF 中，调用 esp_event_handler_instance_register() 注册回调函数。注册时需指定事件所属的事件基（如 Wi-Fi 事件基 WIFI_EVENT、IP 事件基 IP_EVENT）、具体事件类型，以及对应的事件处理函数。

注册事件回调函数原型为：

esp_err_t esp_event_handler_instance_register(esp_event_base_t event_base,
                                              int32_t event_id,
                                              esp_event_handler_t event_handler,
                                              void *event_handler_arg,
                                              esp_event_handler_instance_t *instance);

参数解释

传入参数	参数功能	参数说明
event_base	事件基，用于对事件进行分组	告诉系统这个事件属于哪个子系统或功能模块，避免不同模块相同事件 ID 冲突。
event_id	标识具体的事件类型	由程序在满足特定条件后自行发布，全部 Wi-Fi 事件可参考 ESP32 Wi-Fi 事件描述。事件 ID 只在所属的事件基范围内唯一。
event_handler	指向事件回调函数的指针	根据需求处理对应事件。有关回调函数的进一步介绍请参考。
event_handler_arg	传递给事件回调函数的自定义参数指针	可用于携带上下文信息，可传入 NULL。
instance	返回注册的事件处理实例句柄，用于后续取消注册或管理事件处理。	如果需要使用该句柄，调用前应先定义对应变量并传入；不需要管理时，可传入 NULL。

事件回调函数

事件回调函数是用户按需编写的函数，系统不会自动生成，并且通常由系统或框架在事件发生时自动调用，不需要程序主动调用。其主要作用是在指定事件发生时接收通知，并执行相应的处理逻辑，如日志记录、状态更新、错误处理、自动重连等。

该函数在事件上下文中执行，代码应尽量简短，避免阻塞，否则可能影响系统响应。

事件回调函数原型如下，其中 event_handler 为函数名，可自行修改：

void event_handler( void* arg,
                    esp_event_base_t event_base,
                    int32_t event_id,
                    void* event_data);

参数解释

参数	参数说明	与注册函数参数的对应关系
arg	自定义参数指针	由注册函数中的 event_handler_arg 传入。
event_base	事件基，标识事件所属模块或子系统	与注册时指定的 event_base 保持一致。
event_id	具体事件 ID，标识事件类型	与注册时指定的 event_id 保持一致。
event_data	事件相关的额外数据，类型和内容依事件而异	由系统在事件发生时传递，供回调函数参考和处理。

编写事件回调函数使程序能及时响应异步发生的网络事件，提升灵活性和运行效率。可根据具体需求，在回调函数中实现相应的事件处理逻辑。

非易失性存储（NVS）

1. 初始化非易失性存储：

• 非易失性存储是设备中用于存储持久化数据的关键模块。使能 Wi-Fi NVS flash 后，能够保存如 Wi-Fi 配置、设备参数等重要信息，断电后数据依然保留。

• 调用 nvs_flash_init() 初始化 NVS，完成对存储介质的准备和挂载。相关参数说明请参考 非易失性存储库 API。

2. 检查返回值：

• 及时发现初始化过程中可能出现的问题，比如 NVS 分区已满或版本不匹配等异常情况，避免程序在后续读写数据时出现错误，导致功能异常甚至崩溃。

• 若返回异常，调用 nvs_flash_erase() 擦除 NVS 分区。相关参数说明请参考 非易失性存储库 API。

  • ESP_ERR_NVS_NO_FREE_PAGES：表示 NVS 分区已满，没有可用的空闲页，无法写入新数据。

  • ESP_ERR_NVS_NEW_VERSION_FOUND：表示当前 NVS 分区的数据版本与库期望版本不匹配，可能需要升级或格式化分区。

• 擦除分区后需要重新调用初始化函数，并再次检查返回值，确保初始化成功。