Cluster Client support code

Files
file	zcl_client.h
	Code to support ZCL client clusters.
file	zcl_client.c
	Code to support ZCL client clusters.

Data Structures
struct	zcl_client_read_t

Typedefs
typedef const char *(*	zcl_format_utctime_fn) (char dest[40], zcl_utctime_t utctime)

Functions
int	zcl_find_and_read_attributes (wpan_dev_t *dev, const uint16_t *clusters, const zcl_client_read_t FAR *cr)
	Use ZDO Match Descriptor Requests to find devices with a given profile/cluster and then automatically send a ZCL Read Attributes request for some of that cluster's attributes. More...
int	zcl_process_read_attr_response (zcl_command_t *zcl, const zcl_attribute_base_t FAR *attr_table)
	Process a Read Attributes Response and populate the attibute values into an attribute table as if it was a Write Attributes Request. More...
int	_zcl_send_read_from_zdo_match (wpan_conversation_t FAR *conversation, const wpan_envelope_t FAR *envelope)
int	zdo_send_match_desc (wpan_dev_t *dev, const uint16_t *clusters, uint16_t profile_id, wpan_response_fn callback, const void FAR *context)
	Send a ZDO Match Descriptor request for a list of cluster IDs. More...
int	zcl_client_read_attributes (wpan_envelope_t FAR *envelope, const zcl_client_read_t *client_read)
	Send a Read Attributes request for attributes listed in client_read. More...
int	zcl_create_attribute_records (void FAR *buffer, uint8_t bufsize, const zcl_attribute_base_t FAR **p_attr_list)
	From a list of attributes, write ID (in little-endian byte order), type and value to a buffer as would be done in a Write Attributes Request. More...
int	zcl_send_write_attributes (wpan_envelope_t *envelope, const zcl_attribute_base_t FAR *attr_list)
	Send one or more Write Attributes Requests to a node on the network. More...
int	zcl_print_attribute_value (uint8_t type, const void *value, int value_length)
	Formats an attribute value and prints it to stdout. More...
int	zcl_print_array_value (const void *value, int value_length)
	Print Read Attributes Response value of an array attribute. More...
int	zcl_print_struct_value (const void *value, int value_length)
	Print Read Attributes Response value of a structure attribute. More...
const char *	_zcl_format_utctime (char dest[40], zcl_utctime_t utctime)
	Default function for zcl_format_utctime function pointer. More...

Variables
zcl_format_utctime_fn	zcl_format_utctime
	Pointer to function that converts a zcl_utctime_t value to a human-readable timestamp. More...
zcl_format_utctime_fn	zcl_format_utctime = _zcl_format_utctime
	Pointer to function that converts a zcl_utctime_t value to a human-readable timestamp. More...

Detailed Description

Function Documentation

const char* _zcl_format_utctime	(	char	dest[40],
		zcl_utctime_t	utctime
	)

Default function for zcl_format_utctime function pointer.

References xbee_gmtime().

int _zcl_send_read_from_zdo_match	(	wpan_conversation_t FAR *	conversation,
		const wpan_envelope_t FAR *	envelope
	)

Process responses to ZDO Match_Desc broadcast sent by zdo_send_match_desc() and generate ZCL Read Attributes request for the attributes in the related conversation's context (a pointer to a zcl_client_read_t object).

The Read Attributes Responses are handled by the function registered to the cluster in the endpoint table.

Parameters

[in]	conversation	matching entry in converstation table (which contains a context pointer)
[in]	envelope	envelope of response or NULL if conversation timed out

Return values

0	send ZCL request for current time
!0	error sending ZCL request for current time

Todo:

support a flag in the client_read object for sending ZCL request to first endpoint in list (current behavior) or all endpoints (for example, to query ALL meter endpoints on ALL radios).

Todo:

find a way to track whether frame came in from broadcast or unicast response – if unicast, can return WPAN_CONVERSATION_END

References wpan_envelope_t::cluster_id, wpan_envelope_t::dest_endpoint, FAR, wpan_cluster_table_entry_t::flags, hex_dump(), HEX_DUMP_FLAG_TAB, le16toh, wpan_envelope_t::network_address, wpan_envelope_t::profile_id, wpan_envelope_t::source_endpoint, WPAN_CLUST_FLAG_CLIENT, wpan_cluster_match(), WPAN_CONVERSATION_CONTINUE, WPAN_CONVERSATION_END, wpan_envelope_reply(), zcl_client_read_attributes(), and ZDO_MATCH_DESC_RSP.

Referenced by zcl_find_and_read_attributes().

int zcl_client_read_attributes	(	wpan_envelope_t FAR *	envelope,
		const zcl_client_read_t *	client_read
	)

Send a Read Attributes request for attributes listed in client_read.

Parameters

[in,out]	envelope	addressing information for sending a ZCL Read Attributes request; this function fills in the payload and length
[in]	client_read	data structure used by ZCL clients to do ZDO discovery followed by ZCL attribute reads

Return values

0	successfully sent request
!0	error sending request

References FAR, htole16, wpan_endpoint_next_trans(), wpan_envelope_dump(), wpan_envelope_send(), ZCL_ATTRIBUTE_END_OF_LIST, ZCL_CMD_READ_ATTRIB, ZCL_FRAME_CLIENT_TO_SERVER, ZCL_FRAME_GENERAL, ZCL_FRAME_MFG_SPECIFIC, and ZCL_FRAME_TYPE_PROFILE.

Referenced by _zcl_send_read_from_zdo_match().

int zcl_create_attribute_records	(	void FAR *	buffer,
		uint8_t	bufsize,
		const zcl_attribute_base_t FAR **	p_attr_list
	)

From a list of attributes, write ID (in little-endian byte order), type and value to a buffer as would be done in a Write Attributes Request.

The attribute list should be an array of attribute records, ending with an attribute ID of ZCL_ATTRIBUTE_END_OF_LIST.

Parameters

[out]	buffer	buffer to write values to
[in]	bufsize	size of buffer
[in,out]	p_attr_list	pointer to the attribute list to encode in buffer; points to next attribute to encode if buffer is filled

Returns

number of bytes written to buffer

References FAR, htole16, ZCL_ATTRIBUTE_END_OF_LIST, zcl_attribute_get_next(), and zcl_encode_attribute_value().

Referenced by zcl_send_write_attributes().

int zcl_find_and_read_attributes	(	wpan_dev_t *	dev,
		const uint16_t *	clusters,
		const zcl_client_read_t FAR *	cr
	)

Use ZDO Match Descriptor Requests to find devices with a given profile/cluster and then automatically send a ZCL Read Attributes request for some of that cluster's attributes.

Parameters

[in]	dev	device to use for time request
[in]	clusters	pointer to list of server clusters to search for, must end with WPAN_CLUSTER_END_OF_LIST
[in]	cr	zcl_client_read record containing information on the request (endpoint, attributes, etc.); must be a static object (not an auto variable) since the ZDO responder will need to access it

Return values

0	request sent
!0	error sending request

References _zcl_send_read_from_zdo_match(), and zdo_send_match_desc().

Referenced by zcl_time_find_servers().

int zcl_print_array_value	(	const void *	value,
		int	value_length
	)

Print Read Attributes Response value of an array attribute.

Helper function for zcl_print_attribute_value(), takes a pointer to the "value" field of a Read Attributes Response for an array type, formats it and prints to stdout.

 Example:
of 3 UNSIGNED_8BIT
   [0] = 0x54 = 84
   [1] = 0x42 = 66
   [2] = 0x43 = 67

Parameters

[in]	value	pointer to ZCL-encoded array value
[in]	value_length	number of bytes at value

Return values

-EINVAL	value is NULL or value_length is too small
>=3	number of bytes from value consumed by function

See also

zcl_print_attribute_value, zcl_print_struct_value

References EINVAL, zcl_print_attribute_value(), and zcl_type_name().

Referenced by zcl_print_attribute_value().

int zcl_print_attribute_value	(	uint8_t	type,
		const void *	value,
		int	value_length
	)

Formats an attribute value and prints it to stdout.

Parameters

[in]	type	ZCL datatype of attribute's value
[in]	value	pointer to the ZCL-encoded value
[in]	value_length	number of bytes at value

Return values

-EINVAL	value is NULL or value_length is too small
>=2	number of bytes from value consumed by function

See also

zcl_print_array_value, zcl_print_struct_value

References addr64_format(), EINVAL, hex_dump(), HEX_DUMP_FLAG_TAB, memcpy_letobe, PRId32, PRIu32, PRIX32, zcl_format_utctime, zcl_print_array_value(), zcl_print_struct_value(), zcl_sizeof_type(), ZCL_T_SIGNED, ZCL_TYPE_ARRAY, ZCL_TYPE_BAG, ZCL_TYPE_ID_ATTRIB, ZCL_TYPE_ID_CLUSTER, ZCL_TYPE_IEEE_ADDR, zcl_type_info, ZCL_TYPE_SET, ZCL_TYPE_STRING_CHAR, ZCL_TYPE_STRUCT, ZCL_TYPE_TIME_UTCTIME, and ZCL_TYPE_UNKNOWN.

Referenced by zcl_print_array_value(), and zcl_print_struct_value().

int zcl_print_struct_value	(	const void *	value,
		int	value_length
	)

Print Read Attributes Response value of a structure attribute.

Helper function for zcl_print_attribute_value(), takes a pointer to the "value" field of a Read Attributes Response for a structure type, formats it and prints to stdout.

 Example:
with 3 elements
   .element0 (TIME_UTCTIME) = 2012-01-01 00:00:00
   .element1 (UNSIGNED_8BIT) = 0xAA = 170
   .element2 (SIGNED_8BIT) = 0xAA = -86

Parameters

[in]	value	pointer to ZCL-encoded structure value
[in]	value_length	number of bytes at value

Return values

-EINVAL	value is NULL or value_length is too small
>=2	number of bytes from value consumed by function

See also

zcl_print_attribute_value, zcl_print_array_value

References EINVAL, zcl_print_attribute_value(), and zcl_type_name().

Referenced by zcl_print_attribute_value().

int zcl_process_read_attr_response	(	zcl_command_t *	zcl,
		const zcl_attribute_base_t FAR *	attr_table
	)

Process a Read Attributes Response and populate the attibute values into an attribute table as if it was a Write Attributes Request.

Used in ZCL clients that want to read a lot of ZCL attributes. The client has a mirrored copy of the attributes on the target, and this function is used to populate that copy using the Read Attributes Responses.

Parameters

[in]	zcl	ZCL command to process
[in]	attr_table	start of the attribute list to use for storing attribute responses

Returns

ZCL status value to send in a default response

References zcl_attribute_write_rec_t::buffer, zcl_attribute_write_rec_t::buflen, FAR, zcl_attribute_write_rec_t::flags, zcl_command_t::length, zcl_attribute_write_rec_t::status, ZCL_ATTR_WRITE_FLAG_ASSIGN, ZCL_ATTR_WRITE_FLAG_READ_RESP, zcl_parse_attribute_record(), and zcl_command_t::zcl_payload.

int zcl_send_write_attributes	(	wpan_envelope_t *	envelope,
		const zcl_attribute_base_t FAR *	attr_list
	)

Send one or more Write Attributes Requests to a node on the network.

Note

This function API and is likely to change in a future release to include a Manufacturer ID and flags for sending server-to-client and "undivided" write requests.

Parameters

[in,out]	envelope	envelope to use for sending request; payload and length cleared on function exit
[in]	attr_list	attributes with values to send a Write Attributes Request for

Return values

-EINVAL	NULL parameter passed, or couldn't find source endpoint based on envelope
<0	error trying to send request (for large writes, one or more requests may have been successful)
0	request(s) sent

References EINVAL, wpan_envelope_t::length, wpan_envelope_t::payload, wpan_endpoint_next_trans(), wpan_endpoint_of_envelope(), wpan_envelope_dump(), wpan_envelope_send(), ZCL_ATTRIBUTE_END_OF_LIST, ZCL_CMD_WRITE_ATTRIB, zcl_create_attribute_records(), ZCL_FRAME_CLIENT_TO_SERVER, ZCL_FRAME_DISABLE_DEF_RESP, ZCL_FRAME_GENERAL, and ZCL_FRAME_TYPE_PROFILE.

int zdo_send_match_desc	(	wpan_dev_t *	dev,
		const uint16_t *	clusters,
		uint16_t	profile_id,
		wpan_response_fn	callback,
		const void FAR *	context
	)

Send a ZDO Match Descriptor request for a list of cluster IDs.

Parameters

[in]	dev	device to use for time request
[in]	clusters	pointer to list of server clusters to search for, must end with WPAN_CLUSTER_END_OF_LIST
[in]	profile_id	profile ID associated with the cluster IDs (cannot be WPAN_APS_PROFILE_ANY)
[in]	callback	function that will process the ZDO Match Descriptor responses; see wpan_response_fn for the callback's API
[in]	context	context to pass to callback in the wpan_conversation_t structure

Return values

0	request sent
!0	error sending request

See also

zcl_find_and_read_attributes()

Todo:

update API to allow for unicast request in addition to broadcast

References _WPAN_IEEE_ADDR_BROADCAST, wpan_envelope_t::cluster_id, wpan_envelope_t::dev, EINVAL, wpan_envelope_t::ieee_address, wpan_envelope_t::length, wpan_envelope_t::network_address, wpan_envelope_t::payload, wpan_conversation_register(), wpan_envelope_dump(), wpan_envelope_send(), WPAN_NET_ADDR_BCAST_NOT_ASLEEP, WPAN_NET_ADDR_UNDEFINED, zdo_endpoint_state(), ZDO_MATCH_DESC_REQ, and zdo_match_desc_request().

Referenced by zcl_find_and_read_attributes().

Variable Documentation

zcl_format_utctime_fn zcl_format_utctime

Pointer to function that converts a zcl_utctime_t value to a human-readable timestamp.

Defaults to a function that formats timestamps as "YYYY-MM-DD HH:MM:SS UTC" or "[Invalid Timestamp] if utctime is 0xFFFFFFFF. Can be overriden by the user program to a function that uses another format. Strings must be limited to 40 characters.

Parameters

[out]	dest	buffer to hold the formatted string
[in]	utctime	time value to format

Returns

Value of parameter dest.

Referenced by zcl_print_attribute_value().

zcl_format_utctime_fn zcl_format_utctime = _zcl_format_utctime

Pointer to function that converts a zcl_utctime_t value to a human-readable timestamp.

Defaults to a function that formats timestamps as "YYYY-MM-DD HH:MM:SS UTC" or "[Invalid Timestamp] if utctime is 0xFFFFFFFF. Can be overriden by the user program to a function that uses another format. Strings must be limited to 40 characters.

Parameters

[out]	dest	buffer to hold the formatted string
[in]	utctime	time value to format

Returns

Value of parameter dest.

Referenced by zcl_print_attribute_value().