ZigBee Data Object/ZigBee Device Profile

Files
file	zdo.h
	ZigBee Device Objects (ZDO) and ZigBee Device Profile (ZDP).
file	zigbee_zdo.c

Data Structures
union	zdo_bind_req_t

Typedefs
typedef PACKED_STRUCT	zdo_active_ep_req_t
typedef PACKED_STRUCT	zdo_active_ep_rsp_header_t
	see ZDO_STATUS_* macros More...
typedef PACKED_STRUCT	zdo_bind_address_req_t
typedef PACKED_STRUCT	zdo_bind_group_req_t
typedef PACKED_STRUCT	zdo_bind_req_header_t
typedef union zdo_bind_req_t	zdo_bind_req_t
typedef PACKED_STRUCT	zdo_complex_desc_req_t
typedef PACKED_STRUCT	zdo_device_annce_t
	frame format for a ZDO Device_annce announcement More...
typedef PACKED_STRUCT	zdo_ieee_addr_req_t
	frame format for ZDO IEEE_addr request More...
typedef zdo_nwk_addr_rsp_header_t	zdo_ieee_addr_rsp_header_t
typedef PACKED_STRUCT	zdo_match_desc_out_clust_t
typedef PACKED_STRUCT	zdo_match_desc_req_t
	header for ZDO Match_Desc request More...
typedef PACKED_STRUCT	zdo_match_desc_rsp_header_t
	see ZDO_STATUS_* macros More...
typedef PACKED_STRUCT	zdo_mgmt_leave_req_t
	frame format for a ZDO Management Leave Request More...
typedef PACKED_STRUCT	zdo_mgmt_leave_rsp_t
typedef PACKED_STRUCT	zdo_node_desc_req_t
typedef PACKED_STRUCT	zdo_node_desc_resp_t
	see ZDO_STATUS_* macros More...
typedef PACKED_STRUCT	zdo_node_desc_t
	frame format for ZDO Node_Desc response More...
typedef PACKED_STRUCT	zdo_nwk_addr_req_t
	frame format for ZDO NKW_addr request More...
typedef PACKED_STRUCT	zdo_nwk_addr_rsp_header_t
typedef PACKED_STRUCT	zdo_power_desc_req_t
typedef PACKED_STRUCT	zdo_power_desc_rsp_t
	frame format for ZDO Power_Desc response More...
typedef PACKED_STRUCT	zdo_power_desc_t
	format for ZDO PowerDescriptor More...
typedef PACKED_STRUCT	zdo_simple_desc_header_t
	0x01 to 0xFE More...
typedef PACKED_STRUCT	zdo_simple_desc_req_t
	frame format for ZDO Simple_Desc request More...
typedef PACKED_STRUCT	zdo_simple_desc_resp_header_t
	header for ZDO Simple_Desc response, followed by a SimpleDescriptor More...
typedef PACKED_STRUCT	zdo_user_desc_req_t

Functions
int	_match_desc_cluster_list (uint8_t **buffer, const uint16_t *clust_read, int max_count)
int	_simple_desc_cluster_list (uint8_t **buffer, int max_count, uint8_t mask, const wpan_cluster_table_entry_t *entry)
int	_zdo_active_ep_respond (const wpan_envelope_t FAR *envelope)
const wpan_endpoint_table_entry_t *	_zdo_endpoint_of (wpan_dev_t *dev)
const addr64 *	_zdo_envelope_create (wpan_envelope_t *envelope, wpan_dev_t *dev, const addr64 *address)
int	_zdo_match_desc_respond (const wpan_envelope_t FAR *envelope)
zigbee_zdo_debug int	_zdo_process_ieee_addr_resp (wpan_conversation_t FAR *conversation, const wpan_envelope_t FAR *envelope)
zigbee_zdo_debug int	_zdo_process_nwk_addr_resp (wpan_conversation_t FAR *conversation, const wpan_envelope_t FAR *envelope)
int	_zdo_simple_desc_respond (const wpan_envelope_t FAR *envelope)
wpan_ep_state_t FAR *	zdo_endpoint_state (wpan_dev_t *dev)
	Returns the ZDO endpoint's state if a device has a ZDO endpoint. More...
int	zdo_handler (const wpan_envelope_t FAR *envelope, wpan_ep_state_t FAR *ep_state)
	Process ZDO frames (received on endpoint 0 with Profile ID 0). More...
int	zdo_match_desc_request (void *buffer, int16_t buflen, uint16_t addr_of_interest, uint16_t profile_id, const uint16_t *inClust, const uint16_t *outClust)
	Generate a Match_Desc (Match Descriptor) request (ZigBee spec 2.4.3.1.7) to send on the network. Note that the first byte of buffer is NOT set, and that the caller should set it to the next sequence number/transaction ID. More...
int	zdo_mgmt_leave_req (wpan_dev_t *dev, const addr64 *address, uint16_t flags)
	Send a ZDO Management Leave Request. More...
int	zdo_send_bind_req (wpan_envelope_t *envelope, uint16_t type, wpan_response_fn callback, void FAR *context)
	Send a ZDO Bind (or Unbind) Request to the destination address in the envelope. More...
int	zdo_send_descriptor_req (wpan_envelope_t *envelope, uint16_t cluster, uint16_t addr_of_interest, wpan_response_fn callback, const void FAR *context)
	Send a ZDO Node, Power, Complex or User Descriptor request, or an Active Endpoint request. More...
int	zdo_send_ieee_addr_req (wpan_dev_t *dev, uint16_t net_addr, addr64 FAR *ieee_be)
	Given a device's 16-bit network address, get its IEEE (64-bit) address by unicasting a ZDO IEEE_addr request to it. More...
int	zdo_send_nwk_addr_req (wpan_dev_t *dev, const addr64 FAR *ieee_be, uint16_t FAR *net)
	Given a device's IEEE (64-bit) address, get its 16-bit network address by unicasting a ZDO NWK_addr request to it. More...
int	zdo_send_response (const wpan_envelope_t FAR *request, const void FAR *response, uint16_t length)
	Send a response to a ZDO request. More...
int	zdo_simple_desc_request (wpan_envelope_t *envelope, uint16_t addr_of_interest, uint_fast8_t endpoint, wpan_response_fn callback, const void FAR *context)
	Send a ZDO Simple Descriptor Request. More...

Variables
zdo_bind_address_req_t	address
uint8_t	capability
	see ZDO_CAPABILITY_* macros More...
uint16_t	cluster_id_le
uint8_t	desc_capability
uint16_t	device_id_le
	endpoint's device ID (little-endian) More...
uint8_t	device_version
	upper 4 bits are reserved More...
uint8_t	dst_addr_mode
addr64	dst_address_le
uint8_t	dst_endpoint
uint8_t	endpoint
	0x01 to 0xFE More...
uint8_t	ep_count
uint8_t	flags
uint8_t	flags1
zdo_bind_group_req_t	group
uint16_t	group_addr_le
zdo_bind_req_header_t	header
addr64	ieee_address_le
addr64	ieee_remote_le
uint16_t	in_cluster_list [1]
	variable length More...
uint8_t	length
	length of simple descriptor More...
uint8_t	mac_capability
uint16_t	manufacturer_le
uint8_t	match_length
uint8_t	max_buffer
uint16_t	max_incoming_le
uint16_t	max_outgoing_le
uint16_t	net_remote_le
uint16_t	network_addr_le
	device's network address (little-endian) More...
zdo_node_desc_t	node_desc
uint8_t	num_assoc_dev
uint8_t	num_in_clusters
uint16_t	out_cluster_list [1]
	variable length More...
uint8_t	power1
	combination of ZDO_POWER1_* macros More...
zdo_power_desc_t	power_desc
uint16_t	profile_id_le
	endpoint's profile ID (little-endian) More...
uint8_t	request_type
	See ZDO_REQUEST_TYPE_* macros. More...
uint16_t	server_mask_le
uint8_t	src_endpoint
uint8_t	start_index

Detailed Description

Typedef Documentation

zdo_active_ep_req_t

Initial value:

{
        uint8_t         transaction

frame format for ZDO Active_EP request

See also

zdo_send_descriptor_req()

zdo_active_ep_rsp_header_t

Initial value:

{
        uint8_t         status

see ZDO_STATUS_* macros

header for ZDO Active_EP response, followed by .ep_count uint8_t endpoints

zdo_bind_address_req_t

Initial value:

{
        zdo_bind_req_header_t   header

frame format for a ZDO Bind Request with an IEEE address and endpoint as the destination (header.dst_addr_mode == ZDO_BIND_DST_MODE_ADDR)

zdo_bind_group_req_t

Initial value:

{
        zdo_bind_req_header_t   header

frame format for a ZDO Bind Request with a group address as the destination (header.dst_addr_mode == ZDO_BIND_DST_MODE_GROUP)

zdo_bind_req_header_t

Initial value:

{
        addr64          src_address_le

typedef union zdo_bind_req_t zdo_bind_req_t

zdo_complex_desc_req_t

Initial value:

{
        uint8_t         transaction

frame format for ZDO Complex_Desc request

See also

zdo_send_descriptor_req()

zdo_device_annce_t

Initial value:

{
        uint8_t         transaction

frame format for a ZDO Device_annce announcement

zdo_ieee_addr_req_t

Initial value:

{
        uint8_t         transaction

frame format for ZDO IEEE_addr request

typedef zdo_nwk_addr_rsp_header_t zdo_ieee_addr_rsp_header_t

zdo_match_desc_out_clust_t

Initial value:

{
        uint8_t         num_out_clusters

Second half of Match_Desc request. cast to address of zdo_match_desc_req_t

• offsetof .in_cluster_list + 2 * .num_in_clusters

zdo_match_desc_req_t

Initial value:

{
        uint8_t         transaction

header for ZDO Match_Desc request

zdo_match_desc_rsp_header_t

Initial value:

{
        uint8_t         status

see ZDO_STATUS_* macros

header for ZDO Match_Desc response, followed by .match_length uint8_t endpoints

zdo_mgmt_leave_req_t

Initial value:

{
        addr64          device_address

frame format for a ZDO Management Leave Request

zdo_mgmt_leave_rsp_t

Initial value:

{
        uint8_t         status

zdo_node_desc_req_t

Initial value:

{
        uint8_t         transaction

frame format for ZDO Node_Desc request

See also

zdo_send_descriptor_req()

zdo_node_desc_resp_t

Initial value:

{
        uint8_t                                 status

see ZDO_STATUS_* macros

zdo_node_desc_t

Initial value:

{
        uint8_t         flags0

frame format for ZDO Node_Desc response

zdo_nwk_addr_req_t

Initial value:

{
        uint8_t         transaction

frame format for ZDO NKW_addr request

zdo_nwk_addr_rsp_header_t

Initial value:

{
        uint8_t         status

zdo_power_desc_req_t

Initial value:

{
        uint8_t         transaction

frame format for ZDO Power_Desc request

See also

zdo_send_descriptor_req()

zdo_power_desc_rsp_t

Initial value:

{
        uint8_t                                 status

frame format for ZDO Power_Desc response

see ZDO_STATUS_* macros

zdo_power_desc_t

Initial value:

{
        uint8_t         power0

format for ZDO PowerDescriptor

combination of ZDO_POWER0_* macros

zdo_simple_desc_header_t

Initial value:

{
        uint8_t         endpoint

0x01 to 0xFE

header for ZDO SimpleDescriptor (part of a Simple_Desc response), followed by uint8_t input cluster count, multiple uint16_t input cluster IDs, uint8_t output cluster count, multiple uint16_t output cluster IDs

zdo_simple_desc_req_t

Initial value:

{
        uint8_t         transaction

frame format for ZDO Simple_Desc request

zdo_simple_desc_resp_header_t

Initial value:

{
        uint8_t         status

header for ZDO Simple_Desc response, followed by a SimpleDescriptor

see ZDO_STATUS_* macros

zdo_user_desc_req_t

Initial value:

{
        uint8_t         transaction

frame format for ZDO Complex_Desc request

See also

zdo_send_descriptor_req()

Function Documentation

int _match_desc_cluster_list	(	uint8_t **	buffer,
		const uint16_t *	clust_read,
		int	max_count
	)

int _simple_desc_cluster_list	(	uint8_t **	buffer,
		int	max_count,
		uint8_t	mask,
		const wpan_cluster_table_entry_t *	entry
	)

zigbee_zdo_debug int _zdo_active_ep_respond

(

const wpan_envelope_t FAR *

envelope

)

zigbee_zdo_debug const wpan_endpoint_table_entry_t * _zdo_endpoint_of

(

wpan_dev_t *

dev

)

zigbee_zdo_debug const addr64 * _zdo_envelope_create	(	wpan_envelope_t *	envelope,
		wpan_dev_t *	dev,
		const addr64 *	address
	)

zigbee_zdo_debug int _zdo_match_desc_respond

(

const wpan_envelope_t FAR *

envelope

)

zigbee_zdo_debug int _zdo_process_ieee_addr_resp	(	wpan_conversation_t FAR *	conversation,
		const wpan_envelope_t FAR *	envelope
	)

zigbee_zdo_debug int _zdo_process_nwk_addr_resp	(	wpan_conversation_t FAR *	conversation,
		const wpan_envelope_t FAR *	envelope
	)

zigbee_zdo_debug int _zdo_simple_desc_respond

(

const wpan_envelope_t FAR *

envelope

)

zigbee_zdo_debug wpan_ep_state_t FAR * zdo_endpoint_state

(

wpan_dev_t *

dev

)

Returns the ZDO endpoint's state if a device has a ZDO endpoint.

Parameters

[in]

dev

device to query

Return values

NULL	dev does not have a ZDO endpoint
!NULL	address of wpan_ep_state variable used for state tracking

zigbee_zdo_debug int zdo_handler	(	const wpan_envelope_t FAR *	envelope,
		wpan_ep_state_t FAR *	ep_state
	)

Process ZDO frames (received on endpoint 0 with Profile ID 0).

Parameters

[in]	envelope	envelope of received ZDO frame, contains address, endpoint, profile, and cluster info
[in]	ep_state	pointer to endpoint's state structure (used for tracking transactions)

Return values

0	successfully processed
!0	error trying to process frame

zigbee_zdo_debug int zdo_match_desc_request	(	void *	buffer,
		int16_t	buflen,
		uint16_t	addr_of_interest,
		uint16_t	profile_id,
		const uint16_t *	inClust,
		const uint16_t *	outClust
	)

Generate a Match_Desc (Match Descriptor) request (ZigBee spec 2.4.3.1.7) to send on the network. Note that the first byte of buffer is NOT set, and that the caller should set it to the next sequence number/transaction ID.

Parameters

[out]	buffer	Buffer to hold generated request.
[in]	buflen	Size of buffer used to hold generated request.
[in]	addr_of_interest	See ZDO documentation for NWKAddrOfInterest.
[in]	profile_id	Profile ID to match, must be an actual profile ID (cannot be WPAN_APS_PROFILE_ANY).
[in]	inClust	List of input clusters, ending with #WPAN_CLUSTER_END_OF_LIST. Can use NULL if there aren't any input clusters.
[in]	outClust	List of output clusters, ending with #WPAN_CLUSTER_END_OF_LIST. Can use NULL if there aren't any output clusters.

Return values

-ENOSPC	buffer isn't large enough to hold request; need 7 bytes plus (2 * the number of clusters)
>0	number of bytes written to buffer

zigbee_zdo_debug int zdo_mgmt_leave_req	(	wpan_dev_t *	dev,
		const addr64 *	address,
		uint16_t	flags
	)

Send a ZDO Management Leave Request.

Parameters

[in]	dev	device to send request on
[in]	address	address to send request to, or NULL for self-addressed
[in]	flags	one or more of the following flags: ZDO_MGMT_LEAVE_REQ_FLAG_NONE ZDO_MGMT_LEAVE_REQ_FLAG_REMOVE_CHILDREN - set the Remove Children flag in the ZDO request ZDO_MGMT_LEAVE_REQ_FLAG_REJOIN - set the Rejoin flag in the ZDO request ZDO_MGMT_LEAVE_REQ_ENCRYPTED - send the request with APS encryption

Return values

0	successfully sent request
-EINVAL	bad parameter passed to function
!0	error sending request

zigbee_zdo_debug int zdo_send_bind_req	(	wpan_envelope_t *	envelope,
		uint16_t	type,
		wpan_response_fn	callback,
		void FAR *	context
	)

Send a ZDO Bind (or Unbind) Request to the destination address in the envelope.

Binds .dest_endpoint on .ieee_address to .source_endpoint on .dev using .cluster_id.

Ignores the .options, .payload, and .length members of the envelope.

Parameters

[in]	envelope	addressing information used for the Bind Request
[in]	type	ZDO_BIND_REQ for a Bind Request or ZDO_UNBIND_REQ for an Unbind Request; all other values are invalid
[in]	callback	callback to receive Bind/Unbind (or Default) Response; NULL if you don't care about the response
[in]	context	context passed to callback

Return values

0	successfully sent request
-EINVAL	bad parameter passed to function
!0	error sending request

zigbee_zdo_debug int zdo_send_descriptor_req	(	wpan_envelope_t *	envelope,
		uint16_t	cluster,
		uint16_t	addr_of_interest,
		wpan_response_fn	callback,
		const void FAR *	context
	)

Send a ZDO Node, Power, Complex or User Descriptor request, or an Active Endpoint request.

Parameters

[in,out]	envelope	Envelope created by wpan_envelope_create; this function will fill in the cluster and reset the payload and length.
[in]	cluster	Any ZDO request with a transaction and 16-bit network address as its only fields, including: ZDO_NODE_DESC_REQ ZDO_POWER_DESC_REQ ZDO_ACTIVE_EP_REQ ZDO_COMPLEX_DESC_REQ ZDO_USER_DESC_REQ
[in]	addr_of_interest	address to use in ZDO request
[in]	callback	function to receive response
[in]	context	context to pass to callback with response

Return values

!0	error sending request
0	request sent

zigbee_zdo_debug int zdo_send_ieee_addr_req	(	wpan_dev_t *	dev,
		uint16_t	net_addr,
		addr64 FAR *	ieee_be
	)

Given a device's 16-bit network address, get its IEEE (64-bit) address by unicasting a ZDO IEEE_addr request to it.

This function only works with the following XBee firmware versions:

• S2C: 401F and later (ZigBee), 5123 and later (Smart Energy)
• S2[B]: not supported

After calling this function, *ieee_be is set to *ZDO_IEEE_ADDR_PENDING.

When a SUCCESS response comes back, *ieee_be is set to the 64-bit IEEE address in the response.

If an ERROR response comes back, *ieee_be is set to all zeros (*ZDO_IEEE_ADDR_ERROR).

If a timeout occurs waiting for a response, *ieee_be is set to ZDO_IEEE_ADDR_TIMEOUT.

addr64 ieee_be;         // IEEE address in big-endian byte order
uint16_t net_addr;

printf( "Sending IEEE_addr request for 0x%04X\n", net_addr);
zdo_send_ieee_addr_req( dev, net_addr, &ieee_be);
do {
        wpan_tick( dev);
} while (addr64_equal( &ieee_be, ZDO_IEEE_ADDR_PENDING));

if (addr64_equal( &ieee_be, ZDO_IEEE_ADDR_TIMEOUT))
{
        printf( "IEEE_addr request for 0x%04X timed out\n", net_addr);
}
else if (addr64_is_zero( &ieee_be))
{
        printf( "Error retrieving IEEE_addr for 0x%04X\n", net_addr);
}
else
{
        printf( "IEEE address of 0x%04X is %" PRIsFAR "\n", net_addr,
                addr64_format( buffer, &ieee_be));
}

    @param[in]      dev             wpan_dev_t to send request
    @param[in]      net_addr        network address of device we're seeking an IEEE
                                                            address for
    @param[out]     ieee_be location to store the 64-bit IEEE address when the
                                                            IEEE_addr response comes back.

    @retval -EINVAL invalid parameter passed to function
    @retval -ENOSPC conversation table is full, wait and try sending later
    @retval 0                       request sent
    @retval !0                      error trying to send request

zigbee_zdo_debug int zdo_send_nwk_addr_req	(	wpan_dev_t *	dev,
		const addr64 FAR *	ieee_be,
		uint16_t FAR *	net
	)

Given a device's IEEE (64-bit) address, get its 16-bit network address by unicasting a ZDO NWK_addr request to it.

After calling this function, *net is set to ZDO_NET_ADDR_PENDING.

When a SUCCESS response comes back, *net is set to the 16-bit network address in the response.

When an ERROR response comes back, *net is set to ZDO_NET_ADDR_ERROR.

If a timeout occurs waiting for a response, *net is set to ZDO_NET_ADDR_TIMEOUT.

(So the caller needs to wait until (*net != ZDO_NET_ADDR_PENDING)).

Parameters

[in]	dev	wpan_dev_t to send request
[in]	ieee_be	IEEE address (in big-endian byte order) of device we're seeking a network address for
[out]	net	location to store the 16-bit network address when the NWK_addr response comes back.

Return values

-EINVAL	invalid parameter passed to function
-ENOSPC	conversation table is full, wait and try sending later
0	request sent
!0	error trying to send request

zigbee_zdo_debug int zdo_send_response	(	const wpan_envelope_t FAR *	request,
		const void FAR *	response,
		uint16_t	length
	)

Send a response to a ZDO request.

Automatically builds the response envelope and sets its cluster ID (to the request's cluster ID with the high bit set) before sending.

Parameters

[in]	request	envelope of original request
[in]	response	frame to send in response
[in]	length	length of response

Return values

0	sent response
!0	error sending response

zigbee_zdo_debug int zdo_simple_desc_request	(	wpan_envelope_t *	envelope,
		uint16_t	addr_of_interest,
		uint_fast8_t	endpoint,
		wpan_response_fn	callback,
		const void FAR *	context
	)

Send a ZDO Simple Descriptor Request.

The simple descriptor contains information specific to each of a node's endpoints. Use the ZDO Simple Descriptor Request to get a descriptor for an endpoint on a remote node.

Parameters

[in]	envelope	Envelope created with wpan_envelope_create(). Only dev, ieee_address and network_address should be set, all other structure elements should be zero. Address may match addr_of_interest or an alternative device that contains the discovery information of that device (like an end device's parent).
[in]	addr_of_interest	Network address of the device for which the simple descriptor is required.
[in]	endpoint	Endpoint of interest, a value from 1 to 254.
[in]	callback	Function to receive the Simple Descriptor Response. See documentation for wpan_response_fn for this callback's API.
[in]	context	Context pointer passed to the callback along with the response.

Return values

0	request sent
!0	error sending request

Variable Documentation

zdo_bind_address_req_t address

uint8_t capability

see ZDO_CAPABILITY_* macros

uint16_t cluster_id_le

uint8_t desc_capability

uint16_t device_id_le

endpoint's device ID (little-endian)

uint8_t device_version

upper 4 bits are reserved

uint8_t dst_addr_mode

addr64 dst_address_le

uint8_t dst_endpoint

uint8_t endpoint

0x01 to 0xFE

uint8_t ep_count

uint8_t flags

uint8_t flags1

zdo_bind_group_req_t group

uint16_t group_addr_le

zdo_bind_req_header_t header

addr64 ieee_address_le

addr64 ieee_remote_le

uint16_t in_cluster_list[1]

variable length

uint8_t length

length of simple descriptor

uint8_t mac_capability

uint16_t manufacturer_le

uint8_t match_length

uint8_t max_buffer

uint16_t max_incoming_le

uint16_t max_outgoing_le

uint16_t net_remote_le

uint16_t network_addr_le

device's network address (little-endian)

zdo_node_desc_t node_desc

uint8_t num_assoc_dev

uint8_t num_in_clusters

uint16_t out_cluster_list[1]

variable length

uint8_t power1

combination of ZDO_POWER1_* macros

zdo_power_desc_t power_desc

uint16_t profile_id_le

endpoint's profile ID (little-endian)

uint8_t request_type

See ZDO_REQUEST_TYPE_* macros.

uint16_t server_mask_le

uint8_t src_endpoint

uint8_t start_index