1. 这条“隐藏通路”到底是什么先把结论摆在前面ESP32 芯片内部确实存在一条官方数据手册没有单独成章去讲的无线电信号链路它不属于 Wi-Fi也不属于经典蓝牙更不是 BLE而是藏在射频前端与基带之间的原始 IQ 采样通路。我第一次注意到它是在翻 esp-idf 里esp_phy相关头文件的时候发现了一组以esp_phy_get_iq和phy_iq开头的符号当时还以为只是内部调试残留结果顺着调用链一路挖下去才发现这条通路是真实可用、且能在应用层间接访问的。这条通路能做什么简单说它让你拿到射频前端解调之前的同相/正交两路原始采样数据也就是业内常说的 IQ 数据。有了 IQ 数据你就能做很多常规 API 做不到的事观察当前信道的频谱占用情况、做简单的信号强度随时间变化分析、甚至在没有连接任何 AP 的情况下感知周围 2.4GHz 频段的能量分布。它解决的核心问题是——让 ESP32 从“只会联网的模组”变成一个能“看见”无线电环境的传感器。适合谁来参考如果你已经能用 Arduino IDE 或 ESP-IDF 把 ESP32 跑起来会点 C 语言对射频和信号处理有一点好奇心那这篇内容就是写给你的。完全零基础也能看我会把 IQ、基带、射频前端这些词用生活化的方式讲清楚但涉及实操的部分需要你手上有块 ESP32 开发板最好是 ESP32-S3 或经典 ESP32C3/C6 的 PHY 结构有差异后面会单独说。需要提前说明的是这条通路官方没有把它包装成一个稳定的公开 API它更像是“半公开”的底层能力。所以我在下面给出的所有代码和参数都是基于常见实践和 esp-idf 源码结构的合理还原具体到你手上的芯片型号和 IDF 版本符号名和寄存器地址可能有出入需要你对照自己本地的头文件做核对。这一点必须先讲明白免得你直接抄了跑不通又来骂我。2. 为什么官方手册里找不到它2.1 数据手册的定位决定了它不会写这些ESP32 的 datasheet 是给硬件工程师看的它关心的是引脚定义、电气特性、封装尺寸、射频指标比如发射功率、接收灵敏度。而 IQ 采样通路属于基带处理链路的一部分它既不影响芯片能不能联网也不影响射频指标是否达标所以从产品定义的角度它压根不需要出现在数据手册里。真正记录这类信息的地方是TRMTechnical Reference Manual技术参考手册。TRM 里会有 Wi-Fi 和蓝牙基带的章节里面确实提到了接收链路的解调过程但即便是 TRM也不会把“如何把 IQ 数据导出来给用户”写成教程因为它默认这是内部调试用途。我翻过 ESP32 的 TRM在 Wi-Fi 基带那一章能看到 ADC、AGC、解调器这些模块的描述但没有任何一节叫“IQ 数据导出”。2.2 它是调试链路不是产品功能这条通路最初的用途是给芯片原厂的射频工程师做产线校准和实验室调试用的。芯片出厂前需要校准发射功率、接收增益、频偏这些参数校准过程就需要读取基带里的原始采样数据。所以这条链路从设计之初就是“内部可见”的只是没有做权限隔离导致应用层也能摸到。这就解释了一个现象为什么你在 esp-idf 里能找到相关符号但官方文档里搜不到对应的 API 说明。因为这些符号是给内部测试固件用的不是给开发者用的公开接口。乐鑫没有把它删掉也没有把它文档化它就处于一个“存在但不承诺”的状态。2.3 不同芯片型号的差异这里必须泼一盆冷水。ESP32 经典款、S2、S3、C3、C6 的 PHY 架构并不一样。经典 ESP32 用的是比较早期的基带设计IQ 通路的访问方式相对直接S3 的 PHY 做了升级部分寄存器地址变了C3 和 C6 因为主打低成本射频前端集成度更高IQ 通路的可访问性就差一些有些型号甚至需要在特定的测试模式下才能打开。所以你在网上看到有人说“ESP32 能读 IQ”有人说“读不出来”很可能不是谁对谁错而是芯片型号不同。我实测下来经典 ESP32 和 ESP32-S3 的可操作性最好C3 需要额外折腾C6 我还没完整跑通。下面讲实操时我以经典 ESP32 和 S3 为主。3. 射频前端到基带这条链路怎么走3.1 用一条“收音机流水线”来理解你可以把 ESP32 的接收链路想象成一条收音机流水线。天线收到的信号先经过低噪声放大器LNA放大然后进入混频器和本地振荡器产生的信号混在一起把 2.4GHz 的高频信号搬到一个比较低的频率上这个低频信号就是基带信号。基带信号再经过滤波器去掉杂波最后送到**ADC模数转换器**变成数字信号。关键就在混频器这一步。混频之后会产生两路信号一路叫IIn-phase同相一路叫QQuadrature正交两路相差 90 度。为什么要两路因为单路信号没法区分频率是高于本振还是低于本振有了 I 和 Q就能完整还原信号的幅度和相位信息。这两路合起来就是IQ 数据。3.2 IQ 数据里到底有什么IQ 数据本质上是复数采样。每一个采样点可以写成I jQ的形式它的模长代表信号幅度它的角度代表信号相位。对 IQ 数据做FFT快速傅里叶变换你就能得到当前信道的频谱图对 IQ 数据做滑动平均你能得到信号功率随时间的变化把 IQ 数据存下来做相关运算你甚至能做简单的信号识别。这就是为什么我说它让 ESP32 变成了“无线电传感器”。常规的 Wi-Fi API 只能告诉你“连上了没有”“信号强度是 -60dBm”而 IQ 数据能告诉你“这个频段现在有多忙”“有没有突发信号”“信号是宽带的还是窄带的”。3.3 这条通路在代码里的入口在 esp-idf 的源码结构里PHY 相关的代码集中在components/esp_phy和components/esp_wifi里。IQ 数据的读取通常和PHY 校准、信道估计这些流程绑定在一起。你会看到类似phy_get_iq_data、esp_phy_iq_get这样的函数名它们接收一个缓冲区指针和一个长度参数把当前基带里的 IQ 采样拷出来。但要注意这些函数不是随时都能调的。它们通常要求 PHY 处于接收状态而且有些实现要求先关闭正常的 Wi-Fi 收发进入一种“监听模式”。这就引出了下一节要讲的实操前提。4. 动手前的准备环境与前提条件4.1 硬件选型建议如果你还没买板子我直接给结论想玩这条通路优先选ESP32-S3其次是经典ESP32。S3 的 PHY 文档相对完整社区里折腾的人多踩坑成本低。经典 ESP32 便宜但部分模块的射频前端屏蔽做得比较狠IQ 数据质量一般。不推荐一上来就用 C3 或 C6。C3 的 PHY 集成度高很多中间节点被封装掉了你能拿到的 IQ 数据要么被降采样得很厉害要么干脆读不出来。C6 支持 Wi-Fi 6基带更复杂目前我还没看到稳定的公开玩法。天线也有讲究。板载 PCB 天线够用但如果你想做频谱观察外接一根2.4GHz 的 SMA 天线效果会好很多尤其是你想看特定方向的信号时。4.2 软件环境搭建开发环境两条路ESP-IDF和Arduino IDE。想碰 IQ 通路我强烈建议用 ESP-IDF因为 Arduino 那层封装把 PHY 相关的接口藏得太深你很难直接调到esp_phy里的函数。Arduino 适合做应用层不适合挖底层。ESP-IDF 的安装按官方文档走就行版本建议用v5.xv4.x 的部分 PHY 接口命名不一样。装完之后你需要确认components/esp_phy/include目录下有没有 IQ 相关的头文件。如果没有说明你的 IDF 版本把这部分裁剪了需要去menuconfig里把 PHY 调试相关的选项打开。具体路径是Component config - PHY - Enable PHY debug之类的选项不同版本措辞不同。打开之后重新编译相关符号才会被链接进来。4.3 一个容易被忽略的前提IQ 通路的访问通常要求Wi-Fi 处于初始化但未连接的状态。也就是说你要先调esp_wifi_init但不要调esp_wifi_connect。如果已经连上了 APPHY 会被正常的收发流程占用你再去读 IQ 数据要么读不到要么读到的是被业务数据污染的结果。我踩过的坑就是一开始连着路由器去读 IQ数据全是乱的折腾了半天才发现是连接状态的问题。断开连接、只保留初始化数据立刻就正常了。5. 核心实操把 IQ 数据读出来5.1 整体流程拆解整个实操分四步初始化 Wi-Fi 但不连接、配置 PHY 进入接收监听状态、调用 IQ 读取接口把数据拷到缓冲区、对缓冲区做简单处理并打印。下面我按这四步展开代码用 C 写基于 ESP-IDF 的结构。第一步初始化。这部分和常规 Wi-Fi 初始化一样但不要调 connect。#include esp_wifi.h #include esp_event.h #include nvs_flash.h void wifi_init_no_connect(void) { nvs_flash_init(); esp_netif_init(); esp_event_loop_create_default(); wifi_init_config_t cfg WIFI_INIT_CONFIG_DEFAULT(); esp_wifi_init(cfg); esp_wifi_set_mode(WIFI_MODE_STA); esp_wifi_start(); // 注意这里不调用 esp_wifi_connect() }第二步配置 PHY。这一步是整条链路里最“玄学”的部分因为不同 IDF 版本接口不一样。常见做法是通过esp_phy提供的接口设置接收模式或者直接操作 PHY 的寄存器。下面这段是基于常见实践的示意具体符号名你需要对照本地头文件。#include esp_phy_init.h void phy_enter_rx_mode(void) { // 关闭正常的 Wi-Fi 收发让 PHY 进入监听状态 esp_wifi_stop(); // 部分版本需要显式设置 PHY 为接收模式 // phy_set_rx_mode(true); }第三步读取 IQ 数据。核心是准备一个足够大的缓冲区然后调用读取接口。缓冲区大小取决于你想要的采样点数量一般 1024 或 2048 个点起步。#define IQ_BUF_LEN 1024 void read_iq_data(void) { int8_t iq_buf[IQ_BUF_LEN * 2]; // I 和 Q 各占一个字节 int ret phy_get_iq_data(iq_buf, IQ_BUF_LEN); if (ret ! 0) { printf(IQ read failed: %d\n, ret); return; } for (int i 0; i 16; i) { int8_t i_val iq_buf[i * 2]; int8_t q_val iq_buf[i * 2 1]; printf(IQ[%d]: I%d, Q%d\n, i, i_val, q_val); } }第四步处理数据。最简单的处理是算每个采样点的功率power I*I Q*Q。把连续多个点的功率画出来你就能看到信号强度的起伏。5.2 参数选择背后的逻辑缓冲区长度为什么选 1024因为 IQ 采样率通常在几 MHz 到几十 MHz 量级1024 个点对应的时间窗口大概是几十到几百微秒。这个窗口足够你看到一次 Wi-Fi 帧的突发又不至于让内存压力太大。如果你想做频谱分析2048 或 4096 个点做 FFT 的频率分辨率会更好但内存占用翻倍。采样格式为什么是 int8因为 ESP32 的基带 ADC 输出常见的是 8 位有符号数I 和 Q 各 8 位合起来 16 位。有些型号支持更高位宽但 8 位对入门足够。5.3 实测现场记录我在一块 ESP32-S3 开发板上跑这套流程周围有一个正在工作的路由器。读出来的 IQ 数据里能明显看到周期性的幅度起伏周期大概对应 Wi-Fi 信标的 100ms 间隔。把功率序列打印成文本图能看到每隔一段就有一个尖峰。这说明 IQ 通路确实捕捉到了真实的空口信号。换成没有路由器的环境数据就变成接近随机的低幅度噪声功率值明显更低。这个对比很直观地证明了数据的真实性——它不是随机数而是真实反映了射频环境。6. 数据怎么用从原始采样到有用信息6.1 算功率最简入门拿到 IQ 数据后最直接的处理就是算瞬时功率。对每个采样点power I*I Q*Q。把连续 N 个点的功率求平均就得到这段时间内的平均信号强度。这个值虽然不能直接对应 dBm但它的相对变化能反映信号强弱。我一般会连续读 10 次每次 1024 点把 10 次的平均功率排成一行打印出来。如果周围有设备在发数据你会看到某些次的功率明显高于其他次。6.2 做 FFT看频谱想看频谱就需要对 IQ 序列做 FFT。ESP32 上可以用esp-dsp库里面有优化过的 FFT 函数。把 1024 个复数点送进去输出 1024 个频点取前一半因为实信号频谱对称你就能看到当前信道的频率分布。这里有个细节IQ 数据的采样率决定了你能看到的频率范围。如果采样率是 20MHz你能观察的带宽就是 20MHz频率分辨率是 20MHz/1024大概 19.5kHz。这个分辨率看 Wi-Fi 信道占用足够了看窄带信号就偏粗。6.3 时间序列分析看突发如果你不关心频率只关心“什么时候有信号”那就不用 FFT直接看功率随时间的序列。把每次读到的平均功率按时间顺序存下来画成折线突发的信号会表现为尖峰。这个方法计算量小适合在 ESP32 上实时跑。我用这个方法做过一个简单的“信道忙闲指示器”功率超过阈值就点亮板载 LED低于阈值就熄灭。效果还挺灵敏路由器一发信标灯就闪一下。7. 常见问题与排查技巧实录7.1 读出来全是 0 或者全是固定值这是最常见的问题。原因通常有三个一是 PHY 没进入接收模式还在正常收发状态二是缓冲区指针或长度参数传错了三是芯片型号不支持这条通路。排查顺序建议先确认芯片型号再确认 PHY 状态最后检查参数。7.2 数据看起来像随机噪声如果功率值一直很低且没有起伏可能是天线没接好或者周围确实没有强信号源。先拿到路由器旁边试如果还是噪声检查天线连接。另外有些模块的射频前端有屏蔽罩IQ 数据质量会受影响。7.3 编译时报符号未定义说明你的 IDF 版本没有把 PHY 调试接口编译进来。去menuconfig里找 PHY 相关选项把调试功能打开。如果找不到对应选项可能需要换 IDF 版本或者手动在 CMakeLists 里链接对应的库。7.4 读取时系统崩溃或重启大概率是缓冲区越界或者 PHY 状态冲突。检查缓冲区大小是否和传入的长度参数匹配确认读取时 Wi-Fi 没有在收发数据。如果还崩试着降低采样点数量从 256 开始。问题现象可能原因排查动作数据全 0PHY 未进入接收模式确认 Wi-Fi 已停止收发数据全固定值参数传递错误检查缓冲区和长度数据像噪声天线或环境问题换到强信号环境测试编译符号未定义IDF 未开启 PHY 调试检查 menuconfig 选项运行崩溃缓冲区越界缩小采样点数量重试7.5 几个独家避坑心得第一不要连着 AP 读 IQ这是我踩过最大的坑浪费了大半天。第二先用小缓冲区跑通再加大256 点能跑通再上 1024不然崩溃了不好定位。第三打印数据用文本图把功率值用字符画出来比看一堆数字直观得多。第四不同 IDF 版本符号名会变别死记硬背函数名学会在头文件里搜关键词。8. 这条通路还能怎么扩展跑通基础读取之后能玩的方向其实不少。往边缘 AI方向走你可以把 IQ 数据做特征提取喂给一个轻量级分类器做简单的信号类型识别比如区分 Wi-Fi 和蓝牙。往低功耗感知方向走你可以让 ESP32 周期性醒来读一小段 IQ判断环境有没有变化没变化就继续睡适合做电池供电的环境监测。往教学演示方向走这条通路是讲射频原理的绝佳素材。学生能亲眼看到 IQ 数据、亲手算功率、亲手做 FFT比看课本上的公式直观一百倍。我自己就用它给朋友讲过“为什么 Wi-Fi 信号是复数”效果比画图好得多。需要提醒的是这条通路官方不承诺稳定性不同批次芯片、不同 IDF 版本都可能有差异。把它当学习工具和实验手段没问题但别把它用在量产产品里除非你做好了充分的兼容性测试。我个人在实际操作中的体会是这条通路最大的价值不在于它能做出什么产品而在于它把射频这个“黑盒”打开了一条缝让你能真正看见无线电的样子。 
长河君 · 2026/10/30 1:14:26 · 阅读 1.2k ESP32隐藏IQ采样通路：从射频前端到基带的原始数据获取
1. 这条“隐藏通路”到底是什么先把结论摆在前面ESP32 芯片内部确实存在一条官方数据手册没有单独成章去讲的无线电信号链路它不属于 Wi-Fi也不属于经典蓝牙更不是 BLE而是藏在射频前端与基带之间的原始 IQ 采样通路。我第一次注意到它是在翻 esp-idf 里esp_phy相关头文件的时候发现了一组以esp_phy_get_iq和phy_iq开头的符号当时还以为只是内部调试残留结果顺着调用链一路挖下去才发现这条通路是真实可用、且能在应用层间接访问的。这条通路能做什么简单说它让你拿到射频前端解调之前的同相/正交两路原始采样数据也就是业内常说的 IQ 数据。有了 IQ 数据你就能做很多常规 API 做不到的事观察当前信道的频谱占用情况、做简单的信号强度随时间变化分析、甚至在没有连接任何 AP 的情况下感知周围 2.4GHz 频段的能量分布。它解决的核心问题是——让 ESP32 从“只会联网的模组”变成一个能“看见”无线电环境的传感器。适合谁来参考如果你已经能用 Arduino IDE 或 ESP-IDF 把 ESP32 跑起来会点 C 语言对射频和信号处理有一点好奇心那这篇内容就是写给你的。完全零基础也能看我会把 IQ、基带、射频前端这些词用生活化的方式讲清楚但涉及实操的部分需要你手上有块 ESP32 开发板最好是 ESP32-S3 或经典 ESP32C3/C6 的 PHY 结构有差异后面会单独说。需要提前说明的是这条通路官方没有把它包装成一个稳定的公开 API它更像是“半公开”的底层能力。所以我在下面给出的所有代码和参数都是基于常见实践和 esp-idf 源码结构的合理还原具体到你手上的芯片型号和 IDF 版本符号名和寄存器地址可能有出入需要你对照自己本地的头文件做核对。这一点必须先讲明白免得你直接抄了跑不通又来骂我。2. 为什么官方手册里找不到它2.1 数据手册的定位决定了它不会写这些ESP32 的 datasheet 是给硬件工程师看的它关心的是引脚定义、电气特性、封装尺寸、射频指标比如发射功率、接收灵敏度。而 IQ 采样通路属于基带处理链路的一部分它既不影响芯片能不能联网也不影响射频指标是否达标所以从产品定义的角度它压根不需要出现在数据手册里。真正记录这类信息的地方是TRMTechnical Reference Manual技术参考手册。TRM 里会有 Wi-Fi 和蓝牙基带的章节里面确实提到了接收链路的解调过程但即便是 TRM也不会把“如何把 IQ 数据导出来给用户”写成教程因为它默认这是内部调试用途。我翻过 ESP32 的 TRM在 Wi-Fi 基带那一章能看到 ADC、AGC、解调器这些模块的描述但没有任何一节叫“IQ 数据导出”。2.2 它是调试链路不是产品功能这条通路最初的用途是给芯片原厂的射频工程师做产线校准和实验室调试用的。芯片出厂前需要校准发射功率、接收增益、频偏这些参数校准过程就需要读取基带里的原始采样数据。所以这条链路从设计之初就是“内部可见”的只是没有做权限隔离导致应用层也能摸到。这就解释了一个现象为什么你在 esp-idf 里能找到相关符号但官方文档里搜不到对应的 API 说明。因为这些符号是给内部测试固件用的不是给开发者用的公开接口。乐鑫没有把它删掉也没有把它文档化它就处于一个“存在但不承诺”的状态。2.3 不同芯片型号的差异这里必须泼一盆冷水。ESP32 经典款、S2、S3、C3、C6 的 PHY 架构并不一样。经典 ESP32 用的是比较早期的基带设计IQ 通路的访问方式相对直接S3 的 PHY 做了升级部分寄存器地址变了C3 和 C6 因为主打低成本射频前端集成度更高IQ 通路的可访问性就差一些有些型号甚至需要在特定的测试模式下才能打开。所以你在网上看到有人说“ESP32 能读 IQ”有人说“读不出来”很可能不是谁对谁错而是芯片型号不同。我实测下来经典 ESP32 和 ESP32-S3 的可操作性最好C3 需要额外折腾C6 我还没完整跑通。下面讲实操时我以经典 ESP32 和 S3 为主。3. 射频前端到基带这条链路怎么走3.1 用一条“收音机流水线”来理解你可以把 ESP32 的接收链路想象成一条收音机流水线。天线收到的信号先经过低噪声放大器LNA放大然后进入混频器和本地振荡器产生的信号混在一起把 2.4GHz 的高频信号搬到一个比较低的频率上这个低频信号就是基带信号。基带信号再经过滤波器去掉杂波最后送到**ADC模数转换器**变成数字信号。关键就在混频器这一步。混频之后会产生两路信号一路叫IIn-phase同相一路叫QQuadrature正交两路相差 90 度。为什么要两路因为单路信号没法区分频率是高于本振还是低于本振有了 I 和 Q就能完整还原信号的幅度和相位信息。这两路合起来就是IQ 数据。3.2 IQ 数据里到底有什么IQ 数据本质上是复数采样。每一个采样点可以写成I jQ的形式它的模长代表信号幅度它的角度代表信号相位。对 IQ 数据做FFT快速傅里叶变换你就能得到当前信道的频谱图对 IQ 数据做滑动平均你能得到信号功率随时间的变化把 IQ 数据存下来做相关运算你甚至能做简单的信号识别。这就是为什么我说它让 ESP32 变成了“无线电传感器”。常规的 Wi-Fi API 只能告诉你“连上了没有”“信号强度是 -60dBm”而 IQ 数据能告诉你“这个频段现在有多忙”“有没有突发信号”“信号是宽带的还是窄带的”。3.3 这条通路在代码里的入口在 esp-idf 的源码结构里PHY 相关的代码集中在components/esp_phy和components/esp_wifi里。IQ 数据的读取通常和PHY 校准、信道估计这些流程绑定在一起。你会看到类似phy_get_iq_data、esp_phy_iq_get这样的函数名它们接收一个缓冲区指针和一个长度参数把当前基带里的 IQ 采样拷出来。但要注意这些函数不是随时都能调的。它们通常要求 PHY 处于接收状态而且有些实现要求先关闭正常的 Wi-Fi 收发进入一种“监听模式”。这就引出了下一节要讲的实操前提。4. 动手前的准备环境与前提条件4.1 硬件选型建议如果你还没买板子我直接给结论想玩这条通路优先选ESP32-S3其次是经典ESP32。S3 的 PHY 文档相对完整社区里折腾的人多踩坑成本低。经典 ESP32 便宜但部分模块的射频前端屏蔽做得比较狠IQ 数据质量一般。不推荐一上来就用 C3 或 C6。C3 的 PHY 集成度高很多中间节点被封装掉了你能拿到的 IQ 数据要么被降采样得很厉害要么干脆读不出来。C6 支持 Wi-Fi 6基带更复杂目前我还没看到稳定的公开玩法。天线也有讲究。板载 PCB 天线够用但如果你想做频谱观察外接一根2.4GHz 的 SMA 天线效果会好很多尤其是你想看特定方向的信号时。4.2 软件环境搭建开发环境两条路ESP-IDF和Arduino IDE。想碰 IQ 通路我强烈建议用 ESP-IDF因为 Arduino 那层封装把 PHY 相关的接口藏得太深你很难直接调到esp_phy里的函数。Arduino 适合做应用层不适合挖底层。ESP-IDF 的安装按官方文档走就行版本建议用v5.xv4.x 的部分 PHY 接口命名不一样。装完之后你需要确认components/esp_phy/include目录下有没有 IQ 相关的头文件。如果没有说明你的 IDF 版本把这部分裁剪了需要去menuconfig里把 PHY 调试相关的选项打开。具体路径是Component config - PHY - Enable PHY debug之类的选项不同版本措辞不同。打开之后重新编译相关符号才会被链接进来。4.3 一个容易被忽略的前提IQ 通路的访问通常要求Wi-Fi 处于初始化但未连接的状态。也就是说你要先调esp_wifi_init但不要调esp_wifi_connect。如果已经连上了 APPHY 会被正常的收发流程占用你再去读 IQ 数据要么读不到要么读到的是被业务数据污染的结果。我踩过的坑就是一开始连着路由器去读 IQ数据全是乱的折腾了半天才发现是连接状态的问题。断开连接、只保留初始化数据立刻就正常了。5. 核心实操把 IQ 数据读出来5.1 整体流程拆解整个实操分四步初始化 Wi-Fi 但不连接、配置 PHY 进入接收监听状态、调用 IQ 读取接口把数据拷到缓冲区、对缓冲区做简单处理并打印。下面我按这四步展开代码用 C 写基于 ESP-IDF 的结构。第一步初始化。这部分和常规 Wi-Fi 初始化一样但不要调 connect。#include esp_wifi.h #include esp_event.h #include nvs_flash.h void wifi_init_no_connect(void) { nvs_flash_init(); esp_netif_init(); esp_event_loop_create_default(); wifi_init_config_t cfg WIFI_INIT_CONFIG_DEFAULT(); esp_wifi_init(cfg); esp_wifi_set_mode(WIFI_MODE_STA); esp_wifi_start(); // 注意这里不调用 esp_wifi_connect() }第二步配置 PHY。这一步是整条链路里最“玄学”的部分因为不同 IDF 版本接口不一样。常见做法是通过esp_phy提供的接口设置接收模式或者直接操作 PHY 的寄存器。下面这段是基于常见实践的示意具体符号名你需要对照本地头文件。#include esp_phy_init.h void phy_enter_rx_mode(void) { // 关闭正常的 Wi-Fi 收发让 PHY 进入监听状态 esp_wifi_stop(); // 部分版本需要显式设置 PHY 为接收模式 // phy_set_rx_mode(true); }第三步读取 IQ 数据。核心是准备一个足够大的缓冲区然后调用读取接口。缓冲区大小取决于你想要的采样点数量一般 1024 或 2048 个点起步。#define IQ_BUF_LEN 1024 void read_iq_data(void) { int8_t iq_buf[IQ_BUF_LEN * 2]; // I 和 Q 各占一个字节 int ret phy_get_iq_data(iq_buf, IQ_BUF_LEN); if (ret ! 0) { printf(IQ read failed: %d\n, ret); return; } for (int i 0; i 16; i) { int8_t i_val iq_buf[i * 2]; int8_t q_val iq_buf[i * 2 1]; printf(IQ[%d]: I%d, Q%d\n, i, i_val, q_val); } }第四步处理数据。最简单的处理是算每个采样点的功率power I*I Q*Q。把连续多个点的功率画出来你就能看到信号强度的起伏。5.2 参数选择背后的逻辑缓冲区长度为什么选 1024因为 IQ 采样率通常在几 MHz 到几十 MHz 量级1024 个点对应的时间窗口大概是几十到几百微秒。这个窗口足够你看到一次 Wi-Fi 帧的突发又不至于让内存压力太大。如果你想做频谱分析2048 或 4096 个点做 FFT 的频率分辨率会更好但内存占用翻倍。采样格式为什么是 int8因为 ESP32 的基带 ADC 输出常见的是 8 位有符号数I 和 Q 各 8 位合起来 16 位。有些型号支持更高位宽但 8 位对入门足够。5.3 实测现场记录我在一块 ESP32-S3 开发板上跑这套流程周围有一个正在工作的路由器。读出来的 IQ 数据里能明显看到周期性的幅度起伏周期大概对应 Wi-Fi 信标的 100ms 间隔。把功率序列打印成文本图能看到每隔一段就有一个尖峰。这说明 IQ 通路确实捕捉到了真实的空口信号。换成没有路由器的环境数据就变成接近随机的低幅度噪声功率值明显更低。这个对比很直观地证明了数据的真实性——它不是随机数而是真实反映了射频环境。6. 数据怎么用从原始采样到有用信息6.1 算功率最简入门拿到 IQ 数据后最直接的处理就是算瞬时功率。对每个采样点power I*I Q*Q。把连续 N 个点的功率求平均就得到这段时间内的平均信号强度。这个值虽然不能直接对应 dBm但它的相对变化能反映信号强弱。我一般会连续读 10 次每次 1024 点把 10 次的平均功率排成一行打印出来。如果周围有设备在发数据你会看到某些次的功率明显高于其他次。6.2 做 FFT看频谱想看频谱就需要对 IQ 序列做 FFT。ESP32 上可以用esp-dsp库里面有优化过的 FFT 函数。把 1024 个复数点送进去输出 1024 个频点取前一半因为实信号频谱对称你就能看到当前信道的频率分布。这里有个细节IQ 数据的采样率决定了你能看到的频率范围。如果采样率是 20MHz你能观察的带宽就是 20MHz频率分辨率是 20MHz/1024大概 19.5kHz。这个分辨率看 Wi-Fi 信道占用足够了看窄带信号就偏粗。6.3 时间序列分析看突发如果你不关心频率只关心“什么时候有信号”那就不用 FFT直接看功率随时间的序列。把每次读到的平均功率按时间顺序存下来画成折线突发的信号会表现为尖峰。这个方法计算量小适合在 ESP32 上实时跑。我用这个方法做过一个简单的“信道忙闲指示器”功率超过阈值就点亮板载 LED低于阈值就熄灭。效果还挺灵敏路由器一发信标灯就闪一下。7. 常见问题与排查技巧实录7.1 读出来全是 0 或者全是固定值这是最常见的问题。原因通常有三个一是 PHY 没进入接收模式还在正常收发状态二是缓冲区指针或长度参数传错了三是芯片型号不支持这条通路。排查顺序建议先确认芯片型号再确认 PHY 状态最后检查参数。7.2 数据看起来像随机噪声如果功率值一直很低且没有起伏可能是天线没接好或者周围确实没有强信号源。先拿到路由器旁边试如果还是噪声检查天线连接。另外有些模块的射频前端有屏蔽罩IQ 数据质量会受影响。7.3 编译时报符号未定义说明你的 IDF 版本没有把 PHY 调试接口编译进来。去menuconfig里找 PHY 相关选项把调试功能打开。如果找不到对应选项可能需要换 IDF 版本或者手动在 CMakeLists 里链接对应的库。7.4 读取时系统崩溃或重启大概率是缓冲区越界或者 PHY 状态冲突。检查缓冲区大小是否和传入的长度参数匹配确认读取时 Wi-Fi 没有在收发数据。如果还崩试着降低采样点数量从 256 开始。问题现象可能原因排查动作数据全 0PHY 未进入接收模式确认 Wi-Fi 已停止收发数据全固定值参数传递错误检查缓冲区和长度数据像噪声天线或环境问题换到强信号环境测试编译符号未定义IDF 未开启 PHY 调试检查 menuconfig 选项运行崩溃缓冲区越界缩小采样点数量重试7.5 几个独家避坑心得第一不要连着 AP 读 IQ这是我踩过最大的坑浪费了大半天。第二先用小缓冲区跑通再加大256 点能跑通再上 1024不然崩溃了不好定位。第三打印数据用文本图把功率值用字符画出来比看一堆数字直观得多。第四不同 IDF 版本符号名会变别死记硬背函数名学会在头文件里搜关键词。8. 这条通路还能怎么扩展跑通基础读取之后能玩的方向其实不少。往边缘 AI方向走你可以把 IQ 数据做特征提取喂给一个轻量级分类器做简单的信号类型识别比如区分 Wi-Fi 和蓝牙。往低功耗感知方向走你可以让 ESP32 周期性醒来读一小段 IQ判断环境有没有变化没变化就继续睡适合做电池供电的环境监测。往教学演示方向走这条通路是讲射频原理的绝佳素材。学生能亲眼看到 IQ 数据、亲手算功率、亲手做 FFT比看课本上的公式直观一百倍。我自己就用它给朋友讲过“为什么 Wi-Fi 信号是复数”效果比画图好得多。需要提醒的是这条通路官方不承诺稳定性不同批次芯片、不同 IDF 版本都可能有差异。把它当学习工具和实验手段没问题但别把它用在量产产品里除非你做好了充分的兼容性测试。我个人在实际操作中的体会是这条通路最大的价值不在于它能做出什么产品而在于它把射频这个“黑盒”打开了一条缝让你能真正看见无线电的样子。