From 0f77ec0f60170c8e017083595a77404cd8058f6d Mon Sep 17 00:00:00 2001 From: raul Date: Sun, 9 Nov 2025 20:33:43 +0100 Subject: [PATCH 1/4] Add zigbee component docu --- content/components/_index.md | 2 + content/components/zigbee.md | 87 ++++++++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+) create mode 100644 content/components/zigbee.md diff --git a/content/components/_index.md b/content/components/_index.md index ffbe2f631f..05fb2e25d8 100644 --- a/content/components/_index.md +++ b/content/components/_index.md @@ -97,6 +97,7 @@ ESPHome-specific components or components supporting ESPHome device provisioning "ESP32 Ethernet","components/ethernet","ethernet.svg","dark-invert" "ESP32 Hosted","components/esp32_hosted","network-wifi.svg","dark-invert" "OpenThread","components/openthread","openthread.png","" +"Zigbee","components/zigbee","zigbee.svg","" {{< /imgtable >}} ## Network Protocols @@ -112,6 +113,7 @@ ESPHome-specific components or components supporting ESPHome device provisioning "StatsD","components/statsd","connection.svg","dark-invert" "UDP","components/udp","udp.svg","" "Packet Transport","components/packet_transport/index","packet_transport.svg","dark-invert" +"Zigbee","components/zigbee","zigbee.svg","" {{< /imgtable >}} ## Bluetooth/BLE diff --git a/content/components/zigbee.md b/content/components/zigbee.md new file mode 100644 index 0000000000..fcc60518d0 --- /dev/null +++ b/content/components/zigbee.md @@ -0,0 +1,87 @@ +--- +description: "Instructions for setting up Zigbee component." +title: "Zigbee component" +params: + seo: + description: Instructions for setting up Zigbee component. + image: zigbee.svg +--- + +Zigbee is a low-power mesh networking standard for IoT devices. The low-power aspect is important for + battery-powered smart home devices. However, it’s also low-bandwidth, making it ideal for applications + that don’t send a lot of data, like switches or motion sensors. + +Zigbee uses the same RF technology as Thread (IEEE 802.15.4) but defines also multiple application standards. +This component, however, supports only the Homeautomation profile. +This component allows exposing supported ESPHome components over a Zigbee network to Home Assistant via + **Zigbee2MQTT** or **ZHA**. +Due to the limitations of the Zigbee protocol, only basic properties are exposed. Additional properties must be + configured manually in Home Assistant. + +> [!NOTE] +> You will need a Zigbee coordinator like **Zigbee2MQTT** or **ZHA**. + +## Usage + +This component requires an ESP32 with IEEE 802.15.4 connectivity (ESP32-C6 or ESP32-H2) and the use of +ESP-IDF. + +```yaml +# Example ESP-IDF configuration for ESP32-C6-DevKitM-1 board +esp32: + board: esp32-c6-devkitm-1 + framework: + type: esp-idf +``` + +{{< anchor "config-zigbee" >}} + +## Full Configuration + +This example show how to configure the Zigbee component. +```yaml +# Example configuration entry +zigbee: +``` + +### Configuration variables + +- **name** (*Optional*, string): Name of the Zigbee device. Defauts to the ESPHome node name. +- **router** (*Optional*, boolean): If true the Zigbee role will be `router` instead of `end device` and it will + forward Zigbee packets from other devices. Don't use this for battery powered devices. Defaults to `false`. + +### Actions + +### `factory_reset` Action + +This [action](#config-action) triggers a factory reset of the Zigbee device. It handles the leaving of the Zigbee network. + +```yaml +on_...: + then: + - zigbee.factory_reset +``` + +### Supported Components + +- [Binary Sensor](#config-binary_sensor): only **state** and **name** are exposed over Zigbee. + +## Zigbee Component Base Configuration + +All components in ESPHome that do some sort of communication through +Zigbee can have some overrides for specific options. + +### Configuration variables + +- **report** (**Optional**, enum): Report the state. One of `yes`, `no`, `force`. `yes` activates reporting and uses +the configuration from the coordinator. `force` ignores the the coordinator settings and reports every change. +Defaults to `yes`. + +> [!NOTE] +> ZHA sets the minimum reporting interval to 30 seconds for most sensor devices. If you need faster responses set `report` to `force`. + + +## See Also + +- [Zigbee2MQTT](https://www.zigbee2mqtt.io/) +- [Zigbee Home Automation](https://www.home-assistant.io/integrations/zha/) From 8e9e3a7b68655000cd6391f036b14bfb4443dd7c Mon Sep 17 00:00:00 2001 From: raul Date: Sun, 9 Nov 2025 20:42:27 +0100 Subject: [PATCH 2/4] add zigbee.svg --- static/images/zigbee.svg | 1 + 1 file changed, 1 insertion(+) create mode 100644 static/images/zigbee.svg diff --git a/static/images/zigbee.svg b/static/images/zigbee.svg new file mode 100644 index 0000000000..03f75c9b70 --- /dev/null +++ b/static/images/zigbee.svg @@ -0,0 +1 @@ + \ No newline at end of file From 20c1e2f73e5504dc3849f0f32aa6367cd40b866b Mon Sep 17 00:00:00 2001 From: raul Date: Sun, 9 Nov 2025 20:47:38 +0100 Subject: [PATCH 3/4] fix lint --- content/components/zigbee.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/components/zigbee.md b/content/components/zigbee.md index fcc60518d0..97790961d7 100644 --- a/content/components/zigbee.md +++ b/content/components/zigbee.md @@ -39,6 +39,7 @@ esp32: ## Full Configuration This example show how to configure the Zigbee component. + ```yaml # Example configuration entry zigbee: @@ -80,7 +81,6 @@ Defaults to `yes`. > [!NOTE] > ZHA sets the minimum reporting interval to 30 seconds for most sensor devices. If you need faster responses set `report` to `force`. - ## See Also - [Zigbee2MQTT](https://www.zigbee2mqtt.io/) From 06298e8df67e8896f75f270ef8de65e41cbb003a Mon Sep 17 00:00:00 2001 From: raul Date: Sun, 9 Nov 2025 20:57:27 +0100 Subject: [PATCH 4/4] Add warning for configuration changes --- content/components/zigbee.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/components/zigbee.md b/content/components/zigbee.md index 97790961d7..43c6242a1b 100644 --- a/content/components/zigbee.md +++ b/content/components/zigbee.md @@ -34,6 +34,10 @@ esp32: type: esp-idf ``` +> [!WARNING] +> Whenever the configuration is changed, the device should be re-inerviewed (z2m only) and removed and re-added +> to the Zigbee network. This is especially important if components are added or removed or if names change. + {{< anchor "config-zigbee" >}} ## Full Configuration