如何用ESP32 Wi-Fi CSI实现无接触人体检测？从原理到上手的完整指南

如何用ESP32 Wi-Fi CSI实现无接触人体检测？从原理到上手的完整指南

【免费下载链接】esp-csiApplications based on Wi-Fi CSI (Channel state information), such as indoor positioning, human detection项目地址: https://gitcode.com/GitHub_Trending/es/esp-csi

一个不需要摄像头的"监视器"

下班回家前想确认家里没人闯入，实验室里想记录人员的活动轨迹，甚至只想做一个"人离开就自动关灯"的小装置——这些需求过去往往依赖摄像头或红外传感器。而开源项目esp-csi给出了另一种答案：利用 ESP32 芯片自带的信道状态信息（CSI）采集能力，把再普通不过的 Wi-Fi 信号变成感知工具，实现无接触的人体检测与室内定位。你无需改装任何硬件，一块几十元的开发板就能让信号"看见"房间里的动静，而且全程不涉及隐私画面，部署成本低到几乎没有门槛。

为什么 RSSI 看不见，CSI 却能"透视"？

Wi-Fi 信号在传播途中会被墙壁、家具和人体反复反射，形成多条路径。传统指标 RSSI 只报告"信号总强度有多大"，就像一个只给你音量数字的音响，任何一点干扰都会让读数变得含糊不清。

而 CSI 完全不同：它记录了每个子载波的幅度与相位，相当于把整首"交响乐"的乐谱完整交到你手上。当一个人走过信号路径时，各路反射波的叠加关系发生细微改变，CSI 波形随之起伏；哪怕只是坐着呼吸，静态环境中的 CSI 也会产生可检测的扰动。对变化越敏感，能感知的动作就越精细——这正是它天然适合人体检测的根本原因。

上图展示了从符号映射、信道估计到解调的完整链路，CSI 正是信道估计环节的"副产品"，无需额外传感器即可获得。

三种 CSI 数据来源，按场景对号入座

拿到数据之前，先想清楚信号从哪来。项目提供了三条可选路径，各有各的适用土壤：

部署形态	需要什么设备	亮点	适合谁
借助家用路由器	1 块 ESP32 + 现有路由器	成本最低，插上就能用	入门尝鲜、单房间检测
双机互发数据包	2 块 ESP32	不依赖路由器位置与负载	已有多个开发板的爱好者
专用广播发射机	1 个发包设备 + 多块 ESP32	精度最高、多机同时收	定位系统、研究实验

借助路由器的思路最直白：ESP32 向路由器发送 Ping 包，再从回包中提取 CSI，全程只有两台设备参与，适合作为你的第一次尝试。双机协作则让两块开发板都接入路由器并互发数据包，接收方从对方的数据帧里解析 CSI，绕开了对路由器摆放位置的依赖。

如果目标是搭建多设备定位网络，专用广播方案更值得投资：发包设备持续切换信道广播数据，多块 ESP32 同时接收，检测一致性最好，也不会被路由器下挂的其他设备抢信道。

开箱前先备好三样东西

1. 两块 ESP32 开发板：推荐 ESP32-C5 / ESP32-C6（射频性能出色），其实 ESP32 全系列都支持 CSI。
2. 外置 IPEX 天线：板载 PCB 天线有方向性且易受主板干扰，实测效果差一截。
3. 一个安静的环境：两台设备间距保持 1 米以上，测试时房间内尽量无人，避免他人走动污染数据。

另外，Wi-Fi 信道尽量选空闲的——拥挤信道会让丢包率明显上升，直接影响 CSI 数据质量。

十分钟跑通第一行 CSI 数据

克隆项目仓库（git clone https://gitcode.com/GitHub_Trending/es/esp-csi）后进入examples/get-started目录，把csi_send固件烧到发送板、csi_recv固件烧到接收板：

cd esp-csi/examples/get-started/csi_send idf.py set-target esp32c3 idf.py flash -b 921600 -p /dev/ttyUSB0 monitor cd esp-csi/examples/get-started/csi_recv idf.py set-target esp32c3 idf.py flash -b 921600 -p /dev/ttyUSB1

两块板子通电后，接收板会通过串口持续吐出 CSI 数据。关闭串口监控，再运行解析脚本即可看到图形化波形：

cd esp-csi/examples/get-started/tools pip install -r requirements.txt python csi_data_read_parse.py -p /dev/ttyUSB1

一行原始数据里藏着什么？

接收板输出的一行 CSI 大致长这样：

CSI_DATA,0,94:d9:b3:80:8c:81,-30,11,...,"67,48,4,0,0,0,..."

开头部分是元数据：类型、MAC 地址、RSSI、速率、噪声底、信道、时间戳等；最后引号里的数组才是核心的 CSI 数据，它按子载波排列，每个子载波先存虚部、再存实部（即[虚1, 实1, 虚2, 实2, ...]）。记住这个顺序，后续做相位解算时就能少踩一个坑。

进阶玩法一：让数据"活"起来

逐行读数字太痛苦？examples/esp-radar/console_test提供了一个完整的 CSI 数据可视化测试平台ESP-CSI Tool：左侧Raw data实时绘制各子载波波形与 RSSI，右侧Radar model直接给出"有人/无人、运动/静止"的判断；还支持行为标注与数据存盘，方便你为机器学习准备训练集。

进阶玩法二：从检测走向真实部署

• 现场训练 + 浏览器监控：wifi_sensing_demo支持现场校准阈值，状态变化直接反映在 LED 上，浏览器端的 Web Serial 页面还能实时调参，非常适合快速验证算法。
• 上报云端：connect_rainmaker把"有人/无人、运动次数"等状态推送到 ESP RainMaker 云平台，手机 App 随时查看，做智能家居联动毫无压力。
• 毫米级相位感知：esp-crab通过两片 ESP32-C5 共晶振实现射频相位同步，利用相位信息感知近距离扰动，是研究级精度的进阶选择。

避坑指南：三个常见问题

• 串口报ESP_ERR_ESPNOW_NO_MEM：当前信道拥堵导致发送缓冲占满，换个空闲信道或换到网络环境更好的位置即可解决。
• 解析脚本提示"数据不完整"：多为图形界面占用 CPU 过高、串口缓冲区来不及读取，适当提高波特率能缓解。
• 阈值校不准：校准务必在房间无人时进行，否则会把"人的活动"当成基线，导致后续一连串误判。

现在，动手让 Wi-Fi 开口说话

从一块开发板加一个路由器开始，你可以在半小时内看到属于自己的第一条 CSI 波形；再往前一步，就是人体检测、活动统计，乃至多设备定位。官方文档与全部示例代码都收录在仓库的docs/和examples/目录下，遇到问题随时查阅。装上外置天线、选个空旷信道，让你的 Wi-Fi 第一次"看见"房间吧。

【免费下载链接】esp-csiApplications based on Wi-Fi CSI (Channel state information), such as indoor positioning, human detection项目地址: https://gitcode.com/GitHub_Trending/es/esp-csi