ZDO Command API
Zigbee Device Object (ZDO) commands related APIs for ESP Zigbee SDK.
API Reference
Header File
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 spent scanning each channel, in units of ((1 << scan_duration) + 1) * a beacon time.
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_energy_detect_request(uint32_t channel_mask, uint8_t duration, esp_zb_zdo_energy_detect_callback_t cb)
Energy detect request.
- Parameters
channel_mask – [in] The channel mask that will trigger the energy detection, with a range from 0x00000800 to 0x07FFF800.
duration – [in] The detection duration on each channel, in units of ((1 << scan_duration) + 1) * a beacon time.
cb – [in] A user callback to receive the energy detection result, see esp_zb_zdo_energy_detect_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
-
esp_zb_ieee_addr_t src_address
-
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.
-
uint16_t dst_nwk_addr
-
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
-
uint16_t dst_nwk_addr
-
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.
-
uint16_t dst_nwk_addr
-
struct esp_zb_zdo_simple_desc_req_param_s
The Zigbee ZDO simple descriptor command struct.
-
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
-
uint16_t addr_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
-
uint16_t dst_nwk_addr
-
struct esp_zb_zdo_mgmt_leave_req_param_s
The Zigbee ZDO leave command struct.
-
struct esp_zb_zdo_mgmt_bind_param_s
The Zigbee ZDO binding table request struct.
-
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
-
esp_zb_ieee_addr_t src_address
-
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
-
uint8_t status
-
struct esp_zb_network_descriptor_s
Struture of network descriptor request of active scan response.
Public Members
-
uint16_t short_pan_id
PAN id
-
bool permit_joining
Indicates that at least one router / coordinator on the network currently permits joining
-
esp_zb_ieee_addr_t extended_pan_id
Extended PAN id, the MAC address which forms the network
-
uint8_t logic_channel
The current logical channel occupied by the network.
-
bool router_capacity
This value is set to true if the device is capable of accepting join requests from router-capable devices and set to FALSE otherwise.
-
bool end_device_capacity
This value is set to true if the device is capable of accepting join requests from end devices and set to FALSE otherwise.
-
uint16_t short_pan_id
-
struct esp_zb_energy_detect_channel_info_s
Channel information of Energy Detect.
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_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 struct esp_zb_network_descriptor_s esp_zb_network_descriptor_t
Struture of network descriptor request of active scan response.
-
typedef struct esp_zb_energy_detect_channel_info_s esp_zb_energy_detect_channel_info_t
Channel information of Energy Detect.
-
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_t
- Param count
[in] Number of discovered networks
nwk_descriptor
- Param nwk_descriptor
[in] The pointer to all discovered networks see refer to esp_zb_network_descriptor_t
-
typedef void (*esp_zb_zdo_energy_detect_callback_t)(esp_zb_zdp_status_t status, uint16_t count, esp_zb_energy_detect_channel_info_t *channel_info)
ZDO energy detect callback.
- Param status
[in] The status of callback, refer to esp_zb_zdp_status_t
- Param count
[in] The size of energy detect list
- Param ed_list
[in] The list of energy detect information, refer to esp_zb_energy_detect_channel_info_t
-
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()