ESP-Weaver 方案介绍
此文档分为以下部分：
ESP-Weaver 方案综述
ESP-Weaver 是乐鑫开源的 Home Assistant 集成组件，让客户能够在 Home Assistant 中控制和管理基于乐鑫 ESP 芯片（ESP32、ESP32-S3、ESP32-C 系列）的 IoT 智能设备。
该方案基于 ESP-IDF ESP Local Control 协议开发，通过 mDNS 自动发现和 HTTP 长连接实时通信机制，让 ESP 设备便捷接入 Home Assistant 生态系统。
备注
“Weaver” 取自织巢鸟——一种能将零散草叶编织成精密巢穴的鸟类。ESP-Weaver 的理念与此相似：将网络中分散的 ESP 设备整合为一体，构建成 Home Assistant 中紧密互联的智能家居系统。
方案优势：
开源免费：集成代码和设备端组件均已在 GitHub 开源，客户可自由使用和定制
开发门槛低：设备端通过
idf.py add-dependency一键引入组件，集成端支持 HACS 一键安装芯片覆盖广：支持 ESP32、ESP32-S3、ESP32-C2/C3/C5/C6/C61 等多款芯片
即插即用：mDNS 自动发现，设备上电入网后自动出现在 HA 中，一键添加
基于 ESP-IDF：原生 ESP-IDF 开发，给予开发者完整的底层控制能力
ESP-Weaver 参考资料
ESP-Weaver 工作流程
下图展示了 ESP 设备与 Home Assistant 之间的完整工作流程：
┌──────────────────┐ ┌──────────────────┐
│ ESP 设备 │ │ Home Assistant │
│ (esp_weaver 固件) │ │ (ESP-Weaver 集成) │
└────────┬─────────┘ └────────┬─────────┘
│ │
│ ① 设备发现阶段 │
│ │
│ 连接 WiFi │
│ 启动 ESP Local Control 服务 │
│ 注册 mDNS 服务 (_esp_local_ctrl._tcp) │
│ │
│ ──── mDNS 广播 ─────────────────────────────────────> │
│ mDNS 发现 │
│ 用户点击添加设备 │
│ │
│ ② 连接与认证阶段 │
│ │
│ <─────────── 建立 HTTP 连接 ──────────────────────── │
│ │
│ <═══════════ 安全握手 (Sec0/Sec1) ══════════════════> │
│ (Sec1 需要 PoP 凭据) │
│ │
│ ③ 实体发现阶段 │
│ │
│ <─────────── 查询设备属性与配置 ──────────────────── │
│ ──────────── 上报设备能力与实体信息 ────────────────> │
│ │
│ 动态创建 HA 实体 │
│ (Light, Sensor, │
│ Binary Sensor...) │
│ │
│ ④ 正常运行阶段 │
│ │
│ <─────────── 控制指令 (HTTP Request) ──────────────── │
│ (开灯/调色/调亮度...) │
│ │
│ ──────────── 状态推送 (HTTP Long-Polling) ─────────> │
│ (状态变化实时上报) 实时更新 HA UI │
│ │
│ ⑤ 异常恢复阶段 │
│ │
│ ─ ─ ─ ─ ─ ─ 连接断开 ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │
│ 检测设备离线 │
│ 触发自动重连 │
│ │
│ <═══════════ 重新建立连接 ══════════════════════════> │
│ ──────────── 恢复状态同步 ──────────────────────────> │
│ │
▼ ▼
阶段说明
设备发现：ESP 设备烧录 esp_weaver 固件并接入 WiFi 后，自动注册 mDNS 服务。HA 中的 ESP-Weaver 集成通过 mDNS 协议自动发现网络内的设备。
连接与认证：用户在 HA 中选择发现的设备后，集成与设备建立 HTTP 连接，并完成安全握手（Sec0 无需凭据，Sec1 需要输入 PoP 凭据）。
实体发现：连接建立后，集成查询设备的属性配置，设备上报其支持的实体类型与能力。集成据此在 HA 中自动创建对应的实体（如灯光、传感器等）。
正常运行：HA 通过 HTTP 请求向设备下发控制指令；设备通过 HTTP 长连接（Long-Polling）机制实时推送状态变化到 HA，实现双向通信。
异常恢复：当网络中断或设备离线时，集成自动检测并在设备恢复后重新建立连接，恢复状态同步。
ESP-Weaver 常见应用场景
环境监测系统：温湿度、气压、光照、空气质量等传感器数据采集与监控，支持阈值告警和自动化联动
智能灯光控制：RGB 灯带、色温调节、灯光效果、亮度调节、场景联动控制
手势控制交互：IMU 手势识别（翻转、摇晃、旋转、拍手等），手势触发自动化场景
低功耗物联网：电池供电设备管理、睡眠/唤醒状态监测、能耗统计
智能面板/控制器：按键/触摸事件上报、旋钮控制、物理控制面板
安防报警：门窗开合检测、运动/震动检测、入侵告警
ESP-Weaver 如何启用
Home Assistant 端：安装 ESP-Weaver 集成
确保 Home Assistant 已安装 HACS
在 HACS 中添加自定义存储库：
https://github.com/espressif/esp_weaver，类型选择”集成”搜索 ESP-Weaver 并下载
重启 Home Assistant
设备端：添加 esp_weaver 组件
在已有的 ESP-IDF 工程中，通过 IDF 组件管理器添加 esp_weaver 组件：
idf.py add-dependency "espressif/esp_weaver^0.1.0"
如需参考完整的示例工程：
git clone https://github.com/espressif/esp-iot-solution.git
cd esp-iot-solution/examples/weaver
可用示例：led_light（智能灯光）、imu_gesture（手势传感器）。
添加设备到 Home Assistant
进入 HA 设置 → 设备与服务 → 添加集成
搜索并选择 ESP-Weaver
从已发现的设备列表中选择目标设备
若设备启用安全模式（Sec1），需输入 PoP 凭据
配置完成后，设备实体将自动注册至 Home Assistant
详细安装步骤请参阅 ESP-Weaver GitHub README 。