Wi-Fi 信号如何变成“人体检测雷达“？ESP32 CSI 工具包完整上手指南

Wi-Fi 信号如何变成"人体检测雷达"？ESP32 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 是 Espressif（乐鑫）推出的开源工具包，它让普通 ESP32 开发板读取 Wi-Fi 信道状态信息（CSI），从而在不安装摄像头的前提下实现人体检测、动作感知与室内定位。本文不堆术语，先用一个生活化比喻讲透原理，再手把手带你完成烧录固件、看到波形、四步跑通自己的第一个 CSI 应用。

第一幕 · 开篇钩子：凌晨亮起的灯，和一场"无摄像头"的改造 🎬

独居老人的房间里，家人想确认"人是否安全在家"。装摄像头，隐私别扭；装红外传感器，位置刁钻，还常被窗帘和宠物误触。于是冒出一个念头：能不能让那台常年开着的路由器兼任"哨兵"？

别急着怀疑。Wi-Fi 信号在室内传播时，本就会被墙壁、家具、人体反复反射和吸收，而 CSI（信道状态信息）就是把这种"反弹痕迹"量化下来的数据。esp-csi 恰好把"读取 CSI"这件事做成了几行可烧录的固件，让 ESP32 开发板直接变身"无线感知雷达"，而且全系芯片通用——从 ESP32、ESP32-C3 到 ESP32-C5/C6，都能玩。

第二幕 · 通俗原理：CSI 就是给房间"拍了张 CT" 📡

把房间想象成一池静止的水：路由器投下一颗石子，水波向四周扩散，撞到墙、沙发、还有你，反弹出无数圈涟漪——这就是多径传播。人往池边挪一步，涟漪图案立刻变化。

• RSSI 像音量旋钮，只告诉你"这声浪整体有多大"；
• CSI 像完整曲谱，把每一圈涟漪（每个子载波）的幅度与相位都记了下来。

人体含水量高、又会移动，是改变涟漪图案最明显的"变量"。所以当 CSI 波形发生扰动，基本等于房间里有活物在动；甚至连呼吸引起的胸腔起伏，都会在数据里留下痕迹。下图展示了信号从发射到信道估计的完整链路，CSI 正是在"信道估计"环节被提取出来的。

想深挖 OFDM、多径、相位这些概念，仓库docs/目录下配有配套基础文档（Signal-Processing-Fundamentals、OFDM-introduction、Wireless-Channel-Fundamentals 等），新手也能顺着读下去。

第三幕 · 从 0 到 1 实战：四步跑通你的第一条 CSI 数据流 🔧

第 1 步 准备：先想清楚"数据从哪条路来"

拿到 CSI 之前，得先确定发包的一方是谁。仓库提供了三条采集路线，按部署成本从低到高排列：

路线一：借道路由器（一块板就能玩）ESP32 向路由器发一个 Ping 请求，路由器回复的响应包里就夹带着 CSI。整条链路只需一块 ESP32 加一个现成路由器，最适合第一次上手。

路线二：设备对传（两块板互相当靶子）两块 ESP32 都连上路由器，A 板接收 B 板发来的数据包并提取 CSI。它不依赖路由器摆在哪儿，也不受路由器下挂其他设备的影响，数据来路更纯粹。

路线三：专用发包机（多设备集群定位首选）一个专门设备不断切换信道广播数据包，多块 ESP32 同时接收。精度与可靠性最高，对网络环境打扰最小，适合多人多设备联合的室内定位场景。

建议第一次选路线二：它对应仓库里现成的 csi_send + csi_recv 两个工程，硬件上只需两块 ESP32 开发板（推荐 ESP32-C5 / ESP32-C6）、两条数据线。为什么要强调天线：尽量用外置 IPEX 天线，PCB 天线方向性强、易受主板干扰；两块板间距保持在 1 米以上，太近时波形里全是直达波，反而看不出人体扰动。

第 2 步 安装配置：搭好 ESP-IDF 并拉取代码

CSI 固件需要 ESP-IDF 工具链编译，建议使用 v5.0.0 及以上版本（该版本起支持目的地址过滤，采集效果更好）。然后克隆仓库：

git clone https://gitcode.com/GitHub_Trending/es/esp-csi cd esp-csi

为什么要这么做：固件编译依赖完整的 ESP-IDF 环境，提前装好能避免烧录阶段反复踩环境坑。

第 3 步 首次运行：烧录"一收一发"两块板

先给发送端（板 A）烧 csi_send：

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

再给接收端（板 B）烧 csi_recv：

cd examples/get-started/csi_recv idf.py set-target esp32c3 idf.py flash -b 921600 -p /dev/ttyUSB1

串口号按你电脑上的实际设备调整（ls /dev/ttyUSB*可查看）。为什么要先烧发送端：接收端一开机就等着对端发包，发送端先就位，才能看到稳定的 CSI 数据流。烧录正常时，两块板的串口会输出类似下图的日志：

第 4 步 效果验证：让子载波波形"活"起来

先关闭接收端的idf.py monitor，再运行可视化脚本：

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

为什么要关掉 monitor：Python 脚本和 monitor 会抢同一个串口，同时运行必然丢数据。脚本启动后会弹出一个实时绘图窗口，一根根曲线就是各个子载波的 CSI 幅度/相位。这时让人在两块板之间走动，曲线会明显抖动——看到这一幕，说明你的第一条 ESP32 CSI 数据流已经打通。

顺手认识一下原始数据：串口里每行 CSI_DATA 结尾的方括号数组，按"虚部在前、实部在后"的顺序存放每个子载波的复数信道响应；前面的字段是元信息（RSSI、速率、信道、噪声底等）。看不懂没关系，先跑通，再回看csi_data_read_parse.py的解析逻辑，会轻松很多。

第四幕 · 亮点与延展：从"看得见波形"到"真能派上用场" 🚀

亮点一：esp-radar 可视化平台，把 CSI 翻译成"房间状态"

光看波形太原始，examples/esp-radar/console_test提供了一个带图形界面的分析平台：启动前先做一次"无人校准"，让系统记住空房间的基线；之后它就能持续输出"有人/无人、运动/静止"的判断，还能按分钟/小时/天统计人员运动次数，甚至把指定动作的 CSI 数据采集下来供机器学习使用。

运行方式同样简单：给接收板烧 console_test 固件，然后执行python esp_csi_tool.py -p /dev/ttyUSB1（注意走 UART 口而非 USB Serial/JTAG 口）。对研究者来说，这也是观察"天线摆放、人体位置、设备朝向"如何影响信号的最直观工具。

亮点二：wifi_sensing_demo，自带状态灯和网页监控的最小传感方案

examples/esp-radar/wifi_sensing_demo基于 esp_wifi_sensing 组件封装出更"成品化"的玩法：板载 LED 直接反映检测状态，浏览器打开 Web Serial 页面就能实时看诊断数据、在线调参，无需另装桌面软件。想做智能家居"人在感应"原型的，这条路线最省事。

亮点三：esp-crab，把感知精度推近毫米级

examples/esp-crab用两片 ESP32-C5 共享晶振做相位同步，支持"自发自收"和"单发双收"两种模式，通过对比信号相位差，对近距离微小扰动做出毫米级响应。这是面向研究前沿的硬件方案，双天线 PCB 与两种外壳形态均已开源，适合对精度有执念的进阶玩家。

谁适合玩，以及三个常见坑

这套工具包的受众很宽：想给老宅做"无感看护"的智能家居玩家、研究 Wi-Fi 感知的学生、做安防或养老监护产品原型的工程师，都能各取所需。但下手前记住三条经验：

1. 天线决定上限：优先外置 IPEX 天线，PCB 天线方向性强，信号容易"听偏"。
2. 测试要清场：校准和采集最好在无人环境进行，别人的走动会直接污染基线数据。
3. 卡顿先看串口：Python 绘图很吃 CPU，绘图卡顿导致串口丢包时，试着调高波特率，并确认没有其他程序占用串口。

下一步：沿着官方文档的台阶往上走

想系统学透，仓库docs/下的六篇基础文档已按难度排好：先从 Signal-Processing-Fundamentals 入手理解信号，再看 OFDM-introduction 弄清子载波，接着用 Wireless-Channel-Fundamentals 学信道、Introduction-to-Wireless-Location 学定位、Wireless-indicators-CSI-and-RSSI 看指标差异，最后读 CSI-Applications 纵览应用全景。实践路径建议按 get-started → esp-radar → esp-crab 的顺序递进。

今天文章里讲到的三张架构图、两种固件、一个 Python 脚本，已经足够让你在晚饭前跑通第一版"人体检测雷达"。剩下的事很简单：插上板子，走两步，看看波形。

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