SoftAP 示例

[English]

示例说明

SoftAP (Software-enabled Access Point) 是 ESP32 的一种 Wi-Fi 工作模式，允许设备自身创建一个无线热点，供其他终端（如手机、电脑）连接。但需要注意，仅启用 SoftAP 模式无法访问外部互联网，ESP32 只作为热点提供连接服务，终端设备连接后仅能获取 IP 地址和进行局域网通信，无法通过该网络访问外部网络资源。

本示例展示如何将 ESP32 设备配置为 Wi-Fi SoftAP 模式，在无需依赖外部路由器的情况下创建无线热点，供其他设备连接并进行本地通信。

运行方法

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

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

头文件说明

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

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

  1. FreeRTOS 任务调度 ：提供任务管理、延时控制接口。

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

  1. 系统工具 ：用于设备 MAC 地址获取、日志打印以及非易失性存储的初始化。

#include "esp_mac.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"

宏定义说明

本示例中涉及的宏定义主要用于配置 ESP32 SoftAP 模式的运行参数以及安全相关的 GTK 密钥轮换。

宏定义按功能分类如下：

  1. Wi-Fi 参数配置 ：用于设置 Wi-Fi SSID、密码、信道和连接设备数上限，以便正确识别并连接到指定的接入点。

  • SSID (Service Set Identifier) 是用于标识无线局域网的网络名称，即 Wi-Fi 的名字。在 SoftAP 模式下，ESP32 所广播的 SSID 和密码均可自定义。

  • 信道参数用于指定 ESP32 SoftAP 所使用的 Wi-Fi 信道号，即无线通信所使用的频段子通道，默认配置为 1。若终端设备无法扫描到 ESP32 热点，可能是由于信道不兼容，建议尝试切换信道。

  • 最大连接数用于限制可以同时连接至 ESP32 SoftAP 的终端设备数量，默认值为 4。

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

  1. GTK 密钥轮换 ：根据 menuconfig 中用户的配置，使用条件编译选择是否启用 GTK 密钥轮换及其轮换周期设置。默认启用，轮换周期为 600 秒。

  • GTK（组临时密钥）是 WPA/WPA2 无线安全协议中，用于加密组播和广播数据的密钥。由接入点（AP）生成并分发给所有连接设备，用于保障局域网中广播通信的安全性。

  • 现代 WPA2 及 WPA3 标准推荐或要求定期轮换 GTK，以防止密钥泄露、重放攻击等安全风险，从而提升整体无线通信的安全水平。

  • 示例中宏 EXAMPLE_GTK_REKEY_INTERVAL 对应配置项 CONFIG_ESP_GTK_REKEY_INTERVAL，用于设置 GTK 密钥轮换的时间间隔。

  • 建议在公共或多人同时连接的应用场景中启用 GTK 密钥轮换，以增强安全性。

  • 合理设置轮换周期，周期过短可能导致频繁密钥更新带来性能开销，过长则降低安全效果。

备注

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

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

功能函数说明

本示例通过 wifi_init_softap() 函数完成 ESP32 的 SoftAP 模式初始化，并通过注册回调函数 wifi_event_handler() 实现对终端设备连接状态的监控与响应。

其中，wifi_init_softap() 负责初始化网络相关组件和 Wi-Fi 驱动、配置参数并启动 Wi-Fi 热点功能，而 wifi_event_handler() 则用于监听 Wi-Fi 事件，在终端设备接入或断开时输出对应日志信息，便于调试和状态监控。

两者配合，构建起 SoftAP 模式下的初始化与运行逻辑，实现了热点创建和连接状态管理的完整流程。

wifi_event_handler()

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

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

事件分类

event_id 设置

执行逻辑

连接成功

WIFI_EVENT_AP_STACONNECTED

有终端设备连接到 ESP32，打印其相关信息。

断开连接

WIFI_EVENT_AP_STADISCONNECTED

终端设备断开连接，打印其相关信息。

事件处理函数的 event_data 参数是一个通用的 void* 指针，实际类型依赖于具体事件。

SoftAP 模式下，终端的连接或断开事件分别对应 wifi_event_ap_staconnected_t 和 wifi_event_ap_stadisconnected_t 结构体，使用前需通过强制类型转换提取具体字段，如终端设备的 MAC 地址和 AID。

为了便于日志中输出 MAC 地址，ESP-IDF 提供了两个辅助宏：

  • MACSTA：定义一个格式化字符串 %02x:%02x:%02x:%02x:%02x:%02x，用于打印标准 MAC 地址格式。

  • MAC2STA()：将 uint8_t mac[6] 展开为 6 个十六进制参数，配合 MACSTR 使用，实现便捷输出。

wifi_init_softap()

该函数用于初始化 Wi-Fi SoftAP 模式，完成网络接口和事件循环的创建、事件回调注册、SoftAP 参数配置及 Wi-Fi 启动，最终等待终端设备连接。

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

  1. 初始化阶段

  2. 事件回调函数：

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

event_base

event_id

事件说明

WIFI_EVENT

WIFI_EVENT_AP_STACONNECTED

Wi-Fi 配置完成

WIFI_EVENT

WIFI_EVENT_AP_STADISCONNECTED

Wi-Fi 连接失败

  1. 配置阶段：

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

    配置项

    说明

    示例中配置

    .ssid

    创建的 Wi-Fi 热点的 SSID

    EXAMPLE_ESP_WIFI_SSID

    .ssid_len

    SSID 的长度

    调用 strlen() 获取

    .channel

    Wi-Fi 信道，决定热点所在的频段

    EXAMPLE_ESP_WIFI_CHANNEL

    .password

    热点连接密码

    EXAMPLE_ESP_WIFI_PASS

    .max_connection

    最大允许连接的客户端数

    EXAMPLE_MAX_STA_CONN

    .authmode

    选择认证模式，控制热点的 安全等级

    如启用 CONFIG_ESP_WIFI_SOFTAP_SAE_SUPPORT，选择 WIFI_AUTH_WPA3_PSK，否则选择 WIFI_AUTH_WPA2_PSK。

    .sae_pwe_h2e

    设置 WPA3 SAE 的 PWE 生成模式，用于增强安全性。仅在启用 CONFIG_ESP_WIFI_SOFTAP_SAE_SUPPORT 时配置。

    WPA3_SAE_PWE_BOTH

    .pmf_cfg.required

    选择是否启用受保护管理帧（PMF）

    true

    .bss_max_idle_cfg.period

    设置 BSS 最大空闲时间，超时后客户端可能被断开。仅在启用 CONFIG_ESP_WIFI_BSS_MAX_IDLE_SUPPORT 时有效。

    1

    .bss_max_idle_cfg.protected_keep_alive

    选择是否保护客户端发送的保活帧，避免断连。仅在启用 CONFIG_ESP_WIFI_BSS_MAX_IDLE_SUPPORT 时有效。

    1

    .gtk_rekey_interval

    密钥轮换 周期

    EXAMPLE_GTK_REKEY_INTERVAL

    • CONFIG_ESP_WIFI_SOFTAP_SAE_SUPPORT：启用 SAE（对等同时认证）机制支持，用于 SoftAP 模式下的 WPA3-Personal 安全协议。SAE 提供比传统 WPA2 更强的安全性，适用于对无线加密强度要求较高的场景。该选项默认启用。

    • CONFIG_ESP_WIFI_BSS_MAX_IDLE_SUPPORT：启用对 BSS Max Idle 功能的支持，允许 ESP32 SoftAP 通知连接设备其允许的最长空闲时间，从而帮助终端决定是否保持连接或断开。这一机制可用于优化资源管理，降低空闲连接的系统开销。该选项默认关闭。

    备注

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

  • 判断密码长度，当密码长度为 0 时，将认证模式设为开放（WIFI_AUTH_OPEN)，避免因密码为空而导致配置错误。

  • 设置 Wi-Fi 工作模式为 WIFI_MODE_AP，即 SoftAP模式。

  1. 启动阶段：

  1. 连接阶段：

  • 在 SoftAP 模式下，连接阶段不需要显式调用 API 完成。

  • 连接阶段产生的具体事件可参考 ESP32 Wi-Fi AP 一般情况。

主函数说明

该函数作为程序入口函数，用于完成非易失性存储（NVS）初始化，并启动 Wi-Fi SoftAP 模式，为设备建立无线接入点提供基础环境。

其函数内实现步骤如下：

  1. 初始化 NVS

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

  3. 启动 Wi-Fi 初始化：调用 wifi_init_softap() 函数，完成网络接口配置、事件注册、Wi-Fi 参数设置和驱动启动，使 ESP32 成为可连接的无线接入点。