ESP-Weaver Technical Wiki

[中文]

Note

This document is automatically translated using AI. Please excuse any detailed errors. The official English version is still in progress.

ESP-Weaver Integration Solution

Description: ESP-Weaver is an open-source Home Assistant integration component developed by Espressif, used for controlling and managing IoT smart devices based on ESP chips. Through mDNS auto-discovery and ESP Local Control protocol, it enables convenient device access and control.

GitHub Repository: https://github.com/espressif/esp_weaver

Hardware:

ESP32

ESP32-C2

ESP32-C3

ESP32-C5

ESP32-C6

ESP32-C61

ESP32-S3

✓

✓

✓

✓

✓

✓

✓
Features:

Device Discovery and Access

  • Auto-discovery: Based on the mDNS protocol (service type: _esp_local_ctrl._tcp), devices are automatically discovered by HA after network access, eliminating the need for manual IP address and port configuration

  • One-click addition: Devices discovered can be added simply by selecting them in the HA interface

Communication Mechanism

  • HTTP Long Connection: Implements real-time device status push through HTTP long connection (long-polling) mechanism

  • Bidirectional Communication: Supports HA issuing control commands to devices, as well as devices actively reporting status changes

  • Auto-reconnect: Capable of device online status detection and automatic recovery from disconnection

Security Authentication

  • Sec0: Security Version 0, basic security mode

  • Sec1: Security Version 1, with PoP (Proof of Possession) credential authentication

Dynamic Entity Management

  • Dynamic entity creation: Automatically creates corresponding entity types in HA based on the attribute information reported by the device

  • Real-time status synchronization: Device status changes are reflected in real time on the HA interface

Multi-entity Support

  • Light

    • Switch control, brightness adjustment, hue/saturation (HSV), color temperature adjustment, light effects

    • HA can fully control all parameters of the light

  • Sensor (Environmental Sensor)

    • Environmental sensor data such as temperature, humidity, and atmospheric pressure

    • HA can view real-time values and historical data

  • Binary Sensor

    • Door and window status, motion detection, vibration detection, touch sensing

    • The device transmits on/off, detection/clearance, and other status changes to HA

  • Number (Adjustable Value)

    • Adjustable threshold parameters

  • Battery Energy

    • Battery percentage, voltage, temperature, charging/discharging status

    • Supports low battery warning

  • IMU Gesture

    • Gesture recognition events: throw, flip, shake, rotate, push, circle, direction change, etc.

    • HA supports gesture event-triggered automation

  • Interactive Input

    • Interactive input events and values (single/double click, long press, angle/increment/speed)

  • Low Power Sleep

    • Low power sleep status, wake-up reason, wake-up window status

Architectural Design

The integration adopts a layered architecture, following the single responsibility principle:

┌─────────────────────────────────────────────────────────────┐
│                    Home Assistant Core                       │
├─────────────────────────────────────────────────────────────┤
│  Platforms: light.py, sensor.py, binary_sensor.py, ...     │
├─────────────────────────────────────────────────────────────┤
│  coordinator.py (ESPDataUpdateCoordinator)                  │
│  └── Data update, availability check, reconnection logic   │
├─────────────────────────────────────────────────────────────┤
│  iot/client/device_api.py (ESPWeaverApi)                    │
│  └── Main API coordinator, delegated to various managers   │
├─────────────────────────────────────────────────────────────┤
│  iot/managers/ (Manager classes)                           │
│  ├── DeviceRegistry      - Device status registry          │
│  ├── AvailabilityManager - Availability detection          │
│  ├── ConnectionManager   - Connection lifecycle            │
│  ├── PropertyManager     - Property read/write and message handling │
│  └── DeviceDiscoveryManager - Entity discovery             │
├─────────────────────────────────────────────────────────────┤
│  iot/client/client.py (ESPLocalCtrlClient)                  │
│  └── ESP Local Control protocol underlying implementation  │
└─────────────────────────────────────────────────────────────┘

Device side

The device-side component (esp_weaver) can be obtained through the IDF Component Registry, and can be added to the ESP-IDF project by executing the following command:

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

  • Example firmware path: examples/weaver

  • Available examples: led_light(smart lighting), imu_gesture(gesture sensor)

Installation method

  • HACS installation (recommended): Add custom repository https://github.com/espressif/esp_weaver through HACS for one-click installation

  • Script installation: Suitable for SSH/terminal access scenarios, execute install.sh script

  • Samba sharing: Suitable for Home Assistant OS/Supervised environments, install by copying files

Environment requirements

  • Home Assistant Core ≥ 2025.12.5

  • Python ≥ 3.13.2