Implement Zigbee in Arduino

[P-R-O-C-H-Y]

Related area

Create an API for Zigbee within Arduino

Hardware specification

ESP32-C6 and ESP32-H2 as Standalone Nodes. Other SoC can be used as radio co-processor attached to a RPC (802.15.4 radio layer).

Is your feature request related to a problem?

This is an issue to track the progress of developing Zigbee library, a new API for Arduino.

Describe the solution you'd like

Initial tasks:

• Add zigbee-sdk to Arduino lib-builder Copy Zigbee + Zboss libraries esp32-arduino-lib-builder#146
• Add zigbee support Zigbee protocol support #8844
• Port basic IDF examples to Arduino Add Zigbee examples #9024 Zigbee examples update #9627

Zigbee library (wrapper) tasks:

• Create Zigbee classes and implement all Zigbee roles
• Implement Zigbee network scanning
• Allow multiple endpoints on same Zigbee device (test needed)
• Implement basic HA devices (lights, switches, sensors, etc..)
  • On/off light + switch
  • Color Dimmable light + switch
  • Temperature sensor + Thermostat
• Implement setting Manufacturer and model name
• Update ported examples to use the Zigbee Library
• Documentation (will be handled in separate PR)

PR: #10265

Good to have features:

• Zigbee identify handling (user can for example blink LED of EP) -> comment
• Zigbee sleepy device / deep sleep-lightsleep Zigbee Implementation: Deep Sleep example #10405
• Power source/battery level info feat(Zigbee): Support for sleepy device + Power Source and battery level + Humidity sensor cluster #10551

more tasks will be added while in progress.
Development branch

Describe alternatives you've considered

No other usable Zigbee wrapper around.

Additional context

Related issues:
#8807 #9156 #9962 #9480

I have checked existing list of Feature requests and the Contribution Guide

• I confirm I have checked existing list of Feature requests and Contribution Guide.

[elgerg]

Hi, love the work so far. I'm so excited to get this running. It looks like it's going to be the next best thing since sliced bread!

Are there any intentions to add power source/battery level into the config?

If mains powered could it act as a router as well or is that too much for a H2? Maybe ok for the C6..

Many thanks and appreciate the hard work!

[P-R-O-C-H-Y]

Dev update 12/08/2024 pushed to the dev branch:

• Implemented Factory reset of Zigbee device, in order to connect to new network without reflashing/erasing flash
• Implemented optional setting for Manufacturer and Model names
• Added option to allow endpoint to have multiple endpoint connected -> switch - 2 lights (tested)
• Implemented easy transfer from device it to Device type (0x0000 = ESP_ZB_HA_ON_OFF_SWITCH_DEVICE_ID -> "General On/Off switch".
• Minor sketches update

[elgerg]

Oh wow, that looks amazing! So easy, I'm going to love this. Thanks!

[P-R-O-C-H-Y]

Hi, love the work so far. I'm so excited to get this running. It looks like it's going to be the next best thing since sliced bread!

Are there any intentions to add power source/battery level into the config?

If mains powered could it act as a router as well or is that too much for a H2? Maybe ok for the C6..

Many thanks and appreciate the hard work!

Thank you for your feedback 👍 I really appreciate it.

About the power source/baterry level I will add it on the list as good to have, so I will look after having the main part done :)

[P-R-O-C-H-Y]

Dev Update 14/08/2024 pushed to dev branch:

• Implemented Color Dimmable Light and Colour Dimmer Switch endpoints, working in RGB colour space (automatically convert to/from XYZ).
• Added examples: Zigbee_Color_Dimmable_Light, Zigbee_Color_Dimmer_Switch
• Printing of bound devices (endpoints)
• Minor code updates

[elgerg]

Nice,
Any chance you can take a look at adding temp sensor and light sensor?
They are the 2 I'm most eager to try, I'm currently using the temp sensor and it works great (even if the code is way difficult to understand).
Thanks!

[P-R-O-C-H-Y]

Nice, Any chance you can take a look at adding temp sensor and light sensor? They are the 2 I'm most eager to try, I'm currently using the temp sensor and it works great (even if the code is way difficult to understand). Thanks!

@elgerg The temperature sensor + thermostat are on the list of upcoming tasks.
The light sensor device type is not present in the list in esp32-zigbee-sdk, it should have value 0x106, which is not present.
Can you open a feature request to the esp-zigbee-sdk repository please? Seems that the main part is already there which contains all the clusters and attributes for luminance sensor.

Edit: found your issue you opened. Added a comment.

[elgerg]

Thanks for adding to espressif/esp-zigbee-sdk#401
I'm quite excited about being able to create my own Temp/Lumin Zigbee sensors :D
Thanks for the continued effort!

[elgerg]

Hi @P-R-O-C-H-Y

Any chance I can add this to the "Nice to have" list?

In the current Temp sensor version there is an identify cluster (?) added:

    esp_zb_cluster_list_add_identify_cluster(cluster_list, esp_zb_identify_cluster_create(&(temperature_sensor->identify_cfg)), ESP_ZB_ZCL_CLUSTER_SERVER_ROLE)

Any chance you can add something like that to the list so we can blink an LED when triggered? No idea how to do that at the moment..

Thanks!

[P-R-O-C-H-Y]

Hi @P-R-O-C-H-Y

Any chance I can add this to the "Nice to have" list?

In the current Temp sensor version there is an identify cluster (?) added:

    esp_zb_cluster_list_add_identify_cluster(cluster_list, esp_zb_identify_cluster_create(&(temperature_sensor->identify_cfg)), ESP_ZB_ZCL_CLUSTER_SERVER_ROLE)

Any chance you can add something like that to the list so we can blink an LED when triggered? No idea how to do that at the moment..

Thanks!

Hi @elgerg,

Can you explain a bit more? I am not sure if I got it correctly.
What would be "Nice to have"? Option to customise identify cluster? I don't also get the LED blink.

[elgerg]

Hi @P-R-O-C-H-Y
I should have been more specific.

If you have a look at this:

There is an identify button. In theory this should allow for the device to identify itself by blinking an LED or something when the button is pressed so you can figure out which device is which.

This article explains really well on what identify is:
https://medium.com/@omaslyuchenko/hello-zigbee-part-22-identify-cluster-90cf12680306

So what would be good to have is a simple way of using this just like you are doing with the rest of the wrapper.

Does that make a little more sense?

Thanks

[P-R-O-C-H-Y]

Hi @P-R-O-C-H-Y I should have been more specific.

If you have a look at this:

There is an identify button. In theory this should allow for the device to identify itself by blinking an LED or something when the button is pressed so you can figure out which device is which.

This article explains really well on what identify is: https://medium.com/@omaslyuchenko/hello-zigbee-part-22-identify-cluster-90cf12680306

So what would be good to have is a simple way of using this just like you are doing with the rest of the wrapper.

Does that make a little more sense?

Thanks

Thanks for explaining. That can be really helpful. Adding it to the list :)

[elgerg]

Excellent. Thanks :)

[P-R-O-C-H-Y]

Dev Update 16/08/2024 pushed to dev branch:

• Implemented Zigbee network scanning (mostly match WiFi scan API)
• Added Zigbee_Network_Scan example

[elgerg]

If you're taking requests I'd also like to implement some kind of way of getting the current time from the coordinator to display on a screen. Do you know if it's possible to get the time into some sort of callback?

Thanks :)

[P-R-O-C-H-Y]

If you're taking requests I'd also like to implement some kind of way of getting the current time from the coordinator to display on a screen. Do you know if it's possible to get the time into some sort of callback?

Thanks :)

@elgerg Do you have any example of this feature?

[P-R-O-C-H-Y]

Dev Update 28/08/2024 pushed to dev branch:

• Implemented Temperature sensor and Thermostat endpoints.
• Added examples: Zigbee_Temperature_Sensor, Zigbee_Thermostat
• Implemented configure report handler.
• Updated READMEs and description of examples.
• Minor code updates

[P-R-O-C-H-Y]

Dev Update 28/08/2024 pushed to dev branch:

• Implemented Temperature sensor and Thermostat endpoints.

• Added examples: Zigbee_Temperature_Sensor, Zigbee_Thermostat

• Implemented configure report handler.

• Updated READMEs and description of examples.

• Minor code updates

This looks awesome!

Do you know when it'll end up in the next release?

Thanks 🙏

I am doing the best that the first version can be released soon.

[P-R-O-C-H-Y]

Dev Update 26/09/2024 - PR ready to be reviewed.

• Refactored methods and classes (exchanged virtual methods for callback functions) making it more simpler
• Implemented Identify (tested with HomeAssistant - SONOFF USB Dongle gateway + ESP with RGB example)
• All examples got updated due to the refactor

[P-R-O-C-H-Y]

The Zigbee library got merged! Now it's available in bothmaster and release/v3.1 branches.
So in next release 3.0.6 and 3.1.0-rc2 it will be included.

[lboue]

Great job!

[Abdull]

awesome to hear!

I'm inexperienced what is required to implement software for Zigbee devices.

Having a look at directory https://github.com/espressif/arduino-esp32/tree/master/libraries/Zigbee/src/ep , do I deduce correctly that each "category" of Zigbee device type would require its own implementation files?

Maybe you can give hints how others could join?

[P-R-O-C-H-Y]

awesome to hear!

I'm inexperienced what is required to implement software for Zigbee devices.

Having a look at directory https://github.com/espressif/arduino-esp32/tree/master/libraries/Zigbee/src/ep , do I deduce correctly that each "category" of Zigbee device type would require its own implementation files?

Maybe you can give hints how others could join?

Hello @Abdull, take a look at the basics of the Zigbee protocol. You can find many sources and videos on the internet ;)
As you noticed, Zigbee device can have 1 or more endpoints, which specify its type (light, sensor, switch, etc.). Each type need to have its own implementation as you found in the library (the link you posted). I am open on any suggestion what EPs to add in next updates and also I would be really happy to see a PR with any new EP support. As a reference you can take a look at the EPs I have added. For more details check the esp32-zigbee-sdk repository and sources there. But to be honest, it's not that simple to understand all the clusters, handlers etc. If anyone plan to add new EP type, I will be glad to help with any questions or development.

[elgerg]

Hi @P-R-O-C-H-Y

If you're taking requests these are the sort of things I would like to see:

Human presence detector (PIR etc)
Luminosity/Light sensor
Time Client (get the current time from the coordinator)
Battery monitoring
Sleepy device

Thanks!

[MeisterQ]

Id also like to put a feature request:

• TRV support with stuff like external Temp sensor, window open, temperature setpoint, etc (like everything the Shelly TRV supports but only on zigbee)

[P-R-O-C-H-Y]

Id also like to put a feature request:

• TRV support with stuff like external Temp sensor, window open, temperature setpoint, etc (like everything the Shelly TRV supports but only on zigbee)

Hi @MeisterQ, the TRV is just a thermostat. We have support for this type of endpoint. Also we have a temperature sensor endpoint supported as well. Just regular sensor for example for windows, doors, etc. is not yes supported. So if you plan to build your own TRV you can already start prototyping with the stuff we already have :)

[Hedda]

If you're taking requests these are the sort of things I would like to see:

Human presence detector (PIR etc)
Luminosity/Light sensor
Time Client (get the current time from the coordinator)
Battery monitoring
Sleepy device

Thanks!

FYI, there are more Zigbee examples in the esp32-zigbee-sdk repository which could probably be converted to this new API. See:

• https://github.com/espressif/esp-zigbee-sdk/tree/main/examples

That includes examples for "deep sleep" and "light sleep" (standby) modes for Zigbee End Device:

• https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/esp_zigbee_sleep

As for Battery monitoring, I read note Arduino recently released an open-source Arduino Power Management library for Arduino Pro that could maybe be ported? It includes battery management and charger manager + sleep and standby mode

• https://github.com/arduino-libraries/Arduino_PowerManagement/
  • https://github.com/arduino-libraries/Arduino_PowerManagement/tree/main/examples

More on that here

• https://www.cnx-software.com/2024/09/26/arduino-power-management-library-arduino-pro-modules/

Time Client looks to be missing, and I agree that Zigbee Time Client is needed to make a stand-alone smart thermostat or HVAC.

[MeisterQ]

Id also like to put a feature request:

• TRV support with stuff like external Temp sensor, window open, temperature setpoint, etc (like everything the Shelly TRV supports but only on zigbee)

Hi @MeisterQ, the TRV is just a thermostat. We have support for this type of endpoint. Also we have a temperature sensor endpoint supported as well. Just regular sensor for example for windows, doors, etc. is not yes supported. So if you plan to build your own TRV you can already start prototyping with the stuff we already have :)

Thank you. That could be a start. None of the TRVs existing meet my requirements

[gdivry]

Thanks a lot for this incredible work
Can I use the esp32c6 as a Zigbee coordinator with the lib ?

[dpharris]

Could README.md files be possibly added to the arduino-esp32/libraries /Zigbee/ directory, to the example directory, and/or the individual examples? These would be very helpful to people new to this. They could also include actual or links to pictures and videos. Thanks David

…

On Sun, Oct 13, 2024 at 9:09 AM gdivry ***@***.***> wrote: Thanks a lot for this incredible work Can I use the esp32c6 as a Zigbee coordinator with the lib ? — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you are subscribed to this thread. Message ID: ***@***.***>

[Hedda]

Can I use the esp32c6 as a Zigbee coordinator with the lib ?

As I understand this is currently only to use ESP32-C6/ESP32-H2 as a ”Zigbee End Device” (ZED) or ”Zigbee Router” device (ZR) stand-alone nodes (i.e. standalone devices that can be added to an existing Zigbee network and then controlled via it), not as Zigbee Coordinator or Zigbee Gateway.

If you want a all-in-one Zigbee Gateway using ESP32 then can I suggest that you look into adding support for esp-zigbee-sdk support to Tasmota's sub-project called Zigbee2Tasmota (Z2T) which is currently only compatible with Silicon Labs and Texas Instruments as Zigbee Coordinator but it might give you ideas:

• https://tasmota.github.io/docs/Zigbee/

and

• https://tasmota.github.io/docs/Zigbee-Internals/

For refernce also check out the zigpy-espzb radio libraary for zigpy and their zha project which can now indirectly use a ESP32-H2 Zigbee Coordinator via zigpy-espzb via an hardware abstraction layer for the Zigbee radios CLI serial interface:

• https://github.com/lhespress/zigpy-espzb

And

• https://github.com/zigpy/zha

• https://github.com/zigpy/zigpy

• https://github.com/zigpy/zigpy-cli

[Hedda]

Can I use the esp32c6 as a Zigbee coordinator with the lib ?

As I understand this is currently only to use ESP32-C6/ESP32-H2 as a ”Zigbee End Device” (ZED) or ”Zigbee Router” device (ZR) stand-alone nodes (i.e. standalone devices that can be added to an existing Zigbee network and then controlled via it), not as Zigbee Coordinator or Zigbee Gateway.

If you want a all-in-one Zigbee Gateway using ESP32 then can I suggest that you look into adding support for esp-zigbee-sdk support to Tasmota's sub-project called Zigbee2Tasmota (Z2T) which is currently only compatible with Silicon Labs and Texas Instruments as Zigbee Coordinator but it might give you ideas:

• https://tasmota.github.io/docs/Zigbee/

and

• https://tasmota.github.io/docs/Zigbee-Internals/

@s-hadinger to go off on a tangent with question above; what exact functions are still missing for this new Zigbee API for Arduino to potentially be useful for a Zigbee Gateway project like Zigbee2Tasmota (Z2T)?

[s-hadinger]

@s-hadinger to go off on a tangent with question above; what exact functions are still missing for this new Zigbee API for Arduino to potentially be useful for a Zigbee Gateway project like Zigbee2Tasmota (Z2T)?

I don't know, I have not checked. But there are no plans to port Z2T to H2/C6 due to the predominance of CC2652P and low number of devices using H2/C6. Also for the future, I expect Thread to progressively take over Zigbee. So I think we are well served with Zigbee as of today with both EFR32/CC2652P compatibility

[P-R-O-C-H-Y]

Another update for the Zigbee library -> PR #10551

• Support for sleepy device (only deep-sleep is currently possible).
• Support for selecting power source for the device. If battery is selected, the remaining percentage can be updated.
• Support for Humidity cluster, which was added as optional for the Temperature sensor as there is no HA Device type for humidity sensor.
• New example Zigbee_Temp_Hum_Sensor_Sleepy, which demonstrates all the new functionalities
• Mirror fixes and improvements

[P-R-O-C-H-Y]

I have also did a power consumption test for the sleepy device. Sharing the picture of consumption when sleep was set to 30s, after wakeup, the connection was done, measured data and reported. Then back to sleep.

You can see the average consumption was around 6mA. The more time the device will sleep the better power efficiency you can get.

[tlanfer]

This is great work, and i managed to get it to work immediately using a waveshare ESP32-C6 devkit board.
I'm curious about the possiblities with sleep. One of the major reasons i'm using zigbee devices is when they need to run on low power. I have a bunch TRVs that run on battery at last a long time (months), yet respond to commands almost immediately (less than 5 seconds delay). My specific usecase is having a battery powered LED light that i only need to activate every now and then, but should not drain the battery when not in use. Zigbee would be perfect for this.

With deep sleep i'm getting a full reboot, and if i want reasonably quick response times i can only sleep for relatively short times. So i would assume i need some form of light sleep for that? Just wake up enough to check for commands and go back to sleep?

[ggtimtom]

I have an ESP32-H2 but only with 2MB of Flash. Will this also work?

[ggtimtom]

I want to build two sensors:
A rain meter using a hallsensor an a magnet

A digital water meter: In my installed watermeter a little metalsheet is rotating. As a sensor i will use an geartoothsensor.

[AndunHH]

Thanks for the great work done here. As this whole feature is not jet finished, I'm hesitating to create a new issue. If this here is not the right spot, please give me a hint, where I should put it.

I succesfully used the example for the Switch and the on/off light with the given "light" example on a second seeed xiao esp32-c6 and with an ikea power outlet.

I tried to expand the example, because I don't want to bind a power outlet manually after every reset. I already found a similar ticket for the espressif SDK., that tells me, that this is already possible.

I changed the example to not wait in the setup() for a bound device. But then: nothing happens, because _is_bound = false in the follow up routings.
If I bind the first light again, the whole switch starts working and also the formerly bound power outlet is switching as expected. (= the newly bound light and the power outlet are switching together)

Therefore, I assume, that during initialization the state of _is_bound is not correctly read from the memory, right?
I'm was looking at

arduino-esp32/libraries/Zigbee/src/ZigbeeEP.cpp

Line 13 in e99f1fd

//TODO: is_bound and allow_multiple_binding to make not static

but at this point my knowdlege comes to an end. ...

Thanks for any hints how to solve this, or if this already known and planned.
Or where I should open a individual ticket.

[Hedda]

@P-R-O-C-H-Y have you thought about maybe splitting Zigbee API for Arduino to make one part hardware-agnostic?

That is, breakout the Zigbee API from arduino-esp32 into its own separate library makes that hardware independent so that it could be reused by other projects with other Zigbee radio libraries, especially if they too have based their Zigbee stack on ZBOSS, such as example Nordic Semiconductor. With the point being that such a library would attract more Arduino developers that are interested in this Zigbee API but might want to instead make an implementation for a non-ESP32 based radio.

[P-R-O-C-H-Y]

This is great work, and i managed to get it to work immediately using a waveshare ESP32-C6 devkit board. I'm curious about the possiblities with sleep. One of the major reasons i'm using zigbee devices is when they need to run on low power. I have a bunch TRVs that run on battery at last a long time (months), yet respond to commands almost immediately (less than 5 seconds delay). My specific usecase is having a battery powered LED light that i only need to activate every now and then, but should not drain the battery when not in use. Zigbee would be perfect for this.

With deep sleep i'm getting a full reboot, and if i want reasonably quick response times i can only sleep for relatively short times. So i would assume i need some form of light sleep for that? Just wake up enough to check for commands and go back to sleep?

Hi @tlanfer, thanks for your feedback.
The light sleep is not possible, as it needs the Power Management enabled and use the FreeRTOS tickless mode. We don't want to enable this settings for whole Arduino core, as it may bring unexpected behavior. If you really need the light sleep, you can use the ESP-IDF and the ESP-ZIGBEE-SDK directly. There is an example on how to use the light sleep :)

[P-R-O-C-H-Y]

Thanks for the great work done here. As this whole feature is not jet finished, I'm hesitating to create a new issue. If this here is not the right spot, please give me a hint, where I should put it.

I succesfully used the example for the Switch and the on/off light with the given "light" example on a second seeed xiao esp32-c6 and with an ikea power outlet.

I tried to expand the example, because I don't want to bind a power outlet manually after every reset. I already found a similar ticket for the espressif SDK., that tells me, that this is already possible.

I changed the example to not wait in the setup() for a bound device. But then: nothing happens, because _is_bound = false in the follow up routings. If I bind the first light again, the whole switch starts working and also the formerly bound power outlet is switching as expected. (= the newly bound light and the power outlet are switching together)

Therefore, I assume, that during initialization the state of _is_bound is not correctly read from the memory, right? I'm was looking at

arduino-esp32/libraries/Zigbee/src/ZigbeeEP.cpp

Line 13 in e99f1fd

//TODO: is_bound and allow_multiple_binding to make not static

but at this point my knowdlege comes to an end. ...
Thanks for any hints how to solve this, or if this already known and planned. Or where I should open a individual ticket.

Hi @AndunHH, thank you for your feedback. I will take a look on this issue with the _is_bound if I can see anything wrong there. The TODO comment is there for me, as I might transfer all those variables to not be a static if possible.
If you have more info about that issue you have also with an example and steps how to reproduce it, please open a new issue and describe everything there. It will help a lot to have it separated, so we can discuss it there :)

[P-R-O-C-H-Y]

@P-R-O-C-H-Y have you thought about maybe splitting Zigbee API for Arduino to make one part hardware-agnostic?

That is, breakout the Zigbee API from arduino-esp32 into its own separate library makes that hardware independent so that it could be reused by other projects with other Zigbee radio libraries, especially if they too have based their Zigbee stack on ZBOSS, such as example Nordic Semiconductor. With the point being that such a library would attract more Arduino developers that are interested in this Zigbee API but might want to instead make an implementation for a non-ESP32 based radio.

Hi @Hedda, I was not thinking about that as I use the ESP-ZIGBEE-SDK underneath, which uses the ZBOSS. The main idea of Arduino APIs is to offer a similar approach to other Arduino interfaces. If users want to use ESP-IDF Zigbee APIs, that is still possible, they can just ignore the Arduino Zigbee APIs. This is valid for most of our Arduino APIs, actually, users can always use the ESP-IDF underneath. We don't have a goal of portability of our libraries, only to keep portability of user applications. But for sure other manufacturers can follow the same APIs, but the Implementation will depend on them.