@tom_doerr: 无需摄像头的Wi-Fi动作检测 https://github.com/francescopace/espectre…

Wi-Fi 运动检测，无需摄像头 https://t.co/4t8bf1jnk1 https://t.co/vnhapizthf — # francescopace/espectre 来源：https://github.com/francescopace/espectre 许可证 (https://github.com/francescopace/espectre/blob/main/LICENSE) ESPHome (https://esphome.io/) 平台 (https://www.espressif.com/en/products/socs) 发布 (https://github.com/francescopace/espectre/releases/latest) CI (https://github.com/francescopace/espectre/actions/workflows/ci.yml?query=branch%3Amain) codecov (https://codecov.io/gh/francescopace/espectre) # 🛜 ESPectre 👻 基于 Wi-Fi 频谱分析 (CSI) 的运动检测系统，通过 ESPHome 原生集成 Home Assistant。 > [!TIP] > 新 ML 检测器：基于神经网络的运动检测。无需校准，在设备上运行。这是一个实验性功能，欢迎在专门的 ML 检测器讨论 (https://github.com/francescopace/espectre/discussions/126) 中提供反馈。还提供包含最新更改的快照构建版本 (https://github.com/francescopace/espectre/releases/tag/snapshot)（对于基于机器学习的检测器，请使用 -ml 资产），或按照 设置指南 进行自定义配置。 — ## 目录 - 三点概括 - 所需材料 - 快速开始 - 工作原理 - 可用场景 - 传感器放置指南 - 系统架构 - 常见问题 - 安全与隐私 - 技术深入解析 - 双平台策略 - 未来演进 - 文档 - 媒体报道 - 相关项目 - 致谢 - 许可证 - 作者 — ## 三点概括 1. 功能：利用 Wi-Fi 检测移动（无需摄像头、麦克风） 2. 所需硬件：一个约 €10 的 ESP32 设备（推荐 S3 和 C6，支持其他变体） 3. 设置时间：10-15 分钟 — ## 所需材料 ### 硬件 - 2.4GHz Wi-Fi 路由器 - 你家里现有的就可以 - 支持 CSI 的 ESP32 - ESP32-C6, ESP32-S3, ESP32-C3, ESP32（原始版）或其他变体。完整平台对比表请见 SETUP.md。 3 个带外置天线的 ESP32-S3 DevKit 套装 带外置天线的 ESP32-S3 DevKit ### 软件（全部免费） - Home Assistant（在 Raspberry Pi、PC、NAS 或云端） - ESPHome（集成在 Home Assistant 中或独立运行） ### 所需技能 - 基本 YAML 知识用于配置 - 熟悉 Home Assistant（可选但推荐） - 无需编程 - 无需路由器配置 — ## 快速开始 设置时间：约 10-15 分钟 难度：简单（仅需 YAML 配置） 1. 安装设置：按照 SETUP.md 中的完整指南操作 2. 调优：使用 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 应用或 Web 界面配置 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 (https://github.com/francescopace/espectre/issues) 或通过邮件联系我。 — ## 安全与隐私 隐私、安全与伦理考量（点击展开） ### 收集数据的性质 系统收集与 Wi-Fi 无线信道物理特性相关的匿名数据： - OFDM 子载波的幅度和相位 - 统计信号方差 - 未收集：个人身份、通信内容、图像、音频 CSI 数据仅表示传输介质的属性，不包含直接识别信息。 ### 隐私优势 - 无摄像头：尊重视觉隐私 - 无麦克风：不录制音频 - 无需佩戴设备：不需要可穿戴设备 - 聚合数据：仅统计指标，而非原始识别数据 ### ⚠️ 免责声明与伦理考量 警告：尽管 CSI 数据本身具有匿名性，但该系统可能被用于： - 未经同意的监控：在没有明确同意的情况下检测他人的存在/移动 - 行为画像：通过高级 AI 模型推断日常生活模式 - 家庭隐私侵犯：跟踪私人住宅内的活动 ### 使用责任 用户对使用本系统负全部责任，必须： 1. 获取所有被监测人员的明确同意 2. 遵守当地法规（欧盟 GDPR、当地隐私法律） 3. 明确告知传感系统的存在 4. 限制使用于合法目的（家庭安全、个人家庭自动化） 5. 保护数据，采用加密和受控访问 6. 请勿用于非法监控、跟踪或侵犯他人隐私 — ## 技术深入解析 算法细节（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（生产） | 文档 | 描述 | |–––––|———––| | 介绍 | （本文件）项目概览、快速开始、常见问题 | | 设置指南 | 使用 ESPHome 进行安装和配置 | | 调优指南 | 参数调优以实现最佳检测 | | 性能 | 基准测试、混淆矩阵、F1 分数 | | 游戏 | 浏览器游戏、USB 流式 API、交互式阈值调优 | | 测试套件 | PlatformIO Unity 测试文档 | ### Micro-ESPectre（研发） | 文档 | 描述 | |–––––|———––| | 介绍 | 研发平台概览、CLI、MQTT、Web 监控 | | 算法 | MVS、NBVI 校准、Hampel 滤波器的科学文档 | | 分析工具 | CSI 分析和优化脚本 | | ML 数据收集 | 构建用于机器学习的标记数据集 |