开始前适用开发板：ESP32-S3 Korvo · 开发框架：ESP-IDF
适用开发板：Korvo S3 · 工程
02.beginner.wifi_scan· targetesp32s3
学习时长：约 15 分钟 · 难度：★☆☆☆☆
学习目标
完成本节后，你将能够：
- 理解 Wi-Fi 扫描的工作原理（STA 模式被动扫描）
- 掌握
esp_wifi_scan_start()系列 API 的使用 - 了解 RSSI、信道、加密方式等 AP 信息的含义
- 为后续 Wi-Fi 连接/配网例程打基础
1. 这个例子在干嘛
以 Wi-Fi STA 模式扫描周围所有热点，串口打印全部 AP 列表（SSID、RSSI、信道、加密方式），屏幕显示 AP 总数和信号最强的热点信息。不需要输入密码——只是"看看周围有什么网络"。
生活类比：手机打开 Wi-Fi 设置页，看到的那个列表。
┌──────────┐ 全信道扫描 ┌──────────┐ 结果显示 ┌──────────────┐
│ 周围 AP │────────────→│ ESP32-S3 │────────────→│ 屏幕 + 串口 │
│ 各频段广播 │ 被动接收 │ STA 模式 │ AP列表 │ SSID/RSSI │
└──────────┘ └──────────┘ └──────────────┘
2. 编译烧录
cd Korvo_Firmware\02.beginner.wifi_scan
idf.py set-target esp32s3
idf.py build flash monitor
无需 menuconfig 配置——扫描不需要密码或 SSID。
可选 menuconfig
| 选项 | 默认 | 说明 |
|---|---|---|
EXAMPLE_SCAN_LIST_SIZE | 10 | 最多记录多少个 AP（0~20） |
3. 运行现象
| 显示位置 | 内容 | 示例 |
|---|---|---|
| 屏幕第 1 行 | AP 总数 | AP found = 8 |
| 屏幕第 2 行 | 最强信号的 SSID | SSID: MyHome_5G |
| 屏幕第 3 行 | RSSI 和信道 | RSSI: -42, CH: 6 |
| 串口 | 全部 AP 详细列表 | SSID、RSSI、信道、加密方式 |
4. 关键文件与代码解析
| 文件 | 作用 | 重点 |
|---|---|---|
main/scan.c | 唯一源文件：扫描逻辑 + 显示 | 所有代码在这 |
main/Kconfig.projbuild | 扫描列表大小配置 | 可调整 |
核心流程
app_main()
├── ksdiy_example_display_bootstrap() // 初始化 SPI 屏 + LVGL
├── nvs_flash_init() // NVS（Wi-Fi 内部需要）
└── wifi_scan()
├── esp_netif_init() // 网络协议栈
├── esp_event_loop_create_default() // 事件循环
├── esp_netif_create_default_wifi_sta()
├── esp_wifi_init() + set_mode(STA) + start()
├── esp_wifi_scan_start(NULL, true) // 阻塞扫描全信道
├── esp_wifi_scan_get_ap_num() // 扫到多少个
├── esp_wifi_scan_get_ap_records() // 获取详细信息
└── 屏幕显示 + 串口打印
核心 API 说明
| API | 参数 | 说明 |
|---|---|---|
esp_wifi_scan_start(NULL, true) | NULL=默认配置, true=阻塞 | 扫描全部信道 |
esp_wifi_scan_get_ap_num(&count) | 输出: AP 数量 | 扫到几个 |
esp_wifi_scan_get_ap_records(&n, records) | 输出: AP 数组 | 详细信息 |
AP 信息结构体
wifi_ap_record_t {
uint8_t ssid[33] → 热点名
int8_t rssi → 信号强度（-30 极强，-90 很弱）
uint8_t primary → 主信道号
wifi_auth_mode_t authmode → 加密方式（OPEN/WPA2/WPA3...）
}
5. RSSI 信号强度参考
| RSSI 范围 | 信号质量 | 典型距离 |
|---|---|---|
| > -30 dBm | 极强 | < 1 米 |
| -30 ~ -50 | 很好 | 同一房间 |
| -50 ~ -70 | 一般 | 隔一堵墙 |
| -70 ~ -80 | 较弱 | 隔两堵墙 |
| < -80 dBm | 很弱 | 可能无法连接 |
6. 常见问题与排查
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 扫到 0 个 AP | 周围没有 2.4GHz 网络 | ESP32 只支持 2.4G |
| 扫到 0 个 AP | 天线问题 | 检查板载天线区域无遮挡 |
| 只扫到部分 | 扫描时间有限 | 增大列表或循环扫描 |
| 屏幕不显示 | 显示初始化失败 | 检查 SPI 屏连接 |
7. 动手改造建议
- 循环扫描：加
while(1)每 5 秒扫一次，观察 AP 变化 - 信号排序：按 RSSI 从强到弱排序后显示
- 信道分析：统计各信道的 AP 数量，找最不拥挤的信道
- 配网辅助：扫描结果 → 用户选择 → 输入密码 → 连接
8. 知识延伸
- STA 模式扫描不需要连接：Wi-Fi 芯片在各信道逐个监听 Beacon 帧，收集 AP 信息
- 扫描 vs 连接：
wifi_scan只是"看到"网络，wifi_station才是"连上"网络 - 2.4GHz vs 5GHz：ESP32-S3 只支持 2.4GHz（信道 1~13），看不到 5GHz 热点
- 隐藏 SSID：如果路由器设置了隐藏 SSID，扫描结果中 SSID 为空但其他信息正常
9. 下一步
| 方向 | 推荐例程 | 说明 |
|---|---|---|
| 连接网络 | Wi-Fi Station | 扫描后的下一步 |
| 开热点 | Wi-Fi SoftAP | 反过来让别人连 |
| P4C5 对比 | P4C5 wifi_scan | 通过 C5 协处理器扫描 |
酷世DIY · Kevincoooool