ESP-Weaver Solution Introduction
Note
This document is automatically translated using AI. Please excuse any detailed errors. The official English version is still in progress.
This document is divided into the following sections:
ESP-Weaver Solution Overview
ESP-Weaver is an open-source Home Assistant integration component developed by Espressif, allowing customers to control and manage IoT smart devices based on Espressif ESP chips (ESP32, ESP32-S3, ESP32-C series) in Home Assistant.
This solution is developed based on the ESP-IDF ESP Local Control protocol, and uses mDNS automatic discovery and HTTP long connection real-time communication mechanism to facilitate the access of ESP devices to the Home Assistant ecosystem.
Note
“Weaver” is derived from the weaver bird—a bird species that can weave scattered leaves into precise nests. The concept of ESP-Weaver is similar: integrating scattered ESP devices in the network into a whole, building a tightly interconnected smart home system in Home Assistant.
Advantages of the solution:
Open source and free: The integration code and device-side components are open source on GitHub, and customers can use and customize them freely
Low development threshold: The device side can introduce components with one click through
idf.py add-dependency, and the integration side supports one-click installation of HACSWide chip coverage: Supports multiple chips such as ESP32, ESP32-S3, ESP32-C2/C3/C5/C6/C61
Plug and play: mDNS automatic discovery, the device automatically appears in HA after power-on and networking, one-click addition
Based on ESP-IDF: Native ESP-IDF development, giving developers complete bottom-layer control capabilities
ESP-Weaver Reference Materials
ESP-Weaver Workflow
The following diagram shows the complete workflow between the ESP device and Home Assistant:
┌──────────────────┐ ┌──────────────────┐
│ ESP Device │ │ Home Assistant │
│ (esp_weaver firmware) │ │ (ESP-Weaver Integration) │
└────────┬─────────┘ └────────┬─────────┘
│ │
│ ① Device Discovery Phase │
│ │
│ Connect to WiFi │
│ Start ESP Local Control service │
│ Register mDNS service (_esp_local_ctrl._tcp) │
│ │
│ ──── mDNS Broadcast ──────────────────────────────> │
│ mDNS Discovery │
│ User clicks to add device │
│ │
│ ② Connection and Authentication Phase │
│ │
│ <─────────── Establish HTTP Connection ──────────── │
│ │
│ <═══════════ Secure Handshake (Sec0/Sec1) ═════════> │
│ (Sec1 requires PoP credentials) │
│ │
│ ③ Entity Discovery Phase │
│ │
│ <─────────── Query Device Attributes and Configuration ───── │
│ ──────────── Report Device Capabilities and Entity Information ──────> │
│ │
│ Dynamically create HA entity │
│ (Light, Sensor, │
│ Binary Sensor...) │
│ │
│ ④ Normal Operation Phase │
│ │
│ <─────────── Control Command (HTTP Request) ──────── │
│ (Turn on/off light, adjust color/brightness...) │
│ │
│ ──────────── Status Push (HTTP Long-Polling) ──────> │
│ (Real-time status change reporting) Real-time HA UI update │
│ │
│ ⑤ Exception Recovery Phase │
│ │
│ ─ ─ ─ ─ ─ ─ Connection Disconnection ─ ─ ─ ─ ─ ─ ─ ─ │
│ Device offline detection │
│ Trigger automatic reconnection │
│ │
│ <═══════════ Re-establish Connection ═════════════> │
│ ──────────── Status Synchronization Recovery ──────> │
│ │
▼ ▼
Phase Description
Device Discovery: After the ESP device burns the esp_weaver firmware and connects to WiFi, it automatically registers the mDNS service. The ESP-Weaver integration in HA automatically discovers devices in the network through the mDNS protocol.
Connection and Authentication: After the user selects the discovered device in HA, the integration establishes an HTTP connection with the device and completes the secure handshake (Sec0 does not require credentials, Sec1 requires input of PoP credentials).
Entity Discovery: After the connection is established, the integration queries the device’s attribute configuration, and the device reports its supported entity types and capabilities. Based on this, the integration automatically creates corresponding entities (such as lights, sensors, etc.) in HA.
Normal Operation: HA sends control commands to the device through HTTP requests; the device pushes status changes to HA in real time through the HTTP long connection (Long-Polling) mechanism, achieving two-way communication.
Exception Recovery: When the network is interrupted or the device is offline, it automatically detects and re-establishes the connection after the device recovers, restoring the state synchronization.
ESP-Weaver Common Application Scenarios
Environmental Monitoring System: Collection and monitoring of sensor data such as temperature, humidity, atmospheric pressure, illumination, air quality, etc., supporting threshold alarms and automated linkage
Smart Lighting Control: RGB light strip, color temperature adjustment, lighting effects, brightness adjustment, scene linkage control
Gesture Control Interaction: IMU gesture recognition (flipping, shaking, rotating, clapping, etc.), gesture-triggered automated scenes
Low Power IoT: Battery-powered device management, sleep/wake state monitoring, energy consumption statistics
Smart Panel/Controller: Button/touch event reporting, knob control, physical control panel
Security Alarm: Door and window opening and closing detection, motion/vibration detection, intrusion alarm
ESP-Weaver How to Enable
Home Assistant Side: Install ESP-Weaver Integration
Make sure Home Assistant has installed HACS
Add a custom repository in HACS:
https://github.com/espressif/esp_weaver, select “Integration” for the typeSearch for ESP-Weaver and download
Restart Home Assistant
Device Side: Add esp_weaver component
In an existing ESP-IDF project, add the esp_weaver component through the IDF component manager:
idf.py add-dependency "espressif/esp_weaver^0.1.0"
If you need to refer to a complete example project:
git clone https://github.com/espressif/esp-iot-solution.git
cd esp-iot-solution/examples/weaver
Available examples: led_light(smart lighting), imu_gesture(gesture sensor).
Add Device to Home Assistant
Go to HA Settings → Devices & Services → Add Integration
Search and select ESP-Weaver
Choose the target device from the list of discovered devices
If the device enables secure mode (Sec1), you need to enter PoP credentials
After configuration, the device entity will automatically register to Home Assistant
For detailed installation steps, please refer to ESP-Weaver GitHub README.