Thermostat Cluster

This chapter outlines the Thermostat cluster, which provides an interface for configuring and controlling the functionality of a thermostat.

The Thermostat cluster has a Cluster ID of 0x0201.

Overview

The Thermostat cluster is required in ZigBee devices as indicated in the table below.

Server-side

Client-side

Mandatory in…

Thermostat

Optional in…

Remote Control

The Thermostat cluster is enabled by defining CLD_THERMOSTAT in the zcl_options.h file.

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 Thermostat cluster are fully detailed in Section33.10.

The information that can potentially be stored in this cluster is organised into the following attribute sets:

  • Thermostat Information

  • Thermostat Settings

The attributes are listed and described next, in Section 33.2.

Parent topic:Thermostat Cluster

Thermostat Cluster structure and attributes

The Thermostat cluster is contained in the following tsCLD_Thermostat structure:

typedef struct
{
#ifdef THERMOSTAT_SERVER
    zint16                  i16LocalTemperature;
#ifdef CLD_THERMOSTAT_ATTR_OUTDOOR_TEMPERATURE
    zint16                  i16OutdoorTemperature;
#endif
#ifdef CLD_THERMOSTAT_ATTR_OCCUPANCY
    zbmap8                  u8Occupancy;
#endif
#ifdef CLD_THERMOSTAT_ATTR_ABS_MIN_HEAT_SETPOINT_LIMIT
    zint16                  i16AbsMinHeatSetpointLimit;
#endif
#ifdef CLD_THERMOSTAT_ATTR_ABS_MAX_HEAT_SETPOINT_LIMIT
    zint16                  i16AbsMaxHeatSetpointLimit;
#endif
#ifdef CLD_THERMOSTAT_ATTR_ABS_MIN_COOL_SETPOINT_LIMIT
    zint16                  i16AbsMinCoolSetpointLimit;
#endif
#ifdef CLD_THERMOSTAT_ATTR_ABS_MAX_COOL_SETPOINT_LIMIT
    zint16                  i16AbsMaxCoolSetpointLimit;
#endif
#ifdef CLD_THERMOSTAT_ATTR_PI_COOLING_DEMAND
    zuint8                  u8PICoolingDemand;
#endif
#ifdef CLD_THERMOSTAT_ATTR_PI_HEATING_DEMAND
    zuint8                  u8PIHeatingDemand;
#endif
/* Thermostat settings attribute set attribute IDs */
#ifdef CLD_THERMOSTAT_ATTR_LOCAL_TEMPERATURE_CALIBRATION
    zint8                   i8LocalTemperatureCalibration;
#endif
    zint16                  i16OccupiedCoolingSetpoint;
    zint16                  i16OccupiedHeatingSetpoint;
#ifdef CLD_THERMOSTAT_ATTR_UNOCCUPIED_COOLING_SETPOINT
    zint16                  i16UnoccupiedCoolingSetpoint;
#endif
#ifdef CLD_THERMOSTAT_ATTR_UNOCCUPIED_HEATING_SETPOINT
    zint16                  i16UnoccupiedHeatingSetpoint;
#endif
#ifdef CLD_THERMOSTAT_ATTR_MIN_HEAT_SETPOINT_LIMIT
    zint16                  i16MinHeatSetpointLimit;
#endif
#ifdef CLD_THERMOSTAT_ATTR_MAX_HEAT_SETPOINT_LIMIT
    zint16                  i16MaxHeatSetpointLimit;
#endif
#ifdef CLD_THERMOSTAT_ATTR_MIN_COOL_SETPOINT_LIMIT
    zint16                  i16MinCoolSetpointLimit;
#endif
#ifdef CLD_THERMOSTAT_ATTR_MAX_COOL_SETPOINT_LIMIT
    zint16                  i16MaxCoolSetpointLimit;
#endif
#ifdef CLD_THERMOSTAT_ATTR_MIN_SETPOINT_DEAD_BAND
    zint8                   i8MinSetpointDeadBand;
#endif
#ifdef CLD_THERMOSTAT_ATTR_REMOTE_SENSING
    zbmap8                  u8RemoteSensing;
#endif
    zenum8                  eControlSequenceOfOperation;
    zenum8                  eSystemMode;
#ifdef CLD_THERMOSTAT_ATTR_ALARM_MASK
    zbmap8                  u8AlarmMask;
#endif
#ifdef CLD_THERMOSTAT_ATTR_ATTRIBUTE_REPORTING_STATUS
    zenum8                  u8AttributeReportingStatus;
#endif
#endif
    zuint16                 u16ClusterRevision;
} tsCLD_Thermostat;

where:

‘Thermostat Information’ Attribute Set

  • i16LocalTemperature is a mandatory attribute representing the measured temperature in degrees Celsius, as follows:

    • i16LocalTemperature = 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)

  • i16OutdoorTemperature is an optional attribute representing the outside temperature in degrees Celsius. This temperature is represented as described above for i16LocalTemperature.

  • u8Occupancy is an optional attribute indicating whether the heated/cooled space has been detected as occupied. Bit 0 is used as a flag as follows (all other bits are reserved):

    • 1 = occupied

    • 0 = not occupied

  • i16AbsMinHeatSetpointLimit is an optional attribute specifying the absolute minimum possible temperature of the heating setpoint (as determined by the manufacturer). This temperature is represented as described above for i16LocalTemperature.

  • i16AbsMaxHeatSetpointLimit is an optional attribute specifying the absolute maximum possible temperature of the heating setpoint (as determined by the manufacturer). This temperature is represented as described above for i16LocalTemperature.

  • i16AbsMinCoolSetpointLimit is an optional attribute specifying the absolute minimum possible temperature of the cooling setpoint (as determined by the manufacturer). This temperature is represented as described above for i16LocalTemperature.

  • i16AbsMaxCoolSetpointLimit is an optional attribute specifying the absolute maximum possible temperature of the cooling setpoint (as determined by the manufacturer). This temperature is represented as described above for i16LocalTemperature.

‘Thermostat Settings’ Attribute Set

  • u8PICoolingDemand is an optional attribute indicating the level of cooling required by the PI (Proportional Integral) control loop, if any, used by the thermostat. It is a percentage value and takes the value 0 when the thermostat is ‘off’ or in ‘heating’ mode.

  • u8PIHeatingDemand is an optional attribute indicating the level of heating required by the PI (Proportional Integral) control loop, if any, used by the thermostat. It is a percentage value and takes the value 0 when the thermostat is ‘off’ or in ‘cooling’ mode.

  • i8LocalTemperatureCalibration is an optional attribute representing a temperature offset (in the range -2.5°C to 2.5°C) that can be added to or subtracted from the displayed temperature:

    • i8LocalTemperatureCalibration = 100 x offset in degrees Celsius

    • The possible values are used as follows:

    • 0x00 to 0x19 represent positive offsets from 0°C to 2.5ºC

    • 0x20 to 0xE6 are unused values

    • 0xE7 to 0xFF represent negative offets from -2.5°C to -1°C (in two’s complement form)

  • i16OccupiedCoolingSetpoint is an optional attribute specifying the cooling setpoint (target temperature) when the cooling space is occupied. The value is calculated as described above for the i16LocalTemperature attribute and must take a value in the range defined by the attributes i16MinCoolSetpointLimit and i16MaxCoolSetpointLimit. If it is not known whether the space is occupied, this attribute will be used as the cooling setpoint (rather than i16UnoccupiedCoolingSetpoint).

  • i16OccupiedHeatingSetpoint is an optional attribute specifying the heating setpoint (target temperature) when the heating space is occupied. The value is calculated as described above for the i16LocalTemperature attribute and must take a value in the range defined by the attributes i16MinHeatSetpointLimit and i16MaxHeatSetpointLimit. If it is not known whether the space is occupied, this attribute will be used as the heating setpoint (rather than i16UnoccupiedHeatingSetpoint).

Note: i16OccupiedCoolingSetpoint must always be greater in value than i16OccupiedHeatingSetpoint by an amount at least equal to the value of i8MinSetpointDeadBand (below). An attempt to violate this condition will result in a default response with the status INVALID_VALUE.

  • i16UnoccupiedCoolingSetpoint is an optional attribute specifying the cooling setpoint (target temperature) when the cooling space is unoccupied. The value is calculated as described above for the i16LocalTemperature attribute and must take a value in the range defined by the attributes i16AbsMinCoolSetpointLimit and i16MaxCoolSetpointLimit. If it is not known whether the space is occupied, this attribute will not be used (i16OccupiedCoolingSetpoint will be used instead).

  • i16``UnoccupiedHeatingSetpoint is an optional attribute specifying the heating setpoint (target temperature) when the heating space is unoccupied. The value is calculated as described above for the i16LocalTemperature attribute and must take a value in the range defined by the attributes i16Min``HeatS``etpointLimit and i16MaxHeatSetpointLimit. If it is not known whether the space is occupied, this attribute will not be used (i16Occupied``Heati``ngSetpoint will be used instead).

Note: i16UnoccupiedCoolingSetpoint must always be greater in value than i16``Unoc``cupiedHeatingSetpoint by an amount at least equal to the value of i8MinSetpointDeadBand (below). An attempt to violate this condition will result in a default response with the status INVALID_VALUE.

  • i16MinHeatSetpointLimit is an optional attribute specifying the minimum possible temperature of the heating setpoint. This temperature is represented as described above for i16LocalTemperature. The value set must be greater than or equal to the value of i16AbsMinHeatSetpointLimit, which is also the default value for this attribute.

  • i16MaxHeatSetpointLimit is an optional attribute specifying the maximum possible temperature of the heating setpoint. This temperature is represented as described above for i16LocalTemperature. The value set must be less than or equal to the value of i16AbsMaxHeatSetpointLimit, which is also the default value for this attribute.

  • i16MinCoolSetpointLimit is an optional attribute specifying the minimum possible temperature of the cooling setpoint. This temperature is represented as described above for i16LocalTemperature. The value set must be greater than or equal to the value of i16AbsMinCoolSetpointLimit, which is also the default value for this attribute.

  • i16MaxCoolSetpointLimit is an optional attribute specifying the maximum possible temperature of the cooling setpoint. This temperature is represented as described above for i16LocalTemperature. The value set must be less than or equal to the value of i16AbsMaxCoolSetpointLimit, which is also the default value for this attribute.

Note: The above four ‘Limit’ attributes can be set in the compile-time options using macros, as described in Section 33.10.

  • i8MinSetpointDeadBand is an optional attribute specifying the minimum difference between the heating setpoint and cooling setpoint, in steps of 0.1°C. The attribute can take a value in the range 0x0A to 0x19, representing 1°C to 2.5°C. All other values are unused.

  • u8RemoteSensing is an optional attribute comprising an 8-bit bitmap which indicates whether remote (networked) or internal sensors are being used to measure/detect the local temperature, outside temperature and occupancy. The bitmap is detailed in the table below.

Bit

Description

0

Local temperature

1 - Remote sensor

0 - Internal sensor

| |1|Outside temperature

1 - Remote sensor

0 - Internal sensor

| |2|Occupancy

1 - Remote sensor

0 - Internal sensor

| |3-7|Reserved|

  • eControlSequenceOfOperation is an optional attribute representing the operational capabilities/environment of the thermostat. The possible values are indicated in the table below:

Value

Capabilities

Notes (seeeSystemMode)

0x00

Cooling only

Heat and Emergency Heating are not possible

0x01

Cooling with Reheat

Heat and Emergency Heating are not possible

0x02

Heating only

Cool and Pre-cooling are not possible

0x03

Heating with Reheat

Cool and Pre-cooling are not possible

0x04

Cooling and Heating

4-pipes

|All modes are possible| |0x05|Cooling and Heating

4-pipes with Reheat

|All modes are possible| |0x06 – 0xFE|Reserved|-|

  • eSystemMode is an optional attribute specifying the current operating mode of the thermostat. The possible modes/values are indicated in the table below:

Value

Description

0x00

Off

0x01

Auto

0x02

Reserved

0x03

Cool

0x04

Heat

0x05

Emergency Heating

0x06

Pre-cooling

0x07

Fan only

0x08 – 0xFE

Reserved

  • u8AlarmMask is an optional attribute containing a 3-bit bitmap specifying which alarms are enabled from those listed in the table below (use of the Alarms cluster is also required):

Bit

Description

0

Initialisation failure (device failed to complete initialization at power-up)

1 - Alarm enabled

0 - Alarm disabled

| |1|Hardware failure

1 - Alarm enabled

0 - Alarm disabled

| |2|Self-calibration failure

1 - Alarm enabled

0 - Alarm disabled

| |3-7|Reserved|

Global Attributes

  • 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:Thermostat Cluster

Attributes for Default Reporting

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

i16LocalTemperature 
u8PICoolingDemand

  • u8PIHeatingDemand

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

Parent topic:Thermostat Cluster

Thermostat Operations

The Thermostat cluster server is mandatory for some HVAC devices, such as the Thermostat device, while the cluster client can be used on a controlling device, such as the Remote Control device.

The sections below describe common operations using the Thermostat cluster.

Initialisation

The function eCLD_ThermostatCreateThermostat() is used to create an instance of the Thermostat cluster. The function is generally called by the initialization function for the host device.

Parent topic:Thermostat Operations

Recording and Reporting the Local Temperature

A record of the local temperature is kept in the mandatory attribute i16LocalTemperature on the cluster server - this attribute is fully detailed in Section 33.2. The value of this attribute can be updated by the server application using the function eCLD_ThermostatSetAttribute() - for example, as the result of a local temperature measurement.

The value of the attribute i16LocalTemperature can be regularly reported to a cluster client - for example, to allow the local temperature to be displayed to the user. This automated reporting can be configured and started on the server using the function eCLD_ThermostatStartReportingLocalTemperature(). Reports is sent regularly, but not periodically - maximum and minimum time-intervals between consecutive reports can be specified.

Parent topic:Thermostat Operations

Configuring Heating and Cooling Setpoints

Functions are provided to update the following two optional attributes that are used to specify setpoints (target temperatures) for heating and cooling:

i16OccupiedHeatingSetpoint
i16OccupiedCoolingSetpoint

If both of these setpoints are used, the cooling setpoint value must be greater than the heating setpoint value. These attributes are fully detailed in Section 33.2.

These server attributes can be controlled remotely from a client using the function eCLD_ThermostatCommandSetpointRaiseOrLowerSend(), usually as the result of user input on a controlling device. This function is used on the client to send a SetpointRaiseOrLower command to the server to increase or decrease the value of one or both of these setpoint attributes by a specified amount. On receipt of this command, an E_CLD_THERMOSTAT_CMD_SETPOINT_RAISE_LOWER event is generated on the server to notify the server application.

The server application can modify the values of these attributes using the function eCLD_ThermostatSetAttribute().

Note: These and other attributes of the Thermostat cluster can also be written and read using the general attribute access functions, as described in Section 2.3.

Parent topic:Thermostat Operations

Parent topic:Thermostat Cluster

Thermostat Events

The Thermostat cluster has its own events that are handled through the callback mechanism outlined in Chapter 3. If a device uses the Thermostat cluster then Thermostat event handling must be included in the callback function for the associated endpoint, where this callback function is registered through the relevant endpoint registration function (for example, through eHA_RegisterThermostatEndPoint() for a Thermostat device). The relevant callback function will then be invoked when a Thermostat event occurs.

For a Thermostat event, the eEventType field of the tsZCL_CallBackEvent structure is set to E_ZCL_CBET_CLUSTER_CUSTOM. This event structure also contains an element sClusterCustomMessage, which is itself a structure containing a field pvCustomData. This field is a pointer to the following tsCLD_ThermostatCallBackMessage structure:

typedef struct
{
    uint8                       u8CommandId;
    union
    {
      tsCLD_Thermostat_SetpointRaiseOrLowerPayload 
                               *psSetpointRaiseOrLowerPayload;
    } uMessage;
} tsCLD_ThermostatCallBackMessage;

The u8CommandId field of the above structure specifies the type of command that has been received - only one command type is possible and is described below.

E_CLD_THERMOSTAT_CMD_SETPOINT_RAISE_LOWER

In the tsCLD_ThermostatCallBackMessage structure, the u8CommandId is set to E_CLD_THERMOSTAT_CMD_SETPOINT_RAISE_LOWER on the Thermostat cluster server when a SetpointRaiseOrLower command has been received. On receipt of this command, the Thermostat command handler will be invoked.

Parent topic:Thermostat Cluster

Functions

The following Thermostat cluster functions are provided:

eCLD_ThermostatCreateThermostat

teZCL_Status eCLD_ThermostatCreateThermostat(
    tsZCL_ClusterInstance *psClusterInstance,
    bool_t bIsServer,
    sZCL_ClusterDefinition *psClusterDefinition,
    void *pvEndPointSharedStructPtr,
    uint8 *pu8AttributeControlBits,
    tsCLD_ThermostatCustomDataStructure
    psCustomDataStructure);

Description

This function creates an instance of the Thermostat 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 will create a Thermostat 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 (e.g. the Thermostat device) will be 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 the first Thermostat cluster function called in the application, and 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 should therefore equate to the total number of attributes supported by the Thermostat cluster.

The function initializes the array elements to zero.

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 initialising 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 Thermostat cluster. This parameter can refer to a pre-filled structure called sCLD_``Thermostat which is provided in the Thermostat.h file.

  • pvEndPointSharedStructPtr        Pointer to the shared structure used for attribute storage. This parameter should be the address of the structure of type tsCLD_``Thermostat which defines the attributes of Thermostat 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).

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_FAIL

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_ERR_INVALID_VALUE

Parent topic:Functions

eCLD_ThermostatSetAttribute

teZCL_Status eCLD_ThermostatSetAttribute(
    uint8 u8SourceEndPointId,
    uint8 u8AttributeId,
    int16 i16AttributeValue);

Description

This function can be used on a Thermostat cluster server to update the Thermostat attributes - specifically to write a value to one of the following attributes:

i16LocalTemperature
i16OccupiedCoolingSetpoint
i16OccupiedHeatingSetpoint

The function first checks whether the value to be written falls within the valid range for the relevant attribute. If not, it returns with status E_ZCL_ERR_INVALID_VALUE. If the server attempts to write to an attribute other than those specified above, the function returns with status E_ZCL_DENY_ATTRIBUTE_ACCESS. If the cluster does not exist, it returns with status E_ZCL_ERR_CLUSTER_NOT_FOUND.

Parameters

  • u8SourceEndPointId        Number of the endpoint on which the Thermostat cluster resides

  • u8AttributeId         Identifier of attribute to be updated, one of:

  • E_CLD_THERMOSTAT_ATTR_ID_LOCAL_TEMPERATURE

  • E_CLD_THERMOSTAT_ATTR_ID_OCCUPIED_COOLING_SETPOINT

  • E_CLD_THERMOSTAT_ATTR_ID_OCCUPIED_HEATING_SETPOINT

  • i16AttributeValue        Value to be written to attribute

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_ERR_INVALID_VALUE

  • E_ZCL_DENY_ATTRIBUTE_ACCESS

  • E_ZCL_ERR_CLUSTER_NOT_FOUND

Parent topic:Functions

eCLD_ThermostatStartReportingLocalTemperature

teZCL_Status eCLD_ThermostatStartReportingLocalTemperature(
    uint8 u8SourceEndPointId,
    uint8 u8DstEndPointId,
    uint64 u64DstAddr,
    uint16 u16MinReportInterval,
    uint16 u16MaxReportInterval,
    int16 i16ReportableChange);

Description

This function can be used on a Thermostat cluster server to start automatic reporting of the measured local temperature to a cluster client. The change to be reported can be configured through this function. Reports is sent regularly (but not periodically), within the specified maximum and minimum time-intervals between consecutive reports.

Parameters

  • u8SourceEndPointId        Number of the local endpoint on which the Thermostat cluster server resides

  • u8DstEndPointId        Number of the endpoint to which reports are to be sent on the destination node

  • u64DstAddr                IEEE/MAC address of destination node

  • u16MinReportInterval                Minimum time-interval, in seconds, between reports

  • u16MaxReportInterval                Maximum time-interval, in seconds, between reports

  • i16ReportableChange                Specifies the change to be reported

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_FAIL

  • E_ZCL_ERR_CLUSTER_NOT_FOUND

Parent topic:Functions

eCLD_ThermostatCommandSetpointRaiseOrLowerSend

teZCL_Status eCLD_ThermostatCommandSetpointRaiseOrLowerSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_Thermostat_SetpointRaiseOrLowerPayload
*psPayload);

Description

This function can be used on a Thermostat cluster client to send a ‘Setpoint Raise Or Lower’ command to the cluster server. This command is used to increase or decrease the heating setpoint and/or cooling setpoint by requesting a change to the values of the attribute i16OccupiedHeatingSetpoint and/or the attribute i16OccupiedCoolingSetpoint. The relevant setpoint(s) and the required temperature change are specified in the command payload structure tsCLD_Thermostat_SetpointRaiseOrLowerPayload (see Section 33.9.3).

A pointer must be specified to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request.

Parameters

  • u8SourceEndPointId                Number of the local endpoint through which the request is sent

  • u8DestinationEndPointId                Number of the remote endpoint to which the request is sent

  • psDestinationAddress                Pointer to a structure containing the address of the remote node to which the request is sent

  • pu8TransactionSequenceNumber                Pointer to a location to store the Transaction Sequence Number (TSN) of the request

  • psPayload        Pointer to the command payload (see Section33.9.3)

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_ERR_EP_RANGE

  • E_ZCL_ERR_EP_UNKNOWN

  • E_ZCL_ERR_CLUSTER_NOT_FOUND

  • E_ZCL_ERR_ZBUFFER_FAIL

  • E_ZCL_ERR_ZTRANSMIT_FAIL

Parent topic:Functions

Parent topic:Thermostat Cluster

Return codes

The Thermostat cluster functions use the ZCL return codes defined in Section 7.2.

Parent topic:Thermostat Cluster

Enumerations

‘Attribute ID’ Enumerations

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

typedef enum 
{
    E_CLD_THERMOSTAT_ATTR_ID_LOCAL_TEMPERATURE  = 0x0000,
    E_CLD_THERMOSTAT_ATTR_ID_OUTDOOR_TEMPERATURE,
    E_CLD_THERMOSTAT_ATTR_ID_OCCUPANCY,
    E_CLD_THERMOSTAT_ATTR_ID_ABS_MIN_HEAT_SETPOINT_LIMIT,
    E_CLD_THERMOSTAT_ATTR_ID_ABS_MAX_HEAT_SETPOINT_LIMIT,
    E_CLD_THERMOSTAT_ATTR_ID_ABS_MIN_COOL_SETPOINT_LIMIT,
    E_CLD_THERMOSTAT_ATTR_ID_ABS_MAX_COOL_SETPOINT_LIMIT,
    E_CLD_THERMOSTAT_ATTR_ID_PI_COOLING_DEMAND,
    E_CLD_THERMOSTAT_ATTR_ID_PI_HEATING_DEMAND,  
    E_CLD_THERMOSTAT_ATTR_ID_LOCAL_TEMPERATURE_CALIBRATION  = 0x0010,
    E_CLD_THERMOSTAT_ATTR_ID_OCCUPIED_COOLING_SETPOINT,
    E_CLD_THERMOSTAT_ATTR_ID_OCCUPIED_HEATING_SETPOINT,
    E_CLD_THERMOSTAT_ATTR_ID_UNOCCUPIED_COOLING_SETPOINT,
    E_CLD_THERMOSTAT_ATTR_ID_UNOCCUPIED_HEATING_SETPOINT,
    E_CLD_THERMOSTAT_ATTR_ID_MIN_HEAT_SETPOINT_LIMIT,
    E_CLD_THERMOSTAT_ATTR_ID_MAX_HEAT_SETPOINT_LIMIT,
    E_CLD_THERMOSTAT_ATTR_ID_MIN_COOL_SETPOINT_LIMIT,
    E_CLD_THERMOSTAT_ATTR_ID_MAX_COOL_SETPOINT_LIMIT,
    E_CLD_THERMOSTAT_ATTR_ID_MIN_SETPOINT_DEAD_BAND,
    E_CLD_THERMOSTAT_ATTR_ID_REMOTE_SENSING,
    E_CLD_THERMOSTAT_ATTR_ID_CONTROL_SEQUENCE_OF_OPERATION,
    E_CLD_THERMOSTAT_ATTR_ID_SYSTEM_MODE,
    E_CLD_THERMOSTAT_ATTR_ID_ALARM_MASK
} teCLD_Thermostat_AttributeID;

Parent topic:Enumerations

‘Operating Capabilities’ Enumerations

The following enumerations are used to set the optional attribute eControlSequenceOfOperation in the Thermostat cluster structure tsCLD_Thermostat.

typedef enum 
{
    E_CLD_THERMOSTAT_CSOO_COOLING_ONLY = 0x00,
    E_CLD_THERMOSTAT_CSOO_COOLING_WITH_REHEAT,
    E_CLD_THERMOSTAT_CSOO_HEATING_ONLY,
    E_CLD_THERMOSTAT_CSOO_HEATING_WITH_REHEAT,
    E_CLD_THERMOSTAT_CSOO_COOLING_AND_HEATING_4_PIPES,
    E_CLD_THERMOSTAT_CSOO_COOLING_AND_HEATING_4_PIPES_WITH_REHEAT,
}teCLD_Thermostat_ControlSequenceOfOperation;

The above enumerations are described in the table below.

Enumeration

Description

E_CLD_THERMOSTAT_CSOO_COOLING_ONLY

Heat and Emergency Heating are not

possible

| |E_CLD_THERMOSTAT_CSOO_COOLING_WITH_REHEAT|Heat and Emergency Heating are not

possible

| |E_CLD_THERMOSTAT_CSOO_HEATING_ONLY|Cool and Pre-cooling are not possible| |E_CLD_THERMOSTAT_CSOO_HEATING_WITH_REHEAT|Cool and Pre-cooling are not possible| |E_CLD_THERMOSTAT_CSOO_COOLING_AND_HEATING_

4_PIPES

|All modes are possible| |E_CLD_THERMOSTAT_CSOO_COOLING_AND_HEATING_

4_PIPES_WITH_REHEAT

|All modes are possible|

Parent topic:Enumerations

‘Command ID’ Enumerations

The following enumeration is used to specify the type of command sent to a Thermostat cluster server.

typedef enum 
{
   E_CLD_THERMOSTAT_CMD_SETPOINT_RAISE_LOWER = 0x00,
} teCLD_Thermostat_Command;

The above enumerations are described in the table below.

Enumeration

Command

E_CLD_THERMOSTAT_CMD_SETPOINT_RAISE_LOWER

Setpoint Raise Or Lower

Parent topic:Enumerations

‘Setpoint Raise Or Lower’ Enumerations

The following enumerations are used to specify an operating mode (heating, cooling or both) or the Thermostat.

{
    E_CLD_THERMOSTAT_SRLM_HEAT = 0x00,
    E_CLD_THERMOSTAT_SRLM_COOL,
    E_CLD_THERMOSTAT_SRLM_BOTH
}teCLD_Thermostat_SetpointRaiseOrLowerMode;

The above enumerations are described in the table below.

Enumeration

Description

E_CLD_THERMOSTAT_SRLM_HEAT

Heating mode

E_CLD_THERMOSTAT_SRLM_COOL

Cooling mode

E_CLD_THERMOSTAT_SRLM_BOTH

Heating and Cooling modes

Parent topic:Enumerations

Parent topic:Thermostat Cluster

Structures

Custom Data Structure

The Thermostat cluster requires extra storage space to be allocated for use by internal functions. The structure definition for this storage is shown below:

typedef struct
{
    tsZCL_ReceiveEventAddress         sReceiveEventAddress;
    tsZCL_CallBackEvent               sCustomCallBackEvent;
    tsCLD_ThermostatCallBackMessage   sCallBackMessage;
} tsCLD_ThermostatCustomDataStructure;

The fields are for internal use and no knowledge of them is required.

Parent topic:Structures

tsCLD_ThermostatCallBackMessage

For a Thermostat cluster event, the eEventType field of the tsZCL_CallBackEvent structure is set to E_ZCL_CBET_CLUSTER_CUSTOM. This event structure also contains an element sClusterCustomMessage, which is itself a structure containing a field pvCustomData. This field is a pointer to the following tsCLD_ThermostatCallBackMessage structure:

typedef struct
{
    uint8                                           u8CommandId;
    union
    {
      tsCLD_Thermostat_SetpointRaiseOrLowerPayload *psSetpointRaiseOrLowerPayload;
    } uMessage;
} tsCLD_ThermostatCallBackMessage; 

where:

  • u``8CommandId indicates the type of Thermostat cluster command that has been received - there is only one possibility: E_CLD_THERMOSTAT_CMD_SETPOINT_RAISE_LOWER

  • u``Message is a union containing the command payload in the following form: psSetpointRaiseOrLowerPayload is a pointer to a structure containing the payload of a ‘Setpoint Raise Or Lower’ command - see Section 33.9.3.

Parent topic:Structures

tsCLD_Thermostat_SetpointRaiseOrLowerPayload

This stucture contains the payload of a ‘Setpoint Raise Or Lower’ command (from the cluster client) which requests a change the value of the attribute i16OccupiedHeatingSetpoint and/or the attribute i16OccupiedCoolingSetpoint.

typedef struct
{
    zenum8                 eMode;
    zint8                  i8Amount;
}tsCLD_Thermostat_SetpointRaiseOrLowerPayload;

where:

  • eMode indicates the Thermostat operating mode to which the command relates, one of:

    • E_CLD_THERMOSTAT_SRLM_HEAT (Heating)

    • E_CLD_THERMOSTAT_SRLM_COOL (Cooling)

    • E_CLD_THERMOSTAT_SRLM_BOTH (Heating and Cooling)

  • i8Amount represents the value (in two’s complement form) by which the setpoint corresponding to the specified operating mode is to be changed

Parent topic:Structures

Parent topic:Thermostat Cluster

Compile-time options

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

#define CLD_THERMOSTAT

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

#define THERMOSTAT_SERVER
#define THERMOSTAT_CLIENT

Optional Attributes

The optional attributes for the Thermostat cluster (see Section 33.2) are enabled by defining:

  • CLD_THERMOSTAT_ATTR_ID_LOCAL_TEMPERATURE

  • CLD_THERMOSTAT_ATTR_ID_OUTDOOR_TEMPERATURE

  • CLD_THERMOSTAT_ATTR_ID_OCCUPANCY

  • CLD_THERMOSTAT_ATTR_ID_ABS_MIN_HEAT_SETPOINT_LIMIT

  • CLD_THERMOSTAT_ATTR_ID_ABS_MAX_HEAT_SETPOINT_LIMIT

  • CLD_THERMOSTAT_ATTR_ID_ABS_MIN_COOL_SETPOINT_LIMIT

  • CLD_THERMOSTAT_ATTR_ID_ABS_MAX_COOL_SETPOINT_LIMIT

  • CLD_THERMOSTAT_ATTR_ID_PI_COOLING_DEMAND

  • CLD_THERMOSTAT_ATTR_ID_PI_HEATING_DEMAND

  • CLD_THERMOSTAT_ATTR_ID_LOCAL_TEMPERATURE_CALIBRATION

  • CLD_THERMOSTAT_ATTR_ID_OCCUPIED_COOLING_SETPOINT

  • CLD_THERMOSTAT_ATTR_ID_OCCUPIED_HEATING_SETPOINT

  • CLD_THERMOSTAT_ATTR_ID_UNOCCUPIED_COOLING_SETPOINT

  • CLD_THERMOSTAT_ATTR_ID_UNOCCUPIED_HEATING_SETPOINT

  • CLD_THERMOSTAT_ATTR_ID_MIN_HEAT_SETPOINT_LIMIT

  • CLD_THERMOSTAT_ATTR_ID_MAX_HEAT_SETPOINT_LIMIT

  • CLD_THERMOSTAT_ATTR_ID_MIN_COOL_SETPOINT_LIMIT

  • CLD_THERMOSTAT_ATTR_ID_MAX_COOL_SETPOINT_LIMIT

  • CLD_THERMOSTAT_ATTR_ID_MIN_SETPOINT_DEAD_BAND

  • CLD_THERMOSTAT_ATTR_ID_REMOTE_SENSING

  • CLD_THERMOSTAT_ATTR_ID_CONTROL_SEQUENCE_OF_OPERATION

  • CLD_THERMOSTAT_ATTR_ID_SYSTEM_MODE

  • CLD_THERMOSTAT_ATTR_ID_ALARM_MASK

Global Attributes

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

#define CLD_THERMOSTAT_ATTR_ID_ATTRIBUTE_REPORTING_STATUS

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

#define CLD_THERMOSTAT_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).

Minimum Cooling Setpoint

The value of the attribute i16MinCoolSetpointLimit can be set as follows:

#define CLD_THERMOSTAT_MIN_COOLING_SETPOINT         n

where n is the value to be set (in two’s complement form). The default value is 0x954D.

Maximum Cooling Setpoint

The value of the attribute i16MaxCoolSetpointLimit can be set as follows:

#define CLD_THERMOSTAT_MAX_COOLING_SETPOINT n

where n is the value to be set (in two’s complement form). The default value is 0x7FFF.

Minimum Heating Setpoint

The value of the attribute i16MinHeatSetpointLimit can be set as follows:

#define CLD_THERMOSTAT_MIN_HEATING_SETPOINT n

where n is the value to be set (in two’s complement form). The default value is 0x954D.

Maximum Heating Setpoint

The value of the attribute i16MaxHeatSetpointLimit can be set as follows:

#define CLD_THERMOSTAT_MAX_HEATING_SETPOINT n

where n is the value to be set (in two’s complement form). The default value is 0x7FFF.

Parent topic:Thermostat Cluster