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 ││ (RD Platform) │ algorithms │ (Production Platform)││ │ │ ││ • Fast prototyping │ │ • ESPHome component ││ • Algorithm testing │ │ • Home Assistant ││ • Data analysis │ │ • End-user ready ││ • MQTT flexibility │ │ • Native API │└─────────────────────┘ └──────────────────────┘创新周期新功能和算法首先在Micro - ESPectrePython中开发和验证一旦证明有效再移植到ESPectreC。未来发展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.0GPLv3发布。GPLv3确保软件保持免费开源任何人都可以使用、研究、修改和分发修改后的版本必须在相同许可证下共享以保护最终用户的权利和软件自由。完整的许可证文本请参考LICENSE。贡献需遵循GPLv3并在每次提交时包含DCO Signed - off - by声明git commit - s。作者-姓名Francesco Pace-邮箱francesco.paceespectre.dev-领英[linkedin.com/in/francescopace](https://www.linkedin.com/in/francescopace)如果你觉得ESPectre有用并想支持其开发可以请我喝杯咖啡这完全是自愿的。我热衷于这个项目你的贡献将帮助我购买新的硬件以扩展测试和支持的设备列表并投入更多时间开发新功能。