Scan 示例

[English]

示例说明

在 Wi-Fi 应用中，扫描用于获取周围可用的无线网络信息，是连接流程中的关键步骤。通过扫描，设备可以获取各个接入点（AP）的 SSID、BSSID、信号强度、信道及安全类型等信息，从而判断目标网络是否存在，并据此选择合适的热点连接。

该功能常用于 station 模式下的连接决策、信号强度评估、网络覆盖验证，以及调试网络配置等场景。同时，在多网络环境、漫游、室内定位或多设备协同等应用中，扫描也提供了必要的数据支持。

本示例展示如何在 ESP32 上以 Wi-Fi station 模式扫描周围可用的无线网络，适用于 Wi-Fi 网络环境评估、信道干扰分析和连接前的热点筛选等场景。

备注

扫描功能仅能在 station 模式或 station+AP 混合模式下使用。

运行方法

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

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

头文件说明

本示例所使用的头文件涵盖了 FreeRTOS 任务管理、Wi-Fi 协议栈、系统事件机制、日志输出、NVS 非易失性存储 以及 辅助功能接口 等基础模块，构建了 Wi-Fi 初始化、扫描控制、事件处理与信息输出的核心功能。

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

1. FreeRTOS 任务调度 ：提供基本任务调度、内存管理与事件组同步机制。

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

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

#include "esp_log.h"
#include "nvs_flash.h"

3. Wi-Fi 与事件机制 ：包含 Wi-Fi 启动与连接配置、事件循环注册及处理功能。

#include "esp_wifi.h"
#include "esp_event.h"

4. 辅助功能与标准库 ：提供基础字符串处理和正则表达式接口。

#include "regex.h"

备注

Wi-Fi 扫描功能不涉及网络连接与通信，仅依赖 Wi-Fi 驱动层。

宏定义说明

本示例中涉及的宏定义主要用于控制 Wi-Fi 扫描时的扫描结果数量与扫描信道范围，提升灵活性与配置适配性。

宏定义按功能分类如下：

1. 扫描列表大小 ：定义扫描结果数组的大小，表示最多可以存储多少个扫描到的接入点。默认为 10 个。

• 该宏通过 CONFIG_EXAMPLE_SCAN_LIST_SIZE 配置项定义，通常根据 menuconfig 设置自动生成，保存在 sdkconfig 文件中。

• DEFAULT_SCAN_LIST_SIZE 最大有效值为 64，实际应用中建议根据需求合理设置扫描列表大小，避免占用过多内存。

2. 信道位图 ：用于控制是否启用信道位图扫描方式，默认关闭。

• 信道位图是一种用“位”来表示多个信道状态的数据结构，常用于无线通信系统中，比如 Wi-Fi、蓝牙、Zigbee 等，以表示哪些信道是可用的、被占用的或被禁用的。

• 1 表示该信道可用，0 表示该信道不可用（或被禁用）。

• 通过定义 CONFIG_EXAMPLE_USE_SCAN_CHANNEL_BITMAP 可启用该功能。启用后，系统将使用用户预设的信道列表进行扫描，而非全频段扫描。

• 信道图开启后，USE_CHANNEL_BITMAP 宏作为内部标志，被设置为 1。此外，开启后还需指定：

  • CHANNEL_LIST_SIZE：设置信道列表大小，即定义扫描多少个信道，默认为 3。

  • 静态数组 channel_list：用于保存预设的扫描信道列表，默认为 {1, 6, 11}，即常用的 2.4GHz Wi-Fi 信道。

3. 信道位图转换接口：若启用了信道位图功能，将自动启用 array_2_channel_bitmap() 函数及其对应宏块。

备注

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

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

功能函数说明

本示例通过 wifi_scan() 函数实现 ESP32 主动扫描周围 Wi-Fi 网络，并通过辅助函数 array_2_channel_bitmap()、print_auth_mode() 与 print_cipher_type() 完成信道控制及扫描结果信息的分类输出。

其中，wifi_scan() 负责初始化 Wi-Fi 驱动、配置扫描参数、发起扫描请求并输出扫描结果，是扫描流程的核心执行入口；array_2_channel_bitmap() 在启用信道位图功能时，将用户设定的信道数组转换为位图形式，用于精确控制扫描信道；print_auth_mode() 和 print_cipher_type() 分别用于打印每个接入点的认证方式和加密类型，帮助用户识别不同网络的安全属性。

各函数协同工作，构建了 Wi-Fi 扫描功能的完整流程，实现了信道控制、结果提取与参数解读的自动化处理。

print_auth_mode()

该函数主要用于调试和扫描结果展示，帮助用户直观了解周围 Wi-Fi 网络的安全配置，但它们本身不参与安全设置或连接流程。

参数解释

传入参数	参数功能	参数说明
authmode	接入点认证模式枚举。	类型为 wifi_auth_mode_t，表示扫描结果中每个接入点的认证类型。

print_auth_mode() 函数根据扫描结果中接入点的认证模式枚举值，打印对应的认证类型信息至串口终端，辅助用户识别 Wi-Fi 网络的安全类型（如 WPA2/WPA3 等）。

print_cipher_type()

该函数主要用于调试和扫描结果展示，帮助用户直观了解周围 Wi-Fi 网络的安全配置，但它们本身不参与安全设置或连接流程。

参数解释

传入参数	参数功能	参数说明
pairwise_cipher	Wi-Fi 接入点用于单播通信的加密类型。	类型为 wifi_cipher_type_t，表示单播加密类型的枚举值。
group_cipher	Wi-Fi 接入点用于单播通信的加密类型。	类型为 wifi_cipher_type_t，表示组播加密类型的枚举值。

备注

虽然参数类型是枚举类型，但底层实际上以整数传递，注意避免手动赋值错误导致打印异常。

Wi-Fi 接入点分别通过单播加密和组播加密，保护点对点通信和广播或组播数据的安全。print_cipher_type() 用于识别并打印 Wi-Fi 接入点使用的两类加密算法，帮助了解接入点采用的加密策略。

array_2_channel_bitmap()

参数解释

传入参数	参数功能	参数说明
channel_list[]	信道数组	用于存储待转换的信道号列表。
channel_list_size	信道数组长度	信道数组中信道的数量。
scan_config	扫描配置结构体指针	指向需设置信道位图的 wifi_scan_config_t 结构体。

该函数用于将指定的信道数组转换成 Wi-Fi 扫描配置结构体中的信道位图，用于限定扫描的信道范围，优化扫描效率。

需要注意，该函数仅在宏 USE_CHANNEL_BITMAP 被定义时编译启用。

wifi_scan()

扫描模式初始化主要分为两个部分：初始化 Wi-Fi 并将其配置为 station 模式，设置扫描模式。

完整 station 模式初始化步骤可参考 station 示例 文档，对于重复内容此处不再赘述，仅重点说明本示例中的关键实现与差异部分。

1. station 模式配置：

• 在仅使用扫描功能而不连接特定接入点的情况下，只需要执行 初始化阶段，配置阶段 及 启动阶段。

• 在配置阶段，无需通过 wifi_config_t 结构体配置连接参数（如 SSID 和密码），也无需调用 esp_wifi_set_config() 应用这些参数。

2. 初始化结果缓存区：定义一些变量，用于后续存储扫描到的 AP 信息。

• number：表示期望获取的扫描结果数量，初始值为 扫描列表大小 DEFAULT_SCAN_LIST_SIZE。

• ap_info[]：用于存储扫描到的每个 AP 的详细信息（如 SSID、信号强度、加密类型等）。数组类型为 wifi_ap_record_t，大小为 DEFAULT_SCAN_LIST_SIZE。完整的包含的信息列表请参考 Wi-Fi 库。

• ap_count：用于存储最终扫描到的 AP 数量。该值会在扫描结果处理阶段被赋值。

• 调用 memset() 将 ap_info 数组的所有字节清零，确保结构体内的所有字段初始值为 0，避免读取到未初始化的垃圾数据。

3. 选择 Wi-Fi 扫描方式：该部分根据是否定义了 USE_CHANNEL_BITMAP 宏，执行两种不同的扫描策略：

• 若启用信道位图：

  • 动态申请并初始化一个 wifi_scan_config_t 配置结构体。

  • 调用 array_2_channel_bitmap() 函数，将指定信道列表转换为位图填入配置中，限定只扫描这些信道。

  • 调用 esp_wifi_scan_start() 发起定制化扫描。

  • 扫描完成后释放动态分配的内存，防止内存泄漏。

• 若不启用信道位图：

  • 调用 esp_wifi_scan_start() 使用默认配置（传入 NULL）启动全信道扫描。

• esp_wifi_scan_start() 用于启动一次 Wi-Fi 扫描，获取周围可用接入点信息，支持配置参数和阻塞方式。返回值表示执行结果。更多参数说明请参考 Wi-Fi 库。

4. 获取相关信息并打印：

• 调用 esp_wifi_scan_get_ap_num() 获取本次扫描发现的接入点总数，存入 ap_count 中。更多参数说明请参考 Wi-Fi 库。

• 调用 esp_wifi_scan_get_ap_records() 将最多 number 条接入点信息写入 ap_info 数组，并更新 number 为实际获取的数量。更多参数说明请参考 Wi-Fi 库。

• 遍历 ap_info，依次获取并输出每个接入点的以下信息：

  • SSID

  • RSSI

  • 认证类型（调用 print_auth_mode）

  • 加密算法（调用 print_cipher_type）

备注

RSSI（接收信号强度指示）用于表示 Wi-Fi 模块接收到的信号强度，单位为 dBm，数值越接近 0 表示信号越强（如 -40 dBm），数值越小则信号越弱（如 -85 dBm），常用于评估接入点信号质量和连接稳定性。

主函数说明

该函数作为程序入口函数，用于完成非易失性存储（NVS）初始化，并启动 Wi-Fi 扫描功能，为后续获取周围可用无线网络信息提供基础环境。

其函数内实现步骤如下：

1. 初始化 NVS

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

3. 启动 Wi-Fi 初始化：调用 wifi_scan() 完成网络接口配置、事件注册、Wi-Fi 参数设置及驱动启动，使 ESP32 进入可执行无线网络扫描的工作状态。