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.

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).

Network Status

started

Checks if the Zigbee stack has been started.

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.

bool connected();

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

getRole

Gets the current Zigbee device role.

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.

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.

void setPrimaryChannelMask(uint32_t mask);

  • mask - Channel mask (default: all channels 11-26, mask 0x07FFF800)

setScanDuration

Sets the scan duration for network discovery.

void setScanDuration(uint8_t duration);

  • duration - Scan duration (1-4, where 1 is fastest, 4 is slowest)

getScanDuration

Gets the current scan duration setting.

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.

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.

bool getRxOnWhenIdle();

This function will return current receiver idle setting.

setTimeout

Sets the timeout for network operations.

void setTimeout(uint32_t timeout);

  • timeout - Timeout in milliseconds (default: 30000 ms)

Network Discovery

scanNetworks

Scans for available Zigbee networks.

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.

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.

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.

void scanDelete();

Network Management (Coordinator only)

setRebootOpenNetwork

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

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.

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.

void closeNetwork();

Radio Configuration

setRadioConfig

Sets the radio configuration.

void setRadioConfig(esp_zb_radio_config_t config);

  • config - Radio configuration structure

getRadioConfig

Gets the current radio configuration.

esp_zb_radio_config_t getRadioConfig();

This function will return current radio configuration.

Host Configuration

setHostConfig

Sets the host configuration.

void setHostConfig(esp_zb_host_config_t config);

  • config - Host configuration structure

getHostConfig

Gets the current host configuration.

esp_zb_host_config_t getHostConfig();

This function will return current host configuration.

Debug and Utilities

setDebugMode

Enables or disables debug mode.

void setDebugMode(bool debug);

  • debug - true to enable debug output, false to disable

getDebugMode

Gets the current debug mode setting.

bool getDebugMode();

This function will return current debug mode setting.

factoryReset

Performs a factory reset, clearing all network settings.

void factoryReset(bool restart = true);

  • restart - true to restart after reset (default: true)

onGlobalDefaultResponse

Sets a global callback for default response messages.

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.

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.

static const char *formatShortAddress(uint16_t addr);

  • addr - Short address to format

This function will return formatted address string.