Important
Please help to collect working cluster definitions here.
If something is not working please check the troubleshooting section first. Config validation is not complete. Always consult Zigbee Cluster Library for cluster definitions
External ZigBee component for ESPHome.
- 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
- (binary) sensors can be connected to attributs without need for lambdas/actions
- Wifi co-existence on ESP32-C6
- Deep-sleep should work
- Not tested: groups
- Time sync with coordinator
- Only end devices
- Attribute set action and OnValue trigger works only with numeric types
- Reporting can be enabled, but not configured
- No control devices like switches (workaround)
- Needs esp-idf >=5.1.4
- Needs esphome >=2024.12
- scenes not implemented
- Light effects (through identify cluster commands)
- Router devices
- Easier setup of devices/entpoints
- Coordinator devices
- Binding config in yaml
- Reporting config in yaml
- Control device support like switches (workaround)
Include external component:
external_components:
- source: github://luar123/zigbee_esphome
components: [zigbee]
zigbee:
...
[Todo]
Example:
zigbee:
id: "zb"
endpoints:
- num: 1
device_type: COLOR_DIMMABLE_LIGHT
clusters:
- id: ON_OFF
attributes:
- attribute_id: 0
type: bool
on_value:
then:
- light.control:
id: light_1
state: !lambda "return (bool)x;"
- id: LEVEL_CONTROL
attributes:
- attribute_id: 0
type: U8
on_value:
then:
- light.control:
id: light_1
brightness: !lambda "return ((float)x)/255;"
- device_type: TEMPERATURE_SENSOR
num: 2
clusters:
- id: REL_HUMIDITY_MEASUREMENT
attributes:
- attribute_id: 0
id: hum_attr
type: U16
report: true
value: 200
- id: TEMP_MEASUREMENT
attributes:
- attribute_id: 0x0
type: S16
report: true
value: 100
device: temp_sensor_id
scale: 100
on_join:
then:
- logger.log: "Joined network"
- zigbee.setAttr
- id: "id of attribute"
- value: "value, can be a lambda"
- only numeric types
- zigbee.report: "id of zigbee component"
- Manually send reports
- 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
Add a 'time' component with platform 'zigbee', e.g.:
zigbee:
id: "zb"
...
time:
- platform: zigbee
timezone: Europe/London
on_time_sync:
then:
- logger.log: "Synchronized system clock"
on_time:
- seconds: /10
then:
- logger.log: "Tick-tock 10 seconds"
- Build errors
- Try to run
esphome clean <name.ymal> - Try to delete the
.esphome/build/<name>/folder
- Try to run
- ESP crashes
- Try to erase completely with
esptool.py erase_flashand flash again. - Make sure your configuration is valid. Config validation is not complete. Always consult Zigbee Cluster Library 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).
- Try to erase completely with
- 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
/attributescould 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 is used to create the python enums and C helper functions automatically from zigbee sdk headers.
- Deprecated custom zigbee component
ESPHome Zigbee using only dev board or additionally AHT10 Temperature+Humidity Sensor.
- One development board with ESP32-H2 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 development kit board.
- AHT10 Temperature+Humidity Sensor 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).
- We will build example_esp32h2.yaml file.
- Check Getting Started with the ESPHome Command Line tutorial to set up your dev environment.
- Build with
esphome run example_esp32h2.yaml.
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
Note! The official documentation and reference examples for the ESP Zigbee SDK can currently be obtained from Espressif:
