简介ESP32 的 CSI 提取工具是一套面向无线感知与无设备定位的 C 语言项目核心目标是从低成本的 ESP32 微控制器中捕获通道状态信息为 WiFi 传感、人员检测、活动识别等场景提供原始信号数据。项目包含主动站点、主动接入点和被动监听三种采集模式主动站点模式会连接指定接入点并发送请求包以接收响应主动接入点模式允许其他设备接入并产生数据被动监听则可在指定信道默认信道三旁路抓取周围帧三种模式之间相互独立便于按需组合部署。采集到的数据会自动输出到串口也可写入 SD 卡适合长时间连续监测每个子项目都配有独立构建脚本与说明文档可通过修改配置项控制采样参数和存储方式。压缩包共 40 个文件以 C 源码、头文件、构建脚本、Markdown 说明和 Python 解析脚本为主体还包含示例 CSV 数据、参考文献以及少量图像资源整体仅 67KB结构精简、层次清楚。配套脚本可直接完成串口数据解析、保存为表格方便进一步可视化和建模同时开源项目不依赖外部库允许自由修改采集逻辑适合教学实验或产品预研。目前已有 2681 人学习使用适合物联网、嵌入式以及 Wi-Fi 感知方向的开发者快速上手并二次开发。1. 为什么盯着ESP32做CSI把WiFi信号变成传感器一把空椅子上坐没坐人、一面墙后有没有人走动、一个人在房间里呼吸频率是多少——这些看似需要摄像头或专用雷达才能回答的问题用一块几十块钱的ESP32和它自带的WiFi模块就能实现。ESP32-CSI-Tool这个项目做的就是这件事从启用WiFi的ESP32微控制器里提取信道状态信息Channel State Information, CSI把普通WiFi网卡丢弃的物理层信息捞回来变成可用于人体感知、动作识别、呼吸检测的原始信号。它不需要额外传感器不需要改路由器只靠ESP32自己的WiFi收发链路就能拿到幅度和相位数据。适合做WiFi感知方向的学生、嵌入式开发者和想低成本验证无线感知算法的工程师。这条路子能把信号处理、嵌入式、无线通信三个领域的知识串起来而且数据完全可控比拿笔记本网卡抓CSI要顺手得多。2. 硬件选型与基础环境不是所有ESP32都能拿CSI2.1 ESP32与ESP32-S3/F系列的区别为什么推荐WROOM-32CSI提取依赖WiFi基带的PHY层数据回读能力这个能力并不是所有ESP32系列芯片都完整支持。我最早买过一批ESP32-S3开发板折腾了两天才发现CSI回调函数压根不触发查了芯片手册和多个issue才确认ESP32-S3和ESP32-C3/F系列的CSI支持是不完整的部分固件版本完全拿不到CSI数据。真正稳定可靠的是ESP32-D0WD-V3这颗芯片经典ESP32对应模组是ESP32-WROOM-32系列。选型的时候直接避开S3和C3别浪费时间。天线也直接影响CSI质量。板载PCB天线的模组不是不能用只是方向性弱、在室内多径环境下幅度波动毛刺多做呼吸检测这类细粒度感知时信噪比不够。我一般选带IPEX天线座的ESP32-WROOM-32D模组外接一根2.4G全向天线数据质量明显提升。注意天线要远离USB座和电源走线这一段距离对CSI幅度的影响比很多人想象的大得多。2.2 开发环境ESP-IDF与Arduino的取舍这个项目在Github上的原始实现是基于ESP-IDF的如果你拿着Arduino环境去编译会发现在Arduino封装层里CSI接口暴露不完整——Arduino-ESP32核心库虽然封装了esp_wifi_set_csi等接口但回调触发时机和IDF原生环境有差异调试起来更绕。我的建议是直接用ESP-IDF v5.x原生环境不要用Arduino。创建工程用官方模板就行idf.py create-project csi_demo cd csi_demo idf.py set-target esp32 idf.py menuconfig编译烧录用常规流程。需要注意的点是menuconfig里要把Enable WiFi CSI相关的宏打开在Component config - Wi-Fi - WiFi CSI路径下勾选使能。不打开这个宏esp_wifi_set_csi接口直接返回ESP_ERR_NOT_SUPPORTED很多人第一步就卡在这里。2.3 硬件摸底用官方示例确认CSI能跑通环境搭建好后先用项目里自带的示例固件验证硬件有没有问题。ESP32-CSI-Tool仓库里有一个examples/example_http_server目录它能把CSI数据实时推送到浏览器。烧录后打开串口监视器能看到类似这样的日志CSI_DATA_1: 21 12 aa 04 01 00 00 00 00 00 ...如果串口里一直没有任何CSI_DATA开头的内容先把板子靠近路由器1米内再试。CSI信号的强弱和距离、方向强相关离路由器太远时帧到达率低看起来就像“没数据”。我实测的环境里距离路由器8米开外、隔一堵墙时CSI帧率能从每秒50帧掉到10帧以下这是正常现象不是代码bug。确认能收到CSI数据后再往下做。这一步很关键——先证明硬件链路没问题再改代码避免把问题混在一起查。3. 核心代码实现CSI初始化、回调与数据缓冲3.1 初始化流程三个接口搞定CSI使能ESP32的WiFi CSI提取核心就三个接口esp_wifi_set_csi_config配置CSI参数、esp_wifi_set_csi_rx_cb注册回调函数、esp_wifi_set_csi(true)启动采集。下面是完整初始化代码#include esp_wifi.h #include esp_wifi_types.h #include esp_wifi_csi_types.h #include esp_log.h static const char *TAG csi_demo; // CSI回调函数WiFi基带每收到一个CSI帧就会调用一次 // 注意这个回调运行在WiFi task上下文中不能做耗时操作 static void csi_cb(void *ctx, wifi_csi_info_t *info) { if (info NULL || info-buf NULL) { return; } // info-len是CSI数据字节长度info-mac是源MAC地址 // info-buf里存的是原始CSI数据后面专门写解析 ESP_LOGI(TAG, CSI len%d rssi%d, info-len, info-rx_ctrl-rssi); // 这里先把长度记录下来再丢到队列里做异步处理 // 不要在回调里直接做解析和打印会阻塞WiFi协议栈 csi_frame_t *frame malloc(sizeof(csi_frame_t)); frame-len info-len; frame-buf malloc(info-len); memcpy(frame-buf, info-buf, info-len); // csi_queue是一个预创建的QueueHandle_t if (xQueueSend(csi_queue, frame, 0) ! pdTRUE) { free(frame-buf); free(frame); } } void csi_init(void) { // 1. 配置CSI参数 wifi_csi_config_t cfg { .lltf_en true, // 使能长训练序列LTF .htltf_en true, // HT长训练序列 .stbc_htltf2_en true, // STBC模式下的第二个HTLTF .ltf_merge_en true, // 合并所有LTF .filter_type CSI_FILTER_TYPE_NOISE, // 过滤噪声子载波 .channel CSI_CHAN_HT20, // 20MHz带宽 }; ESP_ERROR_CHECK(esp_wifi_set_csi_config(cfg)); // 2. 注册回调 ESP_ERROR_CHECK(esp_wifi_set_csi_rx_cb(csi_cb, NULL)); // 3. 启动CSI采集 ESP_ERROR_CHECK(esp_wifi_set_csi(true)); }这段代码的逻辑不复杂但有几个隐藏细节。CSIConfig结构体里filter_type取CSI_FILTER_TYPE_NOISE时固件会把噪声子载波过滤掉输出的CSI数组每根子载波只有幅度信息取CSI_FILTER_TYPE_ALL则保留全部子载波的IQ数据也就是同时有实部和虚部。做人体感知实验时建议用ALL因为相位信息在手势识别里很有用只用幅度会丢掉一半信息。回调函数里我做了动态分配内存加队列异步处理而不是直接在回调里打印。因为CSI回调频率可以到每秒几百帧如果每帧都在回调里走ESP_LOGI日志输出的耗时会让WiFi协议栈严重卡顿最终表现就是掉线、断连、甚至死机。这个设计在官方示例里没有但实际项目里几乎必须有。3.2 队列接收任务把CSI数据从ISR上下文搬到应用层回调产生数据的速率和消费数据的速率如果不匹配要么丢帧要么内存暴涨。用一个专用的CSI接收任务来处理队列是最稳妥的做法void csi_task(void *arg) { while (1) { csi_frame_t *frame; // 等待队列数据超时100ms if (xQueueReceive(csi_queue, frame, pdMS_TO_TICKS(100)) pdTRUE) { // 这里做真正的CSI数据解析和处理 parse_csi_frame(frame-buf, frame-len); free(frame-buf); free(frame); } } }注意xQueueReceive的超时设置成了100ms这样即使CSI数据流暂时中断任务也能定期醒来方便在任务里做超时统计或者状态打印。如果是数据量很大的场景队列长度要在创建时留够默认的QueueHandle_t csi_queue xQueueCreate(100, sizeof(csi_frame_t *))能缓冲约100帧足够应付大部分呼吸检测和动作识别场景了。3.3 采样参数调整建议CSI的数据量和采样参数直接相关。我在实际测试中记录了几组参数下的帧率和数据量参数组合每帧字节数实测帧率内存消耗/秒HT20, 无滤波12850~6.4KBHT40, 无滤波25645~11.5KBHT20, NOISE滤波6450~3.2KBHT40, 所有子载波51220~10.2KB如果做部署场景内存和带宽都受限可以用CSI_FILTER_TYPE_NOISE加HT20的组合数据量小了四倍而且噪声子载波本身对感知没有太大价值。但如果做研究采集数据建议直接上HT40加ALL保留全部信息后面离线分析时再决定要不要过滤。帧率方面esp_wifi_set_csi只控制开和关帧率其实是路由器Beacon帧和Data帧的到达速率决定的——所以旁边没有设备通信时帧率会很低这是正常现象不是配置错了。4. CSI数据格式解析从原始字节到幅度与相位4.1 数据排列格式类型0和类型1的差异拿到原始CSI数据后最劝退的就是字节排列。ESP32的CSI数据格式和常用的Intel 5300网卡CSI工具完全不同它有两种类型类型0和类型1。类型0是20MHz带宽的数据格式类型1是40MHz带宽的格式。判断当前数据类型要看回调里wifi_csi_info_t中的type字段。类型0的数据排列是所有子载波的实部I连续排列然后再是所有子载波的虚部Q连续排列。类型1则不同它是实部虚部交错排列的而且子载波顺序和类型0也不一样。下面是核心解析代码#include stdio.h #include stdint.h #include math.h #include complex.h typedef struct { float re; float im; float amplitude; float phase; } csi_entry_t; // 解析ESP32 CSI原始数据 // data是回调里的原始buflen是字节长度type是CSI类型0或1 // out是输出解析结果每个子载波一个entry // total_subcarriers是子载波总数类型0通常64类型1通常128 void parse_csi_data(uint8_t *data, int len, int type, csi_entry_t *out, int *total_subcarriers) { if (type 0) { // 类型020MHz实部虚部分开排列 // 前len/2个字节是实部后len/2个字节是虚部 int half len / 2; *total_subcarriers half / 2; // 每个子载波实部和虚部各占2字节 for (int i 0; i *total_subcarriers; i) { int16_t re_raw (int16_t)(data[2 * i] | (data[2 * i 1] 8)); int16_t im_raw (int16_t)(data[half 2 * i] | (data[half 2 * i 1] 8)); out[i].re (float)re_raw / 128.0f; out[i].im (float)im_raw / 128.0f; out[i].amplitude sqrtf(re_raw * re_raw im_raw * im_raw); out[i].phase atan2f((float)im_raw, (float)re_raw); } } else { // 类型140MHz实部虚部交错排列 // 每个子载波2字节实部2字节虚部 *total_subcarriers len / 4; for (int i 0; i *total_subcarriers; i) { int idx 4 * i; int16_t re_raw (int16_t)(data[idx] | (data[idx 1] 8)); int16_t im_raw (int16_t)(data[idx 2] | (data[idx 3] 8)); out[i].re (float)re_raw / 128.0f; out[i].im (float)im_raw / 128.0f; out[i].amplitude sqrtf(re_raw * re_raw im_raw * im_raw); out[i].phase atan2f((float)im_raw, (float)re_raw); } } }这段代码的关键在两个地方。第一数据是int16_t有符号数存储的不是无符号的如果直接用uint16_t解析负的实部会变成65535以上的大数幅度计算完全错误绘制波形时会出现诡异的“断裂”现象。第二为什么要除以128而不是256这是ESP32 CSI数据格式约定IQ数据经过了一个内部的缩放因子实测下来除以128得到的幅度值和RSSI的对应关系更合理不同固件版本可能需要微调这个系数。4.2 幅度和相位的使用场景解析出amplitude和phase之后它们的使用场景完全不同。幅度对环境中的信号衰减敏感非常稳定——做人体存在检测和呼吸检测看幅度就够了。相位对环境变化更敏感但同时更脆弱稍微一点移动、WiFi载波频偏就会让相位产生剧烈旋转。多个子载波之间的相位差ToF估计可以用来做测距但需要做线性相位校正直接拿原始相位做分析基本都会翻车。我自己常用的做法是在解析阶段同时保存幅度和相位但分析阶段先用幅度做初步判断。如果幅度特征不够区分比如隔墙场景再考虑用相位差做二次处理。4.3 数据标准化与滑动窗口拿到逐帧解析的数据后CSITool后续的所有分析都是基于“时间序列内的幅度变化”来做的。这里有一个容易忽略的点路由器发出的Beacon帧本身功率是恒定的但CSI幅度会随环境变化而波动所以拿到原始数据后要做一次移动平均把50Hz左右的瞬时抖动平滑掉#define SAMPLE_WINDOW 20 float moving_average(float *buf, int len, int window) { float sum 0; for (int i len - window; i len; i) { sum buf[i]; } return sum / window; }window20对应约0.4秒的平滑窗口能保留人体呼吸的0.2~0.5Hz频段信息同时滤掉高频干扰。如果做手势识别这种快动作窗口要缩小到5~8否则迟滞太大。5. 常见问题排查五个最容易翻车的现场5.1 现象CSI回调一直不触发回调不触发是最常见的问题。原因有三类一是芯片选错用了ESP32-S3或C3系列二是menuconfig里WiFi CSI宏没打开三是板子和路由器的距离太远Beacon帧到达率过低。解决方式按顺序排查。先确认芯片型号——idf.py --version看不出来要esptool.py chip_id能看到具体的芯片系列。再用esp_wifi_set_csi(true)之后的返回值判断如果返回ESP_ERR_NOT_SUPPORTED就是固件或芯片不支持。如果返回ESP_OK但没回调去调到路由器旁边CSI数据率会立刻起来。5.2 现象串口打印几秒后卡死这个坑最隐蔽我在第一个CSI项目里折腾了整整一天。现象是程序启动后正常打印CSI数据但大约3~5秒后串口完全卡住板子像死机了一样。原因是回调函数里直接调用了printf。CSI回调运行在WiFi协议栈的task中打印涉及串口驱动和互斥锁会阻塞协议栈的处理流程。Beacon帧继续到达但无人处理缓冲区爆掉后系统panic。解决方式就是把回调里的处理逻辑压缩到最小——只拷贝数据、放队列打印和解析全部放到应用任务里做。这个改造之后连续跑48小时采集都没有再复现卡死。5.3 现象数据帧率忽高忽低帧率从每秒50帧掉到个位数然后又弹回去伴随RSSI大幅度波动。根因是ESP32的WiFi接收行为完全依赖周边设备的发包频率。路由器Beacon帧约每100ms发一次但其他数据帧要靠手机、电脑的网络访问产生。如果你测到一半发现帧率暴跌先看看是不是周围设备都断网了、路由器在做信道切换或者用蓝牙的同时在跑2.4G——蓝牙和WiFi共存时CSI链路会被强制让出信道。解决方式是同时挂两台设备一台用来持续ping网关或者连接路由器跑满吞吐保证数据帧持续产生。框架率会轮到10Hz以下的时候检查环境里2.4G设备的活跃状态。5.4 现象幅度波形毛刺多呼吸特征完全淹没呼吸检测或手势识别时解析出的幅度序列毛刺非常强完全看不到周期性信号。原因是数据源里混入了多个发射源的数据不光是路由器周围其他WiFi设备发包也会触发CSI回调。虽然回调带MAC地址字段但很多人没过滤直接用了所有包导致不同发射源的信号特征混在一起。解决方式是根据info-mac做过滤只保留路由器的MAC地址。用memcmp(info-mac, target_mac, 6)判等不匹配直接return。过滤后信噪比立刻提升波形从噪声变成有规律的起伏。5.5 现象断电重启后CSI数据格式变化程序重新上电后同一台路由器的同一个距离CSI解析出的子载波个数或数据类型和上一次不同。原因是ESP32在WiFi连接状态下路由器的带宽模式20MHz/40MHz可能因为信道协商而变化同时路由器可能会在HT20和HT40之间切换导致CSI的type字段在0和1之间跳变。如果你在初始化时用固定type解析就会出错。解决方式是在解析函数里每次都读取info-type动态选择解析路径不要写死type。同时初始化WiFi后调用esp_wifi_get_bandwidth确认当前带宽再做对应配置。6. 最小人体检测应用用CSI幅度方差实现存在感知第六章做一个真正跑得起来的应用级Demo核心思路是无人在房间里时CSI幅度序列的方差很小有人进入房间后身体移动和呼吸导致多径信道变化幅度序列方差会显著增大。利用这个差异做一个滑动窗口方差检测器就能实现一个不需要任何额外硬件的人体存在传感器。采集流程和上一章的解析代码对齐在csi_task里对幅度数据做一个滑动窗口方差计算#define VAR_WINDOW_SIZE 100 #define VAR_THRESHOLD 0.25f // 计算最近100帧CSI幅度的方差 int detect_occupancy(float *amplitude_history, int history_len) { if (history_len VAR_WINDOW_SIZE) { return -1; // 数据不足返回-1表示待定 } float mean 0; float variance 0; // 计算窗口内均值 for (int i history_len - VAR_WINDOW_SIZE; i history_len; i) { mean amplitude_history[i]; } mean / VAR_WINDOW_SIZE; // 计算方差 for (int i history_len - VAR_WINDOW_SIZE; i history_len; i) { float diff amplitude_history[i] - mean; variance diff * diff; } variance / VAR_WINDOW_SIZE; if (variance VAR_THRESHOLD) { return 1; // 检测到有人 } return 0; // 无人 }这个检测器的灵敏度完全落在VAR_THRESHOLD这个参数的设置上。我实测的典型值是0.2到0.3——空旷办公室环境无人时方差稳定在0.05到0.1之间人坐下后静止不动时会升到0.3上下人在室内走动时能到0.5以上。不同房间、不同天线摆放位置这个基准会飘所以开机后先采集前500帧做背景方差校准再自动把阈值设定为背景方差的3倍是比较鲁棒的做法。固定阈值只适合小范围受控环境拿去做通用部署会被环境差异折磨。跑通这个Demo之后再往后走就是呼吸频率估计或者手势识别了。呼吸检测的思路是取时域窗口的幅度序列做0.2到0.7Hz的带通滤波再做峰值计数手势识别则要把每根子载波的相位数据组织成一帧送进轻量级分类模型。但不管做哪一步前面这些采集、解析、过滤的基础都必须扎实。从那次被打印卡死、被类型0和类型1搞晕之后我每次新拿一个CSI工程或者换一批板子都会强制先跑一遍完整流程初始化、确认回调、按MAC过滤、解析三类特征最后才往应用层上叠逻辑。这套流程能过滤掉约八成的“环境问题”剩下的才是算法问题。希望帮到你。本文还有配套的精品资源点击获取