6. Appendix FAQs

6.1. Compilation errors

Cannot build the application:

Make sure you are on the correct esp-idf branch/release. Run git submodule update --init --recursive to make sure the submodules are at the correct heads
Make sure you are on the correct ESP Zigbee SDK branch.
Delete the build/ directory, sdkconfig, sdkconfig.old and dependencies.lock, then build again.

6.2. Flashing errors

Cannot flash to the target:

Make sure you have connected your device to the PC.
Check the port: run ls -la /dev/ttyUSB* to verify that the corresponding port is recognized by the PC.
Make sure you choose the correct target.

6.3. How to check whether a Zigbee device is on the network?

6.3.1. Inquire Remote Device

When a Zigbee device powers off, the Zigbee network will not immediately detect its unavailability, as the device does not emit any events to network when powered down. The network requires some time to diagnose and confirm the device's status.

If the device is a router, it periodically sends Link Status network commands to maintain connections with its neighbors. When the router goes offline, these Link Status messages stop, and its neighbors will eventually mark it as unreachable in their neighbor tables. The Link Status interval is typically 15 seconds. If a neighbor does not receive this command for four consecutive intervals, it considers the router unreachable.

If the device is an end device, it must periodically send Data Request MAC commands or End Device Timeout Request NWK commands to keep alive with its parent. These requests update the aging timer on the parent. When the aging timer expires without receiving a request, the parent removes the child from its neighbor table.

In summary, the neighbor table retrieved using ezb_nwk_get_next_neighbor() can be used to check whether a Zigbee device is currently online. Additionally, the EZB_ZDO_DEVICE_UNAVAILABLE signal is raised when a request cannot reach the destination device, which also indicates the device is likely offline.

6.3.2. Inquire Local Device

The SDK provides the ezb_bdb_dev_joined() API to indicate whether the local device is currently on a Zigbee network. Additionally, the ezb_bdb_is_factory_new() API indicates whether the device is in a factory-new state. The device that is not currently on a network but has previously joined one will attempt to rejoin the previous network after rebooting.

6.4. Zigbee Light Sleep Mode

The light sleep feature for Zigbee is based on ESP-IDF. Refer to the ESP light sleep User Guide to establish the foundation for implementing Zigbee light sleep mode.

6.4.1. How to Configure the Zigbee End Device to Enter Light Sleep Mode

To enable the Zigbee End Device to enter light sleep mode, the following configurations must be applied in sdkconfig:

CONFIG_PM_ENABLE=y
CONFIG_FREERTOS_USE_TICKLESS_IDLE=y

With these settings, the ESP-IDF system is able to automatically transition the chip into a low-power state when no tasks need to run for a certain number of ticks.

The Power Management provides a more comprehensive explanation of how the system handles power-saving operations.

The Zigbee light sleep example is provided for detailed configuration and usage.

If the Zigbee End Device fails to enter light sleep mode, checking the below list may be helpful:

Verify that both CONFIG_PM_ENABLE and CONFIG_FREERTOS_USE_TICKLESS_IDLE are enabled in sdkconfig.
Confirm that the esp_pm_configure() function is called with the correct configuration parameters.
Check whether the device is set to rx_off_when_idle by calling ezb_nwk_get_rx_on_when_idle().
Use ezb_bdb_dev_joined() to confirm whether the device has joined a network. In the light sleep example, the Zigbee task keeps running if the device is not part of a network.
Try disabling any peripheral wake-up sources.

6.4.2. How to Measure Power Consumption on ESP Development Board

ESP32-series development boards provide dedicated pins for measuring the chip's current consumption. These test points are located near the top of the board and are connected by default using a jumper cap.

6.4.3. Power Consumption in Light Sleep Mode

The power consumption of the chip in different modes is detailed in the Current Consumption Characteristics section of the official datasheet.

If the results in the datasheet differ significantly from your measurements, please contact us via the Technical Inquiries.

6.4.4. How to Set the Sleep Duration for a Zigbee Sleepy End Device

A Zigbee Sleepy End Device is required to maintain a keep-alive interval with its parent device. This interval determines how long the chip can remain in light sleep mode.

It can be configured using esp_zigbee_zed_config_s::keep_alive when initializing the Zigbee stack or using ezb_nwk_set_keepalive_interval() to set the keep-alive interval.

6.4.5. Why Does the Current Detector Capture Multiple Peaks When the Zigbee Sleep End Device Starts Up

This behavior occurs because the Zigbee light sleep example attempts to scan all channels to find an available network. As a result, the chip sends a large number of frames during startup.

If the channel of the destination network is known, you can reduce this overhead by calling ezb_bdb_set_primary_channel_set() to configure a single channel for scanning.

6.4.6. How to Wake Up the Zigbee Sleepy End Device

The light sleep device can be awakened by multiple wake-up sources; please see the light sleep example of ESP-IDF and the official wakeup-source documentation.

The Zigbee light sleep example is configured by default to wake up either when it needs to maintain communication with its parent device (keep-alive) or when the BOOT button is pressed, triggering a GPIO event.

If you encounter any issue when adding other wake-up sources, please submit a ticket to the esp-idf issue tracker.

6.4.7. Zigbee Light Sleep End Device Fails to Connect with Third-Party Devices

Generally, a Zigbee Sleepy End Device behaves the same as a regular Zigbee End Device during the Zigbee commissioning process. Therefore, please first try using the typical Zigbee HA On/Off Light example to connect with the third-party device and help identify the cause of the failure.

6.4.8. Related Issues

If the above answers can not resolve your question, please submit an issue here, and include the background of your application along with a minimal reproducible example.