Core API

Core APIs for ESP Zigbee SDK.

API Reference

Header File

components/esp-zigbee-lib/include/esp_zigbee_core.h

Functions

esp_err_t esp_zb_overall_network_size_set(uint16_t size)

Set the maximum number of devices in a Zigbee network.

Note

The function will only take effect when called before esp_zb_init(), it determins several table size such as the neighbor table and routing table, 64 by default

Parameters:

size – [in] The overall network size is expected to be set

Returns:

ESP_OK: on success
ESP_FAIL: on failure

esp_err_t esp_zb_io_buffer_size_set(uint16_t size)

Set Zigbee stack I/O buffer size.

Note

The function will only take effect when called before esp_zb_init(), 80 by default.

Parameters:

size – [in] The I/O buffer size is expected to be set

Returns:

ESP_OK: on success
ESP_FAIL: on failure

esp_err_t esp_zb_scheduler_queue_size_set(uint16_t size)

Set Zigbee stack scheduler queue size.

Note

The function will only take effect when called before esp_zb_init(), 80 by default.

Parameters:

size – [in] The scheduler queue size is expected to be set

Returns:

ESP_OK: on success
ESP_FAIL: on failure

esp_err_t esp_zb_aps_src_binding_table_size_set(uint16_t size)

Set APS source binding table size.

Note

The function will only take effect when called before esp_zb_init(), 16 by default

Parameters:

size – [in] The source binding table size is expected to be set

Returns:

ESP_OK: on success
ESP_FAIL: on failure

esp_err_t esp_zb_aps_dst_binding_table_size_set(uint16_t size)

Set APS destination binding table size.

Note

The function will only take effect when called before esp_zb_init(), 16 by default

Parameters:

size – [in] The destination binding table size is expected to be set

Returns:

ESP_OK: on success
ESP_FAIL: on failure

void esp_zb_init(esp_zb_cfg_t *nwk_cfg)

Zigbee stack initialization.

Note

To be called inside the application’s main cycle at start.

Note

Default is no NVRAM erase from start up, user could call factory reset for erase NVRAM and other action please refer esp_zb_factory_reset().

Note

Make sure to use correct corresponding nwk_cfg with your device type esp_zb_cfg_s.

Parameters:: nwk_cfg – [in] The pointer to the initialization Zigbee configuration

esp_err_t esp_zb_set_primary_network_channel_set(uint32_t channel_mask)

Set the BDB primary channel mask.

Beacon request will be sent on these channels for the BDB energy scan.

Note

This function should be run AFTER esp_zb_init is called and before esp_zb_start. These masks define the allowable channels on which the device may attempt to form or join a network at startup time. If function is not called, by default it will scan all channels or read from zb_fct NVRAM zone if available. Please refer to tools/mfg_tool.

Parameters:

channel_mask – [in] Valid channel mask is from 0x00000800 (only channel 11) to 0x07FFF800 (all channels from 11 to 26)

Returns:

- ESP_OK on success

ESP_ERR_INVALID_ARG if the channel mask is out of range

uint32_t esp_zb_get_primary_network_channel_set(void)

Get the BDB primary channel mask.

Returns:: A 32-bit channel mask

esp_err_t esp_zb_set_secondary_network_channel_set(uint32_t channel_mask)

Set the BDB secondary channel mask.

Beacon request will be sent on these channels for the BDB energy scan, if no network found after energy scan on the primary channels.

Parameters:

channel_mask – [in] Valid channel mask is from 0x00000800 (only channel 11) to 0x07FFF800 (all channels from 11 to 26)

Returns:

- ESP_OK on success

ESP_ERR_INVALID_ARG if the channel mask is out of range

uint32_t esp_zb_get_secondary_network_channel_set(void)

Get the BDB secondary channel mask.

Returns:: A 32-bit channel mask

esp_err_t esp_zb_set_channel_mask(uint32_t channel_mask)

Set the 2.4G channel mask.

Parameters:

channel_mask – [in] Valid channel mask is from 0x00000800 (only channel 11) to 0x07FFF800 (all channels from 11 to 26)

Returns:

- ESP_OK on success

ESP_ERR_INVALID_ARG if the channel mask is out of range

uint32_t esp_zb_get_channel_mask(void)

Get the 2.4 channel mask.

Returns:: A 32-bit channel mask

bool esp_zb_bdb_is_factory_new(void)

Check if device is factory new.

Returns:: - True factory new.

uint8_t esp_zb_bdb_get_scan_duration(void)

Get the scan duration time.

Returns:: Scan duration is in beacon intervals (15.36 ms)

void esp_zb_bdb_set_scan_duration(uint8_t duration)

Set the scan duration time.

Parameters:: duration – [in] The scan duration time is in beacon intervals, defined as ((1 << duration) + 1) * 15.36 ms

esp_err_t esp_zb_bdb_open_network(uint8_t permit_duration)

Open Zigbee network.

Parameters:

permit_duration – [in] Zigbee network open time

Returns:

ESP_OK: on success
ESP_ERR_NO_MEM: not memory
ESP_FAILED: on failed

esp_err_t esp_zb_bdb_close_network(void)

Close Zigbee network.

Returns:

ESP_OK: on success
ESP_FAIL: on failure

bool esp_zb_bdb_dev_joined(void)

Check if device has joined network or not.

Returns:

true: device is joined
false: device is not joined

void esp_zb_zdo_touchlink_set_nwk_channel(uint8_t channel)

Set Touchlink NWK channel.

Parameters:: channel – [in] Touchlink NWK channel value

void esp_zb_set_tx_power(int8_t power)

Set the tx power.

Parameters:: power – [in] 8-bit of power value in dB, ranging from IEEE802154_TXPOWER_VALUE_MIN to IEEE802154_TXPOWER_VALUE_MAX

void esp_zb_get_tx_power(int8_t *power)

Get the tx power.

Parameters:: power – [in] 8-bit of power pointer value in dB

esp_err_t esp_zb_bdb_start_top_level_commissioning(uint8_t mode_mask)

Start top level commissioning procedure with specified mode mask.

Parameters:: mode_mask – [in] commissioning modes refer to esp_zb_bdb_commissioning_mode
Returns:: - ESP_OK on success

void esp_zb_bdb_reset_via_local_action(void): Perform local reset procedure.

Note

This only takes effect when the device is on a network. The device will leave the current network and clear all Zigbee persistent data, except the outgoing NWK frame counter. It will be in nearly the same state as when it left the factory. A ZB_ZDO_SIGNAL_LEAVE signal with ESP_ZB_NWK_LEAVE_TYPE_RESET will be triggered to indicate the end of the procedure.

void esp_zb_factory_reset(void): Perform “factory reset” procedure.

Note

The device will completely erase the zb_storage partition and then restart

esp_err_t esp_zb_start(bool autostart)

Start Zigbee function.

For example, you can use this function if it is needed to enable leds, timers or any other devices on periphery to work with them before starting working in a network. It’s also useful if you want to run something locally during joining.

Note

Autostart mode: It initializes, load some parameters from NVRAM and proceed with startup. Startup means either Formation (for ZC), rejoin or discovery/association join. After startup complete, esp_zb_app_signal_handler is called, so application will know when to do some useful things.

Note

No-autostart mode: It initializes scheduler and buffers pool, but not MAC and upper layers. Notifies the application that Zigbee framework (scheduler, buffer pool, etc.) has started, but no join/rejoin/formation/BDB initialization has been done yet. Typically esp_zb_start with no_autostart mode is used when application wants to do something before starting joining the network.

Note

Precondition: stack must be initialized by esp_zb_init call. esp_zb_init sets default IB parameters, so caller has a chance to change some of them. Note that NVRAM and product config will be loaded after esp_zb_start() call.

Note

Zigbee stack is not looped in this routine. Instead, it schedules callback and returns. Caller must run esp_zb_stack_main_loop() after this routine.

Note

Application should later call Zigbee commissioning initiation - for instance, esp_zb_bdb_start_top_level_commissioning().

Parameters:

autostart – [in] - true autostart mode

false no-autostart mode

Returns:

- ESP_OK on success

bool esp_zb_is_started(void)

Get the stack is started or not.

Returns:: true if the stack has been started, false otherwise.

bool esp_zb_lock_acquire(TickType_t block_ticks)

Acquire Zigbee lock.

Note

It’s mandatory to acquire the lock before calling any Zigbee SDK APIs, except that the call site is in Zigbee callbacks.

Returns:

true: on success

void esp_zb_lock_release(void): Release Zigbee lock.

void esp_zb_main_loop_iteration(void)

Zigbee main loop iteration.

Deprecated:: Please use esp_zb_stack_main_loop() instead

Note

Must be called after esp_zb_init() and esp_zb_start() inside the application’s main cycle.

void esp_zb_stack_main_loop_iteration(void): Zigbee stack main loop iteration once.

Note

Must be called after esp_zb_init() and esp_zb_start().

void esp_zb_stack_main_loop(void): Zigbee stack main loop.

Note

Must be called after esp_zb_init() and esp_zb_start(), it’s an infinite main loop.

void esp_zb_nvram_erase_at_start(bool erase)

Enable/Disable erasing the zb_storage field before the stack runs.

Note

Enable or disable NVRAM erasing on every application startup. Erasing is disabled by default.

Parameters:: erase – - 1 to enable erasing; 0 - disable.

void esp_zb_app_signal_handler(esp_zb_app_signal_t *signal_s)

Zigbee stack application signal handler.

Note

After esp_zb_start, user shall based on the corresponding signal type refer to esp_zdo_app_signal_type from struct pointer signal_s to do certain actions. User could also use refer to esp_zb_bdb_start_top_level_commissioning to change BDB mode.

Warning

This function has to be defined by user in each example.

Parameters:: signal_s – [in] pointer of Zigbee zdo app signal struct esp_zb_app_signal_s.

void *esp_zb_app_signal_get_params(uint32_t *signal_p)

Obtains pointer to parameters passed with application signal.

Parameters:: signal_p – [in] pointer to the application signal type esp_zb_app_signal_s of p_app_signal
Returns:: void pointer to certain signal param content

void esp_zb_scheduler_alarm(esp_zb_callback_t cb, uint8_t param, uint32_t time)

Schedule alarm - callback to be executed after timeout.

Note

Function will be called via scheduler after timeout expired in millisecond. Timer resolution depends on implementation. Same callback can be scheduled for execution more then once.

Parameters:

cb – [in] - function to call via scheduler
param – [in] - parameter to pass to the function
time – [in] - timeout, in millisecond

void esp_zb_scheduler_alarm_cancel(esp_zb_callback_t cb, uint8_t param)

Cancel scheduled alarm.

Note

This function cancel previously scheduled alarm.

Parameters:

cb – [in] - function to cancel
param – [in] - parameter to pass to the function to cancel

esp_zb_user_cb_handle_t esp_zb_scheduler_user_alarm(esp_zb_user_callback_t cb, void *param, uint32_t time)

Schedule user alarm - callback to be executed after timeout.

Note

Function will be called via scheduler after timeout expired in millisecond. Timer resolution depends on implementation. Same callback can be scheduled for execution more then once.

Parameters:

cb – [in] - function to call via scheduler
param – [in] - parameter to pass to the function
time – [in] - timeout, in millisecond

Returns:

the handle used to cancel the user alarm

esp_err_t esp_zb_scheduler_user_alarm_cancel(esp_zb_user_cb_handle_t handle)

Cancel scheduled user alarm.

Note

This function cancel previously scheduled user alarm.

Parameters:

handle – [in] - the handle returned by esp_zb_scheduler_user_alarm

Returns:

ESP_OK: on success
ESP_ERR_NOT_FOUND: not found the user alarm

void esp_zb_set_bdb_commissioning_mode(esp_zb_bdb_commissioning_mode_mask_t commissioning_mode)

Set BDB commissioning mode.

Parameters:: commissioning_mode – [in] commissioning mode that refer to esp_zb_bdb_commissioning_mode_mask_t.

esp_zb_bdb_commissioning_mode_mask_t esp_zb_get_bdb_commissioning_mode(void)

Set BDB commissioning mode.

Returns:: commissioning mode, refer to esp_zb_bdb_commissioning_mode_mask_t

esp_err_t esp_zb_bdb_cancel_steering(void)

Schedule to cancel Steering procedure for a node not on a network.

Note

The signal ESP_ZB_BDB_SIGNAL_STEERING_CANCELLED with the status of this operation will be raised.

Returns:

ESP_OK: on success
ESP_FAIL: on failed

esp_err_t esp_zb_bdb_cancel_formation(void)

Schedule to cancel Formation procedure.

Note

The signal ESP_ZB_BDB_SIGNAL_FORMATION_CANCELLED with the status of the operation will be raised.

Returns:

ESP_OK: on success
ESP_FAIL: on failed

esp_err_t esp_zb_sleep_set_threshold(uint32_t threshold_ms)

Set the sleep threshold on the device. When the scheduler detects that the device can enter sleep mode, it will notify the application with the signal ESP_ZB_COMMON_SIGNAL_CAN_SLEEP. The default sleep threshold is 20 milliseconds.

Parameters:: threshold_ms – [in] Sleep threshold in milliseconds
Returns:: ESP_OK if new threshold is valid and applied.
Returns:: ESP_FAIL if the user attempts to set a threshold greater than ESP_ZB_SLEEP_MAXIMUM_THRESHOLD_MS.

void esp_zb_sleep_now(void): Blocking function responsible for putting device into sleep mode.

void esp_zb_sleep_enable(bool enable)

Enable the Zigbee sleep.

Parameters:: enable – [in] Enable Zigbee Sleep

bool esp_zb_sleep_is_enable(void)

Get Zigbee sleep is enable or not.

Returns:: TRUE Zigbee sleep is enable.
Returns:: FALSE Zigbee sleep is disable.

esp_zb_bdb_commissioning_status_t esp_zb_get_bdb_commissioning_status(void)

Get bdb_commissioning_status.

Returns:: commissioning_status refer to esp_zb_bdb_commissioning_status_t

void esp_zb_set_node_descriptor_manufacturer_code(uint16_t manufacturer_code)

Set the Zigbee node descriptor manufacturer code.

Note

The function should be called after esp_zb_start()

Parameters:: manufacturer_code – [in] The manufacturer code of Zigbee device

void esp_zb_set_node_descriptor_power_source(bool is_main_power)

Set the power source for the Zigbee node descriptor.

Note

The function should be called after esp_zb_start()

Parameters:: is_main_power – [in] Indicates whether the current power source is mains power (true) or not (false).

void esp_zb_set_node_power_descriptor(esp_zb_af_node_power_desc_t node_power)

Set the node power descriptor.

Structures

struct esp_zb_zczr_cfg_t

The Zigbee Coordinator/ Router device configuration.

Public Members

uint8_t max_children: Max number of the children

struct esp_zb_zed_cfg_t

The Zigbee End device configuration.

Public Members

uint8_t ed_timeout: Set End Device Timeout, refer to esp_zb_aging_timeout_t

uint32_t keep_alive: Set Keep alive Timeout, in milliseconds, with a maximum value of 65,000,000,000.

struct esp_zb_cfg_s

The Zigbee device configuration.

Note

For esp_zb_role please refer defined by esp_zb_nwk_device_type_t.

Public Members

esp_zb_nwk_device_type_t esp_zb_role: The nwk device type

bool install_code_policy: Allow install code security policy or not

esp_zb_zczr_cfg_t zczr_cfg: The Zigbee zc/zr device configuration

esp_zb_zed_cfg_t zed_cfg: The Zigbee zed device configuration

union esp_zb_cfg_s::[anonymous] nwk_cfg: Union of the network configuration

struct esp_zb_app_signal_s

The application signal struct for esp_zb_app_signal_handler.

Public Members

uint32_t *p_app_signal: Application pointer signal type, refer to esp_zb_app_signal_type_t

esp_err_t esp_err_status: The error status of the each signal event, refer to esp_err_t

Macros

ESP_ZB_TRANSCEIVER_ALL_CHANNELS_MASK: channel 11-26 for compatibility with 2.4GHZ

Type Definitions

typedef struct esp_zb_cfg_s esp_zb_cfg_t: The Zigbee device configuration.

Note

For esp_zb_role please refer defined by esp_zb_nwk_device_type_t.

typedef struct esp_zb_app_signal_s esp_zb_app_signal_t: The application signal struct for esp_zb_app_signal_handler.

Enumerations

enum esp_zb_aging_timeout_t

Values:

enumerator ESP_ZB_ED_AGING_TIMEOUT_10SEC: 10 second timeout

enumerator ESP_ZB_ED_AGING_TIMEOUT_2MIN: 2 minutes

enumerator ESP_ZB_ED_AGING_TIMEOUT_4MIN: 4 minutes

enumerator ESP_ZB_ED_AGING_TIMEOUT_8MIN: 8 minutes

enumerator ESP_ZB_ED_AGING_TIMEOUT_16MIN: 16 minutes

enumerator ESP_ZB_ED_AGING_TIMEOUT_32MIN: 32 minutes

enumerator ESP_ZB_ED_AGING_TIMEOUT_64MIN: 64 minutes

enumerator ESP_ZB_ED_AGING_TIMEOUT_128MIN: 128 minutes

enumerator ESP_ZB_ED_AGING_TIMEOUT_256MIN: 256 minutes

enumerator ESP_ZB_ED_AGING_TIMEOUT_512MIN: 512 minutes

enumerator ESP_ZB_ED_AGING_TIMEOUT_1024MIN: 1024 minutes

enumerator ESP_ZB_ED_AGING_TIMEOUT_2048MIN: 2048 minutes

enumerator ESP_ZB_ED_AGING_TIMEOUT_4096MIN: 4096 minutes

enumerator ESP_ZB_ED_AGING_TIMEOUT_8192MIN: 8192 minutes

enumerator ESP_ZB_ED_AGING_TIMEOUT_16384MIN: 16384 minutes