ESPectre：基于Wi-Fi频谱分析的运动检测系统，低成本实现多场景应用！
ESPectre：基于Wi-Fi频谱分析的运动检测系统
ESPectre是一款基于Wi-Fi频谱分析（CSI）的运动检测系统，可通过ESPHome与Home Assistant进行原生集成。新的机器学习探测器采用基于神经网络的运动检测技术，无需校准，可在设备上运行。这是一项实验性功能，欢迎在专门的机器学习探测器讨论区提供反馈。也可获取包含最新更改的快照版本（使用 -ml 资产用于基于机器学习的探测器），或按照设置指南进行自定义配置。
目录要点
1.功能概述：利用Wi-Fi检测运动（无需摄像头和麦克风）。
2.所需条件：约10欧元的ESP32设备（推荐S3和C6，其他型号也支持）。
3.设置时间：10 - 15分钟。
所需条件
硬件
-2.4GHz Wi-Fi路由器：家中现有的路由器即可。
-支持CSI的ESP32：如ESP32 - C6、ESP32 - S3、ESP32 - C3、ESP32（原版）或其他型号。完整的平台比较表请参考SETUP.md。
-带外部天线的ESP32 - S3开发套件
软件（均为免费）
-Home Assistant：可安装在树莓派、PC、NAS或云端。
-ESPHome：可集成在Home Assistant中，也可独立使用。
所需技能
- 具备基本的YAML知识用于配置。
- 熟悉Home Assistant（可选但推荐）。
- 无需编程知识。
- 无需对路由器进行配置。
快速开始
-设置时间：约10 - 15分钟。
-难度：简单（仅需YAML配置）。
-设置与安装：请遵循SETUP.md中的完整指南。
-调试：根据TUNING.md优化系统以适应你的环境。
Home Assistant仪表盘可实现实时运动检测、阈值控制和调试传感器。
工作原理
当有人在房间内移动时，会“干扰”路由器和传感器之间的Wi-Fi信号，就像在手电筒前挥手会看到影子变化一样。ESP32设备“监听”这些变化，从而判断是否有运动发生。
优点
-无摄像头：保障完全隐私。
-无需穿戴设备：无需佩戴手环或传感器。
-穿墙检测：Wi-Fi信号可穿透墙壁。
-成本低廉：总成本约10欧元。
如需了解技术细节，请参考ALGORITHMS.md中的CSI解释和信号处理文档。
应用场景
实际案例
-家庭安全：外出时，若有人进入可收到警报。
-老人护理：监测老人活动，检测跌倒或长时间静止情况。
-智能自动化：有人时自动开启灯光或暖气。
-节能：无人房间自动关闭设备。
-儿童监控：夜间孩子离开房间时发出警报。
-气候控制：仅对有人区域进行加热或制冷。
传感器放置指南
最佳的传感器放置位置对于可靠的运动检测至关重要。
与路由器的推荐距离
| 距离 | 信号强度 | 多径效应 | 灵敏度 | 噪声 | 推荐情况 |
|---|---|---|---|---|---|
| < 2m | 过强 | 最小 | 低 | 低 | ❌ 过近 |
| 3 - 8m | 强 | 良好 | 高 | 低 | ✅ 最佳 |
| > 10 - 15m | 弱 | 不稳定 | 低 | 高 | ❌ 过远 |
放置提示
-建议：将传感器放置在需要监测的区域（不一定要与路由器在同一直线上）；安装高度为离地面1 - 1.5米（桌面高度）；使用IPEX连接器的外部天线以获得更好的接收效果。
-避免：避免路由器和传感器之间存在金属障碍物（如冰箱、金属柜）；避免放置在角落或封闭空间（会降低多径多样性）。
系统架构
处理流程
ESPectre使用专注的处理流程进行运动检测：
┌─────────────┐│ CSI Data │ 原始Wi-Fi信道状态信息└──────┬──────┘ │ ▼┌─────────────┐│ Gain Lock │ AGC/FFT稳定（约3秒）│ │ 锁定硬件增益以实现稳定测量└──────┬──────┘ │ ▼┌─────────────┐│ Auto │ 自动子载波选择（启动时进行一次）│ Calibration │ 选择最佳的12个子载波（NBVI）└──────┬──────┘ │ ▼┌─────────────┐│ Adaptive │ 自动：P95 × 1.1 ；最小：P100│ Threshold │ 或固定手动值└──────┬──────┘ │ ▼┌─────────────┐│ Hampel │ 去除湍流异常值│ Filter │ （默认启用）└──────┬──────┘ │ ▼┌─────────────┐│ Low-pass │ 降噪（平滑处理）│ Filter │ （可选，默认禁用）└──────┬──────┘ │ ▼┌─────────────┐│ Detection │ MVS或ML分数│ Evaluation │ 每evaluation_interval个数据包进行一次评估└──────┬──────┘ │ ▼┌─────────────┐│ Hit Filter │ motion_on_hits / motion_off_hits│ │ 边缘驱动的IDLE ↔ MOTION└──────┬──────┘ │ ▼┌─────────────┐│ Home │ 边缘驱动的运动二进制 +│ Assistant │ 周期性运动分数 / 阈值└─────────────┘
单传感器或多传感器设置
┌─────────┐ ┌─────────┐ ┌─────────┐│ ESP32 │ │ ESP32 │ │ ESP32 ││ Room 1 │ │ Room 2 │ │ Room 3 │└────┬────┘ └────┬────┘ └────┬────┘ │ │ │ └────────────┴────────────┘ │ ▼┌────────────────────┐│ Home Assistant ││ (Auto-discovery) │└────────────────────┘
每个传感器都会被Home Assistant自动发现，包括用于运动检测的二进制传感器（状态变化时立即发布）、周期性发布的运动分数传感器以及可调节的阈值（数字实体）。
自动子载波选择
ESPectre采用NBVI（归一化频带方差指数）进行自动子载波选择，无需手动配置即可实现接近最优的性能（F1 > 96%）。该算法根据稳定性指标和频谱多样性选择12个非连续的子载波。
⚠️重要提示（MVS模式）：设备启动后，请保持房间安静10秒钟。自动校准在此期间进行，运动可能会影响检测精度。ML模式跳过校准。算法详情请参考ALGORITHMS.md。
新手常见问题解答
Q：使用该系统需要编程知识吗？
A：不需要！ESPectre使用YAML配置文件。只需下载示例，进行刷机，然后通过ESPHome应用程序或Web界面配置Wi-Fi即可。
Q：该系统与我的路由器兼容吗？
A：兼容，只要你的路由器支持2.4GHz Wi-Fi（几乎所有现代路由器都支持）。
Q：总费用是多少？
A：硬件方面，ESP32设备约10欧元（推荐S3/C6，其他型号也可）；软件均为免费开源。还需要在某个设备上运行Home Assistant（树莓派约35 - 50欧元，或使用现有的PC/NAS）。
Q：需要对路由器进行修改吗？
A：不需要！路由器正常工作，传感器“监听”Wi-Fi信号，无需对路由器进行任何修改。
Q：该系统能穿墙检测吗？
A：可以，2.4GHz Wi-Fi信号可以穿透石膏板墙。钢筋混凝土墙会降低灵敏度，但在较短距离内仍可检测。
Q：一个房子需要多少个传感器？
A：这取决于房子的大小。一个传感器大约可以监测50平方米。对于较大的房子，建议每50 - 70平方米使用一个传感器以实现最佳覆盖。
Q：该系统能区分人和宠物吗？
A：该系统使用二态分割模型（IDLE/MOTION），可识别通用运动，但无法区分人、宠物或其他移动物体。如需更复杂的分类（如区分人和宠物、活动识别、手势检测），则需要训练AI/ML模型（详见“未来发展”部分）。
Q：该系统与网状Wi-Fi网络兼容吗？
A：兼容，确保ESP32连接到2.4GHz频段即可。
Q：检测精度如何？
A：检测精度高度依赖于环境，需要进行适当的调试。影响性能的因素包括房间布局、墙面材料、家具摆放、与路由器的距离（最佳距离为3 - 8米）以及干扰水平。在最佳条件下并经过适当调试，系统可提供可靠的运动检测。可通过调整segmentation_threshold参数来调整灵敏度以适应特定环境。
Q：功耗是多少？
A：连续运行时典型功耗约为500mW。固件支持电源优化，对于电池供电的部署，可实现深度睡眠模式，但需要对代码进行自定义修改。
Q：如果系统无法正常工作，能获得帮助吗？
A：可以，可在GitHub上创建问题，或通过电子邮件联系我。
安全与隐私
隐私、安全与道德考量
收集数据的性质
系统收集与Wi-Fi无线电信道物理特性相关的匿名数据，包括OFDM子载波的幅度和相位、统计信号方差。不收集个人身份、通信内容、图像和音频。CSI数据仅代表传输介质的属性，不包含直接识别信息。
隐私优势
-无摄像头：尊重视觉隐私。
-无麦克风：不进行音频录制。
-无需穿戴设备：无需佩戴可穿戴设备。
-聚合数据：仅收集统计指标，而非原始识别数据。
⚠️免责声明和道德考量：尽管CSI数据本质上是匿名的，但该系统可能被用于非自愿监测（在未获得明确同意的情况下检测人员的存在/运动）、行为分析（通过先进的AI模型推断日常生活模式）和侵犯家庭隐私（跟踪私人住宅内的活动）。
使用责任
用户对系统的使用负全部责任，必须做到：
- 获得所有被监测人员的明确同意。
- 遵守当地法规（如欧盟的GDPR、当地隐私法）。
- 明确告知传感系统的存在。
- 仅将系统用于合法目的（如家庭安全、个人家庭自动化）。
- 使用加密和受控访问保护数据。
- 不得将系统用于非法监视、跟踪或侵犯他人隐私。
技术深度剖析
算法详情（MVS、NBVI校准、Hampel滤波器）请参考ALGORITHMS.md。性能指标（混淆矩阵、F1分数、基准测试）请参考PERFORMANCE.md。
双平台策略
本项目采用双平台方法，以平衡创新速度和生产稳定性：
ESPectre（本仓库） - 生产平台
-目标用户：终端用户、智能家居爱好者、Home Assistant用户。
-特点：ESPHome组件，与Home Assistant原生集成；使用YAML配置，无需编程；自动发现，设备可自动出现在Home Assistant中；生产就绪，稳定、经过测试且易于部署；具有演示性，以用户友好的方式展示研究成果。
Micro - ESPectre - 研发平台
-目标用户：研究人员、开发者、学术/工业应用。
-特点：采用Python/MicroPython实现，可快速原型开发；基于MQTT，集成灵活（不限于Home Assistant）；迭代速度快，可在数秒内测试新算法；具备分析工具，可对CSI数据进行全面分析。
-应用场景：学术研究、工业传感、算法开发。
-功能基础：人员计数、活动识别（行走、跌倒、坐立、睡眠）、定位和跟踪、手势识别。
开发流程
┌─────────────────────┐ Validated ┌──────────────────────┐│ Micro-ESPectre │ ─────────────────► │ ESPectre ││ (R&D Platform) │ algorithms │ (Production Platform)││ │ │ ││ • Fast prototyping │ │ • ESPHome component ││ • Algorithm testing │ │ • Home Assistant ││ • Data analysis │ │ • End-user ready ││ • MQTT flexibility │ │ • Native API │└─────────────────────┘ └──────────────────────┘
创新周期：新功能和算法首先在Micro - ESPectre（Python）中开发和验证，一旦证明有效，再移植到ESPectre（C++）。
未来发展
ESPectre v2.x主要专注于运动检测（MVS + 自动子载波选择），同时项目也在探索机器学习能力以实现高级应用：
| 功能 | 状态 | 描述 |
|---|---|---|
| ML探测器 | 实验性 | 神经网络（MLP 9→32→16→1） |
| 手势识别 | 计划中 | 检测手势（滑动、推、画圈）以实现智能家居控制 |
| 人类活动识别 | 计划中 | 识别活动（坐、走、跌倒） |
| 人员计数 | 计划中 | 估计房间内的人数 |
| 3D定位 | 研究中 | 通过相位相干天线阵列实现室内定位（精度30 - 50厘米） |
ML探测器已可在YAML配置中使用detection_algorithm: ml。算法详情请参考ALGORITHMS.md，当前指标请参考PERFORMANCE.md。ML数据收集和训练基础设施文档请参考ML_DATA_COLLECTION.md。详细计划、时间表和贡献方式请参考ROADMAP.md。
文档
ESPectre（生产）
| 文档 | 描述 |
|---|---|
| 简介（本文档） | 项目概述、快速开始、常见问题解答 |
| 设置指南 | 使用ESPHome进行安装和配置 |
| 调试指南 | 参数调试以实现最佳检测效果 |
| 性能 | 基准测试、混淆矩阵、F1分数 |
| 游戏 | 浏览器游戏、USB流API、交互式阈值调试 |
| 测试套件 | PlatformIO Unity测试文档 |
Micro - ESPectre（研发）
| 文档 | 描述 |
|---|---|
| 简介 | 研发平台概述、CLI、MQTT、Web监控 |
| 算法 | MVS、NBVI校准、Hampel滤波器的科学文档 |
| 分析工具 | CSI分析和优化脚本 |
| ML数据收集 | 构建用于机器学习的标记数据集 |
| 参考文献 | 学术论文和研究资源 |
项目文档
| 文档 | 描述 |
|---|---|
| 路线图 | 项目愿景和ML计划 |
| 贡献指南 | 如何贡献（代码、数据、文档） |
| 变更日志 | 版本历史和发布说明 |
| 安全 | 安全策略和漏洞报告 |
| 行为准则 | 社区指南 |
媒体报道
- Medium - How I Turned My Wi-Fi Into a Motion Sensor - Part 1
- Medium - How I Turned My Wi-Fi Into a Motion Sensor - Part 2
- IoT For All - How I Turned My Wi-Fi Into a Motion Sensor
- Hackaday - Make Your Own ESP32 - Based Person Sensor, No Special Hardware Needed
- Adafruit Learn - ESPectre Human Detector for Feather
- Seeed Studio Wiki - Deploying Espectre on Seeed Studio XIAO ESP32 Series with ESPHome
- Blog Discussion - Home Assistant ESPectre - Wi-Fi Motion Detection for Home Assistant
视频
- Video @GithubAwesome ESPectre
播客
- Hackaday Podcast Episode 355: Person Detectors, Walkie Talkies, Open Smartphones...
相关项目
-radio - presence - scanner：一个互补的存在感应项目，专注于从主机设备进行BLE无线电观测（Python），可选配HTTP仪表盘。
-micropython - esp32 - csi：自定义的MicroPython分支，暴露ESP32 CSI API，用作Micro - ESPectre工作流中快速CSI原型开发的固件基础。
致谢
ESPectre利用了ESP32芯片的原生Wi-Fi CSI功能。感谢乐鑫（Espressif）在ESP - IDF框架中提供CSI功能，并在其esp - csi仓库中认可ESPectre为社区项目。
许可证
本项目采用GNU通用公共许可证v3.0（GPLv3）发布。GPLv3确保软件保持免费开源，任何人都可以使用、研究、修改和分发，修改后的版本必须在相同许可证下共享，以保护最终用户的权利和软件自由。完整的许可证文本请参考LICENSE。贡献需遵循GPLv3，并在每次提交时包含DCO Signed - off - by声明（git commit - s）。
作者
-姓名：Francesco Pace
-邮箱：francesco.pace@espectre.dev
-领英：[linkedin.com/in/francescopace](https://www.linkedin.com/in/francescopace)
如果你觉得ESPectre有用并想支持其开发，可以请我喝杯咖啡，这完全是自愿的。我热衷于这个项目，你的贡献将帮助我购买新的硬件以扩展测试和支持的设备列表，并投入更多时间开发新功能。