espectre snapshot-dev
ESPectre - 基于Wi-Fi频谱分析（CSI）的运动检测系统，集成Home Assistant。
ESPectre 
将 ESP32 变成一个私有的本地 Wi-Fi 运动传感器。
当有人在房间里移动时，他们会改变 Wi-Fi 信号在房间内的传播方式。ESPectre 读取这些变化并实时报告运动状态。无需摄像头、麦克风、可穿戴设备或专用雷达硬件：只需一块受支持的 ESP32 和房间内已有的 Wi-Fi 网络即可。
ESPectre 是一个开源平台，集成了可即刷即用的固件、可嵌入的 C++ SDK、MicroPython 实现、浏览器工具、主机 CLI、开放数据集、开放模型权重，以及用于构建和验证检测器的研究工作流。
从浏览器刷写 · 查看在线工具 · 阅读文档 · 探索 SDK
应用与集成
ESPectre 可以在检测到运动时打开显示器或灯光，根据房间活动调节供暖和制冷，在应无人的区域发生移动时触发警报或通知，并驱动其他房间自动化。它通过 ESPHome 或 MQTT 连接 Home Assistant，提供标准 Matter 占用传感器和本地 Direct HTTP API，并可通过 C++ SDK 嵌入自定义 ESP32 固件。
ESPectre 在设备上处理 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 控制器；控制器验证仍有限 | Matter 前端 |
| Micro-ESPectre | 在 MicroPython 中进行轻量级传感，支持本地只读 Direct HTTP 监控 | Micro-ESPectre README |
Native、ESPHome 和 Matter 可以在 lightweight 检测器（在启动时学习房间特定阈值，为应用其余部分留出更多资源）和 high_accuracy 检测器（运行仓库中包含的已训练模型）之间选择。它们的行为和实测权衡记录在 SETUP.md、ALGORITHMS.md 和性能报告中。
快速开始
最快的路径使用浏览器，无需本地构建环境。使用桌面版 Chrome 151 或更高版本可获得完整的托管工作流。Edge 支持浏览器刷写，但不保证与 Device settings 和 Monitor 的兼容性：
- 在桌面版 Chrome 或 Edge 中打开 Flash。
- 通过 USB 连接受支持的 ESP32，然后选择固件和发布通道。
- 完成屏幕上的 Wi-Fi 配置，或使用受支持的控制器完成 Matter 配网。
- 可选：打开 Device settings 以固定首选接入点或设置 MQTT。
- 打开 Monitor 以观察运动、调整检测并检查设备。
Matter 状态： Matter 前端仍在各控制器生态系统中进行验证。控制器可能支持标准 Matter 占用传感器，但尚未使用当前固件进行测试。 有关当前兼容性矩阵，请参阅 Matter 控制器兼容性。
本地设置
对于本地构建、从本仓库刷写以及操作路径的其余部分，请从 SETUP.md 开始。仓库包装器通过以下方式暴露可用工作流：
./espectre --help
文档
| 主题 | 涵盖内容 | 指南 |
|---|---|---|
| 安装与操作 | 设备设置、CLI 工作流和检测器调优 | SETUP.md、CLI.md、TUNING.md |
| 理解与集成 | 运行时架构、API、发现、算法和 C++ SDK | ARCHITECTURE.md、API.md、DISCOVERY.md、ALGORITHMS.md、SDK.md |
| 采集与训练 | CSI 采集、模型训练、特征历史、性能和文献 | ML_DATA_COLLECTION.md、ML_TRAINING.md、FEATURES.md、性能报告、LITERATURE.md |
| 研究与方向 | 路线图、架构决策和发布历史 | ROADMAP.md、ADR 索引、CHANGELOG.md |
| 前端参考 | ESPHome、Native、Matter 和 Micro-ESPectre 的固件路径 README | ESPHome、Native、Matter、Micro |
| 贡献 | 如何贡献以及在哪里讨论项目 | CONTRIBUTING.md、GitHub Discussions |
数据集、模型与验证
ESPectre 发布其检测器背后的研究资产和验证证据：
| 资产 | 提供内容 | 从这里开始 |
|---|---|---|
| CSI 数据集 | 空房间、静态存在和运动的真实录音，目录和来源信息见 dataset_info.json | data/ |
| 模型权重 | C++ 和 Python 中的训练权重，以及训练、导出和验证工作流 | ML_TRAINING.md |
| 特征台账 | 已测试、已采用或已拒绝的特征，包括不成功的实验 | FEATURES.md |
| 算法与报告 | 检测器行为、生成的性能报告和数据集质量报告 | ALGORITHMS.md |
| 文献与方向 | 外部研究、架构决策记录和公开路线图 | LITERATURE.md |
安全、隐私与透明
一个能揭示存在状态的传感器不应是黑盒。Wi-Fi 传感避免了图像和音频，但运动和占用数据仍可能揭示作息规律、睡眠或离家情况。ESPectre 将此风险视为工程工作的一部分：
- 运动检测在本地进行，不要求云连接；
- 原始 CSI 采集是可选的，仅用于明确的研究和调试需求；
- 安全与负责任使用指南记录了部署边界、同意、数据最小化、滥用报告和私有漏洞报告；
- 固件版本包含构建特定的 SBOM、通知和许可证档案，以便检查其内容；
- 公共网站和每个浏览器工具都是本仓库的一部分，位于 docs/web 下，包括其源代码、隐私规则、分析契约和固定的浏览器依赖；
- 协议、算法、性能证据、局限性、路线图决策和已知验证边界均公开记录。
仅在您有权部署的空间和网络中使用 ESPectre。告知受影响人员，在需要时获得同意，保护对设备和数据的访问，并遵守适用的隐私法律。
致谢
- 感谢 Espressif 使 CSI 在 ESP-IDF 中可用，并在 esp-csi 中将 ESPectre 认定为社区项目。
- 感谢 MicroPython 维护者审阅、测试并合并了 ESPectre 的 CSI 贡献，该贡献为主线
network.WLAN添加了直接 CSI 方法。
许可证
ESPectre 第一方代码以 GPLv3 提供，符合条件的部分也可通过单独的商业协议获得：
- 当您的固件或应用能够遵守 GPLv3（包括提供相应源代码）时，请选择 GPLv3。参见 LICENSE。
- 如果您希望在专有或闭源固件中嵌入 ESPectre 而无需承担 GPLv3 源代码披露义务，请参阅 LICENSING.md 了解商业许可。商业许可证涵盖符合条件的材料，不替代第三方条款；ESPHome C++ 前端仍仅限 GPLv3。
第三方条款和构建特定的合规工件在 THIRD_PARTY_NOTICES.md 中描述。