Tizen Native API  5.0
Zigbee Device Object

Zigbee provides API for ZDO access.

Required Header

#include <zigbee.h>

Overview

The Zigbee Device Object (ZDO) is simply the application running on endpoint 0 in every Zigbee device. (Remember, application endpoints are numbered 1 through 240.)

This application, ZDO, keeps track of the state of the Zigbee device on and off the network, and provides an interface to the Zigbee Device Profile (ZDP), a specialized Application Profile (with profile ID 0x0000) for discovering, configuring, and maintaining Zigbee devices and services on the network.

ZDO not only interacts with APS, but also interacts directly with the network layer. ZDO controls the network layer, telling it when to form or join a network, and when to leave, and provides the application interface to network layer management services. For example, ZDO can be configured to continue attempting to join a network until it is successful, or until a user-specified number-of-retries has occurred before giving up, and informing the application of the join failure.

The over-the-air Application Profile supported by ZDO, called the Zigbee Device Profile (ZDP), is no different than any other, and in most stacks is handled just like any other application object on an endpoint. ZDP services are separated into client and server. Client side services (also called requests), are always optional in Zigbee, but many of the server side ZDP services (also called responses), are mandatory. Nearly every service follows the same pattern when used. A client device (the node which is doing the asking) first makes a request. The server device then sends the response back to the client device. The cluster number for the response is exactly the same as the cluster number for the request, but with the high bit set. For example, the ZDP command IEEE_ addr_req(zb_zdo_ieee_addr_req) is cluster 0x0001, and IEEE_addr_cb (zb_zdo_addr_cb) is cluster 0x8001.

It doesn't matter how many hops the nodes are from each other. The nodes A and B could be 10 hops away from each other, and the ZDP request/response mechanism will work in exactly the same way, just as it does for applications sending data on an application endpoint.

For sleeping devices, the parents of the device keep track of the IEEE and short address of the child, and will respond for them. However, all other information about the sleeping device, such as the list of active endpoints, are not recorded by the parent and must be retrieved directly from the devices themselves.

Related Features

This function is related with the following features:

It is recommended to design applications with regard to features, for reliability.

You can check if a device supports the related features for these functions by using System Information, and control your application's actions accordingly.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on using features in your application can be found in the Feature List.

Functions

int zb_end_dev_get_end_dev_info_list (zb_zigbee_h handle, int *count, zb_end_dev_info_h **list)
 Gets all children device list information.
int zb_end_dev_get_ep_list (zb_zigbee_h handle, zb_ieee_addr addr64, unsigned char *count, zb_end_point **ep_list)
 Gets endpoint list information.
int zb_end_dev_get_cluster_list (zb_zigbee_h handle, zb_ieee_addr addr64, zb_end_point ep, unsigned char *in_cluster_count, zb_cluster_id **in_cluster_list, unsigned char *out_cluster_count, zb_cluster_id **out_cluster_list)
 Gets cluster list information.
int zb_end_dev_info_list_free (zb_end_dev_info_h *list)
 Frees all children device list information.
int zb_end_dev_info_create (zb_end_dev_info_h *handle)
 Creates an end-device handle.
int zb_end_dev_info_clone (zb_end_dev_info_h src, zb_end_dev_info_h *dst)
 Clones an end-device handle.
int zb_end_dev_info_destroy (zb_end_dev_info_h handle)
 Destroys an end-device handle.
int zb_end_dev_info_get_network_address (zb_end_dev_info_h handle, zb_nwk_addr *addr16)
 Gets network address of a specific end-point.
int zb_end_dev_info_get_ieee_address (zb_end_dev_info_h handle, zb_ieee_addr addr64)
 Gets ieee address of a specific end-point.
int zb_end_dev_info_get_num_of_ep (zb_end_dev_info_h handle, unsigned char *count)
 Gets a number of end-points of a specific end-device.
int zb_end_dev_info_get_ep_list (zb_end_dev_info_h handle, zb_end_point **ep_list)
 Gets pointer of end-points list.
int zb_end_dev_info_get_mac_capability (zb_end_dev_info_h handle, zb_zdp_mac_capability_field_e *capability)
 Gets 802.15.4 MAC capability of a specific end-point.
int zb_end_dev_info_get_alternative_pan_coordinator (zb_end_dev_info_h handle, zb_zdp_do_pan_coordinator_e *can_do_it)
 Gets ability of alternative PAN coordinator of a specific end-point.
int zb_end_dev_info_get_device_id (zb_end_dev_info_h handle, zb_end_point ep, zb_device_id *deviceid)
 Gets device id of a specific end-point.
int zb_end_dev_info_get_profile_id (zb_end_dev_info_h handle, zb_end_point ep, zb_profile_id *profileid)
 Gets profile id of a specific end-point.
int zb_end_dev_info_get_power_source (zb_end_dev_info_h handle, zb_zdp_power_e *power_src)
 Gets power source type of a specific end-point.
int zb_end_dev_info_get_security_capability (zb_end_dev_info_h handle, zb_zdp_security_cap_e *sec_capability)
 Gets security capability of a specific end-point.

Typedefs

typedef void * zb_end_dev_info_h
 The handle of zigbee end-device information.

Defines

#define MAX_ENDPOINT_CLUSTERS   32
 Cluster counts to handle with.

Define Documentation

#define MAX_ENDPOINT_CLUSTERS   32

Cluster counts to handle with.

Since :
5.0

Typedef Documentation

typedef void* zb_end_dev_info_h

The handle of zigbee end-device information.

A zb_end_dev_info_h is an opaque data structure. zb_end_dev_info_h is a data type of network address, IEEE address, endpoint count and endpoint information structure.

Since :
5.0

Enumeration Type Documentation

Values of the Current Power Mode Field in Zigbee Specification.

Since :
5.0
Enumerator:
ZB_ZDP_CUR_PWR_MODE_RECEIVER_SYNCHRONIZED_WITH_RECEIVER_ON 

Register Synchronized with Receiver On

ZB_ZDP_CUR_PWR_MODE_RECEIVER_COMES_ON_PERIODICALLY 

Register Comes on Periodically

ZB_ZDP_CUR_PWR_MODE_RECEIVER_COMES_ON_WHEN_STIMULATED 

Register Comes on When Stimulated

Device type bit in MAC capability Flags.

Since :
5.0
Enumerator:
ZB_ZDP_DEV_TYPE_RFD 

This node is a reduced function device (RFD)

ZB_ZDP_DEV_TYPE_FFD 

This node is a full function device (FFD)

Alternative PAN coordinator bit in MAC capability Flags.

Since :
5.0
Enumerator:
ZB_ZDP_DO_PAN_COORDINATOR_SUPPORTED 

This node is capable of becoming a PAN coordinator.

ZB_ZDP_DO_PAN_COORDINATOR_NOT_SUPPORTED 

Otherwise

Values of the Frequency Band Field.

Since :
5.0
Enumerator:
ZB_ZDP_FREQ_BAND_868_868_6_MHZ 

868~888.6MHz

ZB_ZDP_FREQ_BAND_902_928_MHZ 

902~928MHz

ZB_ZDP_FREQ_BAND_2400_2483_5_MHZ 

2400~2483.5MHz

Values of the Logical Type Field.

Since :
5.0
Enumerator:
ZB_ZDP_LOGICAL_TYPE_COORDINATOR 

Coordinator

ZB_ZDP_LOGICAL_TYPE_ROUTER 

Router

ZB_ZDP_LOGICAL_TYPE_END_DEVICE 

End Device

Format of the MAC Capability Flags Field in Zigbee Specification.

Since :
5.0
Enumerator:
ZB_ZDP_ALTERNATIVE_PAN_COORDINATOR 

Alternative Pan Coordinator (see zb_zdp_do_pan_coordinator_e)

ZB_ZDP_DEVICE_TYPE 

Device Type (see zb_zdp_dev_type_e)

ZB_ZDP_POWER_SOURCE 

Power Source (see zb_zdp_pwr_src_type_e)

ZB_ZDP_RECEIVER_ON_WHEN_IDLE 

Register on When Idle

ZB_ZDP_SECURITY_CAPABILITY 

Security Capability (see zb_zdp_security_cap_e)

ZB_ZDP_ALLOCATE_ADDRESS 

Allocated Address.
This mean device receive network address from coordinator. This field will always have a value of 1 in implementations of IEEE 802.15.4 spec, indicating that the joining device must be issued a 16-bit short address

Receiver on when idle bit in MAC capability Flags.

Since :
5.0
Enumerator:
ZB_ZDP_PM_DO_NOT_POWER_SAVE_MODE 

The device does not disable its receiver to conserve power during idle periods.

ZB_ZDP_PM_KEEP_POWER_SAVE_MODE 

Otherwise

Indicates the device supports main-power in MAC capability Flags.

Since :
5.0
Enumerator:
ZB_ZDP_POWER_NO_POWER 

Not having mains-power

ZB_ZDP_POWER_MAINS_POWER 

Having mains-power

Power Source bit in MAC capability Flags.

Since :
5.0
Enumerator:
ZB_ZDP_PWR_SRC_MAIN_POWER 

Current power source is main power. This information is derived from the node current power source field of the node power descriptor

ZB_ZDP_PWR_SRC_NO_NODE_POWER_DESCRIPTION 

Otherwise

Values of the Available Power Sources Field in Zigbee Specification.

Since :
5.0
Enumerator:
ZB_ZDP_PWR_SRC_LEVEL_CHARGE_LEVEL_CRITICAL 

Charge Level Critical

ZB_ZDP_PWR_SRC_LEVEL_CHARGE_LEVEL_33 

Charge Level 33%

ZB_ZDP_PWR_SRC_LEVEL_CHARGE_LEVEL_66 

Charge Level 66%

ZB_ZDP_PWR_SRC_LEVEL_CHARGE_LEVEL_100 

Charge Level 100%

Fields of the Node Power Descriptor.

Since :
5.0
Enumerator:
ZB_ZDP_PWR_SRC_TYPE_CONSTANT_POWER 

Constant Power

ZB_ZDP_PWR_SRC_TYPE_RECHARGEABLE_BATTERY 

Rechargeable Battery

ZB_ZDP_PWR_SRC_TYPE_DISPOSABLE_BATTERY 

Disposable Battery

Request type Enumeration.

Since :
5.0
Enumerator:
ZB_ZDP_REQ_TYPE_SINGLE_DEVICE_RESPONSE 

Single Device Response : 0

ZB_ZDP_REQ_TYPE_EXTENDED_RESPONSE 

Extended Response : 1

Security capability bit in MAC capability Flags.

Since :
5.0
Enumerator:
ZB_ZDP_SECURITY_CAP_NOT_SUPPORTED 

ZDP does not support security mode

ZB_ZDP_SECURITY_CAP_SUPPORTED 

ZDP supports security mode

Server Mask Bit Assignments.

Since :
5.0
Enumerator:
ZB_ZDP_SERVER_MASK_PRIMARY_TRUST_CENTER 

Primary Trust Center

ZB_ZDP_SERVER_MASK_BACKUP_TRUST_CENTER 

Backup Trust Center

ZB_ZDP_SERVER_MASK_PRIMARY_BINDING_TABLE_CACHE 

Primary Binding Table Cache

ZB_ZDP_SERVER_MASK_BACKUP_BINDING_TABLE_CACHE 

Backup Binding Table Cache

ZB_ZDP_SERVER_MASK_PRIMARY_DISCOVERY_CACHE 

Primary Discovery Cache

ZB_ZDP_SERVER_MASK_BACKUP_DISCOVERY_CACHE 

Backup Discovery Cache

ZB_ZDP_SERVER_MASK_NETWORK_MANAGER 

Network Manager

ZDO Status Enumerations Description.

Since :
5.0
Enumerator:
ZB_ZDP_STATUS_SUCCESS 

Success

ZB_ZDP_STATUS_INVALID_REQUEST_TYPE 

Invalid Request Type

ZB_ZDP_STATUS_DEVICE_NOT_FOUND 

Device Not Found

ZB_ZDP_STATUS_INVALID_EP 

Invalid Endpoint

ZB_ZDP_STATUS_NOT_ACTIVE 

Not Active

ZB_ZDP_STATUS_NOT_SUPPORTED 

Not Supported

ZB_ZDP_STATUS_TIMEOUT 

Timeout

ZB_ZDP_STATUS_NO_MATCH 

No Match

ZB_ZDP_STATUS_NO_ENTRY 

No Entry

ZB_ZDP_STATUS_NO_DESCRIPTOR 

No Descriptor

ZB_ZDP_STATUS_INSUFFICIENT_SPACE 

Insufficient Space

ZB_ZDP_STATUS_NOT_PERMITTED 

Not Permitted

ZB_ZDP_STATUS_TABLE_FULL 

Table Full

ZB_ZDP_STATUS_NOT_AUTHORIZED 

Not Authorized

ZB_ZDP_STATUS_DEVICE_BINDING_TABLE_FULL 

Binding Table Full

ZB_ZDP_STATUS_UNKNOWN 

Unknown


Function Documentation

int zb_end_dev_get_cluster_list ( zb_zigbee_h  handle,
zb_ieee_addr  addr64,
zb_end_point  ep,
unsigned char *  in_cluster_count,
zb_cluster_id **  in_cluster_list,
unsigned char *  out_cluster_count,
zb_cluster_id **  out_cluster_list 
)

Gets cluster list information.

This function return in and out cluster list of each device.

Since :
5.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/zigbee
Remarks:
The in_cluster_list should be released using free().
The out_cluster_list should be released using free().
Parameters:
[in]handleThe handle of zigbee
[in]addr64the Zigbee IEEE MAC address
[in]ependpoint number
[out]in_cluster_countThe number of in-clusters
[out]in_cluster_listThe device server cluster list
[out]out_cluster_countThe number of out-clusters
[out]out_cluster_listThe device client list
Returns:
0 on success, otherwise a negative error value.
Return values:
ZIGBEE_ERROR_NONESuccessful
ZIGBEE_ERROR_INVALID_PARAMETERInvalid parameter
ZIGBEE_ERROR_IO_ERRORUnexpected d-bus error
ZIGBEE_ERROR_PERMISSION_DENIEDPermission denied
ZIGBEE_ERROR_NOT_SUPPORTEDNot supported
See also:
zb_end_dev_get_ep_list()
int zb_end_dev_get_end_dev_info_list ( zb_zigbee_h  handle,
int *  count,
zb_end_dev_info_h **  list 
)

Gets all children device list information.

This function return end-point list and simple description per each end-point at each device.

Since :
5.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/zigbee
Remarks:
The list should be released using zb_end_dev_info_list_free().
Parameters:
[in]handleThe handle of zigbee
[out]countThe number of end-devices
[out]listThe device information list
Returns:
0 on success, otherwise a negative error value.
Return values:
ZIGBEE_ERROR_NONESuccessful
ZIGBEE_ERROR_INVALID_PARAMETERInvalid parameter
ZIGBEE_ERROR_IO_ERRORUnexpected d-bus error
ZIGBEE_ERROR_PERMISSION_DENIEDPermission denied
ZIGBEE_ERROR_NOT_SUPPORTEDNot supported
See also:
zb_end_dev_info_list_free()
int zb_end_dev_get_ep_list ( zb_zigbee_h  handle,
zb_ieee_addr  addr64,
unsigned char *  count,
zb_end_point **  ep_list 
)

Gets endpoint list information.

This function return end-point list of each device.

Since :
5.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/zigbee
Remarks:
The ep_list should be released using free().
Parameters:
[in]handleThe handle of zigbee
[in]addr64the Zigbee IEEE MAC address
[out]countThe number of endpoints
[out]ep_listThe device endpoint list
Returns:
0 on success, otherwise a negative error value.
Return values:
ZIGBEE_ERROR_NONESuccessful
ZIGBEE_ERROR_INVALID_PARAMETERInvalid parameter
ZIGBEE_ERROR_IO_ERRORUnexpected d-bus error
ZIGBEE_ERROR_PERMISSION_DENIEDPermission denied
ZIGBEE_ERROR_NOT_SUPPORTEDNot supported
See also:
zb_end_dev_get_cluster_list()

Clones an end-device handle.

Since :
5.0
Remarks:
The src should be released using zb_end_dev_destroy().
The dst should be released using zb_end_dev_destroy().
Parameters:
[in]srchandle of source end-device descriptor
[in]dsthandle of destination end-device descriptor
Returns:
0 on success, otherwise a negative error value.
Return values:
ZIGBEE_ERROR_NONESuccessful
ZIGBEE_ERROR_INVALID_PARAMETERInvalid parameter
ZIGBEE_ERROR_NOT_SUPPORTEDNot supported
See also:
zb_end_dev_info_create()
zb_end_dev_info_destroy()

Creates an end-device handle.

Since :
5.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/zigbee
Remarks:
The handle should be released using zb_end_dev_destroy().
Parameters:
[out]handleThe handle of end-device descriptor
Returns:
0 on success, otherwise a negative error value.
Return values:
ZIGBEE_ERROR_NONESuccessful
ZIGBEE_ERROR_INVALID_PARAMETERInvalid parameter
ZIGBEE_ERROR_OUT_OF_MEMORYOut-of-memory
ZIGBEE_ERROR_PERMISSION_DENIEDPermission denied
ZIGBEE_ERROR_NOT_SUPPORTEDNot supported
See also:
zb_end_dev_info_clone()
zb_end_dev_info_destroy()

Destroys an end-device handle.

Since :
5.0
Parameters:
[in]handleThe handle of end-device descriptor
Returns:
0 on success, otherwise a negative error value.
Return values:
ZIGBEE_ERROR_NONESuccessful
ZIGBEE_ERROR_INVALID_PARAMETERInvalid parameter
ZIGBEE_ERROR_NOT_SUPPORTEDNot supported
See also:
zb_end_dev_info_create()
zb_end_dev_info_clone()

Gets ability of alternative PAN coordinator of a specific end-point.

Since :
5.0
Parameters:
[in]handleThe handle of a specific end-device
[out]can_do_italternative of PAN coordinator of the end-point
Returns:
0 on success, otherwise a negative error value.
Return values:
ZIGBEE_ERROR_NONESuccessful
ZIGBEE_ERROR_INVALID_PARAMETERInvalid parameter
ZIGBEE_ERROR_NO_DATANo data available
ZIGBEE_ERROR_IO_ERRORUnexpected d-bus error
ZIGBEE_ERROR_NOT_SUPPORTEDNot supported
See also:
zb_end_dev_get_end_dev_info_list()

Gets device id of a specific end-point.

Since :
5.0
Parameters:
[in]handleThe handle of a specific end-device
[in]ependpoint number
[out]deviceiddevice id of the end-point
Returns:
0 on success, otherwise a negative error value.
Return values:
ZIGBEE_ERROR_NONESuccessful
ZIGBEE_ERROR_INVALID_PARAMETERInvalid parameter
ZIGBEE_ERROR_NO_DATANo data available
ZIGBEE_ERROR_IO_ERRORUnexpected d-bus error
ZIGBEE_ERROR_NOT_SUPPORTEDNot supported
See also:
zb_end_dev_get_end_dev_info_list()

Gets pointer of end-points list.

Since :
5.0
Remarks:
The number of items on the list can be found with zb_end_dev_info_get_num_of_ep().
The ep_list should be released using free().
Parameters:
[in]handleThe handle of a specific end-device
[out]ep_listlist of endpoints of the end-point
Returns:
0 on success, otherwise a negative error value.
Return values:
ZIGBEE_ERROR_NONESuccessful
ZIGBEE_ERROR_INVALID_PARAMETERInvalid parameter
ZIGBEE_ERROR_NOT_SUPPORTEDNot supported
See also:
zb_end_dev_get_end_dev_info_list() #
zb_end_dev_info_get_num_of_ep()

Gets ieee address of a specific end-point.

Since :
5.0
Parameters:
[in]handleThe handle of a specific end-device
[out]addr64ieee address of the end-point
Returns:
0 on success, otherwise a negative error value.
Return values:
ZIGBEE_ERROR_NONESuccessful
ZIGBEE_ERROR_INVALID_PARAMETERInvalid parameter
ZIGBEE_ERROR_NOT_SUPPORTEDNot supported
See also:
zb_end_dev_get_end_dev_info_list()

Gets 802.15.4 MAC capability of a specific end-point.

Since :
5.0
Parameters:
[in]handleThe handle of a specific end-device
[out]capability802.15.4 MAC capability of the end-point
Returns:
0 on success, otherwise a negative error value.
Return values:
ZIGBEE_ERROR_NONESuccessful
ZIGBEE_ERROR_INVALID_PARAMETERInvalid parameter
ZIGBEE_ERROR_NO_DATANo data available
ZIGBEE_ERROR_IO_ERRORUnexpected d-bus error
ZIGBEE_ERROR_NOT_SUPPORTEDNot supported
See also:
zb_end_dev_get_end_dev_info_list()

Gets network address of a specific end-point.

Since :
5.0
Parameters:
[in]handleThe handle of a specific end-device
[out]addr16network address of the end-point
Returns:
0 on success, otherwise a negative error value.
Return values:
ZIGBEE_ERROR_NONESuccessful
ZIGBEE_ERROR_INVALID_PARAMETERInvalid parameter
ZIGBEE_ERROR_NOT_SUPPORTEDNot supported
See also:
zb_end_dev_get_end_dev_info_list()
int zb_end_dev_info_get_num_of_ep ( zb_end_dev_info_h  handle,
unsigned char *  count 
)

Gets a number of end-points of a specific end-device.

Since :
5.0
Parameters:
[in]handleThe handle of a specific end-device
[out]counta number of endpoints of the end-point
Returns:
0 on success, otherwise a negative error value.
Return values:
ZIGBEE_ERROR_NONESuccessful
ZIGBEE_ERROR_INVALID_PARAMETERInvalid parameter
ZIGBEE_ERROR_NOT_SUPPORTEDNot supported
See also:
zb_end_dev_get_end_dev_info_list()

Gets power source type of a specific end-point.

Since :
5.0
Parameters:
[in]handleThe handle of a specific end-device
[out]power_srcpower source type of the end-point
Returns:
0 on success, otherwise a negative error value.
Return values:
ZIGBEE_ERROR_NONESuccessful
ZIGBEE_ERROR_INVALID_PARAMETERInvalid parameter
ZIGBEE_ERROR_NO_DATANo data available
ZIGBEE_ERROR_IO_ERRORUnexpected d-bus error
ZIGBEE_ERROR_NOT_SUPPORTEDNot supported
See also:
zb_end_dev_get_end_dev_info_list()

Gets profile id of a specific end-point.

Since :
5.0
Parameters:
[in]handleThe handle of a specific end-device
[in]ependpoint number
[out]profileidprofile id of the end-point
Returns:
0 on success, otherwise a negative error value.
Return values:
ZIGBEE_ERROR_NONESuccessful
ZIGBEE_ERROR_INVALID_PARAMETERInvalid parameter
ZIGBEE_ERROR_NO_DATANo data available
ZIGBEE_ERROR_IO_ERRORUnexpected d-bus error
ZIGBEE_ERROR_NOT_SUPPORTEDNot supported
See also:
zb_end_dev_get_end_dev_info_list()

Gets security capability of a specific end-point.

Since :
5.0
Parameters:
[in]handleThe handle of a specific end-device
[out]sec_capabilitysecurity type of the end-point
Returns:
0 on success, otherwise a negative error value.
Return values:
ZIGBEE_ERROR_NONESuccessful
ZIGBEE_ERROR_INVALID_PARAMETERInvalid parameter
ZIGBEE_ERROR_NO_DATANo data available
ZIGBEE_ERROR_IO_ERRORUnexpected d-bus error
ZIGBEE_ERROR_NOT_SUPPORTEDNot supported
See also:
zb_end_dev_get_end_dev_info_list()

Frees all children device list information.

This function return end-point list and simple description per each end-point at each device.

Since :
5.0
Parameters:
[in]listThe device information list
Returns:
0 on success, otherwise a negative error value.
Return values:
ZIGBEE_ERROR_NONESuccessful
ZIGBEE_ERROR_INVALID_PARAMETERInvalid parameter
ZIGBEE_ERROR_NOT_SUPPORTEDNot supported
See also:
zb_end_dev_get_end_dev_info_list()