|
Tizen Native API
5.0
|
Zigbee provides API for Device Discovery.
#include <zigbee.h>
The Zigbee Device Profile (ZDP) contains a set of commands for discovering various aspects about nodes in the network. The Zigbee specification calls these "device discovery services," which can be confusing because endpoints contain device IDs which really describe individual Zigbee applications running in that node. So, when you see ZDP Device Discovery, think node-wide (not application/endpoint specific) services.
Device discovery services have a few things in common:
The ZDP device discovery services are listed below in the section. Notice that all the ZDP services on the client side are optional. Zigbee does not require that a node be able to send NWK_addr_req , for example. But on the server side of this equation (a node receiving a NWK_addr_req and responding to it), the ZDP service is mandatory.
Functions | |
| int | zb_zdo_nwk_addr_req (zb_zigbee_h handle, zb_ieee_addr addr64, zb_zdp_req_type_e request_type, unsigned char start_idx, zb_zdo_addr_cb cb, void *user_data) |
| Sends 'Network address request' command. | |
| int | zb_zdo_ieee_addr_req (zb_zigbee_h handle, zb_nwk_addr addr16, zb_zdo_addr_cb cb, void *user_data) |
| Sends 'IEEE address request' command. | |
| int | zb_zdo_active_ep (zb_zigbee_h handle, zb_nwk_addr addr16, zb_zdo_active_ep_cb cb, void *user_data) |
| Sends 'active end-point request' command. | |
| int | zb_zdo_simple_desc_req (zb_zigbee_h handle, zb_nwk_addr addr16, zb_end_point ep, zb_zdo_simple_desc_cb cb, void *user_data) |
| Sends 'simple descriptor request' command. | |
Typedefs | |
| typedef void * | zb_zdo_simple_desc_h |
| The handle of zigbee simple description. | |
| typedef void(* | zb_zdo_addr_cb )(zb_zdp_status_e status, zb_ieee_addr remote_dev_addr64, zb_nwk_addr remote_dev_addr16, unsigned char assoc_dev_len, unsigned char start_idx, zb_device_id *assoc_dev_addr_list, void *user_data) |
| Called after Network / IEEE address request. | |
| typedef void(* | zb_zdo_active_ep_cb )(zb_zdp_status_e status, zb_nwk_addr addr16, unsigned char count, zb_end_point *ep_list, void *user_data) |
| Called after active endpoint request command. | |
| typedef void(* | zb_zdo_simple_desc_cb )(zb_nwk_addr addr16, unsigned char len, const zb_zdo_simple_desc_h desc, void *user_data) |
| Called after 'simple descriptor request' command. | |
| typedef void(* zb_zdo_active_ep_cb)(zb_zdp_status_e status, zb_nwk_addr addr16, unsigned char count, zb_end_point *ep_list, void *user_data) |
Called after active endpoint request command.
The Active_EP_cb is generated by a remote device in response to an Active_EP_req directed to the remote device. This command shall be unicast to the originator of the Active_EP_req command.
The remote device shall generate the Active_EP_cb command using the format illustrated param list.
The NWKAddrOfInterest field shall match that specified in the original Active_EP_req command.
If the NWKAddrOfInterest field matches the network address of the remote device, it shall set the Status field to ZB_ZDP_STATUS_SUCCESS, set the ActiveEPCount field to the number of active endpoints on that device and include an ascending list of all the identifiers of the active endpoints on that device in the ActiveEPList field.
If the NWKAddrOfInterest field does not match the network address of the remote device and it is an end device, it shall set the Status field to ZB_ZDP_STATUS_INVALID_REQUEST_TYPE, set the ActiveEPCount field to 0, and not include the ActiveEPList field.
If the NWKAddrOfInterest field does not match the network address of the remote device and it is the coordinator or a router, it shall determine whether the NWKAddrOfInterest field matches the network address of a device it holds in a discovery cache.
If the NWKAddrOfInterest field does not match the network address of a device it holds in a discovery cache, it shall set the Status field to ZB_ZDP_STATUS_DEVICE_NOT_FOUND, set the ActiveEPCount field to 0, and not include the ActiveEPList field.
If the NWKAddrOfInterest matches the network address of a device held in a discovery cache on the remote device, it shall determine whether that device has any active endpoints.
If the discovery information corresponding to the ActiveEP request has not yet been uploaded to the discovery cache, the remote device shall set the Status field to ZB_ZDP_STATUS_NO_DESCRIPTOR, set the ActiveEPCount field to 0 and not include the ActiveEPList field.
If the cached device has no active endpoints, the remote device shall set the Status field to ZB_ZDP_STATUS_SUCCESS, set the ActiveEPCount field to 0, and not include the ActiveEPList field.
If the cached device has active endpoints, the remote device shall set the Status field to ZB_ZDP_STATUS_SUCCESS, set the ActiveEPCount field to the number of active endpoints on that device, and include an ascending list of all the identifiers of the active endpoints on that device in the ActiveEPList field .
| [out] | status | ZB_ZDP_STATUS_SUCCESS ZB_ZDP_STATUS_INVALID_REQUEST_TYPE ZB_ZDP_STATUS_DEVICE_NOT_FOUND ZB_ZDP_STATUS_NO_DESCRIPTOR |
| [out] | addr16 | Network address for the request |
| [out] | count | The count of active endpoints on the remote device |
| [out] | ep_list | List of bytes each of which represents an 8-bit endpoints |
| [out] | user_data | user data |
| typedef void(* zb_zdo_addr_cb)(zb_zdp_status_e status, zb_ieee_addr remote_dev_addr64, zb_nwk_addr remote_dev_addr16, unsigned char assoc_dev_len, unsigned char start_idx, zb_device_id *assoc_dev_addr_list, void *user_data) |
Called after Network / IEEE address request.
The NWK_addr_cb is generated by a Remote Device in response to a NWK_addr_req or IEEE_addr_req command inquiring as to the NWK address of the Remote Device or the NWK address of an address held in a local discovery cache. The destination addressing on this command is unicast.
| [out] | status | ZB_ZDP_STATUS_SUCCESS ZB_ZDP_STATUS_INVALID_REQUEST_TYPE ZB_ZDP_STATUS_DEVICE_NOT_FOUND |
| [out] | remote_dev_addr64 | 64-bit address for the remote device |
| [out] | remote_dev_addr16 | 16-bit address for the remote device |
| [out] | assoc_dev_len | The number of items in the 16-bit short addresses assoc_dev_addr_list. If the RequestType in the request is Extended Response and there are no associated devices on the Remote Device, this field shall be set to 0. If an error occurs or the RequestType in the request is for a Single Device Response, this field shall not be included. |
| [out] | start_idx | Starting index into the list of associated devices for this report. If the RequestType in the request is Extended Response and there are no associated devices on the Remote Device, this field shall not be included in the Zigbee data frame. If an error occurs or the RequestType in the request is for a Single Device Response, this field shall not be included. |
| [out] | assoc_dev_addr_list | A list of 16-bit addresses, one corresponding to each associated device to Remote Device; The number of 16-bit network addresses contained in this field is specified in the NumAssocDev field. If the RequestType in the request is Extended Response and there are no associated devices on the Remote Device, this field shall not be included in the Zigbee data frame. If an error occurs or the RequestType in the request is for a Single Device Response, this field shall not be included. |
| [out] | user_data | user data |
| typedef void(* zb_zdo_simple_desc_cb)(zb_nwk_addr addr16, unsigned char len, const zb_zdo_simple_desc_h desc, void *user_data) |
Called after 'simple descriptor request' command.
The Simple_Desc_cb is generated by a remote device in response to a Simple_Desc_req directed to the remote device. This command shall be unicast to the originator of the Simple_Desc_req command. The remote device shall generate the Simple_Desc_cb command using the format illustrated in Table 2.94 in Zigbee Specification. The NWKAddrOfInterest field shall match that specified in the original Simple_Desc_req command. If the endpoint field specified in the original Simple_Desc_req command does not fall within the correct range specified in param list, the remote device shall set the Status field to ZB_ZDP_STATUS_INVALID_EP, set the Length field to 0 and not include the SimpleDescriptor field.
If the NWKAddrOfInterest field matches the network address of the remote device, it shall determine whether the endpoint field specifies the identifier of an active endpoint on the device. If the endpoint field corresponds to an active endpoint, the remote device shall set the Status field to ZB_ZDP_STATUS_SUCCESS, set the Length field to the length of the simple descriptor on that endpoint, and include the simple descriptor for that endpoint in the SimpleDescriptor field. If the endpoint field does not correspond to an active endpoint, the remote device shall set the Status field to ZB_ZDP_STATUS_NOT_ACTIVE, set the Length field to 0, and not include the SimpleDescriptor field.
If the NWKAddrOfInterest field does not match the network address of the remote device and it is an end device, it shall set the Status field to ZB_ZDP_STATUS_INVALID_REQUEST_TYPE, set the Length field to 0, and not include the SimpleDescriptor field. If the NWKAddrOfInterest field does not match the network address of the remote device and it is the coordinator or a router, it shall determine whether the NWKAddrOfInterest field matches the network address of one of its children. If the NWKAddrOfInterest field does not match the network address of one of the children of the remote device, it shall set the Status field to ZB_ZDP_STATUS_DEVICE_NOT_FOUND, set the Length field to 0, and not include the SimpleDescriptor field.
If the NWKAddrOfInterest matches the network address of one of the children of the remote device, it shall determine whether a simple descriptor for that device and on the requested endpoint is available. If a simple descriptor is not available on the requested endpoint of the child indicated by the NWKAddrOfInterest field, the remote device shall set the Status field to ZB_ZDP_STATUS_NO_DESCRIPTOR, set the Length field to 0, and not include the SimpleDescriptor field. If a simple descriptor is available on the requested endpoint of the child indicated by the NWKAddrOfInterest field, the remote device shall set the Status field to ZB_ZDP_STATUS_SUCCESS, set the Length field to the length of the simple descriptor on that endpoint, and include the simple descriptor for that endpoint of the matching child device in the SimpleDescriptor field.
The desc can be used only in the callback. To use outside, make a copy using zb_simple_desc_clone().
| [out] | addr16 | Network address for the request |
| [out] | len | Length in bytes of the simple descriptor to follow |
| [out] | desc | Simple descriptor structure this filed shall only be included if the status field is equal to ZB_ZDP_STATUS_SUCCESS |
| [out] | user_data | user data |
| typedef void* zb_zdo_simple_desc_h |
The handle of zigbee simple description.
Device descriptions contained in node.
| int zb_zdo_active_ep | ( | zb_zigbee_h | handle, |
| zb_nwk_addr | addr16, | ||
| zb_zdo_active_ep_cb | cb, | ||
| void * | user_data | ||
| ) |
Sends 'active end-point request' command.
The Active_EP_req command is generated from a local device wishing to acquire the list of endpoints on a remote device with simple descriptors. This command shall be unicast either to the remote device itself or to an alternative device that contains the discovery information of the remote device.
The local device shall generate the Active_EP_req command using the format illustrated in param list. The NWKAddrOfInterest field shall contain the network address of the remote device for which the active endpoint list is required.
| [in] | handle | The handle of zigbee |
| [in] | addr16 | Network address for device of interest |
| [in] | cb | Response callback |
| [in] | user_data | user data |
| ZIGBEE_ERROR_NONE | Successful |
| ZIGBEE_ERROR_INVALID_PARAMETER | Invalid parameter |
| ZIGBEE_ERROR_OUT_OF_MEMORY | Out-of-memory |
| ZIGBEE_ERROR_IO_ERROR | Unexpected d-bus error |
| ZIGBEE_ERROR_PERMISSION_DENIED | Permission denied |
| ZIGBEE_ERROR_NOT_SUPPORTED | Not supported |
| int zb_zdo_ieee_addr_req | ( | zb_zigbee_h | handle, |
| zb_nwk_addr | addr16, | ||
| zb_zdo_addr_cb | cb, | ||
| void * | user_data | ||
| ) |
Sends 'IEEE address request' command.
The IEEE_addr_req is generated from a Local Device wishing to inquire as to the 64-bit IEEE address of the Remote Device based on their known 16-bit address. The destination addressing on this command shall be unicast.
| [in] | handle | The handle of zigbee |
| [in] | addr16 | Network address for device of interest |
| [in] | cb | Response callback |
| [in] | user_data | user data |
| ZIGBEE_ERROR_NONE | Successful |
| ZIGBEE_ERROR_INVALID_PARAMETER | Invalid parameter |
| ZIGBEE_ERROR_OUT_OF_MEMORY | Out-of-memory |
| ZIGBEE_ERROR_IO_ERROR | Unexpected d-bus error |
| ZIGBEE_ERROR_PERMISSION_DENIED | Permission denied |
| ZIGBEE_ERROR_NOT_SUPPORTED | Not supported |
| int zb_zdo_nwk_addr_req | ( | zb_zigbee_h | handle, |
| zb_ieee_addr | addr64, | ||
| zb_zdp_req_type_e | request_type, | ||
| unsigned char | start_idx, | ||
| zb_zdo_addr_cb | cb, | ||
| void * | user_data | ||
| ) |
Sends 'Network address request' command.
The NWK_addr_req is generated from a Local Device wishing to inquire as to the 16-bit address of the Remote Device based on its known IEEE address. The destination addressing on this command shall be unicast or broadcast to all devices for which macRxOnWhenIdle = TRUE.
| [in] | handle | The handle of zigbee |
| [in] | addr64 | IEEE address for device of interest |
| [in] | request_type | 0x00 - Single device response 0x01 - Extended response |
| [in] | start_idx | If the Request type for this command is Extended response, is StartIndex provides the starting index for the requested elements of the associated devices list |
| [in] | cb | Response callback |
| [in] | user_data | user data |
| ZIGBEE_ERROR_NONE | Successful |
| ZIGBEE_ERROR_INVALID_PARAMETER | Invalid parameter |
| ZIGBEE_ERROR_OUT_OF_MEMORY | Out-of-memory |
| ZIGBEE_ERROR_IO_ERROR | Unexpected d-bus error |
| ZIGBEE_ERROR_PERMISSION_DENIED | Permission denied |
| ZIGBEE_ERROR_NOT_SUPPORTED | Not supported |
| int zb_zdo_simple_desc_req | ( | zb_zigbee_h | handle, |
| zb_nwk_addr | addr16, | ||
| zb_end_point | ep, | ||
| zb_zdo_simple_desc_cb | cb, | ||
| void * | user_data | ||
| ) |
Sends 'simple descriptor request' command.
The Simple_Desc_req command is generated from a local device wishing to inquire as to the simple descriptor of a remote device on a specified endpoint. This command shall be unicast either to the remote device itself or to an alternative device that contains the discovery information of the remote device.
The local device shall generate the Simple_Desc_req command using the format illustrated in param list. The NWKAddrOfInterest field shall contain the network address of the remote device for which the simple descriptor is required and the endpoint field shall contain the endpoint identifier from which to obtain the required simple descriptor.
| [in] | handle | The handle of zigbee |
| [in] | addr16 | Network address for device of interest |
| [in] | ep | The endpoint on the destination |
| [in] | cb | Response callback |
| [in] | user_data | user data |
| ZIGBEE_ERROR_NONE | Successful |
| ZIGBEE_ERROR_INVALID_PARAMETER | Invalid parameter |
| ZIGBEE_ERROR_INVALID_ENDPOINT | Invalid endpoint. 0 is reserved for ZDP |
| ZIGBEE_ERROR_OUT_OF_MEMORY | Out-of-memory |
| ZIGBEE_ERROR_IO_ERROR | Unexpected d-bus error |
| ZIGBEE_ERROR_PERMISSION_DENIED | Permission denied |
| ZIGBEE_ERROR_NOT_SUPPORTED | Not supported |