ContextQMD
Back to Arduino Esp32

ZigbeeCore

docs/en/zigbee/zigbee_core.rst

3.3.88.5 KB
Original Source

########## ZigbeeCore ##########

About

The ZigbeeCore class is the main entry point for all Zigbee operations. It serves as the central class that manages:

  • Network Operations: Starting, stopping, and managing the Zigbee network
  • Device Role Management: Configuring the device as Coordinator, Router, or End Device
  • Endpoint Management: Adding and managing multiple device endpoints
  • Network Discovery: Scanning for and joining existing networks

ZigbeeCore APIs

Network Initialization

begin ^^^^^

Initializes the Zigbee stack and starts the network.

.. code-block:: arduino

bool begin(zigbee_role_t role = ZIGBEE_END_DEVICE, bool erase_nvs = false);
bool begin(esp_zb_cfg_t *role_cfg, bool erase_nvs = false);
  • role - Device role (default: ZIGBEE_END_DEVICE)
  • role_cfg - Custom role configuration structure
  • erase_nvs - Whether to erase NVS storage (default: false)

This function will return true if initialization successful, false otherwise.

Available Roles:

  • ZIGBEE_COORDINATOR: Network coordinator, forms and manages the network
  • ZIGBEE_ROUTER: Network router, connects to existing network and extends network range and routes messages (if device is mains powered, always use this role)
  • ZIGBEE_END_DEVICE: End device, connects to existing network (typically battery-powered which can sleep)

.. note::

Depending on the Zigbee role, proper Zigbee mode and partition scheme must be set in the Arduino IDE.

* **ZIGBEE_COORDINATOR** and **ZIGBEE_ROUTER**:
    * Zigbee mode to ``Zigbee ZCZR (coordinator/router)``.
    * Partition scheme to ``Zigbee ZCZR xMB with spiffs`` (where ``x`` is the number of MB of selected flash size).
* **ZIGBEE_END_DEVICE**:
    * Zigbee mode to ``Zigbee ED (end device)``.
    * Partition scheme to ``Zigbee xMB with spiffs`` (where ``x`` is the number of MB of selected flash size).

start ^^^^^ Starts the Zigbee stack again, if it was stopped by calling stop().

.. code-block:: arduino

void start();

stop ^^^^ Stops the Zigbee stack. This can be used after calling begin() to stop the Zigbee stack. Usage example is to save power or when you need the radio to be available for other tasks.

.. code-block:: arduino

void stop();

Network Status

started ^^^^^^^

Checks if the Zigbee stack has been started.

.. code-block:: arduino

bool started();

This function will return true if Zigbee stack is running, false otherwise.

connected ^^^^^^^^^

Checks if the device is connected to a Zigbee network.

.. code-block:: arduino

bool connected();

This function will return true if connected to network, false otherwise.

getRole ^^^^^^^

Gets the current Zigbee device role.

.. code-block:: arduino

zigbee_role_t getRole();

This function will return current device role (ZIGBEE_COORDINATOR, ZIGBEE_ROUTER, ZIGBEE_END_DEVICE).

Endpoint Management

addEndpoint ^^^^^^^^^^^

Adds an endpoint to the Zigbee network.

.. code-block:: arduino

bool addEndpoint(ZigbeeEP *ep);
  • ep - Pointer to the endpoint object to add

This function will return true if endpoint added successfully, false otherwise.

Network Configuration

setPrimaryChannelMask ^^^^^^^^^^^^^^^^^^^^^

Sets the primary channel mask for network scanning and joining.

.. code-block:: arduino

void setPrimaryChannelMask(uint32_t mask);
  • mask - Channel mask (default: all channels 11-26, mask 0x07FFF800)

setScanDuration ^^^^^^^^^^^^^^^

Sets the scan duration for network discovery.

.. code-block:: arduino

void setScanDuration(uint8_t duration);
  • duration - Scan duration (1-4, where 1 is fastest, 4 is slowest)

getScanDuration ^^^^^^^^^^^^^^^

Gets the current scan duration setting.

.. code-block:: arduino

uint8_t getScanDuration();

This function will return current scan duration (1-4).

Power Management

setRxOnWhenIdle ^^^^^^^^^^^^^^^

Sets whether the device keeps its receiver on when idle.

.. code-block:: arduino

void setRxOnWhenIdle(bool rx_on_when_idle);
  • rx_on_when_idle - true to keep receiver on, false to allow sleep

getRxOnWhenIdle ^^^^^^^^^^^^^^^

Gets the current receiver idle setting.

.. code-block:: arduino

bool getRxOnWhenIdle();

This function will return current receiver idle setting.

setTimeout ^^^^^^^^^^

Sets the timeout for network operations.

.. code-block:: arduino

void setTimeout(uint32_t timeout);
  • timeout - Timeout in milliseconds (default: 30000 ms)

Network Discovery

scanNetworks ^^^^^^^^^^^^

Scans for available Zigbee networks.

.. code-block:: arduino

void scanNetworks(uint32_t channel_mask = ESP_ZB_TRANSCEIVER_ALL_CHANNELS_MASK, uint8_t scan_duration = 5);
  • channel_mask - Channels to scan (default: all channels)
  • scan_duration - Scan duration (default: 5)

scanComplete ^^^^^^^^^^^^

Checks if network scanning is complete.

.. code-block:: arduino

int16_t scanComplete();

This function will return:

  • -2: Scan failed or not started
  • -1: Scan running
  • 0: No networks found
  • >0: Number of networks found

getScanResult ^^^^^^^^^^^^^

Gets the scan results.

.. code-block:: arduino

zigbee_scan_result_t *getScanResult();

This function will return pointer to scan results, or NULL if no results.

scanDelete ^^^^^^^^^^

Deletes the scan results from memory.

.. code-block:: arduino

void scanDelete();

Network Management (Coordinator only)

setRebootOpenNetwork ^^^^^^^^^^^^^^^^^^^^

Opens the network for joining after reboot for a specified time.

.. code-block:: arduino

void setRebootOpenNetwork(uint8_t time);
  • time - Time in seconds to keep network open after reboot

openNetwork ^^^^^^^^^^^

Opens the network for device joining for a specified time.

.. code-block:: arduino

void openNetwork(uint8_t time);
  • time - Time in seconds to keep network open for device joining

closeNetwork ^^^^^^^^^^^^

Closes the network to prevent new devices from joining.

.. code-block:: arduino

void closeNetwork();

Radio Configuration

setRadioConfig ^^^^^^^^^^^^^^

Sets the radio configuration.

.. code-block:: arduino

void setRadioConfig(esp_zb_radio_config_t config);
  • config - Radio configuration structure

getRadioConfig ^^^^^^^^^^^^^^

Gets the current radio configuration.

.. code-block:: arduino

esp_zb_radio_config_t getRadioConfig();

This function will return current radio configuration.

Host Configuration

setHostConfig ^^^^^^^^^^^^^

Sets the host configuration.

.. code-block:: arduino

void setHostConfig(esp_zb_host_config_t config);
  • config - Host configuration structure

getHostConfig ^^^^^^^^^^^^^

Gets the current host configuration.

.. code-block:: arduino

esp_zb_host_config_t getHostConfig();

This function will return current host configuration.

Debug and Utilities

setDebugMode ^^^^^^^^^^^^

Enables or disables debug mode.

.. code-block:: arduino

void setDebugMode(bool debug);
  • debug - true to enable debug output, false to disable

getDebugMode ^^^^^^^^^^^^

Gets the current debug mode setting.

.. code-block:: arduino

bool getDebugMode();

This function will return current debug mode setting.

factoryReset ^^^^^^^^^^^^

Performs a factory reset, clearing all network settings.

.. code-block:: arduino

void factoryReset(bool restart = true);
  • restart - true to restart after reset (default: true)

onGlobalDefaultResponse ^^^^^^^^^^^^^^^^^^^^^^^

Sets a global callback for default response messages.

.. code-block:: arduino

void onGlobalDefaultResponse(void (*callback)(zb_cmd_type_t resp_to_cmd, esp_zb_zcl_status_t status, uint8_t endpoint, uint16_t cluster));
  • callback - Function pointer to the callback function

This callback will be called for all endpoints when a default response is received.

Utility Functions

formatIEEEAddress ^^^^^^^^^^^^^^^^^

Formats an IEEE address for display.

.. code-block:: arduino

static const char *formatIEEEAddress(const esp_zb_ieee_addr_t addr);
  • addr - IEEE address to format

This function will return formatted address string.

formatShortAddress ^^^^^^^^^^^^^^^^^^

Formats a short address for display.

.. code-block:: arduino

static const char *formatShortAddress(uint16_t addr);
  • addr - Short address to format

This function will return formatted address string.