基于ESP32的Wi-Fi探针数据记录器：从原理到部署实战

1. 项目概述：一个专为ESP32设计的Wi-Fi日志记录器

最近在折腾一个物联网项目，需要实时监控一片区域内多个Wi-Fi热点的信号强度和连接状态变化。市面上现成的网络分析工具要么太笨重，要么无法满足长时间、低功耗的部署需求。就在我头疼的时候，在GitHub上发现了VedantParanjape大佬开源的esp-wifi-logger项目。简单来说，这是一个运行在ESP32系列芯片上的固件，它能将ESP32变成一个专业的、可配置的Wi-Fi探针和数据记录器，把扫描到的Wi-Fi网络信息（比如SSID、BSSID、信号强度、信道等）记录下来，并通过串口或者网络接口输出。

这玩意儿一下子就击中了我项目里的痛点。ESP32本身价格低廉、功耗可控，还自带Wi-Fi和蓝牙，用它来做分布式的无线环境感知节点再合适不过了。这个esp-wifi-logger把复杂的底层扫描和数据封装工作都做好了，我只需要关心如何部署设备和收集数据就行。它非常适合用于无线网络勘测、信号覆盖分析、设备定位辅助，甚至是简单的频谱占用情况监控等场景。无论你是网络管理员想评估办公室的Wi-Fi质量，还是物联网开发者需要环境感知数据，抑或是硬件爱好者想学习ESP32的Wi-Fi编程，这个项目都提供了一个极佳的起点。

2. 核心功能与设计思路拆解

2.1 核心功能全景

esp-wifi-logger的核心任务非常专注：持续或按计划扫描周围的Wi-Fi网络，并将扫描结果以一种结构化的、易于处理的方式输出。它的功能清单可以概括为以下几点：

1. Wi-Fi站点扫描：这是最基本的功能。固件调用ESP-IDF底层的esp_wifi_scan_start()等API，对指定的信道或全信道进行扫描，获取范围内所有Wi-Fi接入点的信息。
2. 丰富的日志信息捕获：它不仅仅收集SSID（网络名称）和RSSI（信号强度）。对于每个探测到的网络，它通常会记录：
   • SSID：网络的公开名称。
   • BSSID：接入点的MAC地址，这是设备的唯一硬件标识，比SSID更可靠。
   • RSSI：接收信号强度指示器，单位通常是dBm，这是评估信号好坏的关键指标。
   • 信道：Wi-Fi网络工作的频率信道。
   • 认证模式：网络的安全类型，如WPA2-Personal、WPA3、Open（开放）等。
   • 隐藏网络标识：标记该SSID是否被隐藏（不广播）。
3. 灵活的输出方式：日志需要被传递出去才有价值。项目支持常见的两种方式：
   • 串口输出：将JSON或CSV格式的日志打印到串行控制台，方便直接查看或通过USB连接电脑采集。
   • 网络输出：通过HTTP POST请求将日志数据发送到指定的服务器端点，或者通过WebSocket进行实时推送，实现远程集中式日志收集。
4. 可配置性：用户可以通过修改配置文件或编译前定义的宏，来调整扫描间隔、扫描信道列表、输出格式、目标服务器地址等参数，以适应不同场景。

2.2 设计思路与方案选型考量

为什么选择ESP32和这样的架构？这背后有很实际的工程考量。

主控选择：ESP32是性价比之王对于需要无线数据采集和边缘处理的场景，ESP32几乎是首选。它双核240MHz的主频处理网络协议栈和日志封装绰绰有余；集成的Wi-Fi模块支持Station、AP和混杂模式，其中混杂模式正是实现被动扫描的基础；丰富的GPIO和低功耗模式使其适合电池供电的长期部署；最重要的是，其庞大的社区和成熟的ESP-IDF开发框架，让开发这类专用固件的门槛大大降低。

数据格式：JSON成为首选日志输出选择JSON格式是明智之举。JSON结构清晰、自描述性强，几乎被所有现代编程语言原生支持，极大简化了后端数据解析程序的设计。相比于自定义的二进制格式或纯文本，JSON在可读性和易用性之间取得了最佳平衡。项目可能也提供CSV格式，用于直接导入电子表格进行快速分析。

输出方式：兼顾调试与部署同时提供串口和网络输出，覆盖了从原型开发到实际部署的全生命周期。开发阶段，通过串口打印日志是最直接的调试方式。部署阶段，通过网络将数据上报到云端或本地服务器，则是规模化应用的必然选择。这种设计体现了模块化的思想，输出模块可以相对独立地替换或扩展。

扫描策略：平衡功耗与实时性简单的周期性全信道扫描虽然全面，但耗电且可能不必要。更高级的设计可能会引入智能扫描策略，例如：只扫描特定频段（2.4GHz或5GHz），根据历史数据动态调整扫描频率，或者在检测到特定目标BSSID时提高扫描频率。这需要在代码中实现一个状态机来管理扫描任务，这也是基于此项目进行二次开发的一个主要方向。

3. 项目构建与环境准备实操

3.1 硬件准备与选型建议

要运行esp-wifi-logger，你首先需要一块ESP32开发板。市面上选择非常多，这里给出一些选型参考：

• 入门推荐（开发调试）：ESP32-DevKitC或NodeMCU-32S。这类板子通常集成了USB转串口芯片、复位和下载按钮，有些还带有LED，非常方便连接电脑进行编程和调试。
• 部署推荐（小型化/低功耗）：ESP32-S3或ESP32-C3系列的核心板。这些板子体积更小，外围电路精简，需要自行焊接引脚或使用底座。ESP32-C3基于RISC-V架构，功耗表现可能更好。
• 天线注意事项：对于信号扫描应用，天线性能至关重要。板载PCB天线在方向性和增益上有限。如果对扫描距离和稳定性有较高要求，可以考虑选用带有IPEX接口的开发板，然后外接一个2.4GHz/5GHz的全向天线。这能显著提升接收灵敏度，获取更准确的RSSI数据。

注意：ESP32的Wi-Fi扫描性能受射频电路和天线设计影响很大。不同型号、不同批次的板子，其信号接收能力可能存在细微差异。在进行多节点数据对比时，尽量使用同型号硬件。

3.2 软件开发环境搭建（基于ESP-IDF）

esp-wifi-logger基于乐鑫官方的ESP-IDF框架开发，因此我们需要先搭建好ESP-IDF开发环境。

步骤一：安装ESP-IDF乐鑫提供了非常详细的安装指南，这里简述最通用的方法：

1. 依赖安装：在Linux/macOS上，需要安装git,curl,cmake,ninja-build等工具。在Windows上，推荐使用乐鑫的ESP-IDF Tools Installer，它能一键安装所有依赖和工具链。
2. 克隆IDF：打开终端或命令提示符，选择一个合适的目录，运行：

   git clone -b v5.1.2 --recursive https://github.com/espressif/esp-idf.git

   这里指定了v5.1.2版本，这是一个长期支持版，相对稳定。你需要根据esp-wifi-logger项目README的要求，选择对应的IDF版本。
3. 设置工具链：进入克隆的esp-idf目录，执行安装脚本。
   • Windows:install.bat
   • Linux/macOS:./install.sh
4. 激活环境：每次打开新的终端窗口进行开发时，都需要激活环境变量。
   • Windows:export.bat
   • Linux/macOS:source export.sh

步骤二：获取项目源码在IDF环境激活后，切换到你的工作目录，克隆esp-wifi-logger仓库：

git clone https://github.com/VedantParanjape/esp-wifi-logger.git cd esp-wifi-logger

步骤三：项目配置这是关键一步，你需要根据你的硬件和需求来配置固件。

1. 运行idf.py menuconfig打开图形化配置界面。
2. 最重要的配置位于Component config -> Wi-Fi Logger Configuration菜单下（具体路径可能因项目设计而异，请以实际项目为准）。这里你可能需要设置：
   • 扫描间隔：两次扫描之间的休眠时间，单位秒。设置太短耗电，太长则数据不连续。
   • 扫描信道列表：可以指定只扫描某些信道，例如1,6,11（2.4GHz不重叠信道），以加快扫描速度。
   • 输出格式：选择JSON或CSV。
   • 输出目标：选择串口、HTTP服务器或WebSocket。如果选择网络输出，需要配置Wi-Fi Station模式的SSID、密码，以及服务器地址和端口。
3. 此外，还需要在Serial flasher config中设置正确的串口端口和波特率，在Partition Table中选择合适的分区方案。

步骤四：编译与烧录配置完成后，依次执行以下命令：

idf.py build # 编译项目 idf.py -p PORT flash # 烧录固件，PORT替换为你的串口设备（如COM3, /dev/ttyUSB0） idf.py -p PORT monitor # 打开串口监视器查看日志

如果一切顺利，在串口监视器中，你将看到ESP32启动的日志，以及周期性输出的Wi-Fi扫描结果。

4. 核心代码逻辑与关键参数解析

4.1 扫描任务调度与实现

项目的核心是一个独立的FreeRTOS任务，负责周期性地执行Wi-Fi扫描。我们来看看这个流程的关键代码逻辑（以下为概念性伪代码，帮助理解）：

void wifi_scan_task(void *pvParameters) { wifi_scan_config_t scan_conf = { .ssid = NULL, // 扫描所有SSID .bssid = NULL, // 扫描所有BSSID .channel = 0, // 信道0表示扫描所有信道 .show_hidden = true // 包含隐藏网络 }; while (1) { // 1. 发起扫描 esp_err_t err = esp_wifi_scan_start(&scan_conf, true); // true表示阻塞等待扫描完成 if (err != ESP_OK) { ESP_LOGE(TAG, "Scan failed: %s", esp_err_to_name(err)); vTaskDelay(pdMS_TO_TICKS(1000)); // 失败后等待1秒重试 continue; } // 2. 获取扫描结果 uint16_t ap_num = DEFAULT_SCAN_LIST_SIZE; wifi_ap_record_t ap_records[DEFAULT_SCAN_LIST_SIZE]; esp_wifi_scan_get_ap_records(&ap_num, ap_records); // 3. 处理并输出结果 process_and_output_scan_results(ap_records, ap_num); // 4. 等待下一个扫描周期 vTaskDelay(pdMS_TO_TICKS(CONFIG_SCAN_INTERVAL_MS)); } }

关键参数解析：

• wifi_scan_config_t：这是ESP-IDF定义的扫描配置结构体。通过设置.channel，你可以实现定向扫描。例如，只设置.channel=6，则设备仅监听6信道，速度极快，适用于追踪特定信道上的设备。
• show_hidden：设置为true时，即使AP不广播SSID，只要其发送信标帧，也能被扫描到并记录其BSSID和RSSI，但SSID字段可能为空或特定值。这对于安全审计或网络发现很有用。
• DEFAULT_SCAN_LIST_SIZE：这个值定义了存储AP记录数组的大小。如果周围网络非常多，你需要确保这个值足够大，否则会丢失部分扫描结果。它可以在menuconfig或代码中调整。
• CONFIG_SCAN_INTERVAL_MS：这是最重要的参数之一，直接决定了数据密度和功耗。其计算需权衡：
  • 数据密度需求：如果你想捕捉快速移动的设备信号变化，间隔可能需要设置在100ms-500ms。
  • 功耗限制：每次主动扫描都会唤醒Wi-Fi射频，消耗可观电流。对于电池供电设备，间隔可能需要设置在5s-60s甚至更长。
  • 经验值：对于一般的环境监测，2-10秒的间隔是一个不错的起点。

4.2 数据封装与网络传输

获取到wifi_ap_record_t数组后，下一步就是将其封装并发送出去。process_and_output_scan_results函数内部可能包含类似下面的逻辑：

void process_and_output_scan_results(wifi_ap_record_t *records, uint16_t count) { cJSON *root = cJSON_CreateObject(); cJSON *aps = cJSON_CreateArray(); cJSON_AddItemToObject(root, "device_id", cJSON_CreateString(CONFIG_DEVICE_ID)); cJSON_AddItemToObject(root, "timestamp", cJSON_CreateNumber(esp_timer_get_time() / 1000)); // 毫秒时间戳 cJSON_AddItemToObject(root, "aps", aps); for (int i = 0; i < count; i++) { cJSON *ap = cJSON_CreateObject(); cJSON_AddItemToObject(ap, "ssid", cJSON_CreateString((char*)records[i].ssid)); // 将BSSID（uint8_t[6]）转换为字符串"AA:BB:CC:DD:EE:FF" char bssid_str[18]; snprintf(bssid_str, sizeof(bssid_str), "%02X:%02X:%02X:%02X:%02X:%02X", records[i].bssid[0], records[i].bssid[1], records[i].bssid[2], records[i].bssid[3], records[i].bssid[4], records[i].bssid[5]); cJSON_AddItemToObject(ap, "bssid", cJSON_CreateString(bssid_str)); cJSON_AddItemToObject(ap, "rssi", cJSON_CreateNumber(records[i].rssi)); cJSON_AddItemToObject(ap, "channel", cJSON_CreateNumber(records[i].primary)); cJSON_AddItemToObject(ap, "authmode", cJSON_CreateNumber(records[i].authmode)); cJSON_AddItemToArray(aps, ap); } char *json_str = cJSON_PrintUnformatted(root); // 选择输出方式：串口打印 或 HTTP POST #ifdef CONFIG_OUTPUT_SERIAL printf("%s\n", json_str); #endif #ifdef CONFIG_OUTPUT_HTTP http_post_data(CONFIG_SERVER_URL, json_str); #endif free(json_str); cJSON_Delete(root); }

网络传输实现要点：

如果选择了HTTP输出，http_post_data函数需要使用ESP-IDF的HTTP客户端组件。这里有几个坑需要注意：

1. 连接复用：为每次扫描都创建和销毁一个HTTP连接开销巨大。务必实现一个连接池或保持长连接（如果服务器支持HTTP Keep-Alive）。
2. 错误处理与重试：网络可能不稳定。发送失败时，需要有重试机制，并设置最大重试次数。同时，要考虑数据积压问题，如果网络长时间中断，是丢弃旧数据还是缓存到非易失性存储器中。
3. 数据压缩：当扫描到的AP很多时，JSON数据包会变大。可以考虑在发送前使用zlib进行简单的GZIP压缩，特别是在使用蜂窝网络等按流量计费的链路时。
4. 时间同步：日志中的时间戳非常重要。建议让ESP32从NTP服务器同步时间，或者由接收日志的服务器在收到数据时打上服务器时间戳。设备自身的时间戳仅用作相对时间参考。

5. 高级应用场景与二次开发思路

基础的数据记录功能已经很强大了，但我们可以基于此项目，拓展出更多有价值的应用。

5.1 场景一：室内定位与区域感知

单个ESP32 Logger可以作为一个锚点。通过部署多个Logger，形成一个感知网络，可以实现更复杂的应用。

• 原理：同一个Wi-Fi信号源（如你的手机，即使未连接AP，也会发送探测请求），在不同位置的Logger上会收到不同强度的信号（RSSI）。利用指纹定位或三角定位算法，可以大致估算出信号源的位置。
• 实现步骤：
  1. 离线训练阶段：在目标区域（如办公室、商场）的已知坐标点上，放置信号发射源（如一部手机）。让所有Logger记录下该位置点的RSSI指纹（各个AP的信号强度向量），并与其坐标关联，存入数据库。
  2. 在线定位阶段：当一个待定位设备进入区域时，所有Logger实时上报扫描到的该设备的信号强度。服务器将收到的实时指纹与数据库中的训练指纹进行匹配（如使用K最近邻算法），找出最相似的点，即为估算位置。
  3. 基于esp-wifi-logger的改造：需要修改固件，使其能够过滤并重点关注特定目标BSSID（如手机的MAC地址）的信号，并提高对该目标的扫描频率。同时，需要开发一个后端服务器来处理数据融合和算法计算。

5.2 场景二：无线网络健康度长期监测

将Logger固定在某个位置，进行长达数周或数月的持续监测，可以分析出许多问题。

• 可发现的问题：
  • 信道干扰：通过长期统计各信道的AP数量和平均信号强度，可以找出长期拥塞的信道，为手动优化Wi-Fi信道提供数据支持。
  • 信号衰减与盲区：通过分析特定AP的RSSI随时间的变化，可以发现因新增障碍物、设备移动导致的信号衰减，定位覆盖盲区。
  • 非法接入点检测：通过维护一个合法的BSSID白名单，Logger可以实时报警新出现的、未授权的AP，提升网络安全性。
• 实现要点：此场景下，数据存储和可视化是关键。需要将Logger的数据持久化到数据库（如InfluxDB），并利用可视化工具（如Grafana）绘制RSSI趋势图、信道热力图等。

5.3 二次开发方向建议

如果你想深入修改或增强这个项目，可以从以下几个方向入手：

1. 低功耗优化：目前的周期扫描模型在间隔期内Wi-Fi可能仍处于活动状态。可以结合ESP32的深度睡眠模式，让设备在扫描间隙完全断电，仅由定时器唤醒，这将极大延长电池寿命。需要处理好RTC内存中状态的保存与恢复。
2. 选择性扫描与过滤：在固件层面增加过滤规则，例如只记录信号强度大于-70dBm的AP，或者只关注特定前缀的SSID。这可以减少数据量和网络传输开销。
3. 本地聚合与边缘计算：不一定每次扫描都上报原始数据。可以在ESP32上先进行简单计算，例如每分钟上报一次该分钟内检测到的AP数量、平均RSSI、信道分布等聚合信息。
4. 增加蓝牙/BLE扫描：ESP32同样具备蓝牙功能。可以扩展固件，使其同时扫描周围的蓝牙和BLE设备，将Wi-Fi和蓝牙的感知数据一并上报，用于更丰富的场景，如客流分析、资产追踪。

6. 常见问题与实战调试技巧

在实际部署和开发过程中，你肯定会遇到各种问题。下面是我踩过的一些坑和总结的排查思路。

6.1 编译与烧录问题

6.2 运行时功能异常

6.3 性能与优化技巧

1. 提升扫描速度：全信道扫描（2.4GHz的1-13信道）比较耗时。如果只关心特定频段，在wifi_scan_config_t中指定channel，或配置scan_time.active.min和scan_time.active.max来减少在每个信道上的驻留时间。注意，驻留时间太短可能会漏掉一些信号。
2. 减少内存碎片：频繁创建和销毁JSON对象容易导致内存碎片。可以改为复用固定的cJSON对象，或者使用静态字符数组来拼接JSON字符串（对于固定格式的输出更高效）。
3. 串口输出瓶颈：默认的115200波特率在输出大量JSON数据时可能成为瓶颈，导致任务阻塞。可以尝试提高串口波特率（如921600），或者将输出改为非阻塞方式，先将数据放入队列，由另一个低优先级任务负责打印。
4. 获取设备自身MAC地址：有时需要在日志中加入Logger设备自身的标识。可以使用esp_read_mac(mac_addr, ESP_MAC_WIFI_STA)函数来获取ESP32的Station模式MAC地址，将其作为device_id输出。

这个项目就像一个乐高积木的基础模块，功能纯粹但足够坚实。把它用起来，你能快速搭建起一个无线环境感知系统；深入它的代码，你能学到ESP32 Wi-Fi编程和嵌入式数据处理的精髓。无论是用于解决实际问题，还是作为学习练手，esp-wifi-logger都是一个值得你花时间去琢磨的好项目。在实际部署中，我最深的体会是，稳定性高于一切。尤其是在网络传输和电源管理上，多做一些防御性编程和异常处理，能让你的数据采集节点在无人值守的环境下运行得更久、更可靠。