ESP Wi-Fi 扫描入门

1 前言

在使用 Wi-Fi 功能时，我们的操作往往是打开手机上的 Wi-Fi 设备，搜索到想要连接的热点，输入密码，联网成功，其实这个过程是有对应的专业术语的，分别是：扫描（Scanning）、认证（Authentication）、关联（Association）。下面用一张图来表示这个过程。

2 扫描目的

扫描主要是找到一个无线网络，然后加入到该网络中。

3 扫描方式

ESP Wi-Fi 有以下几种扫描方式：

模式	描述
主动扫描	通过发送 probe request 进行扫描。该模式为默认的扫描模式。
被动扫描	不发送 probe request。跳至某一特定信道并等待 beacon。应用程序可通过 wifi_scan_config_t 中的 scan_type 字段使能被动扫描。
快速扫描	在这种模式下，扫描在检测到匹配的 AP 后立即完成，即使通道没有被完全扫描到。你可以设置信号强度的阈值，以及选择由 AP 提供的所需的认证模式。Wi-Fi 驱动程序将忽略不符合所述标准的 AP。
全信道扫描	只有在扫描完所有通道后，扫描才会结束；Wi-Fi 驱动程序将存储 4 个完全匹配的 AP。对 AP 的排序方法包括 rssi 和 authmode。扫描后，Wi-Fi 驱动会根据排序选择最适合的 AP。
特定信道扫描	仅扫描特定的信道。wifi_scan_config_t 中的 channel 字段为 1-14 时，当前模式为特定信道扫描。
前端扫描	在 station 模式下 Wi-Fi 未连接时，可进行前端扫描。Wi-Fi 驱动程序决定进行前端扫描还是后端扫描，应用程序无法配置这两种模式。
后端扫描	在 station 模式或 station/AP 共存模式下 Wi-Fi 已连接时，可进行后端扫描。Wi-Fi 驱动程序决定进行前端扫描还是后端扫描，应用程序无法配置这两种模式。

4. 如何使用相关 API

4.1 初始化 Wi-Fi 环境

首先，Wi-Fi 子系统的初始化需要由我们自己来自行，当我们写自己的程序时，需要通过调用 esp_wifi_init（&config）方法来完成。

ESP_ERROR_CHECK(esp_netif_init());
ESP_ERROR_CHECK(esp_event_loop_create_default());esp_netif_t *sta_netif = esp_netif_create_default_wifi_sta();assert(sta_netif);wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();ESP_ERROR_CHECK(esp_wifi_init(&cfg));

4.2 设置操作模式

可以调用函数 esp_wifi_set_mode() 来设定，扫描需要在 station 或者 station/softap 共存模式下完成，同时，我们也可以调用 esp_wifi_get_mode() 来检索我们目前的模式。

ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA));

4.3 开始扫描

ESP_ERROR_CHECK(esp_wifi_start());
esp_wifi_scan_start(NULL, true);

调用 esp_wifi_scan_start(const wifi_scan_config_t *config, bool block) 函数来完成 Wi-Fi 扫描功能，同时也可以调用该接口设置扫描类型与其他扫描属性，下表详细描述了结构体 wifi_scan_config_t 各字段信息。

字段	字段
ssid	如果该字段的值不为 NULL，则仅可扫描到具有相同 SSID 值的 AP
bssid	如果该字段的值不为 NULL，则仅可扫描到具有相同 BSSID 值的 AP
channel	如果该字段值为 0，将进行全信道扫描；反之，将针对特定信道进行扫描。
show_hidden	如果该字段值为 0，本次扫描将忽略具有隐藏 SSID 的 AP；反之，这些 AP 也会在扫描时被视为正常 AP
scan_type	如果该字段值为为 WIFI_SCAN_TYPE_ACTIVE，则本次扫描为主动扫描；反之，将被视为被动扫描。
scan_time	该字段用于控制每个信道的扫描时间。被动扫描时，scan_time.passive 字段负责为每个信道指定扫描时间。主动扫描时，每个信道的扫描时间如下列表所示。其中，min 代表 scan_time_active_min，max 代表 scan_time_active_max。 min=0, max=0：每个信道的扫描时间为 120 ms。 min>0, max=0：每个信道的扫描时间为 120 ms。 min=0, max>0：每个信道的扫描时间为 max ms。 min>0, max>0：每个信道扫描的最短时间为 min ms。如果在这段时间内未找到 AP，将跳转至下一个信道。如这段时间内找到 AP，则该信道的扫描时间为 max ms。如希望提升 Wi-Fi 扫描性能，则可修改上述两个参数。

4.4 查看扫描结果

在发出开始执行扫描的请求后，我们将被通知扫描，当 SYSTEM_EVENT_SCAN_DONE 事件发布完成，我们就认为扫描完成。

Wi-Fi 扫描结束后，扫描的结果会存储在 ESP32 分配的动态存储器内部,当我们调用 esp_wifi_scan_get_ap_records(uint16_t *number, wifi_ap_record_t *ap_records) 时，会返回所存储的 ap 信息，这时也会释放内部分配的存储。

扫描记录包含在包含 wifi_ap_record_t 结构的一个示例，如下所示：

/** @brief Description of a WiFi AP */
typedef struct {uint8_t bssid[6];                     /**< MAC address of AP */uint8_t ssid[33];                     /**< SSID of AP */uint8_t primary;                      /**< channel of AP */wifi_second_chan_t second;            /**< secondary channel of AP */int8_t  rssi;                         /**< signal strength of AP */wifi_auth_mode_t authmode;            /**< authmode of AP */wifi_cipher_type_t pairwise_cipher;   /**< pairwise cipher of AP */wifi_cipher_type_t group_cipher;      /**< group cipher of AP */wifi_ant_t ant;                       /**< antenna used to receive beacon from AP */uint32_t phy_11b:1;                   /**< bit: 0 flag to identify if 11b mode is enabled or not */uint32_t phy_11g:1;                   /**< bit: 1 flag to identify if 11g mode is enabled or not */uint32_t phy_11n:1;                   /**< bit: 2 flag to identify if 11n mode is enabled or not */uint32_t phy_lr:1;                    /**< bit: 3 flag to identify if low rate is enabled or not */uint32_t wps:1;                       /**< bit: 4 flag to identify if WPS is supported or not */uint32_t ftm_responder:1;             /**< bit: 5 flag to identify if FTM is supported in responder mode */uint32_t ftm_initiator:1;             /**< bit: 6 flag to identify if FTM is supported in initiator mode */uint32_t reserved:25;                 /**< bit: 7..31 reserved */wifi_country_t country;               /**< country information of AP */
} wifi_ap_record_t;

如果我们希望在完成扫描之前自行取消扫描，我们可以调用 esp_wifi_scan_stop() 。

ap 扫描的个数可以通过 ESP_ERROR_CHECK(esp_wifi_scan_get_ap_num(&ap_count)) 接口获取。

4.5 参考示例

1） scan 示例

可以在 menuconfig 中设置保存 ap 的数据，默认设置 10 个，最大支持到 20 个。

idf.py menuconfig---->Example Configuration---->(10)Max size of scan list

运行结果如下：


I (636) wifi_init: rx ba win: 6
I (636) wifi_init: tcpip mbox: 32
I (646) wifi_init: udp mbox: 6
I (646) wifi_init: tcp mbox: 6
I (646) wifi_init: tcp tx win: 5744
I (656) wifi_init: tcp rx win: 5744
I (656) wifi_init: tcp mss: 1440
I (666) wifi_init: WiFi IRAM OP enabled
I (666) wifi_init: WiFi RX IRAM OP enabled
I (676) phy_init: phy_version 4670,719f9f6,Feb 18 2021,17:07:07
I (786) wifi:mode : sta (30:ae:a4:10:85:60)
I (786) wifi:enable tsf
I (2886) scan: Total APs scanned = 72
I (2886) scan: SSID         iot
I (2886) scan: RSSI         -25
I (2886) scan: Authmode     WIFI_AUTH_WPA2_PSK
I (2886) scan: Pairwise Cipher  WIFI_CIPHER_TYPE_CCMP
I (2896) scan: Group Cipher     WIFI_CIPHER_TYPE_CCMP
I (2896) scan: Channel      1I (2906) scan: SSID        cc2.4
I (2906) scan: RSSI         -26
I (2906) scan: Authmode     WIFI_AUTH_WPA_WPA2_PSK
I (2916) scan: Pairwise Cipher  WIFI_CIPHER_TYPE_CCMP
I (2916) scan: Group Cipher     WIFI_CIPHER_TYPE_CCMP
I (2926) scan: Channel      1I (2926) scan: SSID        MERCURY_C6D4
I (2936) scan: RSSI         -37
I (2936) scan: Authmode     WIFI_AUTH_WPA_WPA2_PSK
I (2946) scan: Pairwise Cipher  WIFI_CIPHER_TYPE_CCMP
I (2946) scan: Group Cipher     WIFI_CIPHER_TYPE_CCMP
I (2956) scan: Channel      1I (2956) scan: SSID        Huawei-jyf
I (2956) scan: RSSI         -38
I (2966) scan: Authmode     WIFI_AUTH_WPA_WPA2_PSK
I (2966) scan: Pairwise Cipher  WIFI_CIPHER_TYPE_CCMP
I (2976) scan: Group Cipher     WIFI_CIPHER_TYPE_CCMP
I (2976) scan: Channel      5I (2986) scan: SSID        cgh
I (2986) scan: RSSI         -41
I (2986) scan: Authmode     WIFI_AUTH_WPA_WPA2_PSK
I (2996) scan: Pairwise Cipher  WIFI_CIPHER_TYPE_CCMP
I (2996) scan: Group Cipher     WIFI_CIPHER_TYPE_CCMP
I (3006) scan: Channel      11I (3006) scan: SSID       myssid
I (3016) scan: RSSI         -45
I (3016) scan: Authmode     WIFI_AUTH_WPA2_PSK
I (3026) scan: Pairwise Cipher  WIFI_CIPHER_TYPE_CCMP
I (3026) scan: Group Cipher     WIFI_CIPHER_TYPE_CCMP
I (3036) scan: Channel      7I (3036) scan: SSID        xiaomi_2.4g
I (3036) scan: RSSI         -46
I (3046) scan: Authmode     WIFI_AUTH_OPEN
I (3046) scan: Pairwise Cipher  WIFI_CIPHER_TYPE_NONE
I (3056) scan: Group Cipher     WIFI_CIPHER_TYPE_NONE
I (3056) scan: Channel      2I (3066) scan: SSID        myap
I (3066) scan: RSSI         -49
I (3066) scan: Authmode     WIFI_AUTH_WPA_WPA2_PSK
I (3076) scan: Pairwise Cipher  WIFI_CIPHER_TYPE_CCMP
I (3076) scan: Group Cipher     WIFI_CIPHER_TYPE_TKIP
I (3086) scan: Channel      11I (3086) scan: SSID       394
I (3096) scan: RSSI         -51
I (3096) scan: Authmode     WIFI_AUTH_OPEN
I (3096) scan: Pairwise Cipher  WIFI_CIPHER_TYPE_NONE
I (3106) scan: Group Cipher     WIFI_CIPHER_TYPE_NONE
I (3116) scan: Channel      5I (3116) scan: SSID        TL-XDR1860_1
I (3116) scan: RSSI         -52
I (3126) scan: Authmode     WIFI_AUTH_WPA_WPA2_PSK
I (3126) scan: Pairwise Cipher  WIFI_CIPHER_TYPE_CCMP
I (3136) scan: Group Cipher     WIFI_CIPHER_TYPE_CCMP
I (3136) scan: Channel      5

2） fast scan 示例

可以在 menuconfig 中配置快速扫描或者全信道扫描方式。

idf.py menuconfig---->Example Configuration---->[*]fast scan threshold

快速扫描运行结果如下：

I (635) wifi_init: rx ba win: 6
I (635) wifi_init: tcpip mbox: 32
I (645) wifi_init: udp mbox: 6
I (645) wifi_init: tcp mbox: 6
I (645) wifi_init: tcp tx win: 5744
I (655) wifi_init: tcp rx win: 5744
I (655) wifi_init: tcp mss: 1440
I (665) wifi_init: WiFi IRAM OP enabled
I (665) wifi_init: WiFi RX IRAM OP enabled
I (765) phy_init: phy_version 4670,719f9f6,Feb 18 2021,17:07:07
I (865) wifi:mode : sta (30:ae:a4:10:85:60)
I (865) wifi:enable tsf
I (875) wifi:new:<1,0>, old:<1,0>, ap:<255,255>, sta:<1,0>, prof:8
I (1645) wifi:state: init -> auth (b0)
I (1695) wifi:state: auth -> assoc (0)
I (1725) wifi:state: assoc -> run (10)
I (3795) wifi:connected with iot, aid = 58, channel 1, BW20, bssid = 30:a2:c2:70:27:88
I (3795) wifi:security: WPA2-PSK, phy: bgn, rssi: -25
I (3815) wifi:pm start, type: 1I (3815) wifi:AP's beacon interval = 102400 us, DTIM period = 1
I (4565) scan: got ip:192.168.3.17
I (4565) esp_netif_handlers: sta ip: 192.168.3.17, mask: 255.255.255.0, gw: 192.168.3.1

全信道扫描

I (786) wifi:mode : sta (30:ae:a4:10:85:60)
I (796) wifi:enable tsf
I (806) wifi:new:<1,0>, old:<1,0>, ap:<255,255>, sta:<1,0>, prof:8
I (806) wifi:state: init -> auth (b0)
I (826) wifi:state: auth -> assoc (0)
I (826) wifi:state: assoc -> init (3a0)
I (826) wifi:new:<1,0>, old:<1,0>, ap:<255,255>, sta:<1,0>, prof:8
I (2886) wifi:new:<1,0>, old:<1,0>, ap:<255,255>, sta:<1,0>, prof:8
I (2886) wifi:state: init -> auth (b0)
I (2896) wifi:state: auth -> assoc (0)
I (2906) wifi:state: assoc -> run (10)
I (3006) wifi:connected with iot, aid = 60, channel 1, BW20, bssid = 30:a2:c2:70:27:88
I (3006) wifi:security: WPA2-PSK, phy: bgn, rssi: -25
I (3006) wifi:pm start, type: 1I (3076) wifi:AP's beacon interval = 102400 us, DTIM period = 1
I (4066) scan: got ip:192.168.3.17
I (4066) esp_netif_handlers: sta ip: 192.168.3.17, mask: 255.255.255.0, gw: 192.168.3.1

优缺点对比

优点：快速扫描连接时间会缩短 1 s 左右

缺点：如果有同名的 SSID 和 PASSWORD ，这种情况下连接的不一定是最优的 AP ，但全信道扫描连接的 AP 一定是最优的。