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..43c6242a1b --- /dev/null +++ b/content/components/zigbee.md @@ -0,0 +1,91 @@ +--- +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 +``` + +> [!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 + +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/) 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