DOCSEARCHbyAlgolia
Submit Docs

ESP-Zigbee-SDK

repository·main·Indexed 18 days ago

https://github.com/espressif/esp-zigbee-sdk

The official development framework for implementing Zigbee products on Espressif ESP32 series SoCs. It includes the esp-zigbee-lib for core stack integration and the ESP-Zigbee-Console CLI for runtime configuration and management of the Zigbee stack, ZCL data models, BDB commissioning, and network settings.

Tokens
47K
Snippets
86
Records
179
Agent score
63%

What's inside esp-zigbee-sdk

  1. Overview of the Zigbee Gateway Example

    main

    The Zigbee Gateway example demonstrates how to build a gateway device that bridges Zigbee and Wi-Fi networks. It requires a dual-SoC architecture:

    1. Wi-Fi SoC: An ESP32 series chip (e.g., ESP32, ESP32-C3, ESP32-S3) running the gateway application.
    2. 802.15.4 SoC: An 802.15.4 enabled chip (e.g., ESP32-H2 or ESP32-C6) running the OpenThread RCP firmware to provide the Zigbee radio interface.

    Supported Targets: ESP32, ESP32-C3, ESP32-C6, ESP32-S2, ESP32-S3, ESP32-C5, ESP32-P4.

  2. Overview of esp-zigbee-lib functionalities

    main

    The esp-zigbee-lib component provides the binary libraries for the Espressif proprietary Zigbee stack and its integration with ESP-IDF. It is the core component used for Zigbee product development on Espressif SoCs.

    Key capabilities include:

    • ZCL Data Model: APIs for full customization of the Zigbee Cluster Library data model.
    • Standard Clusters: Out-of-the-box implementations of standard ZCL clusters.
    • Device Profiles: Support for standard Home Automation off-the-shelf devices.
    • Node Management: Various ZDO (Zigbee Device Object) commands.
    • Commissioning: Support for Zigbee BDB (Basic Device Behavior) and Touchlink commissioning.
    • Device Roles: Support for Zigbee Coordinator, Router, and (sleepy) End Device roles.
    • Security: Management of Zigbee security, including install codes and TCLK (Trust Center Link Key) exchange.

  3. Overview of ZCL General Clusters in ESP Zigbee Core

    main
    The ESP Zigbee Core provides implementations for various Zigbee Cluster Library (ZCL) General Clusters. These clusters allow devices to perform standard Zigbee functions such as basic identification, power management, group/scene management, and control of common device types like On/Off switches, Level Control, and Alarms. The SDK supports a wide range of clusters including Analog, Binary, and Multistate inputs/outputs/values, as well as Poll Control.

  4. Overview of Espressif Zigbee Solutions

    main

    Espressif provides a complete ecosystem for Zigbee development, including hardware, software, and cloud integration:

    • Hardware Platforms:
      • Zigbee Devices: Built using 802.15.4 SoCs like ESP32-H2 and ESP32-C6.
      • Zigbee Gateways: Built by combining 802.15.4 SoCs with Wi-Fi SoCs (e.g., ESP32, ESP32-C3, ESP32-S3) to bridge Zigbee networks to Wi-Fi.
      • Matter-Zigbee Bridge: Enables non-Matter Zigbee devices to connect to the Matter ecosystem.
    • Software: The esp-zigbee-sdk (v2.x) is built on ESP-IDF and uses a proprietary Zigbee protocol implementation. The core component esp-zigbee-lib is available via the ESP Registry.
    • Cloud Integration: Integration with ESP RainMaker allows for remote control and cloud-based device management of Zigbee devices.

  5. Use ZCL Lighting Clusters in ESP Zigbee Core

    main
    The ESP Zigbee Core provides implementations for Zigbee Cluster Library (ZCL) lighting clusters. These clusters allow devices to control lighting attributes such as brightness, color, and other lighting-specific parameters within a Zigbee network. The implementation includes support for the Color Control cluster to manage color temperature, hue, and saturation.

  7. ZCL Measurement and Sensing Clusters Overview

    main
    The ESP Zigbee Core provides implementations for various Zigbee Cluster Library (ZCL) Measurement and Sensing clusters. These clusters allow Zigbee devices to report environmental and physical data such as temperature, humidity, pressure, illuminance, and more. Each cluster follows the standard ZCL specification for attribute reporting and command handling within the ESP Zigbee SDK.

  8. Explore ESP Zigbee SDK examples

    main

    The examples/ directory contains standalone projects designed to demonstrate various Zigbee protocol functionalities. You can copy any example directory to a new location to modify and adapt it for your own projects.

    Examples are categorized into the following functional groups:

    • all_device_types_app: Demonstrates all Zigbee device types using a Command Line Interface (CLI) mode.
    • customized_devices: Shows how to implement fully customized attributes, clusters, endpoints, and functions for both server and client devices.
    • zigbee_gateway: A gateway example that runs on a Wi-Fi SoC (e.g., ESP32, ESP32-C3, ESP32-C6, ESP32-S3) paired with an 802.15.4 SoC (e.g., ESP32-H2) running the ot_rcp example.
    • home_automation_devices: Includes standard Zigbee Home Automation (ZHA) profiles such as on_off_light, on_off_switch, color_dimmable_light, color_dimmer_switch, temperature_sensor, and thermostat.
    • ota_upgrade: Demonstrates Zigbee Over-The-Air (OTA) firmware upgrade processes.
    • sleepy_devices: Provides examples for Zigbee sleepy end devices using light or deep sleep modes.
    • touchlink: Demonstrates Zigbee TouchLink functionality for both initiator and target devices.

  9. Use ZCL Smart Energy Clusters

    main

    The ESP Zigbee Core provides implementations for several Smart Energy ZCL (Zigbee Cluster Library) clusters. These clusters are used to manage energy-related data such as metering, meter identification, and pricing.

    Available Smart Energy clusters include:

    • Metering: Handles energy consumption data.
    • Meter Identification: Provides information to identify the meter.
    • Price: Manages pricing information related to energy usage.

  10. Use the ESP-Zigbee-Console CLI

    main

    The ESP-Zigbee-Console provides a command-line interface (CLI) to configure and manage the ESP-Zigbee-SDK at runtime.

    Commands follow the pattern: <main_command> [<sub_command>] [options].

    Options are parsed using argtable3 and follow POSIX Utility Conventions. You can view help strings for any command by typing the command name without arguments.

    esp> zdo
zdo: Zigbee Device Object management
    request         Request information from node
    annce           Announce current node
    match           Get matched devices
    bind            Request the node to bind to device
    nwk_open        Request the node to open the network
    nwk_leave       Request the node to leave the network

  11. Explore Zigbee Home Automation (HA) Device Examples

    main

    The examples/home_automation_devices directory contains several implementations of the Zigbee Home Automation (HA) standard. These examples demonstrate different Zigbee device roles (Coordinator, Router, and End-device) using 802.15.4 SoCs like the ESP32-H2.

    Available HA Examples

    ExampleZigbee RoleDescription
    on_off_lightCoordinatorA standard on-off light bulb example.
    on_off_switchEnd-deviceA toggle switch used to control an on-off light.
    color_dimmable_lightCoordinatorA color dimmable light bulb example.
    color_dimmable_switchRouterA switch used to control color and dimming on a light.
    temperature_sensorEnd-deviceUses the on-chip temperature sensor to provide measurements.
    thermostatCoordinatorProvides temperature acquisition with both read and report mechanisms.

  12. Overview of Zigbee ZCL Custom Clusters

    main

    The Zigbee Cluster Library (ZCL) uses standardized clusters to represent groups of related attributes and commands for common application scenarios. When standard clusters do not meet specific requirements, developers can implement Custom Clusters.

    Custom clusters allow you to define your own specific attributes, commands, and corresponding handling functions that are not part of the standard ZCL specification. The esp-zigbee-sdk provides a dedicated API suite to facilitate the creation and management of these custom clusters.