返回更新列表
新发布Aug 18, 2026

espectre snapshot-dev

ESPectre - 基于Wi-Fi频谱分析(CSI)的运动检测系统,集成Home Assistant。

分享

ESP-IDF 组件 Arduino 库 C++ 覆盖率 Python 覆盖率 Web 覆盖率

ESPectre ESPectre logo

将 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 检测的是无线电环境的变化。它不会识别人员、统计人数、证明房间为空,也不能替代经过安全认证的安防、医疗或应急系统。

支持的硬件

  • ESP32-C6、ESP32-C5、ESP32-C3、ESP32-S3、ESP32-S2 以及经典 ESP32
  • 2.4 GHz 上的普通 Wi-Fi 4(802.11n)网络

选择固件路径

路径最适合从这里开始
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 可能无法在其中正常工作。

  1. 在桌面版 Chrome 或 Edge 中打开 Flash。
  2. 通过 USB 连接受支持的 ESP32,然后选择固件和发布通道。
  3. 完成屏幕上的 Wi-Fi 配置,或使用受支持的控制器进行 Matter 调试。
  4. 可选:打开设备设置以固定首选接入点或设置 MQTT。
  5. 打开监控以查看运动、调整检测参数并检查设备。

要在网络上查找你的设备,请使用浏览器工具中的 Find devices 或 ./espectre devices。有关要求和限制,请参阅发现参考。

ESPectre Monitor

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 将这一风险视为设计的一部分:

  • 运动检测在本地进行,不需要云连接;
  • 原始 CSI 采集是可选的,仅用于研究和调试;
  • 安全与负责任使用指南记录了部署边界、知情同意、数据最小化、滥用报告和私密漏洞报告;
  • 固件发布包含针对具体构建的 SBOM、声明和许可证归档,以便检查其内容;
  • 网站和所有浏览器工具均位于本仓库的 docs/web 下,并附有其隐私规则和分析策略;
  • 协议、算法、测试结果、局限性和计划全部公开。

仅在您有权使用的场所使用 ESPectre。告知受影响的人员,在需要时取得同意,保护对设备及其数据的访问,并遵守隐私法律。

致谢

分类