XBee Firmware Library: ZigBee Cluster Library

unsigned int uint16_t

An unsigned integer variable 16 bits.

Definition: types.h:46

uint16_t id_le

Definition: zcl.h:453

General format for an attribute, used for Write Attributes and Report Attributes commands.

typedef struct zcl_attribute_base_t zcl_attribute_base_t

Basic structure for storing a list of attributes in a cluster. If .min and .max are both set to 0, there isn't a limit

Note: Consider putting type after id – it would then be possible to have macros for attributes that include the id AND type.

typedef struct zcl_attribute_full_t zcl_attribute_full_t

Use this structure for attributes with min/max values or the need to have a read/write function. Be sure to set the ZCL_ATTRIB_FLAG_FULL flag in .base.flags so the attribute is parsed with the correct type.

typedef union zcl_attribute_minmax_t zcl_attribute_minmax_t

typedef struct zcl_attribute_tree_t zcl_attribute_tree_t

typedef uint_fast8_t(* zcl_attribute_update_fn) (const struct zcl_attribute_full_t FAR *entry)

Function pointer assigned to a ZCL attribute record, called to update the value of the given attribute.

Necessary for attributes that are tied to physical hardware (only updated when requested) or attributes that change over time (as with the ZCL Identify cluster).

If the return value is not ZCL_STATUS_SUCCESS, the ZCL Read Attributes handler will return that as an error in the response frame.

Parameters

[in,out] entry attribute to update

Return values

ZCL_STATUS_SUCCESS	successfully updated value
ZCL_STATUS_HARDWARE_FAILURE	unable to update value due to hardware problem
ZCL_STATUS_SOFTWARE_FAILURE	unable to update value due to software problem

See also: zcl_attribute_write_fn(), zcl_attribute_full_t

typedef int(* zcl_attribute_write_fn) (const struct zcl_attribute_full_t FAR *entry, zcl_attribute_write_rec_t *rec)

Function pointer assigned to a ZCL attribute record, called instead of zcl_decode_attribute() to process a Write Request for the attribute.

This function typically calls zcl_decode_attribute() to convert the request to a temporary variable and then perform additional checks on it before assigning to the actual variable.

Parameters

[in]	entry	attribute to update
[in,out]	rec	record from Write Request with new value

Returns: number of bytes consumed from Write Request

See also: zcl_attribute_update_fn(), zcl_attribute_full_t

typedef struct zcl_attribute_write_rec_t zcl_attribute_write_rec_t

typedef struct zcl_command_t zcl_command_t

Structure populated by zcl_command_build() with the ZCL header from a received ZCL command frame. Does not look at the ZCL payload.

zcl_default_response_t

Initial value:

{

uint8_t command

zcl_discover_attrib_resp_t

unsigned char uint8_t

A unsigned char variable 8 bits.

Definition: types.h:43

command

uint8_t command

Definition: zcl.h:155

Used for #ZCL_CMD_DEFAULT_RESP.

Initial value:

{
        
        uint8_t                                                 discovery_complete

Used for #ZCL_CMD_DISCOVER_ATTRIB_RESP.

zcl_discover_attrib_t

Initial value:

{

uint16_t start_attrib_id_le

unsigned int uint16_t

An unsigned integer variable 16 bits.

Definition: types.h:46

Used for #ZCL_CMD_DISCOVER_ATTRIB.

zcl_header_common_t

Initial value:

{

uint8_t sequence

sequence

uint8_t sequence

Definition: zcl.h:189

unsigned char uint8_t

A unsigned char variable 8 bits.

Definition: types.h:43

Common portion of ZCL header (appears after optional Manufacturer Code)

zcl_header_nomfg_t

Initial value:

{

uint8_t frame_control

unsigned char uint8_t

A unsigned char variable 8 bits.

Definition: types.h:43

ZLC header structure used when building a normal (non-manufacturer-specific response frame.

zcl_header_response_t

Initial value:

{
        union {
                PACKED_STRUCT {
                        uint8_t         frame_control;
                        uint16_t                mfg_code_le;
                } mfg;
                PACKED_STRUCT {
                        uint16_t                dummy;
                        uint8_t         frame_control;
                } std;
        } u

ZCL header structure used for building response frames that may or may not be manufacturer-specific. Frame is sent starting with element .u.mfg.frame_control or .u.std.frame_control.

zcl_header_t

Initial value:

{

uint8_t frame_control

unsigned char uint8_t

A unsigned char variable 8 bits.

Definition: types.h:43

General header for casting onto an incoming frame. Reference .type.mfg if (.frame_control & ZCL_FRAME_MFG_SPECIFIC != 0). Reference .type.std otherwise.

zcl_header_withmfg_t

Initial value:

{

uint8_t frame_control

unsigned char uint8_t

A unsigned char variable 8 bits.

Definition: types.h:43

ZLC header structure used when building a manufacturer-specific response frame.

zcl_read_struct_attrib_t

Initial value:

{

uint16_t attrib_id_le

unsigned int uint16_t

An unsigned integer variable 16 bits.

Definition: types.h:46

attrib_id_le

uint16_t attrib_id_le

Definition: zcl.h:465

zcl_rec_attrib_report_t

Initial value:

{

uint16_t id_le

unsigned int uint16_t

An unsigned integer variable 16 bits.

Definition: types.h:46

zcl_rec_read_attrib_array_resp_t

uint16_t id_le

Definition: zcl.h:453

Used for #ZCL_CMD_DISCOVER_ATTRIB_RESP.

Initial value:

{

uint16_t id_le

unsigned int uint16_t

An unsigned integer variable 16 bits.

Definition: types.h:46

zcl_rec_read_attrib_error_resp_t

uint16_t id_le

Definition: zcl.h:453

Initial value:

{

uint16_t id_le

unsigned int uint16_t

An unsigned integer variable 16 bits.

Definition: types.h:46

zcl_rec_read_attrib_resp_t

uint16_t id_le

Definition: zcl.h:453

Initial value:

{

uint16_t id_le

unsigned int uint16_t

An unsigned integer variable 16 bits.

Definition: types.h:46

zcl_rec_read_attrib_struct_resp_t

uint16_t id_le

Definition: zcl.h:453

Used for #ZCL_CMD_READ_ATTRIB_RESP.

Initial value:

{

uint16_t id_le

unsigned int uint16_t

An unsigned integer variable 16 bits.

Definition: types.h:46

zcl_rec_read_report_cfg_t

uint16_t id_le

Definition: zcl.h:453

Initial value:

{

uint8_t direction

zcl_rec_report_error_resp_t

unsigned char uint8_t

A unsigned char variable 8 bits.

Definition: types.h:43

direction

uint8_t direction

Definition: zcl.h:496

Initial value:

{

uint8_t status

uint8_t status

Definition: zcl.h:423

zcl_rec_report_receive_resp_t

unsigned char uint8_t

A unsigned char variable 8 bits.

Definition: types.h:43

Initial value:

{

uint8_t status

uint8_t status

Definition: zcl.h:423

unsigned char uint8_t

A unsigned char variable 8 bits.

Definition: types.h:43

zcl_rec_report_receive_t

Initial value:

{

uint8_t direction

zcl_rec_report_send_resp_t

unsigned char uint8_t

A unsigned char variable 8 bits.

Definition: types.h:43

direction

uint8_t direction

Definition: zcl.h:496

Initial value:

{

uint8_t status

uint8_t status

Definition: zcl.h:423

unsigned char uint8_t

A unsigned char variable 8 bits.

Definition: types.h:43

zcl_rec_report_send_t

Initial value:

{

uint8_t direction

zcl_rec_reporting_status_t

unsigned char uint8_t

A unsigned char variable 8 bits.

Definition: types.h:43

direction

uint8_t direction

Definition: zcl.h:496

typedef union zcl_rec_report_t zcl_rec_reporting_config_t

Initial value:

{

uint8_t status

uint8_t status

Definition: zcl.h:423

zcl_rec_write_attrib_status_t

unsigned char uint8_t

A unsigned char variable 8 bits.

Definition: types.h:43

Initial value:

{

uint8_t status

uint8_t status

Definition: zcl.h:423

zcl_rec_write_struct_attrib_resp_t

unsigned char uint8_t

A unsigned char variable 8 bits.

Definition: types.h:43

Used for #ZCL_CMD_WRITE_ATTRIB_RESP.

Initial value:

{

uint8_t status

uint8_t status

Definition: zcl.h:423

zcl_rec_write_struct_attrib_t

unsigned char uint8_t

A unsigned char variable 8 bits.

Definition: types.h:43

Initial value:

{

uint16_t id_le

unsigned int uint16_t

An unsigned integer variable 16 bits.

Definition: types.h:46

uint16_t id_le

Definition: zcl.h:453

zcl_selector_t

Initial value:

{

uint8_t indicator

unsigned char uint8_t

A unsigned char variable 8 bits.

Definition: types.h:43

typedef struct zcl_struct_element_t zcl_struct_element_t

A zcl_struct_t contains an array of these elements, describing each element in the structure and its offset from the zcl_struct_t.base_address.

typedef struct zcl_struct_t zcl_struct_t

If a zcl_attribute_base_t has a type of ZCL_TYPE_STRUCT, its .value points to this structure.

Function Documentation

zigbee_zcl_debug int _zcl_discover_attributes ( zcl_command_t * cmd )

zigbee_zcl_debug int _zcl_encode_array_value	(	uint8_t FAR *	buffer,
		int16_t	bufsize,
		const zcl_array_t FAR *	array
	)

zigbee_zcl_debug int _zcl_encode_struct_value	(	uint8_t FAR *	buffer,
		int16_t	bufsize,
		const zcl_struct_t FAR *	zcl_struct
	)

zigbee_zcl_debug int _zcl_read_attributes ( zcl_command_t * cmd )

zigbee_zcl_debug int _zcl_write_attributes ( zcl_command_t * cmd )

zigbee_zcl_debug const zcl_attribute_base_t FAR * zcl_attribute_get_next ( const zcl_attribute_base_t FAR * entry )

Return a pointer to the next attribute entry from an attribute table.

Parameters

[in] entry current entry from the table

Return values

NULL	entry was NULL
!NULL	pointer to next attribute record

Note: If entry points to the last entry in the table, this function will return the same address instead of advancing off the end of the table.

See also: zcl_find_attribute

zigbee_zcl_debug int zcl_build_header	(	zcl_header_response_t *	rsp,
		zcl_command_t *	cmd
	)

Support function to fill in a ZCL response header.

Set the frame_control, sequence and optional mfg_code fields of the ZCL response header, and return the offset to the actual start of the header (non-mfg specific skips the first two bytes).

Parameters

[out]	rsp	buffer to store header of response
[in]	cmd	command we're responding to

Return values

0	responding to manufacturer-specific command
2	responding to non-manufacturer-specific command
-EINVAL	invalid parameter passed to function

zigbee_zcl_debug int zcl_check_minmax	(	const zcl_attribute_base_t FAR *	entry,
		const uint8_t FAR *	buffer_le
	)

Checks whether a new value from a Write Attributes command is within the limits specified for a given attribute.

Parameters

[in]	entry	entry to use for min/max check
[in]	buffer_le	buffer with new value (in little-endian byte order), from write attributes command

Return values

0	new value is within range (or attribute doesn't have a min/max)
-EINVAL	invalid parameter passed to function
!0	value is out of range

zigbee_zcl_debug int zcl_command_build	(	zcl_command_t *	cmd,
		const wpan_envelope_t FAR *	envelope,
		zcl_attribute_tree_t FAR *	tree
	)

Parse a ZCL request and store in a zcl_command_t structure with fields in fixed locations (therefore easier to use than the variable-length frame header).

Also uses the direction bit and manufacturer ID to search the attribute tree for the correct list of attributes.

Parameters

[out]	cmd	buffer to store parsed ZCL command
[in]	envelope	envelope from received message
[in]	tree	pointer to attribute tree for cluster or NULL if the cluster doesn't have any attributes (typically passed in via endpoint dispatcher)

Return values

0	parsed payload from `envelope` into `cmd`
-EINVAL	invalid parameter passed to function
-EBADMSG	frame is too small for ZCL header's frame_control value

zigbee_zcl_debug void zcl_command_dump ( const zcl_command_t * cmd )

Debugging routine that dumps contents of a parsed ZCL command structure to STDOUT.

Parameters

[in] cmd zcl_command_t structure populated by zcl_command_build()

zigbee_zcl_debug uint32_t zcl_convert_24bit	(	const void FAR *	value_le,
		bool_t	extend_sign
	)

Convert a 24-bit (3-byte) little-endian value to a 32-bit value in host byte order.

Parameters

[in]	value_le	pointer to 3 bytes to convert
[in]	extend_sign	if TRUE, set high byte of result to 0xFF if top bit of 24-bit value is set

Returns: A 32-bit, host-byte-order version of the 24-bit, little-endian value passed in.

zigbee_zcl_debug int zcl_decode_attribute	(	const zcl_attribute_base_t FAR *	entry,
		zcl_attribute_write_rec_t *	rec
	)

Decode attribute value from a Write Attribute Request or Read Attribute Response record and optionally write to entry.

Parameters

[in]	entry	entry from attribute table
[in,out]	rec	state information for parsing write request

Return values

>=0	number of bytes consumed from `rec->buffer`
-EINVAL	invalid parameter passed to function

zigbee_zcl_debug int zcl_default_response	(	zcl_command_t *	request,
		uint8_t	status
	)

Send a Default Response (#ZCL_CMD_DEFAULT_RESP) to a given command.

Parameters

[in]	request	command we're responding to
[in]	status	status to use in the response (see ZCL_STATUS_* macros under "ZCL Status Enumerations" in zigbee/zcl.h)

Return values

0	successfully sent response, or response not required (message was broadcast, sent to the broadcast endpoint, or sender set the disable default response bit)
!0	error on send
-EINVAL	invalid parameter passed to function

zigbee_zcl_debug int zcl_encode_attribute_value	(	uint8_t FAR *	buffer,
		int16_t	bufsize,
		const zcl_attribute_base_t FAR *	entry
	)

Format a ZCL attribute's value for a Read Attributes Response or a Write Attributes Request.

Copies the value of attribute entry to buffer in little-endian byte order. Will not write more than bufsize bytes. Used to build ZCL frames.

Parameters

[out]	buffer	buffer to store encoded attribute
[in]	bufsize	number of bytes available in `buffer`
[in]	entry	attribute to encode into `buffer`

Return values

-ZCL_STATUS_SOFTWARE_FAILURE	invalid parameter passed in
-ZCL_STATUS_DEFINED_OUT_OF_BAND	ghost attribute with NULL `value`
-ZCL_STATUS_INSUFFICIENT_SPACE	buffer too small to encode value
-ZCL_STATUS_FAILURE	unknown/unsupported attribute type
-ZCL_STATUS_HARDWARE_FAILURE	failure updating attribute value
-ZCL_STATUS_SOFTWARE_FAILURE	failure updating attribute value
>=0	number of bytes written

void zcl_envelope_payload_dump ( const wpan_envelope_t * envelope )

Debugging routine that parses an envelope payload as a ZCL command and dumps a parsed copy to STDOUT.

Parameters

[in] envelope wpan_envelope_t structure with a ZCL command payload

zigbee_zcl_debug const zcl_attribute_base_t FAR * zcl_find_attribute	(	const zcl_attribute_base_t FAR *	entry,
		uint16_t	search_id
	)

Search the attribute table starting at entry, for attribute ID search_id.

Parameters

[in]	entry	starting entry for search
[in]	search_id	attribute ID to look for

Return values

NULL	attribute id `search_id` not in list
!NULL	pointer to attribute record

zigbee_zcl_debug int zcl_general_command	(	const wpan_envelope_t FAR *	envelope,
		void FAR *	context
	)

Handler for ZCL General Commands.

Used as the handler for attribute-only clusters (e.g., Basic Cluster), or called from a cluster's handler for commands it doesn't handle.

Will send a Default Response for commands it can't handle.

Currently does not support attribute reporting.

Parameters

[in]	envelope	envelope from received message
[in]	context	pointer to attribute tree for cluster or NULL if the cluster doesn't have any attributes (typically passed in via endpoint dispatcher)

Return values

0	command was processed, including sending a possible response
!0	error sending response or processing command

zigbee_zcl_debug int zcl_invalid_cluster	(	const wpan_envelope_t FAR *	envelope,
		wpan_ep_state_t FAR *	ep_state
	)

Called if a request comes in for an invalid endpoint/cluster combination.

Sends a Default Response (#ZCL_CMD_DEFAULT_RESP) of #ZCL_STATUS_FAILURE unless the received command was a Default Response or was broadcast.

Parameters

[in]	envelope	envelope from received message
[in]	ep_state	pointer to endpoint's wpan_ep_state_t

Return values

0	command was a default response (and therefore ignored), or a default response was successfully sent
!0	error sending response

zigbee_zcl_debug int zcl_invalid_command ( const wpan_envelope_t FAR * envelope )

Called if a request comes in for an invalid command on a valid endpoint/cluster combination.

Sends a Default Response (#ZCL_CMD_DEFAULT_RESP) unless the received command was a Default Response or was broadcast. Depending on the command received, the response will be one of:

ZCL_STATUS_UNSUP_CLUSTER_COMMAND
ZCL_STATUS_UNSUP_GENERAL_COMMAND
ZCL_STATUS_UNSUP_MANUF_CLUSTER_COMMAND
ZCL_STATUS_UNSUP_MANUF_GENERAL_COMMAND

Parameters

[in] envelope envelope from received message

Return values

0	default response was successfully sent, or command did not require a default response
!0	error building or sending response

zigbee_zcl_debug int zcl_parse_attribute_record	(	const zcl_attribute_base_t FAR *	entry,
		zcl_attribute_write_rec_t *	write_rec
	)

Parse an attribute record from a Write Attributes Request or a Read Attributes Response and possibly store the new attribute value.

If #ZCL_ATTR_WRITE_FLAG_READ_RESP is set in write_rec->flags, write_rec->buffer will be parsed as a Read Attributes Response record. Otherwise, it's parsed as a Write Attributes Request record.

Parameters

[in]	entry	attribute table to search or NULL if there aren't any attributes on this cluster
[in,out]	write_rec	state information for parsing write request

Return values

>=0	number of bytes consumed from buffer
-EINVAL	invalid parameter passed to function

zigbee_zcl_debug int zcl_send_response	(	zcl_command_t *	request,
		const void FAR *	response,
		uint16_t	length
	)

Send a response to a ZCL command.

Uses information from the command received to populate fields in the response.

Parameters

[in]	request	command to respond to
[in]	response	payload to send as response
[in]	length	number of bytes in response

Return values

0	successfully sent response
!0	error on send

zigbee_zcl_debug const char * zcl_status_text ( uint_fast8_t status )

Converts a ZCL status byte (one of the ZCL_STATUS_* macros) into a string.

Parameters

[in] status status byte to convert

Returns: pointer to an unmodifiable string with a description of the status

Variable Documentation

float _float

int32_t _signed

uint32_t _unsigned

zcl_rec_attrib_report_t attrib[1]

uint16_t attrib_id_le

uint8_t attrib_type

const zcl_attribute_base_t FAR* attributes

Appropriate list of attributes on this device, related to the command. Based on the direction bit from frame_control and the mfg_code field.

zcl_attribute_base_t base

const void FAR* base_address

base address of structure

const uint8_t FAR* buffer

Source data to write to attribute.

int16_t buflen

Number of bytes in buffer.

const zcl_attribute_base_t FAR* client

List of attributes for the CLIENT cluster (or NULL if none).

uint8_t command

command byte from the ZCL header

zcl_header_common_t common

common

uint16_t count_le

number of elements to follow

uint16_t current_count

current number of elements

uint8_t direction

const zcl_struct_element_t FAR* element

elements in the structure

uint16_t element_count

number of elements in structure

uint16_t element_size

number of bytes in each element

uint8_t element_type

uint8_t elements[1]

mult. uint8_t type and variable-length value

const wpan_envelope_t FAR* envelope

envelope for the received command, envelope's payload and length include the ZCL header

uint8_t flags

Parsing flags (see ZCL_ATTR_WRITE_FLAG_* macros for valid flags).

uint8_t flags

uint8_t frame_control

frame control byte from the ZCL header

uint16_t id

uint16_t id_le

uint16_t index_le[15]

int16_t length

length of the ZCL payload

uint16_t manufacturer_id

ID for manufacturer-specific attributes or ZCL_MFG_NONE if general.

zcl_attribute_minmax_t max

Maximum value for attribute, assumes 32-bit limit. For string attributes, the maximum length that can be stored at value.

uint16_t max_count

maximum number of elements to store

uint16_t max_interval_le

uint8_t max_return_count

mfg

manufacturer-specific extension

mfg

manufacturer-specific extension

uint16_t mfg_code

manufacturer code from the ZCL header, in host byte order, or 0x0000 if not mfg specific

uint16_t mfg_code_le

zcl_attribute_minmax_t min

Minimum value for attribute (currently unused until I pick a value to represent "none").

uint16_t min_interval_le

uint16_t offset

offset into structure

PACKED_STRUCT

Initial value:

{

uint16_t mfg_code_le

PACKED_STRUCT

Initial value:

{

uint16_t mfg_code_le

mfg_code_le

uint16_t mfg_code_le

Definition: zcl.h:197