基于Wi-Fi频谱分析（CSI）的运动检测系统，通过ESPHome原生集成Home Assistant。
[!TIP] 新的ML检测器：基于神经网络的运动检测。无需校准，在设备上运行。这是一个实验性功能，欢迎在专门的ML检测器讨论中提供反馈。还提供了包含最新更改的快照构建（对于基于机器学习的检测器，使用
-ml资源），或按照设置指南进行自定义配置。
带外置天线的ESP32-S3 DevKit
设置时间：约10-15分钟
难度：简单（仅需YAML配置）
带有实时运动检测、阈值控制和调试传感器的Home Assistant仪表板
当有人在房间内移动时，他们会“扰动”路由器与传感器之间的Wi-Fi波。这就像你把手电筒前晃动，看到阴影变化一样。
ESP32设备“监听”这些变化并判断是否有运动。
想了解技术细节？参见ALGORITHMS.md了解CSI解释和信号处理文档。
传感器的最佳放置对于可靠的运动检测至关重要。
最佳范围：3-8米
建议：
不建议：
ESPectre使用针对运动检测的聚焦处理流水线：``` ┌─────────────┐ │ CSI Data │ Raw Wi-Fi Channel State Information └──────┬──────┘ │ ▼ ┌─────────────┐ │ Gain Lock │ AGC/FFT stabilization (~3 seconds) │ │ Locks hardware gain for stable measurements └──────┬──────┘ │ ▼ ┌─────────────┐ │ Auto │ Automatic subcarrier selection (once at boot) │ Calibration │ Selects optimal 12 subcarriers (NBVI) └──────┬──────┘ │ ▼ ┌─────────────┐ │ Adaptive │ auto: P95 × 1.1 | min: P100 │ Threshold │ or fixed manual value └──────┬──────┘ │ ▼ ┌─────────────┐ │ Hampel │ Turbulence outlier removal │ Filter │ (enabled by default) └──────┬──────┘ │ ▼ ┌─────────────┐ │ Low-pass │ Noise reduction (smoothing) │ Filter │ (optional, disabled by default) └──────┬──────┘ │ ▼ ┌─────────────┐ │ Detection │ MVS or ML score │ Evaluation │ every evaluation_interval packets └──────┬──────┘ │ ▼ ┌─────────────┐ │ Hit Filter │ motion_on_hits / motion_off_hits │ │ edge-driven IDLE ↔ MOTION └──────┬──────┘ │ ▼ ┌─────────────┐ │ Home │ Edge-driven motion binary + │ Assistant │ periodic Movement Score / Threshold └─────────────┘
### 单个或多个传感器```
┌─────────┐ ┌─────────┐ ┌─────────┐
│ ESP32 │ │ ESP32 │ │ ESP32 │
│ Room 1 │ │ Room 2 │ │ Room 3 │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└────────────┴────────────┘
│
│ ESPHome Native API
▼
┌────────────────────┐
│ Home Assistant │
│ (Auto-discovery) │
└────────────────────┘
每个传感器会被 Home Assistant 自动发现，并附带以下实体：
ESPectre 实现了基于 NBVI（归一化频带方差指数，Normalized Band Variance Index）的自动子载波选择，能够在 零手动配置 的情况下达到接近最优的性能（F1>96%）。该算法根据稳定性指标和频谱多样性选择 12 个非连续的子载波。
⚠️ 重要提示（MVS 模式）：设备启动后，请保持房间 安静无移动 10 秒钟。自动校准在此期间进行，任何移动都会影响检测精度。ML 模式会跳过校准。
有关算法细节，请参阅 ALGORITHMS.md。
问：使用它需要编程知识吗？
答：不需要！ESPectre 使用 YAML 配置文件。只需下载示例，烧录设备，然后通过 ESPHome 应用或网络界面配置 WiFi 即可。
问：它和我家的路由器兼容吗？
答：兼容，只要您的路由器支持 2.4GHz Wi-Fi（几乎所有现代路由器都支持）。
问：总成本大概是多少？
答：硬件：约 10 欧元购买一个 ESP32 设备（推荐 S3/C6，其他变体也可用）。软件：全部免费开源。您还需要一台运行 Home Assistant 的设备（Raspberry Pi 约 35-50 欧元，或者任何现有的 PC/NAS）。
问：我需要对路由器进行任何修改吗？
答：不需要！路由器正常工作。传感器只“监听”Wi-Fi 信号，无需任何修改。
问：它能穿透墙壁工作吗？
答：能。2.4GHz Wi-Fi 信号可以穿透干墙。钢筋混凝土墙会降低灵敏度，但在缩短距离后仍可进行检测。
问：一栋房子需要多少个传感器？
答：取决于房屋面积。一个传感器可覆盖约 50 平方米。对于更大的房子，建议使用多个传感器（每 50-70 平方米一个传感器以获得最佳覆盖）。
问：它能区分人和宠物吗？
答：该系统使用两状态分割模型（空闲/运动），用于识别一般运动，不区分人、宠物或其他移动物体。若需更精细的分类（如人 vs 宠物、活动识别、手势检测），则需要训练 AI/ML 模型（请参阅未来演进部分）。
问：它能在 Mesh Wi-Fi 网络中工作吗？
答：可以，正常运行。请确保 ESP32 连接到 2.4 GHz 频段。
问：检测精度如何？
答：检测精度高度依赖环境，需要进行适当调整。影响因素包括：房间布局、墙体材料、家具摆放、与路由器的距离（最佳为 3-8 米）以及干扰水平。在最佳条件下经过适当调整，系统能够提供可靠的运动检测。请调整 segmentation_threshold 参数以针对您的特定环境调整灵敏度。
问：功耗是多少？
答：连续运行期间典型功耗约为 500mW。固件支持功耗优化，也可实现深度睡眠模式用于电池供电部署，但这需要对代码进行自定义修改。
问：如果它不工作，我可以获得帮助吗？
答：可以。请在 GitHub 上提交 Issue 或通过电子邮件联系我。
该系统收集的是与 Wi-Fi 无线信道物理特性相关的 匿名数据：
CSI 数据仅代表传输介质的属性，不包含直接的身份识别信息。
警告：尽管 CSI 数据具有内在匿名性，但本系统仍可能被用于：
用户对本系统的使用负全部责任，必须遵循以下要求：
有关算法细节（MVS、NBVI 校准、Hampel 滤波器），请参阅 ALGORITHMS.md。
有关性能指标（混淆矩阵、F1 分数、基准测试），请参阅 PERFORMANCE.md。
本项目采用 双平台方法，在创新速度与生产稳定性之间取得平衡：
目标用户：最终用户、智能家居爱好者、Home Assistant 用户
目标用户：研究人员、开发者、学术/工业应用
Micro-ESPectre 为您提供以下功能的基础：
┌─────────────────────┐ 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-50cm） |
ML 检测器已在 YAML 配置中可通过 `detection_algorithm: ml` 使用。有关算法详情，请参阅 [ALGORITHMS.md](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ALGORITHMS.md#ml-neural-network-detector) 以及 `PERFORMANCE.md` 获取当前指标。
ML 数据收集和训练基础设施记录在 [ML_DATA_COLLECTION.md](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ML_DATA_COLLECTION.md) 中。
有关详细计划、时间线及如何贡献，请参阅 [ROADMAP.md](https://github.com/francescopace/espectre/blob/HEAD/ROADMAP.md)。
---
## 文档
### ESPectre（生产环境）
| 文档 | 描述 |
|------|------|
| [介绍](https://github.com/francescopace/espectre/blob/HEAD/README.md) | （本文件）项目概述、快速入门、常见问题 |
| [设置指南](https://github.com/francescopace/espectre/blob/HEAD/SETUP.md) | 使用 ESPHome 进行安装和配置 |
| [调优指南](https://github.com/francescopace/espectre/blob/HEAD/TUNING.md) | 参数调优以实现最佳检测效果 |
| [性能](https://github.com/francescopace/espectre/blob/HEAD/PERFORMANCE.md) | 基准测试、混淆矩阵、F1 分数 |
| [游戏](https://github.com/francescopace/espectre/blob/HEAD/docs/game/README.md) | 浏览器游戏、USB 流媒体 API、交互式阈值调优 |
| [测试套件](https://github.com/francescopace/espectre/blob/HEAD/test/README.md) | PlatformIO Unity 测试文档 |
### Micro-ESPectre（研发）
| 文档 | 描述 |
|------|------|
| [介绍](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/README.md) | 研发平台概述、CLI、MQTT、Web 监控 |
| [算法](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ALGORITHMS.md) | MVS、NBVI 校准、Hampel 滤波器的科学文档 |
| [分析工具](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/tools/README.md) | CSI 分析和优化脚本 |
| [ML 数据收集](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ML_DATA_COLLECTION.md) | 构建机器学习的标注数据集 |
| [参考资料](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/README.md#references) | 学术论文和研究资源 |
### 项目
| 文档 | 描述 |
|------|------|
| [路线图](https://github.com/francescopace/espectre/blob/HEAD/ROADMAP.md) | 项目愿景和机器学习计划 |
| [贡献指南](https://github.com/francescopace/espectre/blob/HEAD/CONTRIBUTING.md) | 如何贡献（代码、数据、文档） |
| [更新日志](https://github.com/francescopace/espectre/blob/HEAD/CHANGELOG.md) | 版本历史与发布说明 |
| [安全](https://github.com/francescopace/espectre/blob/HEAD/SECURITY.md) | 安全策略与漏洞报告 |
| [行为准则](https://github.com/francescopace/espectre/blob/HEAD/CODE_OF_CONDUCT.md) | 社区指南 |
---
## 媒体报道
| 文章 | 标题 |
|------|------|
| Medium | [如何将我的 Wi-Fi 变成运动传感器 - 第1部分](https://medium.com/@francesco.pace/how-i-turned-my-wi-fi-into-a-motion-sensor-61a631a9b4ec?sk=c7f79130d78b0545fce4a228a6a79af3&utm_source=github&utm_medium=readme&utm_campaign=espectre) |
| Medium | [如何将我的 Wi-Fi 变成运动传感器 - 第2部分](https://medium.com/@francesco.pace/how-i-turned-my-wi-fi-into-a-motion-sensor-part-2-62038130e530?sk=7c8b6f11cf3fcb8d279648016ebff72a&utm_source=github&utm_medium=readme&utm_campaign=espectre) |
| IoT For All | [如何将我的 Wi-Fi 变成运动传感器](https://www.iotforall.com/wifi-motion-sensor-iot) |
| Hackaday | [自制基于 ESP32 的人体传感器，无需特殊硬件](https://hackaday.com/2026/01/28/make-your-own-esp32-based-person-sensor-no-special-hardware-needed/) |
| Adafruit Learn | [用于 Feather 的 ESPectre 人体检测器](https://learn.adafruit.com/espectre-human-detector-for-feather) |
| Seeed Studio Wiki | [在 Seeed Studio XIAO ESP32 系列上使用 ESPHome 部署 ESPectre](https://wiki.seeedstudio.com/xiao-esp32--series-espresense/) |
| 博客 | 讨论 |
|------|------|
| Home Assistant | [ESPectre - Home Assistant 的 Wi-Fi 运动检测](https://community.home-assistant.io/t/espectre-wi-fi-motion-detection-for-home-assistant/961251) |
| 视频 | 视频 |
|------|------|
| @GithubAwesome | [ESPectre](https://www.youtube.com/shorts/iQ_DPHLn8ms) |
| 播客 | 剧集 |
|------|------|
| Hackaday | [播客第 355 集：人体探测器、对讲机、开源智能手机...](https://hackaday.com/2026/01/30/hackaday-podcast-episode-355-person-detectors-walkie-talkies-open-smartphones-and-a-wifi-traffic-light/) |
---
## 相关项目
- [radio-presence-scanner](https://github.com/francescopace/radio-presence-scanner)：互补的存在感知项目，专注于来自主机设备的 BLE 无线电观测（Python），可选 HTTP 仪表盘。
- [micropython-esp32-csi](https://github.com/francescopace/micropython-esp32-csi)：自定义 MicroPython 分支，暴露 ESP32 CSI API，用作 Micro-ESPectre 工作流中快速 CSI 原型开发的固件基础。
---
## 致谢
ESPectre 利用了 ESP32 芯片的原生 Wi-Fi CSI 能力。感谢 [Espressif](https://www.espressif.com/) 在 ESP-IDF 框架中提供 CSI 支持，并在其 [esp-csi](https://github.com/espressif/esp-csi) 存储库中认可 ESPectre 为 [社区项目](https://github.com/espressif/esp-csi#6-related-resources)。
---
## 许可证
本项目采用 **GNU General Public License v3.0 (GPLv3)** 发布。
GPLv3 确保：
- 软件保持自由和开源
- 任何人都可以使用、学习、修改和分发它
- 修改内容必须以相同许可证共享
- 保护最终用户权利和软件自由
请参阅 [LICENSE](https://github.com/francescopace/espectre/blob/HEAD/LICENSE) 获取完整的许可证文本。
贡献内容根据 GPLv3 提交，并且每个提交必须包含 DCO `Signed-off-by` 尾注（`git commit -s`）。
## 作者
**Francesco Pace**
邮箱：[[email protected]](mailto:[email protected])
LinkedIn：[linkedin.com/in/francescopace](https://www.linkedin.com/in/francescopace/)
如果您觉得 ESPectre 有用并希望支持其开发，可以请我喝杯咖啡。这完全是自愿的。
我投入这个项目是因为对它充满热情。您的捐款将帮助我购买新硬件以扩展测试和支持的设备列表，并投入更多时间开发新功能。
<a href="https://www.buymeacoffee.com/espectre" target="_blank"><img src="https://assets.kitploit.com/production/public/readmes/9574/a7e8174c892355a24fbaec083cbef385d097a0b488fd4823dbbb0061643bb5e2.png" alt="给我买杯咖啡" style="height: 60px !important;width: 217px !important;" ></a>
| 距离 | 信号 | 多路径 | 灵敏度 | 噪声 | 建议 |
|---|
| < 2米 | 太强 | 极小 | 低 | 低 | ❌ 太近 |
| 3-8米 | 强 | 良好 | 高 | 低 | ✅ 最佳 |
| > 10-15米 | 弱 | 可变 | 低 | 高 | ❌ 太远 |