ZDO Command API

Zigbee Device Object (ZDO) commands related APIs for ESP Zigbee SDK.

API Reference

Header File

components/esp-zigbee-lib/include/zdo/esp_zigbee_zdo_command.h

Functions

void esp_zb_zdo_active_scan_request(uint32_t channel_mask, uint8_t scan_duration, esp_zb_zdo_scan_complete_callback_t user_cb)

Active scan available network.

Network discovery service for scanning available network

Parameters

channel_mask – [in] Valid channel mask is from 0x00000800 (only channel 11) to 0x07FFF800 (all channels from 11 to 26)
scan_duration – [in] Time to spend scanning each channel
user_cb – [in] A user callback to get the active scan result please refer to esp_zb_zdo_scan_complete_callback_t

void esp_zb_zdo_device_bind_req(esp_zb_zdo_bind_req_param_t *cmd_req, esp_zb_zdo_bind_callback_t user_cb, void *user_ctx)

Send bind device request command.

Parameters

cmd_req – [in] Pointer to the bind request command esp_zb_zdo_bind_req_param_s
user_cb – [in] A user callback that will be called if received bind response refer to esp_zb_zdo_bind_callback_t
user_ctx – [in] A void pointer that contains the user defines additional information when callback trigger

void esp_zb_zdo_device_unbind_req(esp_zb_zdo_bind_req_param_t *cmd_req, esp_zb_zdo_bind_callback_t user_cb, void *user_ctx)

Send unbind device request command.

Parameters

cmd_req – [in] Pointer to the bind request command esp_zb_zdo_bind_req_param_s
user_cb – [in] A user callback that will be called if received bind response refer to esp_zb_zdo_bind_callback_t
user_ctx – [in] A void pointer that contains the user defines additional information when callback trigger

void esp_zb_zdo_find_on_off_light(esp_zb_zdo_match_desc_req_param_t *cmd_req, esp_zb_zdo_match_desc_callback_t user_cb, void *user_ctx)

Send find on-off device request command.

Parameters

cmd_req – [in] Pointer to the find request command esp_zb_zdo_match_desc_req_param_s
user_cb – [in] A user callback that will be called if received find response refer to esp_zb_zdo_match_desc_callback_t
user_ctx – [in] A void pointer that contains the user defines additional information when callback trigger

void esp_zb_zdo_find_color_dimmable_light(esp_zb_zdo_match_desc_req_param_t *cmd_req, esp_zb_zdo_match_desc_callback_t user_cb, void *user_ctx)

Send find color_dimmable device request command.

Parameters

cmd_req – [in] Pointer to the find request command esp_zb_zdo_match_desc_req_param_s
user_cb – [in] A user callback that will be called if received find response refer to esp_zb_zdo_match_desc_callback_t
user_ctx – [in] A void pointer that contains the user defines additional information when callback trigger

esp_err_t esp_zb_zdo_match_cluster(esp_zb_zdo_match_desc_req_param_t *param, esp_zb_zdo_match_desc_callback_t user_cb, void *user_ctx)

Send match desc request to find matched Zigbee device.

Parameters

param – [in] Pointer to esp_zb_zdo_match_desc_req_param_s that will be used to match device
user_cb – [in] A user callback that will be called if received find response refer to esp_zb_zdo_match_desc_callback_t
user_ctx – [in] A void pointer that contains the user defines additional information when callback trigger

Returns

ESP_OK: Success in send match desc request
ESP_ERR_NO_MEM: Failed to allocate the memory for the reqeust
ESP_ERR_INVALID_SIZE: The size of cluster list is wrong in param

void esp_zb_zdo_ieee_addr_req(esp_zb_zdo_ieee_addr_req_param_t *cmd_req, esp_zb_zdo_ieee_addr_callback_t user_cb, void *user_ctx)

Send ieee request command.

Parameters

cmd_req – [in] Pointer to the ieee address request command esp_zb_zdo_ieee_addr_req_param_s
user_cb – [in] A user callback that will be called if received ieee address response refer to esp_zb_zdo_ieee_addr_callback_t
user_ctx – [in] A void pointer that contains the user defines additional information when callback trigger

void esp_zb_zdo_node_desc_req(esp_zb_zdo_node_desc_req_param_t *cmd_req, esp_zb_zdo_node_desc_callback_t user_cb, void *user_ctx)

Send node descriptor request command.

Parameters

cmd_req – [in] Pointer to the node descriptor request command esp_zb_zdo_node_desc_req_param_s
user_cb – [in] A user callback that will be called if received node desc response refer to esp_zb_zdo_node_desc_callback_t
user_ctx – [in] A void pointer that contains the user defines additional information when callback trigger

void esp_zb_zdo_simple_desc_req(esp_zb_zdo_simple_desc_req_param_t *cmd_req, esp_zb_zdo_simple_desc_callback_t user_cb, void *user_ctx)

Send simple descriptor request command.

Parameters

cmd_req – [in] Pointer to the simple descriptor request command esp_zb_zdo_simple_desc_req_param_s
user_cb – [in] A user callback that will be called if received simple desc response refer to esp_zb_zdo_simple_desc_callback_t
user_ctx – [in] A void pointer that contains the user defines additional information when callback trigger

void esp_zb_zdo_active_ep_req(esp_zb_zdo_active_ep_req_param_t *cmd_req, esp_zb_zdo_active_ep_callback_t user_cb, void *user_ctx)

Send active endpoint request command.

Parameters

cmd_req – [in] Pointer to the active endpoint request command esp_zb_zdo_active_ep_req_param_s
user_cb – [in] A user callback that will be called if received active ep response refer to esp_zb_zdo_active_ep_callback_t
user_ctx – [in] A void pointer that contains the user defines additional information when callback trigger

void esp_zb_zdo_device_leave_req(esp_zb_zdo_mgmt_leave_req_param_t *cmd_req, esp_zb_zdo_leave_callback_t user_cb, void *user_ctx)

Send leave request command.

Parameters

cmd_req – [in] Pointer to the leave request command esp_zb_zdo_mgmt_leave_req_param_s
user_cb – [in] A user callback that will be called if received leave response refer to esp_zb_zdo_leave_callback_t
user_ctx – [in] A void pointer that contains the user defines additional information when callback trigger

void esp_zb_zdo_permit_joining_req(esp_zb_zdo_permit_joining_req_param_t *cmd_req, esp_zb_zdo_permit_join_callback_t user_cb, void *user_ctx)

Send permit join request command.

Parameters

cmd_req – [in] Pointer to the permit join request command esp_zb_zdo_permit_joining_req_param_s
user_cb – [in] A user callback that will be called if received permit join response refer to esp_zb_zdo_permit_join_callback_t
user_ctx – [in] A void pointer that contains the user defines additional information when callback trigger

void esp_zb_zdo_binding_table_req(esp_zb_zdo_mgmt_bind_param_t *cmd_req, esp_zb_zdo_binding_table_callback_t user_cb, void *user_ctx)

Send binding table request command.

Parameters

cmd_req – [in] Pointer to the zdo mgmt bind request command esp_zb_zdo_mgmt_bind_param_s
user_cb – [in] A user callback that will be called if received binding table response refer to esp_zb_zdo_binding_table_callback_t
user_ctx – [in] A void pointer that contains the user defines additional information when callback trigger

void esp_zb_zdo_device_announcement_req(void): Send device announcement command.

const char *esp_zb_zdo_signal_to_string(esp_zb_app_signal_type_t signal)

Stringify the Zigbee Device Object signal.

Parameters: signal – [in] A esp_zb_app_signal_type_t object that expect to stringified
Returns: A string pointer of esp_zb_app_signal_type_t

Structures

struct esp_zb_zdo_bind_req_param_s

The Zigbee ZDO bind command struct.

Note

Current implementation of the API ONLY supports 64 bit extended address’s address mode. Other address mode will support later.

Note

Be aware of the one req_dst_addr is address that command send to, while dst_address is the destination of the binding entry.

Note

NOW the dst_addr_mode is default by ZB_BIND_DST_ADDR_MODE_64_BIT_EXTENDED. Later SDK will support other address mode.

Public Members

esp_zb_ieee_addr_t src_address: The IEEE address for the source

uint8_t src_endp: The source endpoint for the binding entry

uint16_t cluster_id: The identifier of the cluster on the source device that is bound to the destination

uint8_t dst_addr_mode: The destination address mode ref to esp_zb_zdo_bind_dst_addr_mode_t

esp_zb_addr_u dst_address_u: The destination address for the binding entry

uint8_t dst_endp: This field shall be present only if the DstAddrMode field has a value of refer to ZB_BIND_DST_ADDR_MODE_64_BIT_EXTENDED refer to bind_dst_addr_mode and, if present, shall be the destination endpoint for the binding entry.

uint16_t req_dst_addr: Destination address of the request send to

struct esp_zb_zdo_match_desc_req_param_s

The Zigbee ZDO match descrpitor command struct.

Public Members

uint16_t dst_nwk_addr: NWK address that request sent to

uint16_t addr_of_interest: NWK address of interest

uint16_t profile_id: Profile ID to be match at the destination which refers to esp_zb_af_profile_id_t

uint8_t num_in_clusters: The number of input clusters provided for matching cluster server

uint8_t num_out_clusters: The number of output clusters provided for matching cluster client

uint16_t *cluster_list: The pointer MUST point the uint16_t object with a size equal to num_in_clusters + num_out_clusters, which will be used to match device.

struct esp_zb_zdo_ieee_addr_req_param_s

The Zigbee ZDO ieee request command struct.

Public Members

uint16_t dst_nwk_addr: NWK address that request sent to

uint16_t addr_of_interest: NWK address of interest

uint8_t request_type: Request type for this command: 0x00 Single device response 0x01 Extended response

uint8_t start_index: If the Request type for this command is Extended response, the StartIndex provides the starting index for the requested elements of the associated devices list

struct esp_zb_zdo_node_desc_req_param_s

The Zigbee ZDO node descriptor command struct.

Public Members

uint16_t dst_nwk_addr: NWK address that is used for IEEE address mapping.

struct esp_zb_zdo_simple_desc_req_param_s

The Zigbee ZDO simple descriptor command struct.

Public Members

uint16_t addr_of_interest: NWK address of interest

uint8_t endpoint: Endpoint of interest

struct esp_zb_zdo_active_ep_req_param_s

The Zigbee ZDO active endpoint command struct.

Public Members

uint16_t addr_of_interest: NWK address of interest

struct esp_zb_zdo_permit_joining_req_param_s

The Zigbee ZDO permit join command struct.

Public Members

uint16_t dst_nwk_addr: NWK address that request sent to

uint8_t permit_duration: The length of time in seconds. 0x00 and 0xff indicate that permission is disabled or enabled

uint8_t tc_significance: If this is set to 0x01 and the remote device is the Trust Center, the command affects the Trust Center authentication policy as described in the sub-clauses below; If this is set to 0x00, there is no effect on the Trust Center

struct esp_zb_zdo_mgmt_leave_req_param_s

The Zigbee ZDO leave command struct.

Public Members

esp_zb_ieee_addr_t device_address: 64-bit IEEE address on device

uint16_t dst_nwk_addr: NWK address that request sent to

unsigned int reserved: Reserved

unsigned int remove_children: Bitfield of remove children or not

unsigned int rejoin: Bitfield of rejoin or not

struct esp_zb_zdo_mgmt_bind_param_s

The Zigbee ZDO binding table request struct.

Public Members

uint8_t start_index: The starting index for the requested elements of the Binding Table

uint16_t dst_addr: The destination address

struct esp_zb_zdo_binding_table_record_s

The Zigbee ZDO binding table record struct.

Public Members

esp_zb_ieee_addr_t src_address: The source IEEE address for the binding entry.

uint8_t src_endp: The source endpoint for the binding entry.

uint16_t cluster_id: The identifier of the cluster on the source device that is bound to the destination device.

uint8_t dst_addr_mode: Destination address mode esp_zb_zdo_bind_dst_addr_mode_t

esp_zb_addr_u dst_address: The destination address for the binding entry.16 or 64 bit. As specified by the dst_addr_mode field.

uint8_t dst_endp: The destination endpoint for binding entry, this field shall be present only if the DstAddrMode field has a value of 0x03 refer to esp_zb_zdo_bind_dst_addr_mode_t

struct esp_zb_zdo_binding_table_record_s *next: The next binding table record

struct esp_zb_zdo_binding_table_info_s

The Zigbee ZDO binding table information struct for users.

Public Members

uint8_t status: The status of binding table information refer to esp_zb_zdp_status

uint8_t index: The index of binding table record

uint8_t total: The total number of records in the binding table for requests

uint8_t count: The number of binding table records in the response

esp_zb_zdo_binding_table_record_t *record: The binding table record list

Macros

ESP_ZB_MATCH_DESC_REQ_TIMEOUT

ESP_ZB_MATCH_DESC_REQ_ROLE

ESP_ZB_IEEE_ADDR_REQ_TIMEOUT

ESP_ZB_NODE_DESC_REQ_TIMEOUT

ESP_ZB_BIND_DEVICE_REQ_TIMEOUT

ESP_ZB_ACTIVE_EP_REQ_TIMEOUT

ESP_ZB_SIMPLE_DESC_REQ_TIMEOUT

ESP_ZB_PERMIT_JOIN_REQ_TIMEOUT

ESP_ZB_DEVICE_LEAVE_REQ_TIMEOUT

ESP_ZB_DEVICE_BIND_TABLE_REQ_TIMEOUT

Type Definitions

typedef void (*esp_zb_zdo_scan_complete_callback_t)(esp_zb_zdp_status_t zdo_status, uint8_t count, esp_zb_network_descriptor_t *nwk_descriptor)

A ZDO active scan request callback for user to get scan list status.

Active scan network callback

Note

User’s callback get response from the device that found in network.

Param zdo_status: [in] The ZDO response status, refer to esp_zb_zdp_status
Param count: [in] Number of discovered networks
Param nwk_descriptor: [in] The pointer to all discvoered networks see refer to esp_zb_network_descriptor_t

typedef void (*esp_zb_zdo_match_desc_callback_t)(esp_zb_zdp_status_t zdo_status, uint16_t addr, uint8_t endpoint, void *user_ctx)

A ZDO match desc request callback for user to get response info.

Find device callback

Note

User’s callback get response from the remote device that local node wants to find a particular device on endpoint.

Param zdo_status: [in] The ZDO response status, refer to esp_zb_zdp_status
Param addr: [in] A short address of the device response, 0xFFFF - invalid address
Param endpoint: [in] An endpoint of the device response, 0xFF - invalid endpoint
Param user_ctx: [in] User information context, set in esp_zb_zdo_find_xxx()

typedef void (*esp_zb_zdo_ieee_addr_callback_t)(esp_zb_zdp_status_t zdo_status, esp_zb_ieee_addr_t ieee_addr, void *user_ctx)

A ZDO ieee address request callback for user to get response info.

IEEE address request callback

Note

User’s callback get response from the remote device that local node wants to get ieee address.

Param zdo_status: [in] The ZDO response status, refer to esp_zb_zdp_status
Param ieee_addr: [in] A ieee address of the device response, 0xFFFF FFFF FFFF FFFF - invalid ieee address
Param user_ctx: [in] User information context, set in esp_zb_zdo_ieee_addr_req()

typedef void (*esp_zb_zdo_node_desc_callback_t)(esp_zb_zdp_status_t zdo_status, uint16_t addr, esp_zb_af_node_desc_t *node_desc, void *user_ctx)

A ZDO Node descriptor request callback for user to get node desc info.

Node descriptor callback

Note

User’s callback get response from the remote device that local node wants to get node descriptor response.

Param zdo_status: [in] The ZDO response status, refer to esp_zb_zdp_status
Param addr: [in] A short address of the device response, 0xFFFF - invalid address
Param node_desc: [in] A pointer to the node desc esp_zb_af_node_desc_s
Param user_ctx: [in] User information context, set in esp_zb_zdo_node_desc_req()

typedef void (*esp_zb_zdo_bind_callback_t)(esp_zb_zdp_status_t zdo_status, void *user_ctx)

A ZDO bind request callback for user to get response info.

Bind request callback

Note

user’s callback get response from the remote device that local node wants to bind.

Param zdo_status: [in] The ZDO response status, refer to esp_zb_zdp_status
Param user_ctx: [in] User information context, set in esp_zb_zdo_device_bind_req()

typedef void (*esp_zb_zdo_active_ep_callback_t)(esp_zb_zdp_status_t zdo_status, uint8_t ep_count, uint8_t *ep_id_list, void *user_ctx)

A ZDO active endpoint request callback for user to get response info.

Active endpoint callback

Note

User’s callback get response from the remote device that local node wants to get active endpoint.

Param zdo_status: [in] The ZDO response status, refer to esp_zb_zdp_status
Param ep_count: [in] A number of active endpoint
Param ep_id_list: [in] A pointer of the endpoint id list
Param user_ctx: [in] User information context, set in esp_zb_zdo_active_ep_req()

typedef void (*esp_zb_zdo_simple_desc_callback_t)(esp_zb_zdp_status_t zdo_status, esp_zb_af_simple_desc_1_1_t *simple_desc, void *user_ctx)

A ZDO simple descriptor request callback for user to get simple desc info.

Simple descriptor callback

Note

User’s callback get response from the remote device that local node wants to get simple desc.

Param zdo_status: [in] The ZDO response status, refer to esp_zb_zdp_status
Param simple_desc: [in] A pointer to the simple desc esp_zb_af_simple_desc_1_1_s
Param user_ctx: [in] User information context, set in esp_zb_zdo_simple_desc_req()

typedef void (*esp_zb_zdo_permit_join_callback_t)(esp_zb_zdp_status_t zdo_status, void *user_ctx)

A ZDO permit join request callback for user to get permit join response info.

Permit join request callback

Note

User’s callback get response from the node requested to permit join.

Param zdo_status: [in] The ZDO response status, refer to esp_zb_zdp_status
Param user_ctx: [in] User information context, set in esp_zb_zdo_permit_joining_req()

typedef void (*esp_zb_zdo_leave_callback_t)(esp_zb_zdp_status_t zdo_status, void *user_ctx)

A ZDO leave request callback for user to get leave status.

Leave request callback

Note

User’s callback get response from the device that wants to leave.

Param zdo_status: [in] The ZDO response status, refer to esp_zb_zdp_status
Param user_ctx: [in] User information context, set in esp_zb_zdo_device_leave_req()

typedef struct esp_zb_zdo_bind_req_param_s esp_zb_zdo_bind_req_param_t: The Zigbee ZDO bind command struct.

Note

Current implementation of the API ONLY supports 64 bit extended address’s address mode. Other address mode will support later.

Note

Be aware of the one req_dst_addr is address that command send to, while dst_address is the destination of the binding entry.

Note

NOW the dst_addr_mode is default by ZB_BIND_DST_ADDR_MODE_64_BIT_EXTENDED. Later SDK will support other address mode.

typedef struct esp_zb_zdo_match_desc_req_param_s esp_zb_zdo_match_desc_req_param_t: The Zigbee ZDO match descrpitor command struct.

typedef struct esp_zb_zdo_ieee_addr_req_param_s esp_zb_zdo_ieee_addr_req_param_t: The Zigbee ZDO ieee request command struct.

typedef struct esp_zb_zdo_node_desc_req_param_s esp_zb_zdo_node_desc_req_param_t: The Zigbee ZDO node descriptor command struct.

typedef struct esp_zb_zdo_simple_desc_req_param_s esp_zb_zdo_simple_desc_req_param_t: The Zigbee ZDO simple descriptor command struct.

typedef struct esp_zb_zdo_active_ep_req_param_s esp_zb_zdo_active_ep_req_param_t: The Zigbee ZDO active endpoint command struct.

typedef struct esp_zb_zdo_permit_joining_req_param_s esp_zb_zdo_permit_joining_req_param_t: The Zigbee ZDO permit join command struct.

typedef struct esp_zb_zdo_mgmt_leave_req_param_s esp_zb_zdo_mgmt_leave_req_param_t: The Zigbee ZDO leave command struct.

typedef struct esp_zb_zdo_mgmt_bind_param_s esp_zb_zdo_mgmt_bind_param_t: The Zigbee ZDO binding table request struct.

typedef struct esp_zb_zdo_binding_table_record_s esp_zb_zdo_binding_table_record_t: The Zigbee ZDO binding table record struct.

typedef struct esp_zb_zdo_binding_table_info_s esp_zb_zdo_binding_table_info_t: The Zigbee ZDO binding table information struct for users.

typedef void (*esp_zb_zdo_binding_table_callback_t)(const esp_zb_zdo_binding_table_info_t *table_info, void *user_ctx)

A ZDO binding table request callback for user to get the binding table record of remote device.

Binding table request callback

Param table_info: [in] The binding table record which is only accessed by read, refer to esp_zb_zdo_binding_table_info_s
Param user_ctx: [in] User information context, set in esp_zb_zdo_binding_table_req()