开始前适用开发板：ESP32-S3 Korvo · 开发框架：ESP-IDF
适用开发板：ESP32-S3 Korvo 2 V3
工程：Korvo_Firmware/02.beginner.wifi_station
target：esp32s3
学习时长：约 20 分钟 · 难度：★★☆☆☆
Wi-Fi 在 S3 芯片内置，上电后可直接连路由器，无需协处理器。
API 概念：WiFi使用教程
学习目标
完成本节后，你将能够：
- 理解 ESP-IDF 的 事件驱动 Wi-Fi 编程模型
- 掌握 Station 模式的完整连接流程
- 学会通过 menuconfig 配置 Wi-Fi 参数
- 为后续 HTTP/MQTT/OTA 等网络例程打好基础
1. 这个例子在干嘛
这是 Korvo 所有网络例程的 起点——连接 Wi-Fi 路由器并获取 IP 地址。
成功后，你的 ESP32-S3 就像一台电脑连上了 Wi-Fi 一样，可以访问互联网、接收远程命令、上传传感器数据。
运行效果：
| 显示位置 | 内容 |
|---|---|
| 屏幕第 1 行 | 连接的 SSID 名称 |
| 屏幕第 2 行 | 获取到的 IP 地址 |
| 屏幕第 3 行 | 重试次数 |
| 串口 | 完整事件日志（CONNECTING → GOT_IP） |
2. 编译烧录
cd Korvo_Firmware\02.beginner.wifi_station
idf.py set-target esp32s3
idf.py menuconfig # 必须配置 Wi-Fi 信息！
idf.py build flash monitor
日常用 左 USB（CH9102） 下载与查看 log。
3. menuconfig 配置详解
进入 menuconfig 后找到 Example Configuration：
| 选项 | 说明 | 示例 |
|---|---|---|
ESP_WIFI_SSID | 路由器 Wi-Fi 名称 | MyHome_2.4G |
ESP_WIFI_PASSWORD | Wi-Fi 密码 | 12345678 |
ESP_MAXIMUM_RETRY | 最大重连次数 | 默认 5，可改大 |
重要提醒：
- 必须是 2.4GHz 网络，ESP32-S3 不支持 5GHz
- SSID 和密码 区分大小写
- 修改 menuconfig 后必须重新
build才生效
4. 核心流程详解
4.1 事件驱动模型
ESP-IDF 的 Wi-Fi 不是「调一个函数等连接」这种阻塞模式，而是 事件驱动——你注册回调，系统在不同阶段通知你。
app_main
│
├── nvs_flash_init() // Wi-Fi 需要 NVS 存储 RF 校准数据
├── esp_netif_init() // 初始化网络接口
├── esp_event_loop_create() // 创建事件循环
├── esp_netif_create_default_wifi_sta() // 创建 STA 网络接口
├── esp_wifi_init() // 初始化 Wi-Fi 驱动
│
├── 注册事件回调 ──────────────────────────────────────┐
│ ├── WIFI_EVENT_STA_START → esp_wifi_connect()│
│ ├── WIFI_EVENT_STA_DISCONNECTED → 重连或放弃 │
│ └── IP_EVENT_STA_GOT_IP → 连接成功！ │
│ │
├── esp_wifi_set_config() // 设置 SSID/密码 │
└── esp_wifi_start() // 启动 → 触发 STA_START│
↓
事件循环在后台持续运行
4.2 事件流程图
esp_wifi_start()
│
▼
STA_START ──→ esp_wifi_connect()
│
▼
┌─ 连接成功 ─→ GOT_IP ──→ 显示 IP，开始工作
│
└─ 连接失败 ─→ DISCONNECTED
│
├─ retry < max → 重连（回到 connect）
│
└─ retry >= max → 放弃，屏幕显示失败
核心教训：绝对不要写
while(!connected) { delay(1000); }这种阻塞循环等连接——这是初学者最常犯的错误。事件模型是异步的，你的 app 继续做其他事，连接成功时系统会通知你。
5. 关键文件与代码解析
| 文件 | 作用 | 重点关注 |
|---|---|---|
main/station_example_main.c | 全部 Wi-Fi 逻辑 | 事件回调函数 |
main/Kconfig.projbuild | menuconfig 选项定义 | SSID/密码/重试次数 |
components/ksdiy_example_display | 屏幕 UI 显示 | 状态更新函数 |
事件回调关键代码（伪代码）
static void event_handler(void* arg, esp_event_base_t event_base, ...)
{
if (event_base == WIFI_EVENT) {
if (event_id == STA_START) {
esp_wifi_connect(); // 开始连接
} else if (event_id == DISCONNECTED) {
if (retry_num < max_retry) {
esp_wifi_connect(); // 重连
retry_num++;
屏幕显示("重试第 %d 次", retry_num);
} else {
屏幕显示("连接失败");
}
}
} else if (event_base == IP_EVENT) {
if (event_id == GOT_IP) {
ip_info = event_data;
屏幕显示("IP: %s", ip_info->ip);
retry_num = 0; // 清零重试
}
}
}
6. 常见问题与排查
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 一直 retry 到上限 | SSID/密码错误 | 仔细核对，注意大小写和空格 |
| 一直 retry 到上限 | 路由器是 5GHz | 切换到 2.4GHz 频段 |
| 一直 retry 到上限 | 路由器隐藏了 SSID | 关闭隐藏 SSID 或使用 BSSID 连接 |
| 连上但无 IP | 路由器 DHCP 池满 | 重启路由器或扩大 DHCP 范围 |
| 连上但无 IP | MAC 地址过滤 | 路由器白名单中添加 S3 MAC |
| 改了 SSID 无效 | 没重新编译 | menuconfig 保存后必须 idf.py build flash |
| 串口无任何输出 | USB 线接错 | 用左侧 CH9102 UART 口 |
7. 动手改造建议
- 显示信号强度：连接成功后调用
esp_wifi_sta_get_ap_info()获取 RSSI 并显示在屏幕 - Wi-Fi 扫描：参考同仓库
02.beginner.wifi_scan，先扫描再连接 - 断线自动重连：把
max_retry改成无限（while(1)重连），加退避延时 - 多 AP 漫游：存储多组 SSID，第一个连不上自动试第二个
8. 知识延伸
- NVS 为什么必须初始化？ Wi-Fi 驱动会将 RF 校准参数写入 NVS Flash，跳过 NVS 初始化会导致 Wi-Fi 启动失败
- STA vs AP 模式：STA 是连别人（本例），AP 是让别人连自己。也可以同时开（STA+AP 共存）
- Korvo vs P4C5 的 Wi-Fi 差异：S3 芯片内置 Wi-Fi，直接
esp_wifi_connect()；P4 没有 Wi-Fi，需要通过 C5 协处理器转发，所以 P4C5 的 Wi-Fi 初始化要多等待 C5 启动 - IPv4 vs IPv6：
GOT_IP事件返回 IPv4 地址；ESP-IDF 也支持 IPv6，但本例使用 IPv4
9. 下一步
本例是网络类例程的起点，掌握后可以进入以下方向：
| 方向 | 推荐例程 | 说明 |
|---|---|---|
| Wi-Fi 扫描 | 02.beginner.wifi_scan | 列出周围所有 AP |
| HTTP 服务器 | HTTP Server | 板子变成 Web 服务器 |
| MQTT 通信 | MQTT | 物联网消息通信 |
| OTA 升级 | OTA | 远程更新固件 |
| 蓝牙配网 | BluFi | 手机蓝牙配网（无需硬编码 SSID） |
酷世DIY · Kevincoooool