Attribute API

Zigbee Attribute related APIs for ESP Zigbee SDK.

API Reference

Header File

components/esp-zigbee-lib/include/esp_zigbee_attribute.h

Functions

esp_zb_attribute_list_t *esp_zb_zcl_attr_list_create(uint16_t cluster_id)

Create an empty attribute list.

Note

This attribute list is ready for certain cluster id to add / update attribute refer to esp_zb_xx_cluster_add_attr() and esp_zb_cluster_update_attr().

Note

Attribute list groups up a cluster.

Parameters: cluster_id – [in] The cluster id for attribute list refer to esp_zb_zcl_cluster_id
Returns: pointer to esp_zb_attribute_list_s

esp_zb_zcl_attr_t *esp_zb_zcl_get_attribute(uint8_t endpoint, uint16_t cluster_id, uint8_t cluster_role, uint16_t attr_id)

Get ZCL attribute descriptor.

Note

Getting the local attribute from the specific endpoint and cluster.

Parameters

endpoint – [in] The endpoint
cluster_id – [in] Cluster id for attribute list refer to esp_zb_zcl_cluster_id
cluster_role – [in] Cluster role of this cluster, either server or client role refer to esp_zb_zcl_cluster_role
attr_id – [in] Attribute id

Returns

pointer to esp_zb_zcl_attr_s

esp_zb_zcl_status_t esp_zb_zcl_set_attribute_val(uint8_t endpoint, uint16_t cluster_id, uint8_t cluster_role, uint16_t attr_id, void *value_p, bool check)

Set ZCL attribute value.

Note

Set the local attribute from the specific endpoint, cluster and attribute.

Note

Please look up the Zigbee Cluster Library for the access method of attribute

Parameters

endpoint – [in] The endpoint
cluster_id – [in] Cluster id for attribute list refer to esp_zb_zcl_cluster_id
cluster_role – [in] Cluster role of this cluster, either server or client role refer to esp_zb_zcl_cluster_role
attr_id – [in] Attribute id
value_p – [in] pointer to new value
check – [in] The access method of attribute whether is required to check or not

Returns

zcl status refer to esp_zb_zcl_status_t

esp_zb_zcl_attr_t *esp_zb_zcl_get_manufacturer_attribute(uint8_t endpoint, uint16_t cluster_id, uint8_t cluster_role, uint16_t attr_id, uint16_t manuf_code)

Get the manufacturer attribute descriptor.

Parameters

endpoint – The endpoint identifier where the attribute is located
cluster_id – The cluster identifier where the attribute is located
cluster_role – The role of cluster
attr_id – The attribute identifier
manuf_code – The manufacturer code

Returns

A pointer to esp_zb_zcl_attr_s for attribute descriptor

esp_zb_zcl_status_t esp_zb_zcl_set_manufacturer_attribute_val(uint8_t endpoint, uint16_t cluster_id, uint8_t cluster_role, uint16_t manuf_code, uint16_t attr_id, void *value_p, bool check)

Set the manufacturer attribute value.

Parameters

endpoint – The endpoint identifier where the attribute is located
cluster_id – The cluster identifier where the attribute is located
cluster_role – The role of cluster
manuf_code – The manufacturer code
attr_id – The attribute identifier
value_p – The value of attribute expected to set
check – The access method of attribute whether is required to check or not

Returns

The zcl status refer to esp_zb_zcl_status_t

esp_err_t esp_zb_basic_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in basic cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_power_config_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in power config cluster.

Note

Attribute for battery information, battery settings 2 and 3 sets haven’t supported yet.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_identify_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in identify cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_groups_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in groups cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_scenes_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in scenes cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_on_off_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in on_off cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_on_off_switch_config_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in on_off switch config cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_level_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in level cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_color_control_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in color control cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_time_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in time cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_binary_input_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in binary input cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_commissioning_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in Commissioning cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_shade_config_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in shade config cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_door_lock_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in door lock cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_ias_zone_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in IAS zone cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_ias_zone_cluster_set_cie_address(uint8_t endpoint, esp_zb_ieee_addr_t cie_ieee_addr)

Set the IAS zone CIE address for IAS zone server.

Parameters

endpoint – [in] A 8-bit endpoint ID which the IAS zone cluster attach
cie_ieee_addr – [in] The 8-byte IEEE address will be regarded as the IAS message destination address

Returns

ESP_OK on success
ESP_FAIL The CIE address has been set, invalid argument or IAS zone cluster does not exist

esp_err_t esp_zb_ias_ace_get_zone_table_length(uint8_t endpoint, uint8_t *table_size)

Get the zone table size of the IAS ACE cluster.

Parameters

endpoint – [in] A 8-bit endpoint ID which the IAS ACE cluster attach
table_size – [out] The zone table size of IAS ACE cluster on the given endpoint.

Returns

ESP_OK on success
ESP_ERR_NOT_FOUND The IAS ACE cluster is not founded on the given endpoint.

esp_err_t esp_zb_ias_ace_get_zone_table(uint8_t endpoint, esp_zb_zcl_ias_ace_zone_table_t **table_p)

Get the zone table of the IAS ACE cluster.

Parameters

endpoint – [in] A 8-bit endpoint ID which the IAS ACE cluster attach
table_p – [out] The address of the zone table of IAS ACE cluster on the given endpoint.

Returns

ESP_OK on success
ESP_ERR_NOT_FOUND The IAS ACE cluster is not founded on the given endpoint.

esp_err_t esp_zb_temperature_meas_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in temperature measurement cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_humidity_meas_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in humidity measurement cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_ota_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute and variables in OTA client cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_illuminance_meas_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in illuminance measurement cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_pressure_meas_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in pressure measurement cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_flow_meas_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in flow measurement cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_electrical_meas_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in electrical measurement cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_window_covering_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in window covering cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_occupancy_sensing_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in occupancy sensor cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_thermostat_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in thermostat cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_fan_control_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in fan control cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_thermostat_ui_config_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in thermostat ui configuration cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_analog_input_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in analog input cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_analog_output_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in analog output cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_analog_value_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in analog value cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_carbon_dioxide_measurement_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in carbon dioxide measurement cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_pm2_5_measurement_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in pm2.5 measurement cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_multistate_value_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in multistate value cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_diagnostics_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in diagnostics cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_meter_identification_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Add an attribute in meter identification cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t cluster_id, uint16_t attr_id, uint8_t attr_type, uint8_t attr_access, void *value_p)

Add an attribute in a specified cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
cluster_id – [in] The cluster ID to which the attribute will be added, refer to esp_zb_zcl_cluster_id_t
attr_id – [in] An attribute id to be added
attr_type – [in] Type of attribute to be added, refer to esp_zb_zcl_attr_type_t
attr_access – [in] Access type of attribute to be added, refer to esp_zb_zcl_attr_access_t
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or attribute type is unsupported

esp_err_t esp_zb_custom_cluster_add_custom_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, uint8_t attr_type, uint8_t attr_access, void *value_p)

Add customized attribute in customized cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id to be added
attr_type – [in] Type of attribute to be added, refer to esp_zb_zcl_attr_type_t
attr_access – [in] Access type of attribute to be added, refer to esp_zb_zcl_attr_access_t
value_p – [in] A pointer to attribute value wants to add

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute is existed or unsupported

esp_err_t esp_zb_cluster_update_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p)

Update an attribute in a specific cluster.

Parameters

attr_list – [in] A pointer to attribute list esp_zb_attribute_list_s
attr_id – [in] An attribute id which wants to update
value_p – [in] A pointer to attribute value wants to update

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if attribute list not initialized
ESP_ERR_NOT_FOUND the request update attribute is not found