开始前适用开发板：ESP32-S3 Korvo · 开发框架：ESP-IDF
适用开发板：Korvo S3 · 工程
02.beginner.wifi_softap· targetesp32s3
学习时长：约 20 分钟 · 难度：★★☆☆☆
学习目标
完成本节后，你将能够：
- 理解 SoftAP（软件热点）模式的工作原理
- 区分 STA 模式（连别人的网络）和 AP 模式（让别人连自己）
- 掌握事件驱动的客户端连入/断开处理
- 了解 AP 配网的基础原理
1. 这个例子在干嘛
把 ESP32-S3 变成一个 Wi-Fi 热点，手机/电脑可以搜索到并连接。屏幕实时显示热点名、IP、信道、已连接设备数。
生活类比：手机开热点给电脑用——ESP32 也可以开热点给其他设备连。
┌──────────┐ ┌──────────┐ 搜索/连接 ┌──────────┐
│ ESP32-S3 │ 广播 SSID │ 周围设备 │────────────→│ 已连接 │
│ AP 模式 │←────────────│ 手机/PC │ │ 192.168. │
│ 192.168. │ │ │ │ 4.x │
│ 4.1 │ │ │ │ │
└──────────┘ └──────────┘ └──────────┘
应用场景：
- AP 配网：配合 HTTP Server 做 Web 配置页面（用户连 AP → 打开网页 → 输入 Wi-Fi 密码）
- 本地通信：无路由器时，设备间直接通信
- 传感器网关：多个设备连到 ESP32 AP 汇聚数据
2. 编译烧录
cd Korvo_Firmware\02.beginner.wifi_softap
idf.py set-target esp32s3
idf.py menuconfig # 可改热点名/密码/信道/最大连接数
idf.py build flash monitor
menuconfig 选项
| 选项 | 默认值 | 说明 |
|---|---|---|
ESP_WIFI_SSID | myssid | 热点名称 |
ESP_WIFI_PASSWORD | mypassword | 密码（空则开放网络） |
ESP_WIFI_CHANNEL | 1 | 信道（1~13） |
ESP_MAX_STA_CONN | 4 | 最大同时连接数 |
ESP_GTK_REKEYING_ENABLE | y | GTK 重密钥（安全） |
ESP_GTK_REKEY_INTERVAL | 600 | 重密钥间隔（秒） |
3. 使用步骤
- 烧录后屏幕显示热点信息（SSID/信道/IP）
- 手机 Wi-Fi 设置中搜索开发板热点名（如
myssid） - 输入密码连接
- 连接后设备 IP 为
192.168.4.1（网关） - 屏幕更新已连接设备数
- 断开 → 屏幕数字减少
4. 运行现象
| 阶段 | 屏幕 | 串口 |
|---|---|---|
| 启动 | SSID/信道/IP 显示 | wifi_init_softap finished |
| 手机连入 | 连接数 +1 | station xx:xx:xx:xx join, AID=1 |
| 手机断开 | 连接数 -1 | station xx:xx:xx:xx leave, AID=1 |
5. 关键文件与代码解析
| 文件 | 作用 | 重点 |
|---|---|---|
main/softap_example_main.c | 核心：AP 配置 + 事件处理 | 所有逻辑 |
main/Kconfig.projbuild | 热点参数配置 | SSID/密码/信道 |
核心流程
app_main()
├── ksdiy_example_display_bootstrap()
├── nvs_flash_init()
└── wifi_init_softap()
├── esp_netif_create_default_wifi_ap()
├── esp_event_handler_instance_register(WIFI_EVENT, ...)
├── wifi_config.ap = { ssid, password, channel, max_connection, authmode }
├── esp_wifi_set_mode(WIFI_MODE_AP)
├── esp_wifi_set_config(WIFI_IF_AP, &wifi_config)
├── esp_wifi_start()
└── refresh_softap_ip() → 显示 192.168.4.1
主循环: while(true) 每 5 秒刷新 IP 与连接数显示
事件处理
wifi_event_handler(WIFI_EVENT_AP_STACONNECTED)
→ wifi_event_ap_staconnected_t → 打印 MAC + AID
→ s_sta_count++
→ update_softap_display()
wifi_event_handler(WIFI_EVENT_AP_STADISCONNECTED)
→ s_sta_count--
→ update_softap_display()
6. STA 模式 vs AP 模式对比
| 对比 | STA 模式（wifi_station） | AP 模式（wifi_softap） |
|---|---|---|
| 角色 | 客户端 | 服务端 |
| 谁连谁 | ESP32 连路由器 | 手机连 ESP32 |
| IP 分配 | 路由器 DHCP 分配 | ESP32 DHCP 分配 |
| 默认 IP | 动态 | 固定 192.168.4.1 |
| 互联网 | 有（通过路由器） | 无（仅局域网） |
| 用途 | 联网/云端 | 配网/本地控制 |
7. 常见问题与排查
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 手机搜不到 | 热点名/密码错误 | menuconfig 确认 |
| 手机搜不到 | 密码少于 8 位 | 补足或设为空（Open） |
| 连上无法上网 | AP 模式不提供互联网 | 正常现象 |
| IP 冲突 | 家庭网段也是 192.168.4.x | 修改 AP 子网或关闭家庭 Wi-Fi |
| 最多 4 个设备 | MAX_STA_CONN 默认 4 | menuconfig 中增大 |
8. 动手改造建议
- AP + HTTP Server：配合
http_server例程做 Web 配网页面 - AP + STA 共存：
WIFI_MODE_APSTA同时连路由器和开热点 - 修改 DHCP 网段：从
192.168.4.x改为其他网段 - 客户端信息展示：在屏幕上显示已连接设备的 MAC 地址
9. 知识延伸
- DHCP Server：AP 模式下 ESP32 自动运行 DHCP 服务器，给连入设备分配 IP
- Beacon 帧：AP 每 100ms 广播一次 Beacon，包含 SSID、信道、加密方式
- WPA2 vs WPA3：IDF 5.x 支持 WPA3-SAE，更安全但部分旧设备不兼容
- AP 容量：ESP32-S3 最多支持 15 个并发 STA 连接
10. 下一步
| 方向 | 推荐例程 | 说明 |
|---|---|---|
| Wi-Fi 连接 | Wi-Fi Station | STA 模式连路由器 |
| HTTP 服务 | HTTP Server | AP + HTTP = Web 配网 |
| BLE 配网 | BluFi | 蓝牙方式配网 |
| P4C5 对比 | P4C5 SoftAP | 通过 C5 开热点 |
酷世DIY · Kevincoooool