Developing with ZBOSS for Zigbee
ZCL common types and definitions

Modules

 ZCL common types
 

Data Structures

struct  zb_zcl_command_send_status_s
 

Macros

#define ZB_ZCL_FIX_ENDIAN(data_ptr, data_type)
 Fix data endian, if needed, and store it in the same buffer. More...
 

Typedefs

typedef struct zb_zcl_command_send_status_s zb_zcl_command_send_status_t
 
typedef void(* zb_zcl_set_default_value_attr_cb_t) (zb_uint8_t ep)
 Set default value attribute callback. More...
 
typedef zb_ret_t(* zb_zcl_app_check_attr_value_cb_t) (zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint8_t endpoint, zb_uint16_t attr_id, zb_uint8_t *value)
 Check attribute value callback. More...
 
typedef zb_ret_t(* zb_zcl_app_check_attr_value_manuf_cb_t) (zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint8_t endpoint, zb_uint16_t attr_id, zb_uint16_t manuf_code, zb_uint8_t *value)
 Check attribute value callback with manufacturer specific code. More...
 
typedef zb_uint16_t(* zb_zcl_peer_revision_cb_t) (zb_ieee_addr_t ieee_addr, zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint8_t endpoint)
 Get peer Cluster revision callback. More...
 

Functions

zb_zcl_attr_tzb_zcl_get_attr_desc (zb_zcl_cluster_desc_t *cluster_desc, zb_uint16_t attr_id)
 Get registered attribute description by cluster descriptor. More...
 
zb_zcl_attr_tzb_zcl_get_attr_desc_manuf (zb_zcl_cluster_desc_t *cluster_desc, zb_uint16_t attr_id, zb_uint16_t manuf_code)
 Get registered attribute description by cluster descriptor. More...
 
zb_uint8_t zb_zcl_check_attribute_writable (zb_zcl_attr_t *attr_desc, zb_uint8_t endpoint, zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint8_t *new_value, zb_bool_t check_access)
 Check registered attribute is writable one. More...
 
void zb_zcl_write_attr_hook (zb_uint8_t endpoint, zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint16_t attr_id, zb_uint8_t *new_value, zb_uint16_t manuf_code)
 
void zb_zcl_set_attr_val_post_process_cluster_specific (zb_zcl_parsed_hdr_t *cmd_info, zb_uint16_t attr_id, zb_uint8_t *value)
 
zb_uint8_t zb_zcl_get_attribute_size (zb_uint8_t attr_type, zb_uint8_t *attr_value)
 Get size of value of given attribute type. More...
 
zb_uint8_t zb_zcl_get_analog_attribute_size (zb_uint8_t attr_type)
 Get size of analog data type. More...
 
zb_bool_t zb_zcl_is_analog_data_type (zb_uint8_t attr_type)
 Check whether type of ZCL attrbiute is analog. More...
 
zb_ret_t zb_zcl_check_attr_value (zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint8_t endpoint, zb_uint16_t attr_id, zb_uint8_t *value)
 Check if attribute value is valid or not. More...
 
zb_ret_t zb_zcl_check_attr_value_manuf (zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint8_t endpoint, zb_uint16_t attr_id, zb_uint16_t manuf_code, zb_uint8_t *value)
 Check if attribute value is valid or not (with manufacturer specific code) More...
 
zb_bool_t zb_zcl_is_target_endpoint (zb_af_endpoint_desc_t *ep_desc, zb_uint16_t profile_id)
 
zb_uint8_t zb_zcl_get_next_target_endpoint (zb_uint8_t start_from_ep, zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint16_t profile_id)
 
zb_zcl_cluster_desc_tget_cluster_desc (const zb_af_endpoint_desc_t *ep_desc, zb_uint16_t cluster_id, zb_uint8_t cluster_role)
 Search endpoint for cluster with given id. More...
 
zb_uint8_t get_endpoint_by_cluster (zb_uint16_t cluster_id, zb_uint8_t cluster_role)
 Find endpoint which has cluster with given ID. More...
 
zb_bool_t is_cluster_present (zb_uint16_t cluster_id)
 Find if device has cluster with given ID. More...
 
zb_uint16_t get_profile_id_by_endpoint (zb_uint8_t endpoint_id)
 
zb_af_endpoint_desc_tget_endpoint_by_cluster_with_role (zb_uint16_t cluster_id, zb_uint8_t cluster_role)
 Find endpoint which has cluster with given ID and role. More...
 
zb_zcl_attr_tzb_zcl_get_attr_desc_a (zb_uint8_t ep, zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint16_t attr_id)
 
zb_zcl_attr_tzb_zcl_get_attr_desc_manuf_a (zb_uint8_t ep, zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint16_t attr_id, zb_uint16_t manuf_code)
 
zb_uint8_tzb_zcl_put_value_to_packet (zb_uint8_t *cmd_ptr, zb_uint8_t attr_type, zb_uint8_t *attr_value)
 
zb_zcl_status_t zb_zcl_set_attr_val_manuf (zb_uint8_t ep, zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint16_t attr_id, zb_uint16_t manuf_code, zb_uint8_t *value, zb_bool_t check_access)
 Sets value for manufacture-specific attribute. Also, perform all needed checks before and after setting new value. More...
 
zb_zcl_status_t zb_zcl_set_attr_val (zb_uint8_t ep, zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint16_t attr_id, zb_uint8_t *value, zb_bool_t check_access)
 Sets attribute value, perform all needed checks before and after setting new value. More...
 
zb_ret_t zb_zcl_register_cb (zb_uint8_t param, zb_callback_t cb)
 Register callback that should be called when APS acknowledge is received for ZCL command. More...
 
zb_ret_t zb_zcl_ack_callback (zb_uint8_t param)
 Call callback on receiving APS acknowledge for ZCL command. More...
 
zb_uint8_t zb_zcl_check_accept_command (zb_uint8_t param)
 
zb_ret_t zb_zcl_set_backward_comp_mode (zb_uint8_t mode)
 Set ZCL backward compatibility modes. More...
 
zb_uint8_t zb_zcl_get_backward_comp_mode (void)
 Get ZCL backward compatibility modes. More...
 
zb_uint16_t zb_zcl_get_cluster_rev_by_mode (zb_uint16_t api_revision, const zb_addr_u *dst_addr, zb_uint8_t dst_addr_mode, zb_uint8_t dst_ep, zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint8_t src_ep)
 Get cluster revision depending on current ZCL backward compatibility mode, see zcl_backward_compatibility_modes. More...
 
zb_ret_t zb_zcl_set_peer_revision_callback (zb_zcl_peer_revision_cb_t cb)
 Set peer revision callback, see zb_zcl_peer_revision_cb_t If the callback is set, ZB_ZCL_COMPATIBILITY_MODE will be enabled automatically. More...
 
zb_uint8_t zb_zcl_get_backward_compatible_statuses_mode (void)
 Returns Backward compatible status values mode When enabled it diversifies some common statuses as it was in ZCL6 and ZCL7. More...
 
zb_ret_t zb_zcl_set_backward_compatible_statuses_mode (zb_uint8_t statuses_mode)
 Set Backward compatible status values mode. More...
 

Detailed Description

Macro Definition Documentation

◆ ZB_ZCL_FIX_ENDIAN

#define ZB_ZCL_FIX_ENDIAN (   data_ptr,
  data_type 
)

Fix data endian, if needed, and store it in the same buffer.

Parameters
data_ptr- pointer to data value
data_type- ZCL data type

Typedef Documentation

◆ zb_zcl_app_check_attr_value_cb_t

typedef zb_ret_t(* zb_zcl_app_check_attr_value_cb_t) (zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint8_t endpoint, zb_uint16_t attr_id, zb_uint8_t *value)

Check attribute value callback.

Parameters
cluster_id- Cluster ID
cluster_role- cluster role (zcl_cluster_role)
endpoint- endpoint number
attr_id- attribute ID
value- new attribute value
Returns
RET_OK - if new value is valid, RET_ERROR - if new value is wrong or RET_IGNORE - if use default Check attribute functions

◆ zb_zcl_app_check_attr_value_manuf_cb_t

typedef zb_ret_t(* zb_zcl_app_check_attr_value_manuf_cb_t) (zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint8_t endpoint, zb_uint16_t attr_id, zb_uint16_t manuf_code, zb_uint8_t *value)

Check attribute value callback with manufacturer specific code.

Parameters
cluster_id- Cluster ID
cluster_role- cluster role (zcl_cluster_role)
endpoint- endpoint number
attr_id- attribute ID
manuf_code- manufacturer specific code
value- new attribute value
Returns
RET_OK - if new value is valid, RET_ERROR - if new value is wrong or RET_IGNORE - if use default Check attribute functions

◆ zb_zcl_command_send_status_t

Command send status structure

◆ zb_zcl_peer_revision_cb_t

typedef zb_uint16_t(* zb_zcl_peer_revision_cb_t) (zb_ieee_addr_t ieee_addr, zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint8_t endpoint)

Get peer Cluster revision callback.

Parameters
ieee_addr- IEEE address
cluster_id- Cluster ID
cluster_role- cluster role (zcl_cluster_role)
endpoint- endpoint number
Returns
peer Cluster revision attribute value, 0xFFFF - if the revision is unknown

◆ zb_zcl_set_default_value_attr_cb_t

typedef void(* zb_zcl_set_default_value_attr_cb_t) (zb_uint8_t ep)

Set default value attribute callback.

Parameters
ep- endpoint number

Function Documentation

◆ get_cluster_desc()

zb_zcl_cluster_desc_t* get_cluster_desc ( const zb_af_endpoint_desc_t ep_desc,
zb_uint16_t  cluster_id,
zb_uint8_t  cluster_role 
)

Search endpoint for cluster with given id.

Parameters
ep_desc- application endpoint description
cluster_id- cluster ID (see zcl_cluster_id)
cluster_role- role (see zcl_cluster_role)
Returns
cluster descriptor or NULL if not present

◆ get_endpoint_by_cluster()

zb_uint8_t get_endpoint_by_cluster ( zb_uint16_t  cluster_id,
zb_uint8_t  cluster_role 
)

Find endpoint which has cluster with given ID.

Parameters
cluster_id- cluster ID (see zcl_cluster_id)
cluster_role- role (see zcl_cluster_role)
Returns
endpoint number or 0 if not found

◆ get_endpoint_by_cluster_with_role()

zb_af_endpoint_desc_t* get_endpoint_by_cluster_with_role ( zb_uint16_t  cluster_id,
zb_uint8_t  cluster_role 
)

Find endpoint which has cluster with given ID and role.

Parameters
cluster_id- cluster ID (see zcl_cluster_id)
cluster_role- role (see zcl_cluster_role)
Returns
endpoint number or 0 if not found

◆ is_cluster_present()

zb_bool_t is_cluster_present ( zb_uint16_t  cluster_id)

Find if device has cluster with given ID.

Parameters
cluster_id- cluster ID (see zcl_cluster_id)
Returns
ZB_TRUE if cluster found

◆ zb_zcl_ack_callback()

zb_ret_t zb_zcl_ack_callback ( zb_uint8_t  param)

Call callback on receiving APS acknowledge for ZCL command.

Parameters
param- buffer with ZCL command
Returns
RET_OK if callback was found and called RET_NOT_FOUND if no callback was registered

◆ zb_zcl_check_accept_command()

zb_uint8_t zb_zcl_check_accept_command ( zb_uint8_t  param)

Check whether ZCL command should be handled by stack

Parameters
param- reference to buffer with parsed ZCL command
Returns
ZB_ZCL_STATUS_SUCCESS if command should be handled ZB_ZCL_STATUS_UNSUP_MANUF_CLUST_CMD if manufacturer specific command is not supported ZB_ZCL_STATUS_UNSUP_CLUST_CMD if general command is not supported ZB_ZCL_STATUS_UNSUP_CLUST if cluster with role specified in ZCL header is not supported

◆ zb_zcl_check_attr_value()

zb_ret_t zb_zcl_check_attr_value ( zb_uint16_t  cluster_id,
zb_uint8_t  cluster_role,
zb_uint8_t  endpoint,
zb_uint16_t  attr_id,
zb_uint8_t value 
)

Check if attribute value is valid or not.

Deprecated:
This function will be removed in the next Major release after February 2023 Use zb_zcl_check_attr_value_manuf instead
Parameters
cluster_id- cluster ID
cluster_role- cluster role (zcl_cluster_role)
endpoint- endpoint
attr_id- attribute ID
value- pointer to attribute data
Returns
RET_OK if data value is valid, some error code otherwise

◆ zb_zcl_check_attr_value_manuf()

zb_ret_t zb_zcl_check_attr_value_manuf ( zb_uint16_t  cluster_id,
zb_uint8_t  cluster_role,
zb_uint8_t  endpoint,
zb_uint16_t  attr_id,
zb_uint16_t  manuf_code,
zb_uint8_t value 
)

Check if attribute value is valid or not (with manufacturer specific code)

Parameters
cluster_id- cluster ID
cluster_role- cluster role (zcl_cluster_role)
endpoint- endpoint
attr_id- attribute ID
manuf_code- manufacturer specific code
value- pointer to attribute data
Returns
ZB_TRUE if data value is valid, ZB_FALSE otherwise

◆ zb_zcl_check_attribute_writable()

zb_uint8_t zb_zcl_check_attribute_writable ( zb_zcl_attr_t attr_desc,
zb_uint8_t  endpoint,
zb_uint16_t  cluster_id,
zb_uint8_t  cluster_role,
zb_uint8_t new_value,
zb_bool_t  check_access 
)

Check registered attribute is writable one.

Parameters
attr_desc- attribute descriptor
endpoint- endpoint
cluster_id- cluster identifier
cluster_role- cluster role (zcl_cluster_role)
new_value- new value for an attribute
check_access- check READ_ONLY access or not
Returns
ZB_ZCL_STATUS_SUCCESS on success, error status otherwise

◆ zb_zcl_get_analog_attribute_size()

zb_uint8_t zb_zcl_get_analog_attribute_size ( zb_uint8_t  attr_type)

Get size of analog data type.

Parameters
attr_type- attribute type in question (see zcl_attr_type)
Returns
size in bytes of 0xFF in type is not analog or invalid

◆ zb_zcl_get_attr_desc()

zb_zcl_attr_t* zb_zcl_get_attr_desc ( zb_zcl_cluster_desc_t cluster_desc,
zb_uint16_t  attr_id 
)

Get registered attribute description by cluster descriptor.

Parameters
cluster_desc- cluster descriptor
attr_id- attribute identifier
Returns
Pointer to attribute description, or NULL if no attribute description found.

◆ zb_zcl_get_attr_desc_a()

zb_zcl_attr_t* zb_zcl_get_attr_desc_a ( zb_uint8_t  ep,
zb_uint16_t  cluster_id,
zb_uint8_t  cluster_role,
zb_uint16_t  attr_id 
)

Find attribute descriptor by given endpoint number, cluster ID and attribute ID

Parameters
ep- endpoint number (must exist)
cluster_id- cluster ID (must exist on given ep, see zb_zcl_cluster_id_t)
cluster_role- role (see zcl_cluster_role)
attr_id- attribute ID
Returns
attribute descriptor

◆ zb_zcl_get_attr_desc_manuf()

zb_zcl_attr_t* zb_zcl_get_attr_desc_manuf ( zb_zcl_cluster_desc_t cluster_desc,
zb_uint16_t  attr_id,
zb_uint16_t  manuf_code 
)

Get registered attribute description by cluster descriptor.

Parameters
cluster_desc- cluster descriptor
attr_id- attribute identifier
manuf_code- manufacturer specific ID
Returns
Pointer to attribute description, or NULL if no attribute description found.

◆ zb_zcl_get_attr_desc_manuf_a()

zb_zcl_attr_t* zb_zcl_get_attr_desc_manuf_a ( zb_uint8_t  ep,
zb_uint16_t  cluster_id,
zb_uint8_t  cluster_role,
zb_uint16_t  attr_id,
zb_uint16_t  manuf_code 
)

Find attribute descriptor by given endpoint number, cluster ID, attribute ID, and manuf code

Parameters
ep- endpoint number (must exist)
cluster_id- cluster ID (must exist on given ep, see zb_zcl_cluster_id_t)
cluster_role- role (see zcl_cluster_role)
attr_id- attribute ID
manuf_code- manufacturer code
Returns
attribute descriptor

◆ zb_zcl_get_attribute_size()

zb_uint8_t zb_zcl_get_attribute_size ( zb_uint8_t  attr_type,
zb_uint8_t attr_value 
)

Get size of value of given attribute type.

Parameters
attr_type- attribute type in question (see zcl_attr_type)
attr_value- pointer to value in question (needed for variable sized types)
Returns
size in bytes or 0xFF if type is invalid

◆ zb_zcl_get_backward_comp_mode()

zb_uint8_t zb_zcl_get_backward_comp_mode ( void  )

Get ZCL backward compatibility modes.

Returns
current backward compatibility mode - see zcl_backward_compatibility_modes

◆ zb_zcl_get_backward_compatible_statuses_mode()

zb_uint8_t zb_zcl_get_backward_compatible_statuses_mode ( void  )

Returns Backward compatible status values mode When enabled it diversifies some common statuses as it was in ZCL6 and ZCL7.

Returns
zcl_backward_compatibility_status_modes

◆ zb_zcl_get_cluster_rev_by_mode()

zb_uint16_t zb_zcl_get_cluster_rev_by_mode ( zb_uint16_t  api_revision,
const zb_addr_u dst_addr,
zb_uint8_t  dst_addr_mode,
zb_uint8_t  dst_ep,
zb_uint16_t  cluster_id,
zb_uint8_t  cluster_role,
zb_uint8_t  src_ep 
)

Get cluster revision depending on current ZCL backward compatibility mode, see zcl_backward_compatibility_modes.

Parameters
api_revision-
dst_addrdestination address pointer (see zb_addr_u)
dst_addr_modedestination address mode (only ZB_APS_ADDR_MODE_16_GROUP_ENDP_NOT_PRESENT and ZB_APS_ADDR_MODE_16_ENDP_PRESENT are supported)
dst_epdestination endpoint
cluster_idcluster identifier
cluster_rolecluster role
src_epsource endpoint
Returns
cluster revision for the specific cluster

◆ zb_zcl_is_analog_data_type()

zb_bool_t zb_zcl_is_analog_data_type ( zb_uint8_t  attr_type)

Check whether type of ZCL attrbiute is analog.

Parameters
attr_type- attribute type in question (see zcl_attr_type)
Returns
ZB_TRUE if type is analog, ZB_FALSE otherwise

◆ zb_zcl_put_value_to_packet()

zb_uint8_t* zb_zcl_put_value_to_packet ( zb_uint8_t cmd_ptr,
zb_uint8_t  attr_type,
zb_uint8_t attr_value 
)

Put attribute value to command packet, fix endian if needed.

Parameters
cmd_ptr- pointer to destination
attr_type- type of attribute being written (see zcl_attr_type)
attr_value- pointer to value to be put into packet
Returns
command pointer adjusted to point at the tail of written value

◆ zb_zcl_register_cb()

zb_ret_t zb_zcl_register_cb ( zb_uint8_t  param,
zb_callback_t  cb 
)

Register callback that should be called when APS acknowledge is received for ZCL command.

Parameters
param- pointer to buffer with ZCL command
cb- pointer to callback function

◆ zb_zcl_set_attr_val()

zb_zcl_status_t zb_zcl_set_attr_val ( zb_uint8_t  ep,
zb_uint16_t  cluster_id,
zb_uint8_t  cluster_role,
zb_uint16_t  attr_id,
zb_uint8_t value,
zb_bool_t  check_access 
)

Sets attribute value, perform all needed checks before and after setting new value.

Parameters
ep- endpoint number
cluster_id- cluster ID (see zb_zcl_cluster_id_t)
cluster_role- role (see zcl_cluster_role)
attr_id- ID of the attribute being set
value- pointer to new value
check_access- whether read-only check should be performed
Returns
ZB_ZCL_STATUS_SUCCESS if value was written
ZB_ZCL_STATUS_READ_ONLY if attribute is read only and check_access is false ZB_ZCL_STATUS_UNSUP_ATTRIB if attribute is not supported by cluster ZB_ZCL_STATUS_INVALID_VALUE if current value of attribute is invalid
Note
given endpoint with given cluster ID should exist

◆ zb_zcl_set_attr_val_manuf()

zb_zcl_status_t zb_zcl_set_attr_val_manuf ( zb_uint8_t  ep,
zb_uint16_t  cluster_id,
zb_uint8_t  cluster_role,
zb_uint16_t  attr_id,
zb_uint16_t  manuf_code,
zb_uint8_t value,
zb_bool_t  check_access 
)

Sets value for manufacture-specific attribute. Also, perform all needed checks before and after setting new value.

Parameters
ep- endpoint number
cluster_id- cluster ID (see zb_zcl_cluster_id_t)
cluster_role- role (see zcl_cluster_role)
attr_id- ID of the attribute being set
value- pointer to new value
check_access- whether read-only check should be performed
manuf_code- manufacturer code attribute
Returns
ZB_ZCL_STATUS_SUCCESS if value was written
ZB_ZCL_STATUS_READ_ONLY if attribute is read only and check_access is false ZB_ZCL_STATUS_UNSUP_ATTRIB if attribute is not supported by cluster ZB_ZCL_STATUS_INVALID_VALUE if current value of attribute is invalid
Note
given endpoint with given cluster ID should exist

◆ zb_zcl_set_attr_val_post_process_cluster_specific()

void zb_zcl_set_attr_val_post_process_cluster_specific ( zb_zcl_parsed_hdr_t cmd_info,
zb_uint16_t  attr_id,
zb_uint8_t value 
)

Set attribute value cluster specific postprocessing

Parameters
cmd_info- cluster role (zcl_cluster_role)
attr_id- attribute ID
value- new value of attribute

◆ zb_zcl_set_backward_comp_mode()

zb_ret_t zb_zcl_set_backward_comp_mode ( zb_uint8_t  mode)

Set ZCL backward compatibility modes.

ZB_ZCL_LEGACY_MODE is default mode

Parameters
mode- see zcl_backward_compatibility_modes
Returns
RET_OK if ZCL backward compatibility modes were set
RET_OUT_OF_RANGE if parameter is out of range

◆ zb_zcl_set_backward_compatible_statuses_mode()

zb_ret_t zb_zcl_set_backward_compatible_statuses_mode ( zb_uint8_t  statuses_mode)

Set Backward compatible status values mode.

Parameters
statuses_mode- see zcl_backward_compatibility_status_modes
Returns
RET_OK if the mode was set, RET_OUT_OF_RANGE if value is invalid

◆ zb_zcl_set_peer_revision_callback()

zb_ret_t zb_zcl_set_peer_revision_callback ( zb_zcl_peer_revision_cb_t  cb)

Set peer revision callback, see zb_zcl_peer_revision_cb_t If the callback is set, ZB_ZCL_COMPATIBILITY_MODE will be enabled automatically.

Parameters
cb- peer revision callback, NULL if the callback should be removed
Returns
RET_OK if callback was set, otherwise an error

◆ zb_zcl_write_attr_hook()

void zb_zcl_write_attr_hook ( zb_uint8_t  endpoint,
zb_uint16_t  cluster_id,
zb_uint8_t  cluster_role,
zb_uint16_t  attr_id,
zb_uint8_t new_value,
zb_uint16_t  manuf_code 
)

Hook on Write Attribute command

Parameters
endpoint- endpoint
cluster_id- cluster ID
cluster_role- cluster role (zcl_cluster_role)
attr_id- attribute ID
new_value- pointer to newly assigned value
manuf_code- manufacturer specific code