📚 课程目录第1章 ESP32-S3 连接 WiFi 6 路由器

1. ESP32-S3 连接 WiFi 6 路由器

任务目标

本案例将配置 ESP32-S3 开发板连接 WiFi 6 路由器（兼容 802.11ax 协议），完成基本连接并获取 IP 地址。通过串口日志验证连接状态与分配到的 IP。

环境与依赖

硬件：ESP32-S3-DevKitC-1 开发板（或任意 ESP32-S3 模组开发板）
软件：ESP-IDF v5.x（需支持 WiFi 6 的 IDF 版本，建议 v5.1 及以上）
路由器：支持 WiFi 6（802.11ax）且开启 2.4GHz 频段（ESP32-S3 仅支持 2.4GHz WiFi 6）

完整代码

创建项目后，将以下代码写入 main.c。代码使用 ESP-IDF 的 Wi-Fi 事件驱动模型，实现连接、断线重连及 IP 获取。

#include <string.h>
#include "freertos/FreeRTOS.h"
#include "freertos/event_groups.h"
#include "esp_wifi.h"
#include "esp_event.h"
#include "esp_log.h"
#include "nvs_flash.h"

#define WIFI_SSID      "YOUR_WIFI6_SSID"
#define WIFI_PASS      "YOUR_PASSWORD"
#define WIFI_MAX_RETRY 5

static const char *TAG = "wifi6_sta";
static EventGroupHandle_t s_wifi_event_group;
#define WIFI_CONNECTED_BIT BIT0
#define WIFI_FAIL_BIT      BIT1
static int s_retry_num = 0;

static void 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_START) {
        esp_wifi_connect();
    } else if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
        if (s_retry_num < WIFI_MAX_RETRY) {
            esp_wifi_connect();
            s_retry_num++;
            ESP_LOGI(TAG, "retry connecting... (%d/%d)", s_retry_num, WIFI_MAX_RETRY);
        } else {
            xEventGroupSetBits(s_wifi_event_group, WIFI_FAIL_BIT);
        }
    } else 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, "got ip: " IPSTR, IP2STR(&event->ip_info.ip));
        s_retry_num = 0;
        xEventGroupSetBits(s_wifi_event_group, WIFI_CONNECTED_BIT);
    }
}

void wifi6_init_sta(void)
{
    s_wifi_event_group = xEventGroupCreate();

    ESP_ERROR_CHECK(esp_netif_init());
    ESP_ERROR_CHECK(esp_event_loop_create_default());
    esp_netif_create_default_wifi_sta();

    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
    ESP_ERROR_CHECK(esp_wifi_init(&cfg));

    esp_event_handler_instance_t instance_any_id;
    esp_event_handler_instance_t instance_got_ip;
    ESP_ERROR_CHECK(esp_event_handler_instance_register(WIFI_EVENT, ESP_EVENT_ANY_ID,
                    &event_handler, NULL, &instance_any_id));
    ESP_ERROR_CHECK(esp_event_handler_instance_register(IP_EVENT, IP_EVENT_STA_GOT_IP,
                    &event_handler, NULL, &instance_got_ip));

    wifi_config_t wifi_config = {
        .sta = {
            .ssid = WIFI_SSID,
            .password = WIFI_PASS,
            .threshold.authmode = WIFI_AUTH_WPA2_PSK,
            .sae_pwe_h2e = WPA3_SAE_PWE_BOTH,
        },
    };
    ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA));
    ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_STA, &wifi_config));
    ESP_ERROR_CHECK(esp_wifi_start());

    ESP_LOGI(TAG, "wifi6_init_sta finished. Connecting to %s", WIFI_SSID);

    EventBits_t bits = xEventGroupWaitBits(s_wifi_event_group,
            WIFI_CONNECTED_BIT | WIFI_FAIL_BIT,
            pdFALSE, pdFALSE, portMAX_DELAY);

    if (bits & WIFI_CONNECTED_BIT) {
        ESP_LOGI(TAG, "connected to WiFi 6 AP successfully");
    } else if (bits & WIFI_FAIL_BIT) {
        ESP_LOGE(TAG, "Failed to connect to AP after %d retries", WIFI_MAX_RETRY);
    }
}

void app_main(void)
{
    ESP_ERROR_CHECK(nvs_flash_init());
    wifi6_init_sta();
}

运行与验证

将代码中的 WIFI_SSID 和 WIFI_PASS 替换为你的 WiFi 6 路由器实际 SSID 和密码。
在项目根目录执行 idf.py set-target esp32s3 设置目标芯片，然后 idf.py build flash monitor 编译烧录并打开串口监视器（波特率 115200）。
观察串口输出日志。

通过判定标准：

日志中出现 wifi6_init_sta finished. Connecting to <你的SSID>，表示 Wi-Fi 初始化成功并开始连接。
随后出现 got ip: 192.168.x.x，表示已成功从路由器获取 IP 地址，连接建立完成。
若出现 connected to WiFi 6 AP successfully，则确认整个流程执行成功。

预期输出示例（实际 IP 取决于你的路由器分配）：

I (1234) wifi6_sta: wifi6_init_sta finished. Connecting to MyWiFi6
I (2345) wifi6_sta: got ip: 192.168.1.100
I (2345) wifi6_sta: connected to WiFi 6 AP successfully

常见问题

连接失败且持续重试：确认 SSID/密码正确，路由器工作在 2.4GHz 频段（ESP32-S3 不支持 5GHz WiFi 6）。
编译报错找不到 WPA3_SAE_PWE_BOTH：请升级 ESP-IDF 至 v5.1 或更高版本，该枚举在旧版本中不存在。
若路由器仅开启 WPA3 加密：代码中 threshold.authmode 可改为 WIFI_AUTH_WPA3_PSK，并保留 sae_pwe_h2e 设置以兼容 WPA3 连接。