将 ESP32 变成一台私密、本地的 Wi-Fi 运动传感器。
当有人穿过房间时,会改变 Wi-Fi 信号在房间中的传播方式。ESPectre 读取这些变化并实时报告运动。无需摄像头、无需麦克风、无需可穿戴设备,也无需专用雷达硬件:只需一块受支持的 ESP32 和房间中已有的 Wi-Fi 网络。
ESPectre 是一个开源平台,汇集了可直接烧录的固件、可嵌入的 C++ SDK、Arduino 库、MicroPython 实现、浏览器工具、主机 CLI、开放数据集、开放模型权重,以及用于构建和验证检测器的研究工作流。
从浏览器烧录 · 查看在线工具 · 阅读文档 · 探索 SDK
使用 ESPectre 可以在有人走进来时打开灯光或显示器,在房间被使用时调节供暖,或在不应有人的地方出现移动时发送警报。它可与 Home Assistant 配合使用(通过 ESPHome 或 MQTT),可作为标准的 Matter 占用传感器出现,提供本地 HTTP API,并可通过 C++ SDK 或 Arduino-ESP32 草图构建到你自己的 ESP32 固件中。
一切都在设备上运行:它测量 Wi-Fi 信道(信道状态信息,即 CSI),并报告运动状态和运动评分。无需将任何数据发送到云端。一块开发板覆盖一个区域,因此请按每个房间一块板来规划。
ESPectre 检测的是无线电环境的变化。它不会识别人员、统计人数、证明房间为空,也不能替代经过安全认证的安防、医疗或应急系统。
| 路径 | 最适合 | 从这里开始 |
|---|---|---|
| Native | 独立传感器、MQTT 集成(包括 Home Assistant MQTT Discovery)以及自定义应用 | Native 前端 |
| ESPHome | 希望获得原生实体、ESPHome 配置和 Device Builder 更新的 Home Assistant 用户 | ESPHome 前端 |
| Matter | 支持占用传感器的 Matter 控制器;已在 Google Home、Apple Home 和 Home Assistant 上测试 | Matter 前端 |
| Micro-ESPectre | 在 MicroPython 中实现轻量级感知,并提供本地只读的 Direct HTTP 监控 | Micro-ESPectre README |
最快的方式只需要一个浏览器。请使用桌面版 Chrome 151 或更高版本;Edge 可以烧录,但 Device settings 和 Monitor 可能无法在其中正常工作。
要在网络上查找你的设备,请使用浏览器工具中的 Find devices 或 ./espectre devices。有关要求和限制,请参阅发现参考。

Matter 状态: 配对、占用状态更新和自动化已在 Google Home、Apple Home 和 Home Assistant 上测试。Amazon Alexa 和 Samsung SmartThings 尚未测试。Google Home 需要一次性完成开发者控制台设置。 有关当前兼容性矩阵,请参阅 Matter 控制器兼容性。
要从本仓库构建并烧录,请先阅读设置指南。要查看所有可用命令,请运行:
./espectre --help
| 主题 | 涵盖内容 | 指南 |
|---|---|---|
| 安装与操作 | 设备设置、CLI 工作流程和故障排除 | 安装指南、CLI 参考、故障排除指南 |
| 理解与集成 | 运行时架构、CSI 采集、API、发现、算法和 C++ SDK | 架构概览、CSI 指南、API 参考、发现参考、算法参考、SDK 指南 |
| 研究与方向 | 路线图、架构决策和发布历史 | 路线图、ADR 索引、变更日志 |
| 前端参考 | 各固件、Micro-ESPectre 和 Arduino 库的指南 | ESPHome、Native、Matter、Micro、Arduino |
| 贡献 | 贡献、发布流程和项目讨论 | 贡献指南、发布指南、GitHub Discussions |
ESPectre 公开发布其检测器背后的研究资产和验证证据:
| 资产 | 提供内容 | 从这里开始 |
|---|---|---|
| CSI 数据集 | 空房间、静态存在和运动的真实录制数据,目录和来源信息见 dataset_info.json | 数据采集指南、Data/ |
| 模型权重 | 训练好的权重,提供 C++ 和 Python 版本,以及训练、导出和验证工作流程 | ML 训练指南 |
| 特征分析 | 经过测试、采纳或拒绝的特征,包括未成功的实验 | 特征分析 |
| 报告 | 生成的检测器指标和数据集质量检查 | 性能报告、数据集质量报告 |
| 文献 | 外部 Wi-Fi 感知研究及其可迁移到 ESPectre 的内容 | 文献综述 |
一个能够揭示人员存在的传感器不应是黑盒。Wi-Fi 感知不记录图像或音频,但运动数据仍可能揭示日常作息、睡眠情况或家中无人的时段。ESPectre 将这一风险视为设计的一部分:
仅在您有权使用的场所使用 ESPectre。告知受影响的人员,在需要时取得同意,保护对设备及其数据的访问,并遵守隐私法律。