Skip to content

reivew of README content #73

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bestbug456 wants to merge 2 commits into
base: master
Choose a base branch
from
Open

reivew of README content #73

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b9027d5
reivew of README content
Dec 4, 2025
4eb312a
docs: Update README with required partition table configuration
Dec 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
291 changes: 161 additions & 130 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
# ESPHome ZigBee Component

External ZigBee component for ESPHome, enabling integration with Zigbee devices using the ESP Zigbee SDK.

> [!TIP]
> **New simple Mode! No more endpoint definitions needed.**
>
Expand All @@ -8,65 +12,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))
Comment on lines -47 to -55
Copy link
Copy Markdown
Owner

@luar123 luar123 Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please keep this information.

## 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"
Expand All @@ -80,23 +93,32 @@ 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)
Copy link
Copy Markdown
Owner

@luar123 luar123 Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please also keep the second half of this paragraph.

Copy link
Copy Markdown
Author

@bestbug456 bestbug456 Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You mean "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)"?

Copy link
Copy Markdown
Owner

@luar123 luar123 Dec 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this

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:
**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:
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:
Expand Down Expand Up @@ -178,39 +200,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
Expand All @@ -224,28 +237,65 @@ time:
```

## Troubleshooting
* Build errors
- Try to run `esphome clean <name.ymal>`
- Try to delete the `.esphome/build/<name>/` 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 <name.ymal>`
* Try to delete the `.esphome/build/<name>/` 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

Expand All @@ -259,31 +309,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)