espectre

基于Wi-Fi Channel State Information (CSI) 的无线人体运动检测系统，与Home Assistant原生集成。利用ESP32芯片采集Wi-Fi信号变化，通过传统信号处理或实验性ML神经网络（9→32→16→1 MLP）实现运动识别，无需摄像头/麦克风。亮点：零编程YAML配置、自动载波选择(NBVI)、支持多种ESP32模组、€10成本，且开箱即用。注意：使用前需获得被监测者同意，遵守当地隐私法规。

README

🛜 ESPectre 👻

基于 Wi-Fi 频谱分析（CSI）的运动检测系统，通过 ESPHome 原生集成 Home Assistant。

[!TIP] 新功能：ML 检测器：基于神经网络的运动检测，无需校准，在设备端运行。这是一项实验性功能，欢迎在专门的 ML 检测器讨论区反馈意见。此外，还提供了包含最新变更的快照版本（针对机器学习检测器请使用 -ml 资源），或参考设置指南进行自定义配置。

三个要点

功能：利用 Wi-Fi 检测移动（无需摄像头、无需麦克风）
所需材料：约 10 欧元的 ESP32 设备（推荐 S3 和 C6，也支持其他型号）
设置时间：10-15 分钟

所需材料

硬件

2.4GHz Wi-Fi 路由器——家中已有的路由器即可正常工作
支持 CSI 的 ESP32——ESP32-C6、ESP32-S3、ESP32-C3、ESP32（原始版）或其他型号。完整平台对比表请参见 SETUP.md。

3 x ESP32-S3 DevKit 套件（带外置天线） ESP32-S3 DevKit（带外置天线）

软件（全部免费）

Home Assistant（运行在 Raspberry Pi、PC、NAS 或云端）
ESPHome（集成在 Home Assistant 中或独立运行）

所需技能

基本 YAML 知识，用于配置
熟悉 Home Assistant（可选但推荐）
无需编程
无需修改路由器配置

快速开始

设置时间：约 10-15 分钟
难度：简单（仅需 YAML 配置）

安装与配置：参照 SETUP.md 的完整指南
调优：通过 TUNING.md 针对你的环境进行优化

ESPectre Home Assistant 仪表盘 Home Assistant 仪表盘，显示实时运动检测、阈值控制及调试传感器

工作原理

当有人在房间内移动时，他们就会“扰动”在路由器和传感器之间传播的 Wi-Fi 波。这就像你在手电筒前挥手时看到影子变化一样。

ESP32 设备“监听”这些变化，从而判断是否有移动。

优点

无需摄像头（完全保护隐私）
无需佩戴设备（无需佩戴手环或传感器）
可通过墙壁工作（Wi-Fi 能穿透墙壁）
成本极低（总计约 10 欧元）

想了解技术细节？请参见 ALGORITHMS.md 中的 CSI 解释和信号处理文档。

应用场景

实际示例

家庭安防：当你外出时，如果有人进入立刻接收警报
老人照护：监测活动，检测跌倒或长时间不活动
智能自动化：仅当有人在场时开启灯光/暖气
节能：空房间自动关闭设备
儿童监护：夜间儿童离开房间时发出警报
气候控制：仅对有人区域供暖/制冷

传感器放置位置

传感器的最佳放置位置对于可靠的运动检测至关重要。

与路由器的推荐距离

最佳范围：3-8 米

距离	信号	多径	灵敏度	噪声	建议
< 2 米	太强	极少	低	低	❌ 太近
3-8 米	强	良好	高	低	✅ 最佳
> 10-15 米	弱	变化	低	高	❌ 太远

放置技巧

应做到：

将传感器放置在你想要监测的区域（不一定与路由器直线相对）
高度：距地面 1-1.5 米（桌面/桌台高度）
外置天线：使用 IPEX 连接器以获得更好的接收效果

应避免：

避免路由器与传感器之间有金属障碍物（冰箱、金属柜）
避免角落或封闭空间（会降低多径多样性）

系统架构

处理流水线

ESPectre 使用专注的处理流水线进行运动检测：

┌─────────────┐
│  CSI 数据   │ 原始 Wi-Fi 信道状态信息
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  增益锁定   │ AGC/FFT 稳定（约 3 秒）
│             │ 锁定硬件增益以获得稳定测量值
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   自动      │ 自动子载波选择（启动时执行一次）
│ 校准        │ 选择最佳 12 个子载波（NBVI）
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  自适应     │ auto: P95 × 1.1 | min: P100
│  阈值       │ 或固定的手动值
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Hampel     │ 湍流离群值去除
│  滤波器     │ （默认启用）
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  低通       │ 噪声降低（平滑）
│  滤波器     │ （可选，默认禁用）
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ 检测评估    │ MVS 或 ML 分数
│             │ 每 evaluation_interval 个数据包评估
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ 命中过滤器  │ motion_on_hits / motion_off_hits
│             │ 边缘驱动的 IDLE ↔ MOTION
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Home        │ 边缘驱动的运动二进制信号 +
│ Assistant   │ 定期发布的运动分数 / 阈值
└─────────────┘

单传感器或多传感器

┌─────────┐  ┌─────────┐  ┌─────────┐
│ ESP32   │  │ ESP32   │  │ ESP32   │
│ 房间 1   │  │ 房间 2   │  │ 房间 3   │
└────┬────┘  └────┬────┘  └────┬────┘
     │            │            │
     └────────────┴────────────┘
                  │
                  │ ESPHome 原生 API
                  ▼
         ┌────────────────────┐
         │   Home Assistant   │
         │   （自动发现）     │
         └────────────────────┘

每个传感器会被 Home Assistant 自动发现，并提供：

用于运动检测的二进制传感器，在状态边沿时立即发布
运动分数传感器，按固定节奏发布
可调节的阈值（数字实体）

自动子载波选择

ESPectre 实现了 NBVI（归一化频带方差指数）进行自动子载波选择，无需任何手动配置即可达到接近最优的性能（F1>96%）。该算法基于稳定性指标和频谱多样性选择 12 个非连续子载波。

⚠️ 重要说明（MVS 模式）：设备启动后保持房间安静且静止 10 秒。在此期间自动校准会运行，移动会影响检测精度。ML 模式跳过校准。

算法详情请参见 ALGORITHMS.md。

常见问题（入门级）

点击展开常见问题

问：使用它需要编程知识吗？
答：不需要！ESPectre 使用 YAML 配置文件。只需下载示例、烧录，然后通过 ESPHome 应用或网页界面配置 Wi-Fi 即可。

问：它兼容我的路由器吗？
答：是的，只要你的路由器有 2.4GHz Wi-Fi（几乎所有现代路由器都具备）。

问：总费用是多少？
答：硬件：约 10 欧元购买一个 ESP32 设备（推荐 S3/C6，其他型号也可用）。软件：全部免费开源。你还需要运行 Home Assistant 的环境（Raspberry Pi 约 35-50 欧元，或任何现有的 PC/NAS）。

问：需要修改路由器吗？
答：不需要！路由器正常工作。传感器“监听” Wi-Fi 信号而不做任何修改。

问：能穿过墙壁工作吗？
答：能，2.4GHz Wi-Fi 信号可以穿透石膏板墙。钢筋混凝土墙会降低灵敏度，但在近距离时仍可检测。

问：一栋房子需要多少个传感器？
答：取决于面积。一个传感器可监测约 50 m²。对于更大的房子，使用多个传感器（每 50-70 m² 一个传感器以获得最佳覆盖）。

问：能区分人和宠物吗？
答：系统使用两状态分割模型（空闲/运动），只识别通用移动，不区分人、宠物或其他移动物体。如需更复杂的分类（人 vs 宠物、活动识别、手势检测），则需要训练 AI/ML 模型（参见未来演进部分）。

问：支持 Mesh Wi-Fi 网络吗？
答：支持，正常工作。请确保 ESP32 连接到 2.4 GHz 频段。

问：检测精度如何？
答：检测精度高度依赖环境，需要适当调优。影响性能的因素包括：房间布局、墙体材料、家具摆放、距离路由器距离（最佳 3-8 米）以及干扰水平。在最佳条件下经过适当调优，系统能提供可靠的运动检测。调整 segmentation_threshold 参数可根据具体环境调节灵敏度。

问：功耗是多少？
答：连续运行期间典型功耗约 500mW。固件支持功耗优化，电池供电部署可以实现深度睡眠模式，但需要对代码进行自定义修改。

问：如果不起作用，我能获得帮助吗？
答：可以，在 GitHub 上提交 Issue 或通过电子邮件联系我。

安全与隐私

隐私、安全和伦理考量（点击展开）

收集数据的性质

系统收集与 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 数据分析的综合工具集
应用场景：学术研究、工业感知、算法开发

Micro-ESPectre 为你提供以下基础能力：

人数统计
活动识别（行走、跌倒、坐下、睡眠）
定位与跟踪
手势识别

开发流程

┌─────────────────────┐    验证通过      ┌──────────────────────┐
│   Micro-ESPectre    │ ─────────────────► │      ESPectre        │
│   （研发平台）      │    算法          │ （生产平台）         │
│                     │                    │                      │
│ • 快速原型开发      │                    │ • ESPHome 组件       │
│ • 算法测试          │                    │ • Home Assistant     │
│ • 数据分析          │                    │ • 终端用户就绪       │
│ • MQTT 灵活         │                    │ • 原生 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，当前指标请看 PERFORMANCE.md。
ML 数据收集和训练基础设施在 ML_DATA_COLLECTION.md 中有文档。

详细计划、时间线以及如何参与贡献，请参见 ROADMAP.md。

文档

ESPectre（生产版本）

文档	描述
简介	（本文档）项目概述、快速开始、FAQ
设置指南	使用 ESPHome 进行安装和配置
调优指南	参数调优以获得最佳检测效果
性能报告	基准测试、混淆矩阵、F1 分数
小游戏	浏览器游戏、USB 流 API、交互式阈值调优
测试套件	PlatformIO Unity 测试文档

Micro-ESPectre（研发版本）

文档	描述
简介	研发平台概述、CLI、MQTT、Web 监控
算法	MVS、NBVI 校准、Hampel 滤波器的科学文档
分析工具	CSI 分析和优化脚本
机器学习数据收集	构建带标签的数据集用于机器学习
参考文献	学术论文和研究资源

项目

文档	描述
路线图	项目愿景和 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

博客	讨论
Home Assistant	ESPectre - Wi-Fi Motion Detection for Home Assistant

视频	视频
@GithubAwesome	ESPectre

播客	节目
Hackaday	Podcast Episode 355: Person Detectors, Walkie Talkies, Open Smartphones...

致谢

ESPectre 利用了 ESP32 芯片的原生 Wi-Fi CSI 能力。感谢 Espressif 在 ESP-IDF 框架中开放 CSI 访问，并将 ESPectre 列为其 esp-csi 仓库中的社区项目。

许可证

本项目基于 GNU General Public License v3.0 (GPLv3) 发布。

GPLv3 确保：

软件保持自由和开源
任何人可以使用、研究、修改和分发
修改版本必须使用相同的许可证共享
保护最终用户权利和软件自由

请参见 LICENSE 获取完整的许可证文本。

贡献内容在 GPLv3 下提交，并且每个提交必须包含 DCO Signed-off-by 标记（git commit -s）。

作者

Francesco Pace
邮箱：francesco.pace@espectre.dev
LinkedIn：linkedin.com/in/francescopace

如果你觉得 ESPectre 有用并想支持它的发展，可以请我喝杯咖啡。这完全是自愿的。我开发这个项目是出于热爱。你的贡献将帮助我购买新硬件以扩大测试和支持设备列表，并投入更多时间开发新功能。

开源项目francescopace2026-06-09原文

打开互动版