Temperature Measurement Cluster

This chapter describes the Temperature Measurement cluster which is concerned with configuring and reporting temperature measurement.

The Temperature Measurement cluster has a Cluster ID of 0x0402.

Overview

The Temperature Measurement cluster provides an interface to a temperature measuring device, allowing the configuration of measuring and the reporting of measurements.

To use the functionality of this cluster, you must include the file TemperatureMeasurement.h in your application and enable the cluster by defining CLD_TEMPERATURE_MEASUREMENT in the zcl_options.h file.

A Temperature Measurement cluster instance can act as a client or a server. The inclusion of the client or server software must be pre-defined in the application’s compile-time options (in addition, if the cluster is to reside on a custom endpoint then the role of client or server must also be specified when creating the cluster instance).

The compile-time options for the Temperature Measurement cluster are fully detailed in Section 25.6.

Parent topic:Temperature Measurement Cluster

Temperature Measurement Structure and Attributes

The structure definition for the Temperature Measurement cluster (server) is:

typedef struct
{
#ifdef TEMPERATURE_MEASUREMENT_SERVER
  zint16    i16MeasuredValue;
  zint16    i16MinMeasuredValue;
  zint16    i16MaxMeasuredValue;
#ifdef CLD_TEMPMEAS_ATTR_TOLERANCE
  zuint16  u16Tolerance;
#endif
#ifdef CLD_TEMPMEAS_ATTR_ATTRIBUTE_REPORTING_STATUS
  zenum8    u8AttributeReportingStatus;
#endif
#endif
 zuint16 u16ClusterRevision;
} tsCLD_TemperatureMeasurement;

where:

i16MeasuredValue is a mandatory attribute representing the measured temperature in degrees Celsius, as follows:
- i16MeasuredValue = 100 x temperature in degrees Celsius
- The possible values are used as follows:
  - 0x0000 to 0x7FFF represent positive temperatures from 0°C to 327.67ºC.
  - 0x8000 indicates that the temperature measurement is invalid.
  - 0x8001 to 0x954C are unused values.
  - 0x954D to 0xFFFF represent negative temperatures from -273.15°C to -1°C (in two’s complement form).
- This attribute is updated continuously as measurements are made.
i16MinMeasuredValue is a mandatory attribute specifying the value of the attribute i16MeasuredValue which corresponds to the minimum possible temperature that can be measured. Its value must be less than that of the attribute i16MaxMeasuredValue (below). The special value 0x8000 indicates that the minimum is not known.
i16MaxMeasuredValue is a mandatory attribute specifying the value of the attribute i16MeasuredValue which corresponds to the maximum possible temperature that can be measured. Its value must be greater than that of the attribute i16MinMeasuredValue (above). The special value 0x8000 indicates that the maximum is not known.
u16Tolerance is an optional attribute which indicates the magnitude of the maximum possible error in the value of the attribute u16MeasuredValue. The true value is in the range (u16MeasuredValue – u16Tolerance) to (u16MeasuredValue + u16Tolerance).
u8AttributeReportingStatus is an optional attribute that should be enabled when attribute reporting is used for the cluster (see Section 2.3.5). The value of this attribute indicates whether there are attribute reports still pending (0x00) or the attribute reports are complete (0x01) - all other values are reserved. This attribute is also described in Section 2.4.
u16ClusterRevision is a mandatory attribute that specifies the revision of the cluster specification on which this cluster instance is based. The cluster specification in the ZCL r6 corresponds to a cluster revision of 1. The value is incremented by one for each subsequent revision of the cluster specification. This attribute is also described in Section 2.4.

Parent topic:Temperature Measurement Cluster

Attributes for Default Reporting

The following attributes of the Temperature Measurement cluster can be selected for default reporting:

i16MeasuredValue 
u16Tolerance

Attribute reporting (including default reporting) is described in Appendix B. Enabling reports for these attributes is described in Appendix B.3.6.

Parent topic:Temperature Measurement Cluster

Functions

The following Temperature Measurement cluster function is provided in the NXP implementation of the ZCL:eCLD_TemperatureMeasurementCreateTemperatureMeasurement

eCLD_TemperatureMeasurementCreateTemperatureMeasurement

teZCL_Status  eCLD_TemperatureMeasurementCreateTemperatureMeasurement(
  tsZCL_ClusterInstance *psClusterInstance,
  bool_t bIsServer,
  tsZCL_ClusterDefinition *psClusterDefinition,
  void *pvEndPointSharedStructPtr,
  uint8 *pu8AttributeControlBits);

Description

This function creates an instance of the Temperature Measurement cluster on an endpoint. The cluster instance is created on the endpoint which is associated with the supplied tsZCL_ClusterInstance structure and can act as a server or a client, as specified.

The function should only be called when setting up a custom endpoint containing one or more selected clusters (rather than the whole set of clusters supported by a standard ZigBee device). This function creates a Temperature Measurement cluster instance on the endpoint, but instances of other clusters may also be created on the same endpoint by calling their corresponding creation functions.

Note: This function must not be called for an endpoint on which a standard ZigBee device is used. In this case, the device and its supported clusters must be registered on the endpoint using the relevant device registration function.

When used, this function must be called after the stack has been started and after the ZCL has been initialized.

The function requires an array to be declared for internal use, which contains one element (of type uint8) for each attribute of the cluster. The array length is automatically adjusted by the compiler using the following declaration:

uint8 au8TemperatureMeasurementAttributeControlBits
        [(sizeof(asCLD_TemperatureMeasurementClusterAttributeDefinitions) 
    /     sizeof(tsZCL_AttributeDefinition))];

Parameters

psClusterInstance: Pointer to structure containing information about the cluster instance to be created (see Section 6.1.16). This structure is updated by the function by initializing individual structure fields.
bIsServer: Type of cluster instance (server or client) to be created:
TRUE - server
FALSE - client
psClusterDefinition: Pointer to structure indicating the type of cluster to be created (see Section 6.1.2). In this case, this structure must contain the details of the Temperature Measurement cluster. This parameter can refer to a pre-filled structure called sCLD_TemperatureMeasurement which is provided in the TemperatureMeasurement.h file.
pvEndPointSharedStructPtr: Pointer to the shared structure used for attribute storage. This parameter should be the address of the structure of type tsCLD_TemperatureMeasurementwhich defines the attributes of Temperature Measurement cluster. The function initializes the attributes with default values.
pu8AttributeControlBits: Pointer to an array of uint8 values, with one element for each attribute in the cluster (see above). For a cluster client, set this pointer to NULL.

Returns

E_ZCL_SUCCESS
E_ZCL_FAIL
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_INVALID_VALUE

Parent topic:Functions

Parent topic:Temperature Measurement Cluster

Enumerations

teCLD_TemperatureMeasurement_AttributeID

The following structure contains the enumerations used to identify the attributes of the Temperature Measurement cluster.

typedef enum 
{
 E_CLD_TEMPMEAS_ATTR_ID_MEASURED_VALUE = 0x0000, /* Mandatory */
 E_CLD_TEMPMEAS_ATTR_ID_MIN_MEASURED_VALUE,      /* Mandatory */
 E_CLD_TEMPMEAS_ATTR_ID_MAX_MEASURED_VALUE,      /* Mandatory */
 E_CLD_TEMPMEAS_ATTR_ID_TOLERANCE,
} teCLD_TemperatureMeasurement_AttributeID;

Parent topic:Enumerations

Parent topic:Temperature Measurement Cluster

Compile-time Options

To enable the Temperature Measurement cluster in the code to be built, it is necessary to add the following to the zcl_options.h file:

#define CLD_TEMPERATURE_MEASUREMENT

In addition, to include the software for a cluster client or server, it is necessary to add one of the following to the same file:

#define TEMPERATURE_MEASUREMENT_CLIENT
#define TEMPERATURE_MEASUREMENT_SERVER

Optional Attribute

Add this line to enable the optional Tolerance attribute:

#define CLD_TEMPMEAS_ATTR_TOLERANCE

Global Attributes

Add this line to enable the optional Attribute Reporting Status attribute:

#define CLD_TEMPMEAS_ATTR_ID_ATTRIBUTE_REPORTING_STATUS

Add this line to define the value (n) of the Cluster Revision attribute:

#define CLD_TEMPMEAS_CLUSTER_REVISION <n>

The default value is 1, which corresponds to the revision of the cluster in the ZCL r6 specification (see Section 2.4).

Parent topic:Temperature Measurement Cluster