5.1. SDK API

APIs added by ESP Zigbee SDK.

5.1.1. API Reference

5.1.1.1. Header File

5.1.1.2. Functions

esp_err_t esp_zigbee_init(const esp_zigbee_config_t *config)

Initialize ESP-Zigbee stack. .

Parameters:

config -- [in] The Zigbee configuration, esp_zigbee_config_s.

Returns:

ESP_OK on success, error code otherwise.

esp_err_t esp_zigbee_deinit(void)

Deinitialize ESP-Zigbee stack. .

Returns:

ESP_OK on success, error code otherwise.

esp_err_t esp_zigbee_start(bool autostart)

Start Zigbee function. .

Note

  • Prerequisite: The stack SHALL be initialized by esp_zigbee_init.

  • Postprocess: The stack is not looped in this routine. Instead, it schedules callback and returns. The application SHALL call esp_zigbee_launch_mainloop after this routine.

Note

  • The stack will initialize the framework, load persistent data from datasets and continue the startup procedure. The startup procedure always means commissioning the device to a network (formation, rejoin or join the network; typically by BDB process).

  • Autostart: Do everything, including the startup procedure.

  • No-autostart: Do everything, but skip the startup procedure. Typically esp_zigbee_start() with no-autostart mode is used when application wants to do something before starting joining the network and control the startup process by itself.

Parameters:

autostart -- [in]

  • True: autostart mode

  • False: no-autostart mode.

Returns:

  • ESP_OK: Stack started successfully.

  • ESP_FAIL: Stack failed to start.

bool esp_zigbee_is_started(void)

Get the stack is started or not. .

Returns:

true if the stack has been started, false otherwise.

esp_err_t esp_zigbee_launch_mainloop(void)

Launch the mainloop of ESP-Zigbee. .

Returns:

ESP_OK on success, error code otherwise.

bool esp_zigbee_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.

Parameters:

block_ticks -- [in] The maximum number of RTOS ticks to wait for the lock.

Returns:

  • True on lock acquired

  • False on failing to acquire the lock with the timeout.

void esp_zigbee_lock_release(void)

Release Zigbee lock.

esp_err_t esp_zigbee_task_queue_post(esp_zigbee_callback_t cb, void *ctx)

This function posts a task to the ESP-Zigbee task queue.

Parameters:

  • cb -- [in] The callback function to execute.

  • ctx -- [in] The context to be passed to the callback.

Returns:

  • ESP_OK

  • ESP_FAIL

esp_err_t esp_zigbee_err_to_esp(ezb_err_t error)

Convert core stack error to esp_err_t.

Parameters:

error -- [in] The error code from the core stack.

Returns:

The esp_err_t error code.

void esp_zigbee_factory_reset(void)

Perform "factory reset" procedure.

Note

This function will clear all the datasets and restart the device.

5.1.1.3. Structures

struct esp_zigbee_uart_config_s

The uart port config for Zigbee.

Public Members

uart_port_t port

UART port number

uart_config_t uart_config

UART configuration, see uart_config_t docs

gpio_num_t rx_pin

UART RX pin

gpio_num_t tx_pin

UART TX pin

struct esp_zigbee_radio_config_s

Zigbee radio configuration.

Public Members

esp_zigbee_radio_mode_t radio_mode

The radio mode

esp_zigbee_uart_config_t radio_uart_config

The uart configuration to RCP

struct esp_zigbee_platform_config_s

Zigbee platform configuration.

Public Members

const char *storage_partition_name

The name of the storage partition

esp_zigbee_radio_config_t radio_config

The radio configuration

struct esp_zigbee_zczr_config_s

The Zigbee Coordinator/ Router device configuration.

Public Members

uint8_t max_children

Max number of the children

struct esp_zigbee_zed_config_s

The Zigbee End device configuration.

Public Members

uint8_t ed_timeout

Set End Device Timeout, refer to ezb_nwk_ed_timeout_e

uint32_t keep_alive

Set Keep alive Timeout, in milliseconds.

struct esp_zigbee_device_config_s

The Zigbee device configuration.

Public Members

ezb_nwk_device_type_t device_type

The nwk device type, ezb_nwk_device_type_t

bool install_code_policy

Allow install code security policy or not

struct esp_zigbee_zczr_config_s zczr_config

The Zigbee zc/zr device configuration

struct esp_zigbee_zed_config_s zed_config

The Zigbee zed device configuration

struct esp_zigbee_config_s

The Zigbee configuration.

Public Members

esp_zigbee_device_config_t device_config

The Zigbee device configuration

esp_zigbee_platform_config_t platform_config

The Zigbee platform configuration

5.1.1.4. Type Definitions

typedef struct esp_zigbee_uart_config_s esp_zigbee_uart_config_t

The uart port config for Zigbee.

typedef struct esp_zigbee_radio_config_s esp_zigbee_radio_config_t

Zigbee radio configuration.

typedef struct esp_zigbee_platform_config_s esp_zigbee_platform_config_t

Zigbee platform configuration.

typedef struct esp_zigbee_device_config_s esp_zigbee_device_config_t

The Zigbee device configuration.

typedef struct esp_zigbee_config_s esp_zigbee_config_t

The Zigbee configuration.

typedef void (*esp_zigbee_callback_t)(void *ctx)

The ESP-Zigbee callback type.

Param ctx:

[in] The context to be passed to the callback.

5.1.1.5. Enumerations

enum esp_zigbee_radio_mode_t

Enumeration of Zigbee radio mode.

Values:

enumerator ESP_ZIGBEE_RADIO_MODE_NATIVE

Use the native 15.4 radio

enumerator ESP_ZIGBEE_RADIO_MODE_UART_RCP

UART connection to a 15.4 capable radio co-processor (RCP)

enumerator ESP_ZIGBEE_RADIO_MODE_MAX_NR

Using for parameter check

5.1.1.6. Header File

5.1.1.7. Functions

const char *esp_zigbee_get_version_string(void)

Get the version string of the SDK.

Returns:

The version string of the SDK.

5.1.1.8. Macros

ESP_ZIGBEE_VER_MAJOR

The major version of the SDK.

ESP_ZIGBEE_VER_MINOR

The minor version of the SDK.

ESP_ZIGBEE_VER_PATCH

The patch version of the SDK.