From b9027d53b9e8851eea67b2100487d7a15512f040 Mon Sep 17 00:00:00 2001 From: bestbug456 Date: Thu, 4 Dec 2025 18:42:55 +0100 Subject: [PATCH 1/4] reivew of README content --- README.md | 288 +++++++++++++++++++++++++++++------------------------- 1 file changed, 157 insertions(+), 131 deletions(-) diff --git a/README.md b/README.md index e64a6c3..c69af0d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,11 @@ +# ESPHome ZigBee Component + +[![GitHub](https://img.shields.io/github/license/luar123/zigbee_esphome)](https://github.com/luar123/zigbee_esphome/blob/main/LICENSE) +[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/luar123/zigbee_esphome)](https://github.com/luar123/zigbee_esphome/releases/latest) +[![GitHub issues](https://img.shields.io/github/issues/luar123/zigbee_esphome)](https://github.com/luar123/zigbee_esphome/issues) + +External ZigBee component for ESPHome, enabling integration with Zigbee devices using the ESP Zigbee SDK. + > [!TIP] > **New simple Mode! No more endpoint definitions needed.** > @@ -8,65 +16,74 @@ > > **If something is not working please check the [troubleshooting](#troubleshooting) section first. Config validation is not complete. Always consult [Zigbee Cluster Library](https://csa-iot.org/wp-content/uploads/2022/01/07-5123-08-Zigbee-Cluster-Library-1.pdf) for cluster definitions** -# ESPHome ZigBee external component - -External ZigBee component for ESPHome. - -### Features -* Automated generation of zigbee definition for lights, switches, sensors and binary sensors (see basic mode) -* Definition of endpoints, clusters and attributes supported by esp-zigbee-sdk 1.6 -* Set attributes action -* Manual report action -* Reset zigbee action -* Join trigger -* Attribute received trigger -* Time sync with coordinator -* Custom clusters and attributes -* (normal, binary, text) sensors, switches and lights can be connected to attributes without need for lambdas/actions -* Wifi co-existence on ESP32-C6 and ESP32-C5 -* Deep-sleep should work -* Not tested: groups -* Time sync with coordinator -* Router - -### Limitations -* No coordinator devices -* Attribute set action works only with numeric types and character string -* Attribute OnValue trigger works only with numeric types -* Reporting can be enabled, but not configured -* No control devices like switches ([workaround](https://github.com/luar123/zigbee_esphome/discussions/18#discussioncomment-11875376)) -* Needs esp-idf >=5.1.4 -* Needs esphome >=2025.7 -* scenes not implemented -* Officially the zigbee stack supports only 10 endpoints. however, this is not enforced and at least for sensor endpoints more than 10 seem to work. More then 10 light endpoints will crash! -* zigbee2mqtt: Only one light is supported without creating a custom converter/definition -* zigbee2mqtt: Analog input cluster (used for sensors) is supported by 2025 October release, but ignores type and unit -* ZHA: Analog input cluster (used for sensors) without unit/type is ignored -* ZHA: Minimum reporting interval is set to high values (30s) for some sensors and can't be changed. Keep that in mind if reporting seems not to work properly. - -### ToDo List (Short-Mid term) -* Light effects (through identify cluster commands) -* more components to support basic mode - -### Not planed (feel free to submit a PR) -* Coordinator devices -* Binding config in yaml -* Reporting config in yaml -* Control device support like switches ([workaround](https://github.com/luar123/zigbee_esphome/discussions/18#discussioncomment-11875376)) +## Table of Contents +1. [Features](#features) +2. [Requirements](#requirements) +3. [Installation](#installation) +4. [Usage](#usage) +5. [Configuration](#configuration) +6. [Basic Mode](#basic-mode) +7. [Advanced Mode](#advanced-mode) +8. [Actions](#actions) +9. [Time Sync](#time-sync) +10. [Troubleshooting](#troubleshooting) +11. [Limitations](#limitations) +12. [Contributing](#contributing) +13. [External Documentation](#external-documentation) + +## Features + +* **Automated Generation**: Automated generation of Zigbee definitions for lights, switches, sensors and binary sensors (see basic mode) +* **Manual Definitions**: Definition of endpoints, clusters and attributes supported by esp-zigbee-sdk 1.6 +* **Attribute Actions**: Set attributes action +* **Reporting**: Manual report action +* **Reset**: Reset zigbee action +* **Join Trigger**: Join trigger +* **Attribute Triggers**: Attribute received trigger +* **Time Sync**: Time sync with coordinator +* **Custom Clusters**: Custom clusters and attributes +* **Component Support**: (normal, binary, text) sensors, switches and lights can be connected to attributes without need for lambdas/actions +* **WiFi Co-existence**: WiFi co-existence on ESP32-C6 and ESP32-C5 +* **Deep Sleep**: Deep-sleep should work +* **Router Support**: Router support + +## Requirements + +* **ESP-IDF**: >=5.1.4 +* **ESPHome**: >=2025.7 +* **Supported Boards**: ESP32-H2, ESP32-C5, ESP32-C6 SoC + +## Installation + +### Using External Component (Recommended) + +Add to your ESPHome YAML configuration: + +```yaml +external_components: + - source: github://luar123/zigbee_esphome + components: [zigbee] + +zigbee: + components: all # to add all supported components +``` ## Usage Include external component: -``` +```yaml external_components: - source: github://luar123/zigbee_esphome components: [zigbee] zigbee: components: all # to add all supported components - ... ``` -### Configuration variables: + +## Configuration + +### Zigbee Configuration Variables: + * **id** (Optional, string): Manually specify the ID for code generation. * **name** (Optional, string): Zigbee Model Identifier in basic cluster. Used by coordinator to match custom converters. Defaults to esphome.name * **manufacturer** (Optional, string): Zigbee Manufacturer Name in basic cluster. Used by coordinator to match custom converters. Defaults to "esphome" @@ -80,23 +97,23 @@ zigbee: * **as_generic** (Optional, bool): Use generic/basic clusters where possible. Currently sensors and switches. Defaults to false * **endpoints** (Optional, list): endpoint list for advanced definitions. See examples -[Todo] +## Basic Mode -### Basic mode -By adding `components: all` the endpoint definition is generated automatically. Currently sensor, binary_sensor, light and switch components are supported. Because this is an external component the whole implementation is a bit hacky and likely to fail with some setups. Also it is not possible to tweak the generated definitions. Each entity creates a new endpoint. Lights are using the light clusters, switches on_off or binary_output clusters, binary sensors using binary_input clusters and sensors are using either special clusters (e.g. temperature) or analog_input clusters. For sensors also the unit/type is set. Please note that these definitions are not complete. Feel free to open an issue or pull request (see zigbee_ep.py) +By adding `components: all` the endpoint definition is generated automatically. Currently sensor, binary_sensor, light and switch components are supported. Because this is an external component the whole implementation is a bit hacky and likely to fail with some setups. Also it is not possible to tweak the generated definitions. Each entity creates a new endpoint. -example: -``` +### Example: +```yaml zigbee: id: "zb" components: all ``` -### Advanced mode +## Advanced Mode + Endpoint/Cluster definitions can be defined manually. Can be combined with automated definition. -Advanced example: -``` +### Advanced Example: +```yaml zigbee: id: "zb" endpoints: @@ -178,39 +195,30 @@ zigbee: - logger.log: "Joined network" ``` -### Actions -* zigbee.setAttr - * id: "id of attribute" - * value: "value, can be a lambda" - * only numeric or string types -* zigbee.report: "id of zigbee component" - * Manually send reports for all attributes with report=true -* zigbee.reportAttr: "id of zigbee_attribute component" - * Manually send report for attribute -* zigbee.reset: "id of zigbee component" - * Reset Zigbee Network and Device. Leave the current network and tries to join open networks. - -Examples: -``` - on_value: - then: - - zigbee.setAttr: - id: hum_attr - value: !lambda "return x*100;" -``` -``` - on_press: - then: - - zigbee.report: zb -``` +## Actions + +### zigbee.setAttr +* **id**: "id of attribute" +* **value**: "value, can be a lambda" + * only numeric or string types + +### zigbee.report +* **id**: "id of zigbee component" +* **Manually send reports for all attributes with report=true** + +### zigbee.reportAttr +* **id**: "id of zigbee_attribute component" +* **Manually send report for attribute** + +### zigbee.reset +* **id**: "id of zigbee component" +* **Reset Zigbee Network and Device. Leave the current network and tries to join open networks.** + +## Time Sync -### Time sync Add a 'time' component with platform 'zigbee', e.g.: -``` -zigbee: - id: "zb" - ... +```yaml time: - platform: zigbee timezone: Europe/London @@ -224,28 +232,65 @@ time: ``` ## Troubleshooting -* Build errors - - Try to run `esphome clean ` - - Try to delete the `.esphome/build//` folder -* ESP crashes - - Try to erase completely with `esptool.py erase_flash` and flash again. - - Make sure your configuration is valid. Config validation is not complete. Always consult [Zigbee Cluster Library](https://csa-iot.org/wp-content/uploads/2022/01/07-5123-08-Zigbee-Cluster-Library-1.pdf) for cluster definitions - - Common issues are that attributes do not support reporting (try set `report: false`), use a different type, or are not readable/writable (see ZCL). -* Zigbee is not working as expected - - Whenever the cluster definition changed you need to re-interview and remove/add the device to your network. - - Sometimes it helps to power-cycle the coordinator and restarting z2m. - - Remove other endpoints. Sometimes coordinators struggle with multiple endpoints. -## Notes -* I don't have much free time to work on this right now, so feel free to fork/improve/create PRs/etc. -* At the moment, the C++ implementation is rather simple and generic. I tried to keep as much logic as possible in the python part. However, endpoints/clusters ~~/attributes~~ could also be classes, this would simplify the yaml setup but requires more sophisticated C++ code. -* There is also a project with more advanced C++ zigbee libraries for esp32 that could be used here as well: https://github.com/Muk911/esphome/tree/main/esp32c6/hello-zigbee -* [parse_zigbee_headers.py](components/zigbee/files_to_parse/parse_zigbee_headers.py) is used to create the python enums and C helper functions automatically from zigbee sdk headers. -* Deprecated [custom zigbee component](https://github.com/luar123/esphome_zb_sensor) +* **Build errors** + * Try to run `esphome clean ` + * Try to delete the `.esphome/build//` folder +* **ESP crashes** + * Try to erase completely with `esptool.py erase_flash` and flash again. + * Make sure your configuration is valid. Config validation is not complete. Always consult [Zigbee Cluster Library](https://csa-iot.org/wp-content/uploads/2022/01/07-5123-08-Zigbee-Cluster-Library-1.pdf) for cluster definitions + * Common issues are that attributes do not support reporting (try set `report: false`), use a different type, or are not readable/writable (see ZCL). +* **Zigbee is not working as expected** + * Whenever the cluster definition changed you need to re-interview and remove/add the device to your network. + * Sometimes it helps to power-cycle the coordinator and restarting z2m. + * Remove other endpoints. Sometimes coordinators struggle with multiple endpoints. + +## Limitations + +* **No Coordinator Support**: No coordinator devices +* **Attribute Set**: Attribute set action works only with numeric types and character string +* **OnValue Trigger**: OnValue trigger works only with numeric types +* **Reporting**: Reporting can be enabled, but not configured +* **Control Devices**: No control devices like switches [workaround available](https://github.com/luar123/zigbee_esphome/discussions/18#discussioncomment-11875376) +* **ESP-IDF Requirement**: Needs esp-idf >=5.1.4 +* **ESPHome Version**: Needs esphome >=2025.7 +* **Scenes**: Scenes not implemented +* **Endpoint Limit**: Officially the zigbee stack supports only 10 endpoints. However, this is not enforced and at least for sensor endpoints more than 10 seem to work. More than 10 light endpoints will crash! +* **Zigbee2MQTT Compatibility**: Only one light is supported without creating a custom converter/definition +* **Zigbee2MQTT Sensors**: Analog input cluster (used for sensors) is supported by 2025 October release, but ignores type and unit +* **ZHA Compatibility**: Analog input cluster (used for sensors) without unit/type is ignored +* **ZHA Reporting**: Minimum reporting interval is set to high values (30s) for some sensors and can't be changed. Keep that in mind if reporting seems not to work properly. + +## Contributing + +**Please submit all PRs here** and not to https://github.com/luar123/esphome/tree/zigbee + +Use pre-commit hook by enabling you esphome environment first and then running `pre-commit install` in the git root foulder. + +If looking to contribute to this project, then suggest follow steps in these guides + look at issues in Espressif's ESP Zigbee SDK repository: + +* https://github.com/espressif/esp-zigbee-sdk/issues +* https://github.com/firstcontributions/first-contributions/blob/master/README.md +* https://github.com/firstcontributions/first-contributions/blob/master/github-desktop-tutorial.md + +## External Documentation + +### Official Resources + +* [ESP Zigbee SDK Programming Guide](https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32/) +* [ESP-Zigbee-SDK Github repo](https://github.com/espressif/esp-zigbee-sdk) +* [ESP-Zigbee-SDK examples](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/) + * [Zigbee HA Example](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/esp_zigbee_HA_sample) + * [Zigbee HA Light Bulb example](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/esp_zigbee_HA_sample/HA_on_off_light) + * [Zigbee HA temperature sensor example](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/esp_zigbee_HA_sample/HA_temperature_sensor) + * [Zigbee HA thermostat example](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/esp_zigbee_HA_sample/HA_thermostat) + +### Additional Resources -## Example Zigbee device +* [ESP32-H2 Application User Guide](https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32h2/application.html) +* [ESP32-C6 Application User Guide](https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32c6/application.html) -ESPHome Zigbee using only dev board or additionally [AHT10 Temperature+Humidity Sensor](https://next.esphome.io/components/sensor/aht10). +## Example Zigbee Device ### Hardware Required @@ -259,31 +304,12 @@ ESPHome Zigbee using only dev board or additionally [AHT10 Temperature+Humidity * We will build [example_esp32h2.yaml](example_esp32h2.yaml) file. * Check [Getting Started with the ESPHome Command Line](https://esphome.io/guides/getting_started_command_line.html) tutorial to set up your dev environment. -* Build with `esphome run example_esp32h2.yaml`. +* Build with `esphome run example_esp32h2.yaml`. -## How to contribute - -**Please submit all PRs here** and not to https://github.com/luar123/esphome/tree/zigbee - -Use pre-commit hook by enabling you esphome environment first and then running `pre-commit install` in the git root foulder. - -If looking to contribute to this project, then suggest follow steps in these guides + look at issues in Espressif's ESP Zigbee SDK repository: - -- https://github.com/espressif/esp-zigbee-sdk/issues -- https://github.com/firstcontributions/first-contributions/blob/master/README.md -- https://github.com/firstcontributions/first-contributions/blob/master/github-desktop-tutorial.md - - -## External documentation and reference - -Note! The official documentation and reference examples for the ESP Zigbee SDK can currently be obtained from Espressif: +## Notes - - [ESP32 Zigbee SDK Programming Guide](https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32/) - - [ESP32-H2 Application User Guide](https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32h2/application.html) - - [ESP32-C6 Application User Guide](https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32c6/application.html) -- [ESP-Zigbee-SDK Github repo](https://github.com/espressif/esp-zigbee-sdk) - - [ESP-Zigbee-SDK examples](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/) - - [Zigbee HA Example](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/esp_zigbee_HA_sample) - - [Zigbee HA Light Bulb example](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/esp_zigbee_HA_sample/HA_on_off_light) - - [Zigbee HA temperature sensor example](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/esp_zigbee_HA_sample/HA_temperature_sensor) - - [Zigbee HA thermostat example](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/esp_zigbee_HA_sample/HA_thermostat) +* I don't have much free time to work on this right now, so feel free to fork/improve/create PRs/etc. +* At the moment, the C++ implementation is rather simple and generic. I tried to keep as much logic as possible in the python part. However, endpoints/clusters ~~/attributes~~ could also be classes, this would simplify the yaml setup but requires more sophisticated C++ code. +* There is also a project with more advanced C++ zigbee libraries for esp32 that could be used here as well: https://github.com/Muk911/esphome/tree/main/esp32c6/hello-zigbee +* [parse_zigbee_headers.py](components/zigbee/files_to_parse/parse_zigbee_headers.py) is used to create the python enums and C helper functions automatically from zigbee sdk headers. +* Deprecated [custom zigbee component](https://github.com/luar123/esphome_zb_sensor) From 4eb312aeda3239ef056eb5d499c2951a89303381 Mon Sep 17 00:00:00 2001 From: bestbug456 Date: Sat, 6 Dec 2025 10:35:03 +0100 Subject: [PATCH 2/4] docs: Update README with required partition table configuration Removed GitHub badges from README and added important documentation about the mandatory partitions_zb.csv file that must be included in ESP32 configurations when using this component. The new section explains that this file is required for proper Zigbee operations and can be found in the component directory, defining the memory partitions needed for Zigbee functionality. --- README.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index c69af0d..ac730e0 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,5 @@ # ESPHome ZigBee Component -[![GitHub](https://img.shields.io/github/license/luar123/zigbee_esphome)](https://github.com/luar123/zigbee_esphome/blob/main/LICENSE) -[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/luar123/zigbee_esphome)](https://github.com/luar123/zigbee_esphome/releases/latest) -[![GitHub issues](https://img.shields.io/github/issues/luar123/zigbee_esphome)](https://github.com/luar123/zigbee_esphome/issues) - External ZigBee component for ESPHome, enabling integration with Zigbee devices using the ESP Zigbee SDK. > [!TIP] @@ -101,6 +97,15 @@ zigbee: By adding `components: all` the endpoint definition is generated automatically. Currently sensor, binary_sensor, light and switch components are supported. Because this is an external component the whole implementation is a bit hacky and likely to fail with some setups. Also it is not possible to tweak the generated definitions. Each entity creates a new endpoint. +**Important**: you must include the required partition table file in your ESP32 configuration each time that you using this components: + +```yaml +esp32: + partitions: partitions_zb.csv +``` + +This file is mandatory for proper operation and can be found in the component directory. It defines the memory partitions needed for Zigbee operations. + ### Example: ```yaml zigbee: From 7e95f064ed5317aaadfd016cde1c7ba29782ea6e Mon Sep 17 00:00:00 2001 From: bestbug456 Date: Sat, 30 May 2026 17:23:57 +0200 Subject: [PATCH 3/4] update doc as requested by the mantainer --- README.md | 38 +++++++++++++++++++++++++++++++++----- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ac730e0..c32bee4 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,10 @@ External ZigBee component for ESPHome, enabling integration with Zigbee devices using the ESP Zigbee SDK. > [!TIP] -> **New simple Mode! No more endpoint definitions needed.** +> **Experimental zigbee-sdk v2.0 implementation in [v2 branch](https://github.com/luar123/zigbee_esphome/tree/v2)** > -> I started to implement the automated endpoint definition generation, see basic mode section for details. +> Please test. For issues and limitations see [#96](https://github.com/luar123/zigbee_esphome/issues/96). +> Once stable this will be merged into master. If you want to stay on v1.x you can use the v1.x branch. > [!Important] > **Please help to collect working cluster definitions [here](https://github.com/luar123/zigbee_esphome/discussions/22).** @@ -24,8 +25,10 @@ External ZigBee component for ESPHome, enabling integration with Zigbee devices 9. [Time Sync](#time-sync) 10. [Troubleshooting](#troubleshooting) 11. [Limitations](#limitations) -12. [Contributing](#contributing) -13. [External Documentation](#external-documentation) +12. [ToDo List](#todo-list-short-mid-term) +13. [Not Planned](#not-planned-feel-free-to-submit-a-pull-request) +14. [Contributing](#contributing) +15. [External Documentation](#external-documentation) ## Features @@ -85,9 +88,14 @@ zigbee: * **manufacturer** (Optional, string): Zigbee Manufacturer Name in basic cluster. Used by coordinator to match custom converters. Defaults to "esphome" * **date** (Optional, string): Date Code in basic cluster. Defaults to build time * **power_supply** (Optional, int): Zigbee Power Source in basic cluster. See ZCL. Defaults to 0 = unknown + - `1` = single phase mains (USB) + - `2` = three phase mains + - `3` = battery * **version** (Optional, int): Zigbee App Version in basic cluster. Defaults to 0 * **area** (Optional, int): Zigbee Physical Environment in basic cluster. See ZCL. Defaults to 0 = unknown * **router** (Optional, bool): Create a router device instead of an end device. Defaults to false +* **device_version** (Optional, int): Set the Home Automation Profile device version. Custom values might be needed for compatibility with some vendors. Defaults to 0 +* **trust_center_key** (Optional, bind_key): Set custom trust center key. 32 digits hex number. * **debug** (Optional, bool): Print zigbee stack debug messages * **components** (Optional, string|list): all: add definitions for all supported components that have a name and are not marked as internal. None: Add no definitions (default). List of component ids: Add only those. Can be combined with manual definitions in endpoints * **as_generic** (Optional, bool): Use generic/basic clusters where possible. Currently sensors and switches. Defaults to false @@ -95,7 +103,14 @@ zigbee: ## Basic Mode -By adding `components: all` the endpoint definition is generated automatically. Currently sensor, binary_sensor, light and switch components are supported. Because this is an external component the whole implementation is a bit hacky and likely to fail with some setups. Also it is not possible to tweak the generated definitions. Each entity creates a new endpoint. +By adding `components: all` the endpoint definition is generated automatically. Currently sensor, binary_sensor, light and switch components are supported. Because this is an external component the whole implementation is a bit hacky and likely to fail with some setups. Also it is not possible to tweak the generated definitions. Each entity creates a new endpoint. For sensors the unit/type is set automatically. Please note that these definitions are not complete. Feel free to open an issue or pull request (see zigbee_ep.py) + +| ESPHome Entity | Zigbee Cluster | +| --------------- | ------------------------------------------------------------------ | +| `light` | `light` | +| `switch` | `on_off`, `binary_output` | +| `binary_sensor` | `binary_input` | +| `sensor` | `analog_input` or mapped to specific (e.g. `temperature`) clusters | **Important**: you must include the required partition table file in your ESP32 configuration each time that you using this components: @@ -266,6 +281,19 @@ time: * **ZHA Compatibility**: Analog input cluster (used for sensors) without unit/type is ignored * **ZHA Reporting**: Minimum reporting interval is set to high values (30s) for some sensors and can't be changed. Keep that in mind if reporting seems not to work properly. +## ToDo List (Short-Mid term) + +- Light effects (through identify cluster commands) +- more components to support basic mode + +## Not planned (feel free to submit a pull request) + +- [Zigbee ZCL OTA Upgrade Cluster](https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32/user-guide/zcl_ota_upgrade.html) and related [OTA API for ESP Zigbee SDK](https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32/api-reference/esp_zigbee_ota.html) to allow OTA (over-the-air) firmware updates via Zigbee +- Coordinator devices +- Binding config in yaml +- Reporting config in yaml +- Control device support like switches ([workaround](https://github.com/luar123/zigbee_esphome/discussions/18#discussioncomment-11875376)) + ## Contributing **Please submit all PRs here** and not to https://github.com/luar123/esphome/tree/zigbee From e2dc17688a40b593eda29093bfc79b23bb7a983a Mon Sep 17 00:00:00 2001 From: bestbug456 Date: Tue, 2 Jun 2026 12:56:43 +0200 Subject: [PATCH 4/4] Merge PR #73 changes (README improvements from #85) and remove partition table note - Reorganized README with table of contents - Formatted features, limitations, and configuration sections - Removed partition table requirement (no longer needed) - Kept all recent changes from #85 --- README.md | 338 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 173 insertions(+), 165 deletions(-) diff --git a/README.md b/README.md index 055e53c..a864e11 100644 --- a/README.md +++ b/README.md @@ -1,114 +1,109 @@ -> [!Warning] -> **Experimental zigbee-sdk v2.0 implementation.** +# ESPHome ZigBee Component + +External ZigBee component for ESPHome, enabling integration with Zigbee devices using the ESP Zigbee SDK. + +> [!TIP] +> **Experimental zigbee-sdk v2.0 implementation in [v2 branch](https://github.com/luar123/zigbee_esphome/tree/v2)** > -> **Breaking Change: needs re-join!** -> For issues and limitations see [#96](https://github.com/luar123/zigbee_esphome/issues/96). Please test and report issues. Once stable, this will be merged into master. If you want to stay on v1.x you can use the v1.x branch. +> Please test. For issues and limitations see [#96](https://github.com/luar123/zigbee_esphome/issues/96). +> Once stable this will be merged into master. If you want to stay on v1.x you can use the v1.x branch. > [!Important] > **Please help to collect working cluster definitions [here](https://github.com/luar123/zigbee_esphome/discussions/22).** -> +> > **If something is not working please check the [troubleshooting](#troubleshooting) section first. Config validation is not complete. Always consult [Zigbee Cluster Library](https://csa-iot.org/wp-content/uploads/2022/01/07-5123-08-Zigbee-Cluster-Library-1.pdf) for cluster definitions** -# ESPHome ZigBee external component - -External Zigbee component for ESPHome. - -- v2 branch is based on Espressif's self-developed proprietary Zigbee stack (used by ESP Zigbee SDK 2.0). -- v1.x branch was based on the ZBOSS Zigbee stack (used by ESP Zigbee SDK 1.x). - -This is tested on ESP32-H2 and ESP32-C6, however, is in theory also compatible with all ESP32 models with a 802.15.4 radio, which includes ESP32-H2, ESP32-C5, ESP32-C6, ESP32-H4, ESP32-H21, ESP32-S31 (but only once those are supported by ESPHome and Espressif ESP Zigbee SDK 2.0). +## Table of Contents +1. [Features](#features) +2. [Requirements](#requirements) +3. [Installation](#installation) +4. [Usage](#usage) +5. [Configuration](#configuration) +6. [Basic Mode](#basic-mode) +7. [Advanced Mode](#advanced-mode) +8. [Actions](#actions) +9. [Time Sync](#time-sync) +10. [Troubleshooting](#troubleshooting) +11. [Limitations](#limitations) +12. [ToDo List](#todo-list-short-mid-term) +13. [Not Planned](#not-planned-feel-free-to-submit-a-pull-request) +14. [Contributing](#contributing) +15. [External Documentation](#external-documentation) ## Features -- Automated generation of zigbee definition for lights, switches, sensors and binary sensors (see basic mode) -- Definition of endpoints, clusters and attributes supported by esp-zigbee-sdk 1.6 -- Set attributes action -- Manual report action -- Reset zigbee action -- Join trigger -- Attribute received trigger -- Time sync with coordinator -- Custom clusters and attributes -- (normal, binary, text) sensors, switches and lights can be connected to attributes without need for lambdas/actions -- Wifi co-existence on ESP32-C6 and ESP32-C5 -- Deep-sleep should work -- Not tested: groups -- Time sync with coordinator -- Router +* **Automated Generation**: Automated generation of Zigbee definitions for lights, switches, sensors and binary sensors (see basic mode) +* **Manual Definitions**: Definition of endpoints, clusters and attributes supported by esp-zigbee-sdk 1.6 +* **Attribute Actions**: Set attributes action +* **Reporting**: Manual report action +* **Reset**: Reset zigbee action +* **Join Trigger**: Join trigger +* **Attribute Triggers**: Attribute received trigger +* **Time Sync**: Time sync with coordinator +* **Custom Clusters**: Custom clusters and attributes +* **Component Support**: (normal, binary, text) sensors, switches and lights can be connected to attributes without need for lambdas/actions +* **WiFi Co-existence**: WiFi co-existence on ESP32-C6 and ESP32-C5 +* **Deep Sleep**: Deep-sleep should work +* **Router Support**: Router support -## Limitations +## Requirements -- No coordinator devices -- Attribute set action works only with numeric types and character string -- Attribute OnValue trigger works only with numeric types -- Reporting can be enabled, but not configured -- No control devices like switches ([workaround](https://github.com/luar123/zigbee_esphome/discussions/18#discussioncomment-11875376)) -- Needs esp-idf >=5.1.4 -- Needs esphome >=2025.7 -- scenes not implemented -- Officially the zigbee stack supports only 10 endpoints. however, this is not enforced and at least for sensor endpoints more than 10 seem to work. More then 10 light endpoints will crash! -- zigbee2mqtt: Only one light is supported without creating a custom converter/definition -- zigbee2mqtt: Analog input cluster (used for sensors) is supported by 2025 October release, but ignores type and unit -- ZHA: Analog input cluster (used for sensors) without unit/type is ignored -- ZHA: Minimum reporting interval is set to high values (30s) for some sensors and can't be changed. Keep that in mind if reporting seems not to work properly. +* **ESP-IDF**: >=5.1.4 +* **ESPHome**: >=2025.7 +* **Supported Boards**: ESP32-H2, ESP32-C5, ESP32-C6 SoC -## ToDo List (Short-Mid term) +## Installation -- Light effects (through identify cluster commands) -- more components to support basic mode +### Using External Component (Recommended) -## Not planned (feel free to submit a pull request) +Add to your ESPHome YAML configuration: -- [Zigbee ZCL OTA Upgrade Cluster](https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32/user-guide/zcl_ota_upgrade.html) and related [OTA API for ESP Zigbee SDK](https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32/api-reference/esp_zigbee_ota.html) to allow OTA (over-the-air) firmware updates via Zigbee -- Coordinator devices -- Binding config in yaml -- Reporting config in yaml -- Control device support like switches ([workaround](https://github.com/luar123/zigbee_esphome/discussions/18#discussioncomment-11875376)) +```yaml +external_components: + - source: github://luar123/zigbee_esphome + components: [zigbee] + +zigbee: + components: all # to add all supported components +``` ## Usage Include external component: - -``` +```yaml external_components: - source: github://luar123/zigbee_esphome components: [zigbee] zigbee: - use_v2_sdk: true components: all # to add all supported components - ... ``` -### Configuration variables +## Configuration -- **id** (Optional, string): Manually specify the ID for code generation. -- **name** (Optional, string): Zigbee Model Identifier in basic cluster. Used by coordinator to match custom converters. Defaults to `esphome.name` -- **manufacturer** (Optional, string): Zigbee Manufacturer Name in basic cluster. Used by coordinator to match custom converters. Defaults to `"esphome"` -- **date** (Optional, string): Date Code in basic cluster. Defaults to build time -- **power_supply** (Optional, int): Zigbee Power Source in basic cluster. Defaults to `0` = unknown +### Zigbee Configuration Variables: + +* **id** (Optional, string): Manually specify the ID for code generation. +* **name** (Optional, string): Zigbee Model Identifier in basic cluster. Used by coordinator to match custom converters. Defaults to esphome.name +* **manufacturer** (Optional, string): Zigbee Manufacturer Name in basic cluster. Used by coordinator to match custom converters. Defaults to "esphome" +* **date** (Optional, string): Date Code in basic cluster. Defaults to build time +* **power_supply** (Optional, int): Zigbee Power Source in basic cluster. See ZCL. Defaults to 0 = unknown - `1` = single phase mains (USB) - `2` = three phase mains - `3` = battery -- **version** (Optional, int): Zigbee App Version in basic cluster. Defaults to `0` -- **area** (Optional, int): Zigbee Physical Environment in basic cluster. See ZCL. Defaults to `0` = unknown -- **router** (Optional, bool): Create a router device instead of an end device. Defaults to `false` -- **device_version** (Optional, int): Set the Home Automation Profile device version. Custom values might be needed for compatibility with some vendors. Defaults to `0` -- **trust_center_key** (Optional, bind_key): Set custom trust center key. 32 digits hex number. -- **debug** (Optional, bool): Print zigbee stack debug messages. Defaults to `false` -- **components** (Optional, string|list): `all`: add definitions for all supported components that have a name and are not marked as internal. - - None: Add no definitions (default). - - List of component ids: Add only those. Can be combined with manual definitions in endpoints -- **as_generic** (Optional, bool): Use generic/basic clusters where possible. Currently sensors and switches. Defaults to false -- **endpoints** (Optional, list): endpoint list for advanced definitions. See examples - -[Todo] - -### Basic mode - -By adding `components: all` the endpoint definition is generated automatically. Currently [sensor](https://esphome.io/components/sensor/), [binary_sensor](https://esphome.io/components/binary_sensor/), [light](https://esphome.io/components/light/) and [switch](https://esphome.io/components/switch/) ESPHome components are supported. -Because this is an [external component](https://esphome.io/components/external_components/) the whole implementation is a bit hacky and likely to fail with some setups. Also it is not possible to tweak the generated definitions. -Each entity creates a new endpoint. For sensors the unit/type is set automatically. Please note that these definitions are not complete. Feel free to open an issue or pull request (see zigbee_ep.py) +* **version** (Optional, int): Zigbee App Version in basic cluster. Defaults to 0 +* **area** (Optional, int): Zigbee Physical Environment in basic cluster. See ZCL. Defaults to 0 = unknown +* **router** (Optional, bool): Create a router device instead of an end device. Defaults to false +* **device_version** (Optional, int): Set the Home Automation Profile device version. Custom values might be needed for compatibility with some vendors. Defaults to 0 +* **trust_center_key** (Optional, bind_key): Set custom trust center key. 32 digits hex number. +* **debug** (Optional, bool): Print zigbee stack debug messages +* **components** (Optional, string|list): all: add definitions for all supported components that have a name and are not marked as internal. None: Add no definitions (default). List of component ids: Add only those. Can be combined with manual definitions in endpoints +* **as_generic** (Optional, bool): Use generic/basic clusters where possible. Currently sensors and switches. Defaults to false +* **endpoints** (Optional, list): endpoint list for advanced definitions. See examples + +## Basic Mode + +By adding `components: all` the endpoint definition is generated automatically. Currently sensor, binary_sensor, light and switch components are supported. Because this is an external component the whole implementation is a bit hacky and likely to fail with some setups. Also it is not possible to tweak the generated definitions. Each entity creates a new endpoint. For sensors the unit/type is set automatically. Please note that these definitions are not complete. Feel free to open an issue or pull request (see zigbee_ep.py) | ESPHome Entity | Zigbee Cluster | | --------------- | ------------------------------------------------------------------ | @@ -117,21 +112,19 @@ Each entity creates a new endpoint. For sensors the unit/type is set automatical | `binary_sensor` | `binary_input` | | `sensor` | `analog_input` or mapped to specific (e.g. `temperature`) clusters | -**Basic example**: - -``` +### Example: +```yaml zigbee: id: "zb" components: all ``` -### Advanced mode +## Advanced Mode Endpoint/Cluster definitions can be defined manually. Can be combined with automated definition. -Advanced example: - -``` +### Advanced Example: +```yaml zigbee: id: "zb" endpoints: @@ -192,7 +185,7 @@ zigbee: # // Value of the attribute sent from server side. # T value; # // Address of device which sent this value. - # ezb_zcl_addr_t src_address; + # esp_zb_zcl_addr_t src_address; # // Number of the endpoint on device which sent this value. # uint8_t src_endpoint; # }; @@ -213,44 +206,30 @@ zigbee: - logger.log: "Joined network" ``` -### Actions +## Actions -- `zigbee.setAttr` - - `id`: id of attribute - - `value`: attribute value. (can be a `lambda`) - - only numeric or string types -- `zigbee.report`: `id` of zigbee component - - Manually send reports for all attributes with `report=true` -- `zigbee.reportAttr`: `id` of zigbee_attribute component - - Manually send report for attribute -- `zigbee.reset`: `id` of zigbee component - - Reset Zigbee Network and Device. Leave the current network and tries to join open networks. +### zigbee.setAttr +* **id**: "id of attribute" +* **value**: "value, can be a lambda" + * only numeric or string types -Examples: +### zigbee.report +* **id**: "id of zigbee component" +* **Manually send reports for all attributes with report=true** -``` - on_value: - then: - - zigbee.setAttr: - id: hum_attr - value: !lambda "return x*100;" -``` +### zigbee.reportAttr +* **id**: "id of zigbee_attribute component" +* **Manually send report for attribute** -``` - on_press: - then: - - zigbee.report: zb -``` +### zigbee.reset +* **id**: "id of zigbee component" +* **Reset Zigbee Network and Device. Leave the current network and tries to join open networks.** -### Time sync +## Time Sync Add a 'time' component with platform 'zigbee', e.g.: -``` -zigbee: - id: "zb" - ... - +```yaml time: - platform: zigbee timezone: Europe/London @@ -265,45 +244,48 @@ time: ## Troubleshooting -- Build errors - - Try to run `esphome clean ` - - Try to delete the `.esphome/build//` folder -- ESP crashes - - Try to erase completely with `esptool.py erase_flash` and flash again. - - Make sure your configuration is valid. Config validation is not complete. Always consult [Zigbee Cluster Library](https://csa-iot.org/wp-content/uploads/2022/01/07-5123-08-Zigbee-Cluster-Library-1.pdf) for cluster definitions - - Common issues are that attributes do not support reporting (try set `report: false`), use a different type, or are not readable/writable (see ZCL). -- Zigbee is not working as expected - - Whenever the cluster definition changed you need to re-interview and remove/add the device to your network. - - Sometimes it helps to power-cycle the coordinator and restarting z2m. - - Remove other endpoints. Sometimes coordinators struggle with multiple endpoints. - -## Notes +* **Build errors** + * Try to run `esphome clean ` + * Try to delete the `.esphome/build//` folder +* **ESP crashes** + * Try to erase completely with `esptool.py erase_flash` and flash again. + * Make sure your configuration is valid. Config validation is not complete. Always consult [Zigbee Cluster Library](https://csa-iot.org/wp-content/uploads/2022/01/07-5123-08-Zigbee-Cluster-Library-1.pdf) for cluster definitions + * Common issues are that attributes do not support reporting (try set `report: false`), use a different type, or are not readable/writable (see ZCL). +* **Zigbee is not working as expected** + * Whenever the cluster definition changed you need to re-interview and remove/add the device to your network. + * Sometimes it helps to power-cycle the coordinator and restarting z2m. + * Remove other endpoints. Sometimes coordinators struggle with multiple endpoints. -- I don't have much free time to work on this right now, so feel free to fork/improve/create PRs/etc. -- At the moment, the C++ implementation is rather simple and generic. I tried to keep as much logic as possible in the python part. However, endpoints/clusters ~~/attributes~~ could also be classes, this would simplify the yaml setup but requires more sophisticated C++ code. -- There is also a project with more advanced C++ zigbee libraries for esp32 that could be used here as well: https://github.com/Muk911/esphome/tree/main/esp32c6/hello-zigbee -- [parse_zigbee_headers.py](components/zigbee/files_to_parse/parse_zigbee_headers.py) is used to create the python enums and C helper functions automatically from zigbee sdk headers. -- Deprecated [custom zigbee component](https://github.com/luar123/esphome_zb_sensor) - -## Example Zigbee device +## Limitations -ESPHome Zigbee using only dev board or additionally [AHT10 Temperature+Humidity Sensor](https://next.esphome.io/components/sensor/aht10). +* **No Coordinator Support**: No coordinator devices +* **Attribute Set**: Attribute set action works only with numeric types and character string +* **OnValue Trigger**: OnValue trigger works only with numeric types +* **Reporting**: Reporting can be enabled, but not configured +* **Control Devices**: No control devices like switches [workaround available](https://github.com/luar123/zigbee_esphome/discussions/18#discussioncomment-11875376) +* **ESP-IDF Requirement**: Needs esp-idf >=5.1.4 +* **ESPHome Version**: Needs esphome >=2025.7 +* **Scenes**: Scenes not implemented +* **Endpoint Limit**: Officially the zigbee stack supports only 10 endpoints. However, this is not enforced and at least for sensor endpoints more than 10 seem to work. More than 10 light endpoints will crash! +* **Zigbee2MQTT Compatibility**: Only one light is supported without creating a custom converter/definition +* **Zigbee2MQTT Sensors**: Analog input cluster (used for sensors) is supported by 2025 October release, but ignores type and unit +* **ZHA Compatibility**: Analog input cluster (used for sensors) without unit/type is ignored +* **ZHA Reporting**: Minimum reporting interval is set to high values (30s) for some sensors and can't be changed. Keep that in mind if reporting seems not to work properly. -### Hardware Required +## ToDo List (Short-Mid term) -- One development board with ESP32-H2, ESP32-C5 or ESP32-C6 SoC acting as Zigbee end-device (that you will load ESPHome with the example config to). - - For example, the official [ESP32-H2-DevKitM-1](https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/esp32h2/esp32-h2-devkitm-1/user_guide.html) development kit board. -- [AHT10 Temperature+Humidity Sensor](https://next.esphome.io/components/sensor/aht10) connected to I2C pins (SDA: 12, SCL: 22) for the aht10 example. -- A USB cable for power supply and programming. -- (Optional) A USB-C cable to get ESP32 logs from the UART USB port (UART0). +- Light effects (through identify cluster commands) +- more components to support basic mode -### Build ESPHome Zigbee sensor +## Not planned (feel free to submit a pull request) -- We will build [example_esp32h2.yaml](example_esp32h2.yaml) file. -- Check [Getting Started with the ESPHome Command Line](https://esphome.io/guides/getting_started_command_line.html) tutorial to set up your dev environment. -- Build with `esphome run example_esp32h2.yaml`. +- [Zigbee ZCL OTA Upgrade Cluster](https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32/user-guide/zcl_ota_upgrade.html) and related [OTA API for ESP Zigbee SDK](https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32/api-reference/esp_zigbee_ota.html) to allow OTA (over-the-air) firmware updates via Zigbee +- Coordinator devices +- Binding config in yaml +- Reporting config in yaml +- Control device support like switches ([workaround](https://github.com/luar123/zigbee_esphome/discussions/18#discussioncomment-11875376)) -## How to contribute +## Contributing **Please submit all PRs here** and not to https://github.com/luar123/esphome/tree/zigbee @@ -311,21 +293,47 @@ Use pre-commit hook by enabling you esphome environment first and then running ` If looking to contribute to this project, then suggest follow steps in these guides + look at issues in Espressif's ESP Zigbee SDK repository: -- https://github.com/espressif/esp-zigbee-sdk/issues -- https://github.com/firstcontributions/first-contributions/blob/master/README.md -- https://github.com/firstcontributions/first-contributions/blob/master/github-desktop-tutorial.md +* https://github.com/espressif/esp-zigbee-sdk/issues +* https://github.com/firstcontributions/first-contributions/blob/master/README.md +* https://github.com/firstcontributions/first-contributions/blob/master/github-desktop-tutorial.md + +## External Documentation + +### Official Resources + +* [ESP Zigbee SDK Programming Guide](https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32/) +* [ESP-Zigbee-SDK Github repo](https://github.com/espressif/esp-zigbee-sdk) +* [ESP-Zigbee-SDK examples](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/) + * [Zigbee HA Example](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/esp_zigbee_HA_sample) + * [Zigbee HA Light Bulb example](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/esp_zigbee_HA_sample/HA_on_off_light) + * [Zigbee HA temperature sensor example](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/esp_zigbee_HA_sample/HA_temperature_sensor) + * [Zigbee HA thermostat example](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/esp_zigbee_HA_sample/HA_thermostat) + +### Additional Resources -## External documentation and reference +* [ESP32-H2 Application User Guide](https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32h2/application.html) +* [ESP32-C6 Application User Guide](https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32c6/application.html) -> [!NOTE] -> The official documentation and reference examples for the ESP Zigbee SDK can currently be obtained from Espressif: +## Example Zigbee Device + +### Hardware Required + +* One development board with ESP32-H2, ESP32-C5 or ESP32-C6 SoC acting as Zigbee end-device (that you will load ESPHome with the example config to). + * For example, the official [ESP32-H2-DevKitM-1](https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/esp32h2/esp32-h2-devkitm-1/user_guide.html) development kit board. +* [AHT10 Temperature+Humidity Sensor](https://next.esphome.io/components/sensor/aht10) connected to I2C pins (SDA: 12, SCL: 22) for the aht10 example. +* A USB cable for power supply and programming. +* (Optional) A USB-C cable to get ESP32 logs from the UART USB port (UART0). + +### Build ESPHome Zigbee sensor + +* We will build [example_esp32h2.yaml](example_esp32h2.yaml) file. +* Check [Getting Started with the ESPHome Command Line](https://esphome.io/guides/getting_started_command_line.html) tutorial to set up your dev environment. +* Build with `esphome run example_esp32h2.yaml`. + +## Notes -- [ESP32 Zigbee SDK Programming Guide](https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32/) - - [ESP32-H2 Application User Guide](https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32h2/application.html) - - [ESP32-C6 Application User Guide](https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32c6/application.html) -- [ESP-Zigbee-SDK Github repo](https://github.com/espressif/esp-zigbee-sdk) - - [ESP-Zigbee-SDK examples](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/) - - [Zigbee HA Example](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/esp_zigbee_HA_sample) - - [Zigbee HA Light Bulb example](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/esp_zigbee_HA_sample/HA_on_off_light) - - [Zigbee HA temperature sensor example](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/esp_zigbee_HA_sample/HA_temperature_sensor) - - [Zigbee HA thermostat example](https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/esp_zigbee_HA_sample/HA_thermostat) +* I don't have much free time to work on this right now, so feel free to fork/improve/create PRs/etc. +* At the moment, the C++ implementation is rather simple and generic. I tried to keep as much logic as possible in the python part. However, endpoints/clusters ~~/attributes~~ could also be classes, this would simplify the yaml setup but requires more sophisticated C++ code. +* There is also a project with more advanced C++ zigbee libraries for esp32 that could be used here as well: https://github.com/Muk911/esphome/tree/main/esp32c6/hello-zigbee +* [parse_zigbee_headers.py](components/zigbee/files_to_parse/parse_zigbee_headers.py) is used to create the python enums and C helper functions automatically from zigbee sdk headers. +* Deprecated [custom zigbee component](https://github.com/luar123/esphome_zb_sensor)