Add zigbee component docu

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

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/)