ESP-Weaver 技术 Wiki

[English]

ESP-Weaver 集成方案

描述：ESP-Weaver 是乐鑫开源的 Home Assistant 集成组件，用于控制和管理基于 ESP 芯片的 IoT 智能设备。通过 mDNS 自动发现和 ESP Local Control 协议，实现设备的便捷接入和控制。

GitHub 仓库：https://github.com/espressif/esp_weaver

硬件:

ESP32

ESP32-C2

ESP32-C3

ESP32-C5

ESP32-C6

ESP32-C61

ESP32-S3

✓

✓

✓

✓

✓

✓

✓
特性:

设备发现与接入

  • 自动发现：基于 mDNS 协议（服务类型：_esp_local_ctrl._tcp），设备接入网络后自动被 HA 发现，无需手动配置 IP 地址和端口

  • 一键添加：在 HA 界面中选择发现的设备即可完成添加

通信机制

  • HTTP 长连接：采用 HTTP 长连接（long-polling）机制实现设备状态实时推送

  • 双向通信：支持 HA 向设备下发控制指令，以及设备主动上报状态变化

  • 自动重连：具备设备在线状态检测与断线自动恢复能力

安全认证

  • Sec0：Security Version 0，基础安全模式

  • Sec1：Security Version 1，带 PoP (Proof of Possession) 凭据认证

动态实体管理

  • 动态实体创建：根据设备上报的属性信息，自动在 HA 中创建对应的实体类型

  • 实时状态同步：设备状态变化实时反映到 HA 界面

多实体支持

  • Light（灯光）

    • 开关控制、亮度调节、色调/饱和度（HSV）、色温调节、灯光效果

    • HA 可完整控制灯光的各项参数

  • Sensor（环境传感器）

    • 温度、湿度、气压等环境传感数据

    • HA 可查看实时值与历史数据

  • Binary Sensor（二值传感器）

    • 门窗状态、运动检测、震动检测、触摸感应

    • 设备传输开/关、检测/清除等状态变化到 HA

  • Number（可调数值）

    • 可调节阈值参数

  • Battery Energy（电池能源）

    • 电池电量百分比、电压、温度、充/放电状态

    • 支持低电告警

  • IMU Gesture（IMU 手势）

    • 手势识别事件：抛掷、翻转、摇晃、旋转、推动、画圈、方向变化等

    • HA 支持手势事件触发自动化

  • Interactive Input（交互输入）

    • 交互输入事件与数值（单击/双击/长按、角度/增量/速度）

  • Low Power Sleep（低功耗睡眠）

    • 低功耗睡眠状态、唤醒原因、唤醒窗口状态

架构设计

集成采用分层架构，遵循单一职责原则：

┌─────────────────────────────────────────────────────────────┐
│                    Home Assistant Core                       │
├─────────────────────────────────────────────────────────────┤
│  平台: light.py, sensor.py, binary_sensor.py, ...           │
├─────────────────────────────────────────────────────────────┤
│  coordinator.py (ESPDataUpdateCoordinator)                  │
│  └── 数据更新、可用性检查、重连逻辑                          │
├─────────────────────────────────────────────────────────────┤
│  iot/client/device_api.py (ESPWeaverApi)                    │
│  └── 主 API 协调器，委托到各管理器                           │
├─────────────────────────────────────────────────────────────┤
│  iot/managers/ (管理器类)                                   │
│  ├── DeviceRegistry      - 设备状态注册表                    │
│  ├── AvailabilityManager - 可用性检测                        │
│  ├── ConnectionManager   - 连接生命周期                      │
│  ├── PropertyManager     - 属性读写和消息处理                │
│  └── DeviceDiscoveryManager - 实体发现                       │
├─────────────────────────────────────────────────────────────┤
│  iot/client/client.py (ESPLocalCtrlClient)                  │
│  └── ESP Local Control 协议底层实现                          │
└─────────────────────────────────────────────────────────────┘

设备端

设备端组件（esp_weaver）可通过 IDF 组件注册表 获取，在 ESP-IDF 工程中执行以下命令即可添加：

idf.py add-dependency "espressif/esp_weaver^0.1.0"

  • 示例固件路径：examples/weaver

  • 可用示例：led_light（智能灯光）、imu_gesture（手势传感器）

安装方式

  • HACS 安装（推荐）：通过 HACS 添加自定义存储库 https://github.com/espressif/esp_weaver 后一键安装

  • 脚本安装：适用于 SSH/终端访问场景，执行 install.sh 脚本

  • Samba 共享：适用于 Home Assistant OS/Supervised 环境，通过文件复制安装

环境要求

  • Home Assistant Core ≥ 2025.12.5

  • Python ≥ 3.13.2