We need more and better examples for this project (TZ-308)

[baylf2000]

Please consider urgently adding more examples for this project. The examples provided often don't work, have zero documentation / commenting and very limited functionality.

Combine that with the very poor documentation and this project becomes essentially unusable.

I'm very disappointed with this project overall. I'm a huge fan of the ESP32 products, and have used them for many years. I was very excited when Espressif first announced their Zigbee hardware, but two years later and two hardware releases and it seems it remains unusable in its current state.

Please urgently add some more examples with proper comments and documentation, in particular dealing with groups, scenes etc.

[chshu]

@baylf2000 Please find the current examples and documentation from the following links:

Examples: https://github.com/espressif/esp-zigbee-sdk/tree/main/examples Documentation: https://docs.espressif.com/projects/esp-zigbee-sdk

Could you kindly review these resources and submit GitHub issues with specific requirements for the examples?

[xieqinan]

Hello @baylf2000,

We have added the necessary examples to the ESP-Zigbee-SDK, which should provide you with a lot of valuable insights into using the SDK. We encourage users to refer to these examples when developing their own projects. We have included comments for every user API, so please be patient when working with this SDK.

If you encounter any examples that frequently do not work, please let us know, and we will promptly address the issue.

For the group and scene cluster, we offer user APIs that you can find in the scene cluster features, scene commands. If you find these APIs insufficient, please create an issue to let us know.

Furthermore, if you have any questions or need support while using this SDK, please don't hesitate to open an issue here. We are committed to helping you resolve any concerns as quickly as possible.

[baylf2000]

@xieqinan @chshu

Here are my urgent suggestions:

1. The coordinator roles should be removed from all examples, especially the simple HA examples. Lights and Switches are NOT ever coordinators. There should be a simple standalone coordinator example.
2. Remove the complex LED functionality from the lighting examples. The example should toggle a pin HIGH/LOW at most. All that added complexity just makes the example difficult to understand and difficult to adapt to other purposes.
3. ALL examples should ALWAYS set model id and manufacturer name by default. Without those attributes set these examples won't work with common coordinators like zigbee2mqtt, which very many people use for testing.
4. Group handling is a very important aspect of properly designed Zigbee devices, yet there are NO examples anywhere in the Espressif SDK for handling group actions.
5. Overall the Espressif documentation in poor. Doxygen generated pages are of little help to users looking to get started. If you look at the documentation of your competitors like Silicon Labs, NXP, Nordic, Microchip etc, they all have advanced, detailed, properly written documentation for their stacks, and for Zigbee in general. Maybe Espressif Chinese documentation is better? I understand Espressif has only recently entered this market, but the only way developers outside of China will start using your products is if you provide proper detailed English documentation.

I have been a HUGE fan of Espressif for a very long time. I began using the 8266 in products in 2015 and have used many Espressif products in my own products ever since. I really hope you can improve this aspect of your product, as if you do so I believe the 802.15.4 products will do just as well as the Wifi products, or even better.

Thank you.

[chshu]

@baylf2000 Thank you for your suggestions. Here is some feedback:

1. Initially, we did have a standalone coordinator example, but it required three devkits to set up the demo (coordinator, light, switch). So, we combined the coordinator and switch into a single example. It's easy to change the role by modifying the esp_zb_role configuration.

2. The light example works as-is with the LEDs on the devkit. You can simply replace it by integrating your own LED driver, for example: turn on/off.

3. Your suggestion is well-received, and we will add model IDs and manufacturer names to the examples.

4. Could you please create a new GitHub issue and describing your group use case? We will provide you with some code snippets to assist in unblocking your development.

5. We place a high value on documentation. Zigbee is a very mature protocol with a long history, and there are indeed many useful documents available. Our current documentation primarily focuses on the SDK itself. Please feel free to provide detailed requirements for further documentation improvements.

We look forward to collaborating with you on Zigbee SDK and products!

[baylf2000]

@chshu @xieqinan

1. Initially, we did have a standalone coordinator example, but it required three devkits to set up the demo (coordinator, light, switch). So, we combined the coordinator and switch into a single example. 

I am certain you will find that customers looking to Zigbee aren't trying to have two dev kits communicate with each other. They are trying to have devices join to and communicate with existing networks.

It's easy to change the role by modifying the [esp_zb_role].

Unfortunately that is not all that is required. The switch/coordinator example does not allow the device to respond to requests for model id and manufacturer despite the correct additions to the basic cluster list, even after modifying the device to a router.

2. The light example works as-is with the LEDs on the devkit. You can simply replace it by integrating your own LED driver, for example: [turn on/off](https://github.com/espressif/esp-zigbee-sdk/blob/main/examples/esp_zigbee_HA_sample/HA_on_off_light/main/esp_zb_light.c#L88).

If you want to keep those examples, that's great. However I strongly suggest adding simpler examples without all the extra code required to deal with the LEDS.

4. Could you please create a new GitHub issue and describing your group use case? We will provide you with some code snippets to assist in unblocking your development.

Sir I've provided all the information required already. Simple use cases for allowing a device to join to, be removed from and operate as part of a Zigbee group. I can't be any more detailed than that.

5. We place a high value on documentation. Zigbee is a very mature protocol with a long history, and there are indeed many useful documents available. Our current documentation primarily focuses on the SDK itself. Please feel free to provide detailed requirements for further documentation improvements.

I'm sorry, but what you have produced so far suggest you place little value at all on documentation. Your current "documentation" is almost entirely auto-generated Doxygen files, generated from poorly commented header files only. Even the most experienced developers will struggle as they are unable to work around the poor documentation by examining detailed source code due to the use of binary libraries. This is not acceptable for a company hoping to sell their devices to international developers.

May I suggest you take a look at https://www.nxp.com/pages/jn516x-7x-zigbee-3-0:ZIGBEE-3-0, and from there, for example https://www.nxp.com/docs/en/user-guide/JN-UG-3113.pdf. These are properly documented products. SL, TI, Microchip and others all have very detailed, written documentation on all aspects of their Zigbee offerings, not auto-generated Doxygen files.