ESP8266 Arduino Core Wi-Fi 扫描实战：scanNetworks 同步与异步模式完整指南

ESP8266 Arduino Core Wi-Fi 扫描实战scanNetworks 同步与异步模式完整指南【免费下载链接】ArduinoESP8266 core for Arduino项目地址: https://gitcode.com/gh_mirrors/ard/Arduino本篇指南以 Arduino 官方文档 scan-examples.rst 为主线系统讲解在 ESP8266 Arduino Core 中如何使用 Scan Class 扫描周边 Wi-Fi 网络从最简同步扫描开始再到不阻塞主流程的异步扫描配合 LED 闪烁演示并深入 Scan Class API 与 ESP8266WiFiScan.cpp 源码实现让你既能直接复制可运行代码也能理解扫描背后的状态机与 SDK 回调机制最终能够在自己项目中按需选择同步、异步或回调式扫描方案。一、为什么需要手动扫描先断开再扫描手机连接热点时通常要打开 Wi-Fi 设置、列出可用网络、再选择目标热点。ESP8266 也可以做到同样的事——通过 Scan Class 的 API 列出周围可用的无线网络。扫描前有一个容易被忽略的前提先让模块进入 station 模式并主动断开连接。原因在于模块可能用之前保存的凭据自动连上某个接入点如果不先断开扫描行为可能与已有连接互相干扰。WiFi.mode(WIFI_STA); WiFi.disconnect();从 ESP8266WiFiScan.cpp 的scanNetworks()实现可以看到扫描启动时会调用WiFi.enableSTA(true)强制启用 station 接口并且在当前连接状态既不是STATION_GOT_IP也不是STATION_IDLE时主动调用wifi_station_disconnect()。也就是说即使你忘了手动disconnect()底层也会尽量保证扫描不被已有连接干扰但文档示例中显式断开并delay(100)等待模块稳定仍是更稳妥的写法。二、简单扫描同步模式最小可用代码这是检查可用网络列表所需的最少代码。在setup()中完成模式和断开配置后调用一次扫描int n WiFi.scanNetworks();scanNetworks()会阻塞直到扫描完成并一次性返回结果数量。若返回值大于 0即可遍历打印每个网络的 SSIDfor (int i 0; i n; i) { Serial.println(WiFi.SSID(i)); }完整示例同步模式#include ESP8266WiFi.h void setup() { Serial.begin(115200); Serial.println(); WiFi.mode(WIFI_STA); WiFi.disconnect(); delay(100); } void loop() { Serial.print(Scan start ... ); int n WiFi.scanNetworks(); Serial.print(n); Serial.println( network(s) found); for (int i 0; i n; i) { Serial.println(WiFi.SSID(i)); } Serial.println(); delay(5000); }上传到 ESP 模块并打开串口监视器波特率 115200如果周围有接入点会看到类似下面这样反复打印的列表Scan start ... 5 network(s) found Tech_D005107 HP-Print-A2-Photosmart 7520 ESP_0B09E3 Hack-4-fun-net UPC Wi-Free同步模式的代价阻塞注意观察串口输出Scan start ...出现后要等明显的一段时间才轮到n network(s) found。这是因为WiFi.scanNetworks()执行本身耗时文档与 scan-class.rst 明确指出一次扫描需要数百毫秒而同步模式下程序会一直等它完成才继续下一行代码。问题随之而来如果同一时间我们希望 ESP8266 去跑对时间敏感的任务比如 LED 动画、传感器采样这种阻塞就无法接受。解决方法是改用异步扫描。三、异步扫描不阻塞主流程异步扫描的目标触发扫描后立即返回继续执行loop()中的代码等扫描完成后的某个合适时机再检查结果列表。文档用一个 250ms 周期的 LED 闪烁来模拟时间关键任务并承诺闪烁节奏全程不受扫描干扰。3.1 摒弃 delay()用 millis() 做时间基准要在loop()里同时驱动 LED 闪烁和周期扫描就不能再用任何delay()否则两者会互相阻塞。标准做法是记录上次动作的毫秒时间戳每次进入loop()用millis()内部毫秒时钟判断周期是否已到。这与 Arduino 经典示例 BlinkWithoutDelay 是同一套思路可完全套用到 Wi-Fi 周期扫描上。先定义扫描周期和记录上次扫描时间的变量#define SCAN_PERIOD 5000 long lastScanMillis;3.2 触发异步扫描在loop()中检查SCAN_PERIOD是否到期到期则触发一次扫描if (currentMillis - lastScanMillis SCAN_PERIOD) { WiFi.scanNetworks(true); Serial.print(\nScan start ... ); lastScanMillis currentMillis; }注意WiFi.scanNetworks(true)比简单扫描示例多了一个参数true——它指示以异步模式扫描触发扫描进程后立即返回、不等待结果后台处理直接执行下一行代码。如果不用异步模式250ms 的 LED 闪烁节奏必然被打乱因为一次扫描耗时超过 250ms。3.3 检查扫描完成scanComplete()异步模式下用WiFi.scanComplete()轮询扫描状态。该函数在扫描完成时返回找到的网络数量返回值语义如下与 ESP8266WiFiType.h 中WIFI_SCAN_RUNNING(-1)/WIFI_SCAN_FAILED(-2)定义一致scanComplete() 返回值含义 0扫描已完成返回发现网络的数量-1扫描仍在进行中-2扫描尚未被触发int n WiFi.scanComplete(); if(n 0) { Serial.printf(%d network(s) found\n, n); for (int i 0; i n; i) { Serial.printf(%d: %s, Ch:%d (%ddBm) %s\n, i1, WiFi.SSID(i).c_str(), WiFi.channel(i), WiFi.RSSI(i), WiFi.encryptionType(i) ENC_TYPE_NONE ? open : ); } WiFi.scanDelete(); }输出比简单扫描更丰富序号、SSID、信道Ch、信号强度dBm以及是否为开放网络open。最后一行WiFi.scanDelete()必不可少它把扫描结果从内存中删除避免结果在每次loop()运行时被反复打印。从 ESP8266WiFiScan.cpp 可以看到scanDelete()会delete[]掉内部保存的bss_info数组并把计数清零同时重置_scanComplete标志——这也意味着同一份扫描结果只能被读取一轮用完必须清理否则后续scanComplete()将一直返回旧数据。3.4 异步扫描完整示例setup()与同步示例相同仅额外增加pinMode()配置 LED 输出引脚#include ESP8266WiFi.h #define BLINK_PERIOD 250 long lastBlinkMillis; boolean ledState; #define SCAN_PERIOD 5000 long lastScanMillis; void setup() { Serial.begin(115200); Serial.println(); pinMode(LED_BUILTIN, OUTPUT); WiFi.mode(WIFI_STA); WiFi.disconnect(); delay(100); } void loop() { long currentMillis millis(); // blink LED if (currentMillis - lastBlinkMillis BLINK_PERIOD) { digitalWrite(LED_BUILTIN, ledState); ledState !ledState; lastBlinkMillis currentMillis; } // trigger Wi-Fi network scan if (currentMillis - lastScanMillis SCAN_PERIOD) { WiFi.scanNetworks(true); Serial.print(\nScan start ... ); lastScanMillis currentMillis; } // print out Wi-Fi network scan result upon completion int n WiFi.scanComplete(); if(n 0) { Serial.printf(%d network(s) found\n, n); for (int i 0; i n; i) { Serial.printf(%d: %s, Ch:%d (%ddBm) %s\n, i1, WiFi.SSID(i).c_str(), WiFi.channel(i), WiFi.RSSI(i), WiFi.encryptionType(i) ENC_TYPE_NONE ? open : ); } WiFi.scanDelete(); } }3.5 运行效果上传后打开串口监视器每 5 秒打印一次类似的列表Scan start ... 5 network(s) found 1: Tech_D005107, Ch:6 (-72dBm) 2: HP-Print-A2-Photosmart 7520, Ch:6 (-79dBm) 3: ESP_0B09E3, Ch:9 (-89dBm) open 4: Hack-4-fun-net, Ch:9 (-91dBm) 5: UPC Wi-Free, Ch:11 (-79dBm)同时观察 LED它应该以每秒 4 次的频率毫无干扰地持续闪烁——这正是异步扫描的价值所在。四、Scan Class API 全景扫描控制函数Scan Class 是 Arduino 标准 WiFi 库scanNetworks()在 ESP8266 Core 上的扩展实现。完整接口声明见 ESP8266WiFiScan.h分为扫描控制与结果访问两组函数。4.1 scanNetworks(async, show_hidden)WiFi.scanNetworks() WiFi.scanNetworks(async, show_hidden)在真实源码中该函数还有两个额外参数声明见 ESP8266WiFiScan.hint8_t scanNetworks(bool async false, bool show_hidden false, uint8 channel 0, uint8* ssid NULL);参数类型默认值作用asyncboolfalse设为true时后台启动扫描并立即返回不等待结果结果用scanComplete()查询show_hiddenboolfalse设为true时扫描结果包含隐藏 SSID 的网络channeluint80只扫描指定信道0表示扫描所有信道ssiduint8*NULL只扫描指定 SSIDNULL表示扫描所有 SSID4.2 scanComplete() 与 scanDelete()WiFi.scanComplete() // 查询异步扫描状态0 返回数量-1 进行中-2 未触发 WiFi.scanDelete() // 从内存中删除上一次扫描结果4.3 scanNetworksAsync(onComplete, show_hidden)回调式扫描如果不想每轮loop()都轮询scanComplete()可以用回调式接口扫描一完成就自动执行你注册的处理函数。WiFi.scanNetworksAsync(onComplete, show_hidden)参数onComplete为扫描完成时执行的事件处理函数show_hidden为可选 bool 参数设为true可扫描隐藏网络。#include ESP8266WiFi.h void prinScanResult(int networksFound) { Serial.printf(%d network(s) found\n, networksFound); for (int i 0; i networksFound; i) { Serial.printf(%d: %s, Ch:%d (%ddBm) %s\n, i 1, WiFi.SSID(i).c_str(), WiFi.channel(i), WiFi.RSSI(i), WiFi.encryptionType(i) ENC_TYPE_NONE ? open : ); } } void setup() { Serial.begin(115200); Serial.println(); WiFi.mode(WIFI_STA); WiFi.disconnect(); delay(100); WiFi.scanNetworksAsync(prinScanResult); } void loop() {}示例输出5 network(s) found 1: Tech_D005107, Ch:6 (-72dBm) 2: HP-Print-A2-Photosmart 7520, Ch:6 (-79dBm) 3: ESP_0B09E3, Ch:9 (-89dBm) open 4: Hack-4-fun-net, Ch:9 (-91dBm) 5: UPC Wi-Free, Ch:11 (-79dBm)五、结果访问 API每个网络能取到什么信息无论同步还是异步扫描结果都用同一套 API 读取。所有networkItem均为从 0 开始的索引。5.1 SSID 与 BSSIDString WiFi.SSID(networkItem); // 返回 String 类型 SSID uint8_t* WiFi.BSSID(networkItem); // 返回指向 6 字节 uint8_t 数组的指针AP 的 MAC 地址 String WiFi.BSSIDstr(networkItem); // 返回形如 AA:BB:CC:DD:EE:FF 的 StringBSSID 即 AP 的 MAC 地址。实现上SSID()会先把 32 字节 SSID 拷贝进 33 字节缓冲区并强制补上字符串结束符保证 32 字符满长 SSID 也不会越界见 ESP8266WiFiScan.cppBSSIDstr()则用sprintf格式化成冒号分隔的可读字符串同文件 L282-L290。若索引越界SSID()/BSSIDstr()返回空串BSSID()返回空指针。5.2 encryptionType加密类型编码uint8_t WiFi.encryptionType(networkItem);返回数值对应以下加密类型数值定义见 wl_definitions.h返回值常量含义5ENC_TYPE_WEPWEP2ENC_TYPE_TKIPWPA / PSK4ENC_TYPE_CCMPWPA2 / PSK7ENC_TYPE_NONE开放网络无加密8ENC_TYPE_AUTOWPA / WPA2 / PSK从源码看ESP8266WiFiScan.cpp该函数实际是把 SDK 的AUTH_MODE认证模式映射到上述枚举AUTH_OPEN → ENC_TYPE_NONE、AUTH_WEP → ENC_TYPE_WEP、AUTH_WPA_PSK → ENC_TYPE_TKIP、AUTH_WPA2_PSK → ENC_TYPE_CCMP、AUTH_WPA_WPA2_PSK → ENC_TYPE_AUTO其他未知模式返回-1。这也是示例中encryptionType(i) ENC_TYPE_NONE ? open : 判断开放网络的依据。5.3 RSSI / channel / isHiddenint32_t WiFi.RSSI(networkItem); // 接收信号强度指示负值 dBm越大信号越强 int32_t WiFi.channel(networkItem); // 网络所在信道1~13 等 bool WiFi.isHidden(networkItem); // true 表示隐藏网络不广播 SSID5.4 getNetworkInfo一次取全部信息如果不想逐个函数调用可以一次取出某个网络的全部信息。所有输出参数按引用传入函数调用后即被填充为对应网络的实际值函数返回bool表示取值是否成功。WiFi.getNetworkInfo(networkItem, ssid, encryptionType, RSSI, *BSSID, channel, isHidden)示例同步扫描含隐藏网络再用getNetworkInfo统一输出int n WiFi.scanNetworks(false, true); String ssid; uint8_t encryptionType; int32_t RSSI; uint8_t* BSSID; int32_t channel; bool isHidden; for (int i 0; i n; i) { WiFi.getNetworkInfo(i, ssid, encryptionType, RSSI, BSSID, channel, isHidden); Serial.printf(%d: %s, Ch:%d (%ddBm) %s %s\n, i 1, ssid.c_str(), channel, RSSI, encryptionType ENC_TYPE_NONE ? open : , isHidden ? hidden : ); }示例输出注意第 5 个网络 SSID 为空但被标记为hidden这正是show_hiddentrue的效果6 network(s) found 1: Tech_D005107, Ch:6 (-72dBm) 2: HP-Print-A2-Photosmart 7520, Ch:6 (-79dBm) 3: ESP_0B09E3, Ch:9 (-89dBm) open 4: Hack-4-fun-net, Ch:9 (-91dBm) 5: , Ch:11 (-77dBm) hidden 6: UPC Wi-Free, Ch:11 (-79dBm)从实现看ESP8266WiFiScan.cppgetNetworkInfo内部直接解引用bss_info结构SSID 拷贝到 33 字节缓冲后转Stringrssi/channel直接赋值isHidden由it-is_hidden ! 0得出BSSID直接指向内部缓冲区因此该指针在下次扫描或scanDelete()前有效。5.5 getScanInfoByIndex直接读取 SDK 原始结构getNetworkInfo是封装好的便捷接口如果你需要更底层的原始数据可以用getScanInfoByIndex直接拿到 NONOS SDK 内部使用的bss_info结构指针WiFi.getScanInfoByIndex(networkItem)networkItem超过结果数量或没有扫描结果时返回nullptr。bss_info的完整字段定义在 user_interface.h除了bssid、ssid、channel、rssi、authmode、is_hidden之外还包含物理模式位域phy_11b/phy_11g/phy_11n、wps标志以及成对/组密码pairwise_cipher/group_cipher等高级信息。典型用法先同步扫描再遍历原始结构auto n WiFi.scanNetworks(false, true); if (n 0) { // scan failed or there are no results return; } for (int i 0; i n; i) const auto* info WiFi.getScanInfoByIndex(i) // ... use the raw data from the bss_info structure ... }官方示例 WiFiScan.ino 正是利用这一点读取bss_info中的phy_11b/11g/11n与wps字段打印出每个网络的 802.11 物理模式b/g/n和 WPS 支持情况if (bssInfo) { phyMode.reserve(12); phyMode F(802.11); String slash; if (bssInfo-phy_11b) { phyMode b; slash /; } if (bssInfo-phy_11g) { phyMode slash g; slash /; } if (bssInfo-phy_11n) { phyMode slash n; } if (bssInfo-wps) { wps PSTR(WPS); } } Serial.printf(PSTR( %02d: [CH %02d] [%02X:%02X:%02X:%02X:%02X:%02X] %ddBm %c %c %-11s %3S %s\n), i, channel, bssid[0], bssid[1], bssid[2], bssid[3], bssid[4], bssid[5], rssi, (encryptionType ENC_TYPE_NONE) ? : *, hidden ? H : V, phyMode.c_str(), wps, ssid.c_str());该示例完整展示了将getNetworkInfo与getScanInfoByIndex组合使用的进阶写法是理解 Scan Class 全部能力的最佳参考可直接在 Arduino IDE 中通过ExamplesESP8266WiFiWiFiScan打开当前 Core 自带版本即仓库中的 WiFiScan.ino。六、源码级原理扫描状态机与 SDK 回调最后从实现层面理解同步/异步的区别。ESP8266WiFiScanClass用四个静态变量维护整个扫描生命周期见 ESP8266WiFiScan.h_scanAsync本次扫描是否为异步模式_scanStarted扫描是否已启动且未结束_scanComplete扫描是否已完成_scanCount/_scanResult结果数量与结果缓冲区bss_info数组。核心流程在scanNetworks()与回调_scanDone()中防重入若_scanStarted为真直接返回WIFI_SCAN_RUNNING(-1)ESP8266WiFiScan.cpp。准备WiFi.enableSTA(true)确保 station 接口开启必要时wifi_station_disconnect()断开已有连接调用scanDelete()清掉上一次结果。发起扫描构造struct scan_configssid、channel、show_hidden三字段结构定义见 user_interface.h调用 SDK 的wifi_station_scan(config, _scanDone)注册完成回调。同步 vs 异步分流同文件 L94-L102异步模式调用esp_yield()让出 CPU 给操作系统触发扫描然后立即返回WIFI_SCAN_RUNNING(-1)主流程继续执行同步模式调用esp_suspend()挂起当前任务直到_scanDone触发esp_schedule()才恢复恢复后返回_scanCount——这就是同步版等待数百毫秒的本质。完成回调_scanDone()同文件 L319-L354SDK 以链表形式给出结果函数先遍历链表统计数量再new bss_info[n]拷贝一份到堆上保证结果在 SDK 缓冲区释放后依然可用随后清除_scanStarted、置位_scanComplete同步模式下esp_schedule()唤醒等待者异步且注册过回调时调用_onComplete(数量)并清空回调。理解这个状态机后几个容易踩的坑就一目了然扫描进行中再次调用scanNetworks()会直接得到-1scanDelete()之前不能重复读取结果异步回调scanNetworksAsync本质是scanNetworks(true)加回调包装见 同文件 L114-L117因此同样遵循上述防重入与状态标志规则。七、总结Scan Class 提供了完整的同步与异步扫描 API。通过本指南你可以用同步WiFi.scanNetworks()快速实现列出周边网络的最小功能用异步WiFi.scanNetworks(true)scanComplete()/scanDelete()在不打扰 LED 闪烁等时间敏感任务的前提下周期扫描用scanNetworksAsync()注册回调扫描完成自动处理结果用SSID()、encryptionType()、RSSI()、channel()、isHidden()、getNetworkInfo()甚至底层getScanInfoByIndex()提取每个网络的完整信息。掌握了扫描机制你就能在背景中持续扫描 Wi-Fi 而不会干扰 ESP8266 上运行的其他进程为热点检测、信号监测、自动配网等应用打下基础。更完整的函数清单与参数说明请参阅 Scan Class 文档 及 ESP8266WiFiScan.h。【免费下载链接】ArduinoESP8266 core for Arduino项目地址: https://gitcode.com/gh_mirrors/ard/Arduino创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考