Station 示例

[English]

示例说明

Station（站点）模式是 Wi-Fi 的一种工作方式。在该模式下，设备作为“客户端”连接到已有的 Wi-Fi 路由器或接入点（AP），加入本地局域网。这是嵌入式设备最常用的联网方式之一，广泛应用于 IoT、智能家居等场景。

本示例展示如何将设备配置为 Wi-Fi station 模式，并连接至指定的路由器，实现基础的无线联网功能。

备注

设备能否访问互联网取决于路由器是否接入外网：即使设备成功连接到局域网，如果路由器未连接外网，也无法访问网站或云服务。

运行方法

示例完整代码见 station 示例。运行前的配置说明、构建与烧录流程详见示例目录下的 README.md 文件。

如需自定义配置项及查看默认值，可参考 宏定义说明 部分。

头文件说明

本示例所使用的头文件涵盖了 FreeRTOS 任务管理、 Wi-Fi 协议栈、系统事件机制、日志输出、NVS 非易失性存储以及 TCP/IP 协议栈接口等基础模块。构建了任务创建、 Wi-Fi 初始化、事件注册与响应、日志打印以及网络连接等核心功能。

各头文件按功能分类如下：

  1. FreeRTOS 任务调度 ：提供任务管理、延时控制与事件注册等接口。

#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/event_groups.h"

  1. 系统工具 ：用于系统初始化、日志打印和非易失性存储的配置与读写。

#include "esp_system.h"
#include "esp_log.h"
#include "nvs_flash.h"

  1. Wi-Fi 与事件机制 ：包含 Wi-Fi 启动与连接配置、事件循环注册及处理功能。

#include "esp_wifi.h"
#include "esp_event.h"

  1. 网络协议栈 ：包含 TCP/IP 协议栈中常用的错误码定义和底层系统抽象接口，用于处理网络连接过程中的状态。

#include "lwip/err.h"
#include "lwip/sys.h"

宏定义说明

本示例中涉及的宏定义主要用于配置 Wi-Fi 参数、选择认证模式、设置安全等级以及定义事件组中标志位。

宏定义按功能分类如下：

  1. Wi-Fi 参数配置 ：用于设置 Wi-Fi SSID、密码和最大重试次数，以便正确识别并连接到指定的接入点。

  • SSID (Service Set Identifier) 是用于标识无线局域网的网络名称，即 Wi-Fi 的名字。

  • 示例中的参数宏实际引用自以 CONFIG_ 开头的配置宏，这些配置宏由 ESP-IDF 构建系统根据 menuconfig 设置自动生成，保存在 sdkconfig 文件中。

  1. 安全认证模式设置 ：根据 menuconfig 中用户的配置，默认启用 Both 模式，使用条件编译选择对应的 WPA3 SAE 的密码元素（PWE）生成模式和辅助标识符。

  • WPA3 SAE (Simultaneous Authentication of Equals) 是一种增强型密码认证机制。

  • 密码元素（PWE）是由密码加工得到的一个中间值，不直接暴露密码本身，但能用来验证双方身份，防止密码被窃听或破解。

  • PWE 生成模式是 WPA3 连接中计算密码的一种方法，决定设备如何根据密码生成加密密钥，影响连接的安全性和兼容性。

  • ESP-IDF 支持三种 PWE 生成模式，选择哪种模式取决于应用需求和设备支持情况：

    • Hunt-and-Peck 模式：设备尝试多种可能的 PWE 组合，直到找到一个与对端，即通信方，匹配的元素。 这种方式属于尝试再验证类型，兼容性较好，适合硬件和固件版本支持较宽松的环境，但计算复杂度和连接延迟相对较高。

    • Hash-to-Element 模式：通过密码和双方身份信息的哈希计算，直接生成唯一的 PWE。该方法计算复杂度较低，连接速度更快，安全性也更高， 但要求双方设备都支持哈希算法。适合硬件和固件版本较新的设备以及对安全和效率有更高需求的场景。

    • Both 模式：同时支持上述两种方法，能够根据对端设备的能力动态选择最合适的密码元素生成方式，兼顾兼容性和性能。

  1. 设置 Wi-Fi 扫描时的最低安全等级 ：在进行 Wi-Fi 扫描时，过滤掉低于设定安全等级（默认为 WIFI_AUTH_WPA2_PSK）的接入点，只显示或连接符合要求的网络。

  • 通过条件编译机制，根据 menuconfig 中的配置，定义 ESP_WIFI_SCAN_AUTH_MODE_THRESHOLD 的值，用于设置 Wi-Fi 扫描时的最低安全等级。编译时会自动选择对应的认证模式宏，无需手动修改代码。

  • 在 ESP-IDF 中， Wi-Fi 支持的安全等级从低到高依次为：

    • WIFI_AUTH_OPEN ：开放网络，无需密码，通信数据不加密，安全性最低。

    • WIFI_AUTH_WEP ：使用 WEP 加密，存在已知漏洞，安全性较低，不推荐使用。

    • WIFI_AUTH_WPA_PSK ：使用 WPA 协议和预共享密钥（PSK）加密，已逐渐淘汰。

    • WIFI_AUTH_WPA2_PSK ：使用 WPA2 协议和 PSK 加密，为当前主流加密方式之一，安全性较好。

    • WIFI_AUTH_WPA_WPA2_PSK ：同时支持 WPA 和 WPA2 的混合模式，提升兼容性。

    • WIFI_AUTH_WPA3_PSK ：使用 WPA3 协议和 PSK 加密，具备更强的抗暴力破解能力，安全性更高。

    • WIFI_AUTH_WPA2_WPA3_PSK ：同时支持 WPA2 和 WPA3，自动协商连接方式，兼顾安全与兼容性。

    • WIFI_AUTH_WAPI_PSK ：使用中国国家标准的 WAPI 协议和 PSK 加密，适用于特定行业或地区要求。

  1. 定义事件组中标志位：为配合事件组机制实现任务与事件回调之间的 Wi-Fi 连接状态同步，示例中定义了两个事件标志位，用于标识连接是否成功。

  • WIFI_CONNECTED_BIT：对应事件组的第 0 位（BIT0）。Wi-Fi 连接成功时，将该位置 1。

  • WIFI_FAIL_BIT：对应事件组的第 1 位（BIT1）。Wi-Fi 连接失败时，将该位置 1。

备注

  • 以上宏定义修改 menuconfig 并再次构建/编译示例后会自动同步更新，无需手动更改代码。

  • 可以直接编辑这些宏以进行快速测试，但通过 menuconfig 配置更规范，适用于标准开发流程。

功能函数说明

本示例通过 wifi_init_sta() 函数完成 ESP32 station 模式的配置、启动及连接，并通过注册回调函数 event_handler() 实现对连接状态变化的响应处理。

其中，wifi_init_sta() 负责初始化网络相关组件和 Wi-Fi 驱动、配置连接参数并启动 Wi-Fi，而 event_handler() 则用于监听 Wi-Fi 和 IP 事件，根据连接过程中的不同状态触发相应操作。

两者配合，构建起完整的连接与状态管理流程。

event_handler()

此函数为事件响应函数，具体介绍请参考 事件回调函数。

在本示例中，该函数根据不同的 event_base 和 event_id 传入，用于处理以下三类事件：

事件分类

event_base 设置

event_id 设置

执行逻辑

连接 Wi-Fi

WIFI_EVENT

WIFI_EVENT_STA_START

调用 esp_wifi_connect() 尝试连接 Wi-Fi。

重连 Wi-Fi

WIFI_EVENT

WIFI_EVENT_STA_DISCONNECTED

如果 s_retry_num 小于设定的最大重试次数，则调用 esp_wifi_connect() 连接 Wi-Fi；否则设置事件组失败标志位。

获取 IP

IP_EVENT

IP_EVENT_STA_GOT_IP

从 event_data 中获取 IP 信息并打印，设置事件组连接成功标志位。

函数中的 xEventGroupSetBits() 用于将指定的事件位设置到事件组中，常用于任务间的事件通知与同步。返回值表示设置操作是否成功，并包含事件组中设置后的全部事件位状态。更多参数说明及相关示例可参考事件组 设置事件标志位 部分。

wifi_init_sta()

该函数用于初始化 Wi-Fi station 模式，完成网络连接的准备、事件注册、配置及启动 Wi-Fi，并等待连接结果。

以下为函数的主要实现步骤，鉴于流程的大部分步骤已在 通用步骤 中详细介绍，对于重复内容此处不再赘述，仅重点说明本示例中的关键实现与差异部分。

  1. 创建事件组：

  • 创建事件组，并返回其句柄，用于后续标记连接状态。有关事件组的详细介绍可参考 事件组 文档。

  • 在本示例中，Wi-Fi 连接状态存在多种可能（如连接成功、连接失败等），且程序需要根据这些状态做出不同响应。事件组通过标志位同步不同任务和事件，使得状态检测更为精准和高效，是实现复杂状态管理的关键手段。

  1. 初始化阶段

  2. 事件回调函数：

本示例涉及的事件如下表所示：

event_base

event_id

事件说明

WIFI_EVENT

WIFI_EVENT_STA_START

Wi-Fi 配置完成

WIFI_EVENT

WIFI_EVENT_STA_DISCONNECTED

Wi-Fi 连接失败

IP_EVENT

IP_EVENT_STA_GOT_IP

IP 获取成功

  1. 配置阶段：

  • wifi_config_t 结构体使用 .sta 成员，即 station 模式配置，其他成员均通过宏定义设置，具体可参考 宏定义说明 ：

    配置项

    说明

    示例中配置

    .ssid

    需要连接的 Wi-Fi 网络的 SSID

    EXAMPLE_ESP_WIFI_SSID

    .password

    对应 Wi-Fi 网络的密码

    EXAMPLE_ESP_WIFI_PASS

    .threshold.authmode

    设置 Wi-Fi 连接的最低 认证模式 阈值

    ESP_WIFI_SCAN_AUTH_MODE_THRESHOLD

    .sae_pwe_h2e

    设置 WPA3 SAE 的 PWE 生成模式，用于增强安全性

    ESP_WIFI_SAE_MODE

    .sae_h2e_identifier

    当使用 SAE Hash-to-Element 模式时，可选的 H2E 标识符，用于增强安全性。

    ESP_WIFI_SAE_MODE

    备注

    未显式赋值的 .sta 结构体成员会被自动初始化为零（或相应的默认值），表示使用默认行为或关闭对应功能，因此只有关键字段需要手动定义。

  • 设置 Wi-Fi 工作模式为 WIFI_MODE_STA，即 station 模式。

  1. 启动阶段：

  1. 连接阶段：

  • 本示例通过事件回调函数 event_handler() 调用 API 发起 Wi-Fi 连接。

  • 连接阶段产生的具体事件可参考 Wi-Fi 连接阶段。

  • 等待连接结果的阻塞操作通过 xEventGroupWaitBits() 实现，程序根据返回的事件位判断连接是否成功，并输出相应日志。有关 xEventGroupWaitBits() 的详细介绍及参数说明请参考 等待事件标志位 部分。

主函数说明

该函数作为程序入口函数，用于完成非易失性存储（NVS）初始化、日志等级设置，并调用 Wi-Fi station 模式初始化函数 wifi_init_sta()，启动 Wi-Fi 连接流程。

其函数内实现步骤如下：

  1. 初始化 NVS

  2. 设置日志等级：

  • 根据配置参数调整 Wi-Fi 模块的日志等级，提高调试信息的详细程度。

  • 调用 esp_log_level_set() 设置指定模块的日志输出等级，需传入模块名和日志等级。通常在模块初始化前调用。更多参数说明请参考 日志库 API。

  1. 打印启动信息：使用日志输出 Wi-Fi 模式信息。

  2. 启动 Wi-Fi 初始化：调用 wifi_init_sta() 函数，完成 Wi-Fi station 模式的初始化及连接过程。