Matter Application Clusters

2.2.5.5. LightSensorType Attribute

The LightSensorType attribute specifies the electronic type of the light sensor. This attribute shall be set to one of the non-reserved values listed in Values of the LightSensorType Attribute .

Table 29. Values of the LightSensorType Attribute
Value	Description
0	Photodiode
1	CMOS
0x40 to 0xfe	Reserved for manufacturer specific light sensor types
null	Unknown

2.2.6. Commands

This cluster has no cluster specific commands.

2.3. Temperature Measurement

This cluster provides an interface to temperature measurement functionality, including configuration and provision of notifications of temperature measurements.

2.3.1. Revision History

The global ClusterRevision attribute value SHALL be the highest revision number in the table below.

Revision	Description
1	mandatory global ClusterRevision attribute added
2	CCB 2241 2370
3	CCB 2823
4	New data model format and notation

2.3.2. Classification

Hierarchy

Role

Context

PICS Code

Base

Application

Type 2 (server to client)

TMP

2.3.3. Cluster Identifiers

Identifier

Name

0x0402

Temperature Measurement

2.3.4. Attributes

Table 30. Temperature Measurement Attributes
ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0000	MeasuredValue	int16	MinMeasuredValue to MaxMeasuredValue	XP		R V	M
0x0001	MinMeasuredValue	int16	-27315 to MaxMeasuredValue-1	X		R V	M
0x0002	MaxMeasuredValue	int16	MinMeasuredValue+1 to 32767	X		R V	M
0x0003	Tolerance	uint16	0 to 2048		0	R V	O

2.3.4.1. MeasuredValue Attribute

Represents the temperature in degrees Celsius as follows:

MeasuredValue = 100 x temperature [°C]

Where -273.15°C ≤ temperature ≤ 327.67°C, with a resolution of 0.01°C.

The null value indicates that the temperature is unknown.

2.3.4.2. MinMeasuredValue Attribute

The MinMeasuredValue attribute indicates the minimum value of MeasuredValue that is capable of being measured. See Measured Value for more details.

The null value indicates that the value is not available.

2.3.4.3. MaxMeasuredValue Attribute

The MaxMeasuredValue attribute indicates the maximum value of MeasuredValue that is capable of being measured. See Measured Value for more details.

The null value indicates that the value is not available.

2.3.4.4. Tolerance Attribute

2.3.5. Commands

This cluster has no cluster specific commands.

2.4. Pressure Measurement

This cluster provides an interface to pressure measurement functionality, including configuration and provision of notifications of pressure measurements.

2.4.1. Revision History

The global ClusterRevision attribute value SHALL be the highest revision number in the table below.

Revision	Description
1	Mandatory global ClusterRevision attribute added
2	CCB 2241 2370
3	New data model format and notation

2.4.2. Classification

Hierarchy

Role

Context

PICS Code

Base

Application

Type 2 (server to client)

PRS

2.4.3. Cluster Identifiers

Identifier

Name

0x0403

Pressure Measurement

2.4.4. Features

This cluster SHALL support the FeatureMap bitmap attribute as defined below.

Bit

Code

Feature

Description

Conformance

EXT

Extended

The cluster is capable of extended range and resolution

2.4.5. Attributes

Name

Type

Constraint

Quality

Default

Access

Conformance

0x0000

MeasuredValue

int16

MinMeasuredValue to MaxMeasuredValue

R V

0x0001

MinMeasuredValue

int16

-32767 to MaxMeasuredValue-1

R V

0x0002

MaxMeasuredValue

int16

MinMeasuredValue+1 to 32767

R V

0x0003

Tolerance

uint16

0 to 2048

R V

0x0010

ScaledValue

int16

MinScaledValue to MaxScaledValue

R V

EXT

0x0011

MinScaledValue

int16

-32767 to MaxScaledValue-1

R V

EXT

0x0012

MaxScaledValue

int16

MinScaledValue+1 to 32767

R V

EXT

0x0013

ScaledTolerance

uint16

0 to 2048

R V

[EXT]

0x0014

Scale

int8

-127 to 127

R V

EXT

2.4.5.1. MeasuredValue Attribute

This attribute represents the pressure in kPa as follows:

MeasuredValue = 10 x Pressure [kPa]

The null value indicates that the value is not available.

2.4.5.2. MinMeasuredValue Attribute

This attribute indicates the minimum value of MeasuredValue that can be measured. See Measured Value for more details.

The null value indicates that the value is not available.

2.4.5.3. MaxMeasuredValue Attribute

This attribute indicates the maximum value of MeasuredValue that can be measured. See Measured Value for more details.

The null value indicates that the value is not available.

2.4.5.4. Tolerance Attribute

This attribute indicates the magnitude of the possible error that is associated with ScaledValue.

2.4.5.5. ScaledValue Attribute

ScaledValue represents the pressure in Pascals as follows:

ScaledValue = 10 ^Scale x Pressure [Pa]

The null value indicates that the value is not available.

2.4.5.6. MinScaledValue Attribute

The MinScaledValue attribute indicates the minimum value of ScaledValue that can be measured.

The null value indicates that the value is not available.

2.4.5.7. MaxScaledValue Attribute

This attribute indicates the maximum value of ScaledValue that can be measured.

MaxScaledValue SHALL be greater than MinScaledValue.

The null value indicates that the value is not available.

2.4.5.8. ScaledTolerance Attribute

This attribute indicates the magnitude of the possible error that is associated with ScaledValue. The true value is located in the range

(ScaledValue – ScaledTolerance) to (ScaledValue + ScaledTolerance).

2.4.5.9. Scale Attribute

This attribute indicates the base 10 exponent used to obtain ScaledValue (see ScaledValue Attribute ).

2.4.6. Commands

This cluster has no cluster specific commands.

2.5. Flow Measurement

This cluster provides an interface to flow measurement functionality, including configuration and provision of notifications of flow measurements.

2.5.1. Revision History

The global ClusterRevision attribute value SHALL be the highest revision number in the table below.

Revision	Description
1	Mandatory global ClusterRevision attribute added
2	CCB 2241 2370
3	New data model format and notation

2.5.2. Classification

Hierarchy

Role

Context

PICS Code

Base

Application

Type 2 (server to client)

FLW

2.5.3. Cluster Identifiers

Identifier

Name

0x0404

Flow Measurement

2.5.4. Attributes

The Flow Measurement Information attribute set contains the attributes summarized in the following table.

Name

Type

Constraint

Quality

Default

Access

Conformance

0x0000

MeasuredValue

uint16

MinMeasuredValue to MaxMeasuredValue

null

R V

0x0001

MinMeasuredValue

uint16

0 to MaxMeasuredValue-1

R V

0x0002

MaxMeasuredValue

uint16

MinMeasuredValue+1 to 65534

R V

0x0003

Tolerance

uint16

0 to 2048

R V

2.5.4.1. MeasuredValue Attribute

MeasuredValue represents the flow in m ³ /h as follows:

MeasuredValue = 10 x Flow

The null value indicates that the flow measurement is unknown, otherwise the range SHALL be as described in Measured Value .

2.5.4.2. MinMeasuredValue Attribute

The MinMeasuredValue attribute indicates the minimum value of MeasuredValue that can be measured. See Measured Value for more details.

The null value indicates that the value is not available.

2.5.4.3. MaxMeasuredValue Attribute

The MaxMeasuredValue attribute indicates the maximum value of MeasuredValue that can be measured. See Measured Value for more details.

The null value indicates that the value is not available.

2.5.4.4. Tolerance Attribute

2.5.5. Commands

This cluster has no cluster specific commands.

2.6. Water Content Measurement

This is a base cluster. The server cluster provides an interface to water content measurement functionality. The measurement is reportable and may be configured for reporting. Water content measurements include, but are not limited to, leaf wetness, relative humidity, and soil moisture.

2.6.1. Revision History

The global ClusterRevision attribute value SHALL be the highest revision number in the table below.

Revision	Description
1	Mandatory global ClusterRevision attribute added
2	CCB 2241
3	New data model format and notation

2.6.2. Classification

Hierarchy

Role

Scope

PICS Code

Base

Application

Endpoint

2.6.3. Cluster Identifiers

Identifier

Name

Description

0x0405

Relative Humidity Measurement

Percentage of water in the air

0x0407

Leaf Wetness Measurement

Percentage of water on the leaves of plants

0x0408

Soil Moisture Measurement

Percentage of water in the soil

2.6.4. Attributes

Name

Type

Constraint

Quality

Default

Access

Conformance

0x0000

MeasuredValue

uint16

MinMeasuredValue to MaxMeasuredValue

R V

0x0001

MinMeasuredValue

uint16

0 to MaxMeasuredValue-1

R V

0x0002

MaxMeasuredValue

uint16

MinMeasuredValue+1 to 10000

R V

0x0003

Tolerance

uint16

0 to 2048

R V

2.6.4.1. MeasuredValue Attribute

MeasuredValue represents the water content in % as follows:

MeasuredValue = 100 x water content

Where 0% < = water content < = 100%, corresponding to a MeasuredValue in the range 0 to 10000.

The maximum resolution this format allows is 0.01%.

MinMeasuredValue and MaxMeasuredValue define the range of the sensor.

The null value indicates that the measurement is unknown, otherwise the range SHALL be as described in Measured Value .

MeasuredValue is updated continuously as new measurements are made.

2.6.4.2. MinMeasuredValue Attribute

The MinMeasuredValue attribute indicates the minimum value of MeasuredValue that can be measured. The null value means this attribute is not defined. See Measured Value for more details.

2.6.4.3. MaxMeasuredValue Attribute

The MaxMeasuredValue attribute indicates the maximum value of MeasuredValue that can be measured. The null value means this attribute is not defined. See Measured Value for more details.

2.6.4.4. Tolerance Attribute

2.6.5. Commands

This cluster has no cluster specific commands.

2.7. Occupancy Sensing

2.7.1. Introduction

The server cluster provides an interface to occupancy sensing functionality, including configuration and provision of notifications of occupancy status.

2.7.2. Revision History

The global ClusterRevision attribute value SHALL be the highest revision number in the table below.

Rev	Description
1	mandatory global ClusterRevision attribute added
2	Physical Contact Occupancy feature with mandatory OccupancySensorTypeBitmap
3	new data model format and notation

2.7.3. Classification

Hierarchy

Role

PICS Code

Primary Transaction

Base

Application

OCC

Type 2 (server to client)

2.7.4. Cluster Identifiers

Identifier

Name

0x0406

Occupancy Sensing

2.7.5. Data Types

2.7.5.1. OccupancyBitmap

This data type is derived from bitmap8.

Bit

Name

Summary

Conformance

Occupied

Indicates the sensed occupancy state; 1 = occupied, 0 = unoccupied.

All other bits are reserved.

2.7.5.2. OccupancySensorTypeEnum

This data type is derived from enum8.

Value

Name

Summary

Conformance

PIR

Indicates a passive infrared sensor.

Ultrasonic

Indicates a ultrasonic sensor.

PIRAndUltrasonic

Indicates a passive infrared and ultrasonic sensor.

PhysicalContact

Indicates a physical contact sensor.

2.7.5.3. OccupancySensorTypeBitmap

This data type is derived from bitmap8.

Bit

Name

Summary

Conformance

PIR

Indicates a passive infrared sensor.

Ultrasonic

Indicates a ultrasonic sensor.

PhysicalContact

Indicates a physical contact sensor.

2.7.5. 2.7.6. Occupancy Sensor Information Attribute Set

For convenience, the attributes defined in this specification are arranged into sets of related attributes.

The occupancy sensor information attribute set contains the attributes summarized in Occupancy Sensor Information Attribute Set .

Table 31. Occupancy Sensor Information Attribute Set
ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0000	Occupancy	~~map8~~ OccupancyBitmap	0b0000 000x	P		R V	M
0x0001	OccupancySensorType	~~enum8~~ OccupancySensorTypeEnum	desc		MS	R V	M
0x0002	OccupancySensorTypeBitmap	~~map8~~ OccupancySensorTypeBitmap	0b0000 0xxx			R V	M

2.7.5.1. 2.7.6.1. Occupancy Attribute

The Occupancy attribute ~~is a bitmap. Bit 0 specifies~~ indicates the ~~sensed occupancy as follows: 1 = occupied, 0 = unoccupied. All other bits are reserved.~~ status of occupancy.

2.7.5.2. 2.7.6.2. OccupancySensorType Attribute

The OccupancySensorType attribute specifies the type of the occupancy sensor. ~~This attribute shall be set to one of the non-reserved values listed in Values of the OccupancySensorType Attribute .~~

~~Table 32. Values of the OccupancySensorType Attribute Value Description 0 PIR 1 Ultrasonic 2 PIR and ultrasonic 3 Physical contact~~

2.7.5.3. 2.7.6.3. OccupancySensorTypeBitmap Attribute

The OccupancySensorTypeBitmap attribute specifies the types of the occupancy ~~sensor, as listed below; a~~ sensor. A ‘1’ in each bit position indicates ~~this type~~ the capability is implemented.

~~Table 33. The OccupancySensorTypeBitmap Attribute Bit Description 0 PIR 1 Ultrasonic 2 Physical contact~~

The value of the OccupancySensorTypeBitmap attribute and the OccupancySensorType attribute SHALL be aligned as defined below.

~~OccupancySensorTypeBitmap~~ 0 1

Table ~~34.~~ 32. Mapping between ~~OccupancySensorType and~~ OccupancySensorTypeBitmap and OccupancySensorType Attributes
~~Description~~ OccupancySensorTypeBitmap	OccupancySensorType
PIR	~~0000 0001~~ PIR
Ultrasonic	~~0000 0010~~ Ultrasonic
PIR ~~and ultrasonic 2~~ + Ultrasonic	~~0000 0011~~ PIRAndUltrasonic
~~Physical contact and PIR~~ PhysicalContact	0 PhysicalContact
~~0000 0101~~ PhysicalContact + PIR	~~Physical contact and ultrasonic~~ PIR
1 PhysicalContact + Ultrasonic	~~0000 0110~~ Ultrasonic
~~Physical contact and~~ PhysicalContact + PIR ~~and ultrasonic 2~~ + Ultrasonic	~~0000 0111~~ PIRAndUltrasonic

2.7.6. 2.7.7. PIR Configuration Attribute Set

The PIR sensor configuration attribute set contains the attributes summarized in Attributes of the PIR Configuration Attribute Set .

Table ~~35.~~ 33. Attributes of the PIR Configuration Attribute Set
ID	Name	Type	Constraint	Default	Access	Conformance
0x0010	PIROccupiedToUnoccupiedDelay	uint16	all	0	RW VM	O
0x0011	PIRUnoccupiedToOccupiedDelay	uint16	all	0	RW VM	O
0x0012	PIRUnoccupiedToOccupiedThreshold	uint8	1 to 254	1	RW VM	O

2.7.6.1. 2.7.7.1. PIROccupiedToUnoccupiedDelay Attribute

The PIROccupiedToUnoccupiedDelay attribute specifies the time delay, in seconds, before the PIR sensor changes to its unoccupied state after the last detection of movement in the sensed area.

2.7.6.2. 2.7.7.2. PIRUnoccupiedToOccupiedDelay Attribute

The PIRUnoccupiedToOccupiedDelay attribute specifies the time delay, in seconds, before the PIR sensor changes to its occupied state after the detection of movement in the sensed area. This attribute is mandatory if the PIRUnoccupiedToOccupiedThreshold attribute is implemented.

2.7.6.3. 2.7.7.3. PIRUnoccupiedToOccupiedThreshold Attribute

The PIRUnoccupiedToOccupiedThreshold attribute specifies the number of movement detection events that must occur in the period PIRUnoccupiedToOccupiedDelay, before the PIR sensor changes to its occupied state. This attribute is mandatory if the PIRUnoccupiedToOccupiedDelay attribute is implemented.

2.7.7. 2.7.8. Ultrasonic Configuration Attribute Set

The ultrasonic sensor configuration attribute set contains the attributes summarized in Attributes of the Ultrasonic Configuration Attribute Set .

Table ~~36.~~ 34. Attributes of the Ultrasonic Configuration Attribute Set
ID	Name	Type	Constraint	Default	Access	Conformance
0x0020	UltrasonicOccupiedToUnoccupiedDelay	uint16	all	0	RW VM	O
0x0021	UltrasonicUnoccupiedToOccupiedDelay	uint16	all	0	RW VM	O
0x0022	UltrasonicUnoccupiedToOccupiedThreshold	uint8	1 to 254	1	RW VM	O

2.7.7.1. 2.7.8.1. UltrasonicOccupiedToUnoccupiedDelay Attribute

The UltrasonicOccupiedToUnoccupiedDelay attribute and specifies the time delay, in seconds, before the Ultrasonic sensor changes to its unoccupied state after the last detection of movement in the sensed area.

2.7.7.2. 2.7.8.2. UltrasonicUnoccupiedToOccupiedDelay Attribute

The UltrasonicUnoccupiedToOccupiedDelay attribute and specifies the time delay, in seconds, before the Ultrasonic sensor changes to its occupied state after the detection of movement in the sensed area. This attribute is mandatory if the UltrasonicUnoccupiedToOccupiedThreshold attribute is implemented.

2.7.7.3. 2.7.8.3. UltrasonicUnoccupiedToOccupiedThreshold Attribute

The UltrasonicUnoccupiedToOccupiedThreshold attribute specifies the number of movement detection events that must occur in the period UltrasonicUnoccupiedToOccupiedDelay, before the Ultrasonic sensor changes to its occupied state. This attribute is mandatory if the UltrasonicUnoccupiedToOccupiedDelay attribute is implemented.

2.7.8. 2.7.9. Physical Contact Configuration Attribute Set

The physical contact configuration attribute set contains the attributes summarized below.

Table ~~37.~~ 35. Attributes of the Physical Contact Configuration Attribute Set
ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0030	PhysicalContactOccupiedToUnoccupiedDelay	uint16	all	X	0	RW VM	O
0x0031	PhysicalContactUnoccupiedToOccupiedDelay	uint16	all	X	0	RW VM	O
0x0032	PhysicalContactUnoccupiedToOccupiedThreshold	uint8	1 to 254		1	RW VM	O

2.7.8.1. 2.7.9.1. PhysicalContactOccupiedToUnoccupiedDelay Attribute

The PhysicalContactOccupiedToUnoccupiedDelay attribute specifies the time delay, in seconds, before the physical contact occupancy sensor changes to its unoccupied state after detecting the unoccupied event. The null value indicates that the sensor does not report occupied to unoccupied transition.

2.7.8.2. 2.7.9.2. PhysicalContactUnoccupiedToOccupiedDelay Attribute

The PhysicalContactUnoccupiedToOccupiedDelay attribute specifies the time delay, in seconds, before the physical contact sensor changes to its occupied state after the detection of the occupied event.

The null value indicates that the sensor does not report unoccupied to occupied transition.

2.7.8.3. 2.7.9.3. PhysicalContactUnoccupiedToOccupiedThreshold Attribute

The PhysicalContactUnoccupiedToOccupiedThreshold attribute specifies the number of movement detection events that must occur in the period PhysicalContactUnoccupiedToOccupiedDelay, before the PIR sensor changes to its occupied state. This attribute is mandatory if the PhysicalContactUnoccupiedToOccupiedDelay attribute is implemented.

2.7.9. 2.7.10. Commands

This cluster has no cluster specific commands.

3. Lighting

3.1. General Description

3.1.1. Introduction

The clusters specified in this document are for use typically in lighting applications, but MAY be used in any application domain.

3.1.2. Terms

Ballast Factor: A measure of the light output (lumens) of a ballast and lamp combination in comparison to an ANSI standard ballast operated with the same lamp. Multiply the ballast factor by the rated lumens of the lamp to get the light output of the lamp/ballast combination.

HSV: Hue, Saturation, Value. A color space, also known as HSB (Hue, Saturation, Brightness). This is a well-known transformation of the RGB (Red, Green, Blue) color space. For more information see e.g., http://en.wikipedia.org/wiki/HSV_color_space .

Illuminance: The density of incident luminous flux on a surface. Illuminance is the standard metric for lighting levels, and is measured in lux (lx).

3.1.3. Cluster List

This section lists the lighting specific clusters as specified in this chapter.

Table ~~38.~~ 36. Overview of the Lighting Specific Clusters
ID	Cluster Name	Description
0x0300	Color Control	Attributes and commands for controlling the color of a color-capable light.
0x0301	Ballast Configuration	Attributes and commands for configuring a lighting ballast

3.2. Color Control Cluster

3.2.1. Introduction

This cluster provides an interface for changing the color of a light. Color is specified according to the Commission Internationale de l’Éclairage (CIE) specification CIE 1931 Color Space, [I1]. Color control is carried out in terms of x,y values, as defined by this specification.

Additionally, color MAY optionally be controlled in terms of color temperature, or as hue and saturation values based on optionally variable RGB and W color points. It is recommended that the hue and saturation are interpreted according to the HSV (aka HSB) color model.

Control over luminance is not included, as this is provided by means of the Level Control for Lighting cluster. It is recommended that the level provided by this cluster be interpreted as representing a proportion of the maximum intensity achievable at the current color.

3.2.2. Revision History

The global ClusterRevision attribute value SHALL be the highest revision number in the table below.

Rev	Description
1	mandatory global ClusterRevision attribute added; CCB 2028
2	added Options attribute, CCB 2085 2104 2124 2230; ZLO 1.0
3	CCB 2501 2814 2839 2840 2843 2861
4	All Hubs changes
5	new data model format and notation, FeatureMap support

3.2.3. Classification

Hierarchy

Role

PICS Code

Primary Transaction

Base

Application

Type 1 (client to server)

3.2.4. Cluster Identifiers

Identifier

Name

0x0300

Color Control

3.2.5. Features

This cluster SHALL support the FeatureMap bitmap attribute as defined below.

Bit

Code

Feature

Description

Hue/Saturation

Supports color specification via hue/saturation.

EHUE

Enhanced Hue

Enhanced hue is supported.

Color loop

Color loop is supported.

Supports color specification via XY.

Color temperature

Supports specification of color temperature.

Support for EHUE SHALL require support for HS.

Support for CL SHALL require support for EHUE.

3.2.6. Dependencies

3.2.6.1. Coupling color temperature to Level Control

If the Level Control for Lighting cluster identifier 0x0008 is supported on the same endpoint as the Color Control cluster and color temperature is supported, it is possible to couple changes in the current level to the color temperature.

The CoupleColorTempToLevel bit of the Options attribute of the Level Control cluster indicates whether the color temperature is to be linked with the CurrentLevel attribute in the Level Control cluster.

If the CoupleColorTempToLevel bit of the Options attribute of the Level Control cluster is equal to 1 and the ColorMode or EnhancedColorMode attribute is set to 2 (color temperature) then a change in the CurrentLevel attribute SHALL affect the ColorTemperatureMireds attribute. This relationship is manufacturer specific, with the qualification that the maximum value of the CurrentLevel attribute SHALL correspond to a ColorTemperatureMired attribute value equal to the CoupleColorTempToLevelMinMireds attribute. This relationship is one-way so a change to the ColorTemperatureMireds attribute SHALL NOT have any effect on the CurrentLevel attribute.

In order to simulate the behavior of an incandescent bulb, a low value of the CurrentLevel attribute SHALL be associated with a high value of the ColorTemperatureMireds attribute (i.e., a low value of color temperature in kelvins).

If the CoupleColorTempToLevel bit of the Options attribute of the Level Control cluster is equal to 0, there SHALL be no link between color temperature and current level.

3.2.7. Color Information Attribute Set

The attributes defined in this cluster specification are arranged into four sets of related attributes.

The Color Information attribute set contains the attributes summarized below.

Table ~~39.~~ 37. Attributes of the Color Information Attribute Set
ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0000	CurrentHue	uint8	0 to 254	PN	0	R V	HS
0x0001	CurrentSaturation	uint8	0 to 254	PSN	0	R V	HS
0x0002	RemainingTime	uint16	0 to 65534		0	R V	O
0x0003	CurrentX	uint16	0 to 0xfeff	PSN	0x616b (0.381)	R V	XY
0x0004	CurrentY	uint16	0 to 0xfeff	PSN	0x607d (0.377)	R V	XY
0x0005	DriftCompensation	enum8	0 to 4		-	R V	O
0x0006	CompensationText	string	max 254		-	R V	O
0x0007	ColorTemperatureMireds	uint16	0 to 0xfeff	PSN	0x00fa (4000K)	R V	CT
0x0008	ColorMode	enum8	0 to 2	N	1	R V	M
0x000f	Options	map8	desc		0	RW VO	M
0x4000	EnhancedCurrentHue	uint16	all	SN	0	R V	EHUE
0x4001	EnhancedColorMode	enum8	0 to 3	N	1	R V	M
0x4002	ColorLoopActive	uint8	all	SN	0	R V	CL
0x4003	ColorLoopDirection	uint8	all	SN	0	R V	CL
0x4004	ColorLoopTime	uint16	all	SN	0x0019	R V	CL
0x4005	ColorLoopStartEnhancedHue	uint16	all		0x2300	R V	CL
0x4006	ColorLoopStoredEnhancedHue	uint16	all		0	R V	CL
0x400a	ColorCapabilities	map16	0 to 0x001f		0	R V	M
0x400b	ColorTempPhysicalMinMireds	uint16	0 to 0xfeff		0	R V	CT
0x400c	ColorTempPhysicalMaxMireds	uint16	0 to 0xfeff		0xfeff	R V	CT
0x400d	CoupleColorTempToLevelMinMireds	uint16	ColorTempPhysicalMinMireds to ColorTemperatureMireds		MS	R V	CT \| ColorTemperatureMireds
0x4010	StartUpColorTemperatureMireds	uint16	0 to 0xfeff	X	MS	RW VM	CT \| ColorTemperatureMireds

Regarding attributes whose values persistent across an OTA restart (designated by ‘N’ in the Access column in the table above), only those attributes that are supported (due to the color capabilities of the device) need to be stored.

If the Scenes server cluster is implemented on the same endpoint, the following extension fields SHALL be added to the Scene Table in the given order, i.e., the attribute listed as 1 is added first:

CurrentX
CurrentY
EnhancedCurrentHue
CurrentSaturation
ColorLoopActive
ColorLoopDirection
ColorLoopTime
ColorTemperatureMireds

Since there is a direct relation between ColorTemperatureMireds and XY, color temperature, if supported, is stored as XY in the scenes table.

Attributes in the scene table that are not supported by the device (according to the FeatureMap attribute) SHALL be present in the scene table but ignored.

3.2.7.1. CurrentHue Attribute

The CurrentHue attribute contains the current hue value of the light. It is updated as fast as practical during commands that change the hue.

The hue in degrees SHALL be related to the CurrentHue attribute by the relationship:
Hue = CurrentHue x 360 / 254 (CurrentHue in the range 0 to 254 inclusive)

If this attribute is implemented then the CurrentSaturation and ColorMode attributes SHALL also be implemented.

3.2.7.2. CurrentSaturation Attribute

The CurrentSaturation attribute holds the current saturation value of the light. It is updated as fast as practical during commands that change the saturation.

The saturation SHALL be related to the CurrentSaturation attribute by the relationship:
Saturation = CurrentSaturation/254 (CurrentSaturation in the range 0 to 254 inclusive)

If this attribute is implemented then the CurrentHue and ColorMode attributes SHALL also be implemented.

3.2.7.3. RemainingTime Attribute

The RemainingTime attribute holds the time remaining, in 1/10ths of a second, until the currently active command will be complete.

3.2.7.4. CurrentX Attribute

The CurrentX attribute contains the current value of the normalized chromaticity value x, as defined in the CIE xyY Color Space. It is updated as fast as practical during commands that change the color.

The value of x SHALL be related to the CurrentX attribute by the relationship

x = CurrentX / 65536 (CurrentX in the range 0 to 65279 inclusive)

3.2.7.5. CurrentY Attribute

The CurrentY attribute contains the current value of the normalized chromaticity value y, as defined in the CIE xyY Color Space. It is updated as fast as practical during commands that change the color.

The value of y SHALL be related to the CurrentY attribute by the relationship

y = CurrentY / 65536 (CurrentY in the range 0 to 65279 inclusive)

3.2.7.6. DriftCompensation Attribute

The DriftCompensation attribute indicates what mechanism, if any, is in use for compensation for color/intensity drift over time. It SHALL be one of the non-reserved values in Values of the DriftCompensation Attribute .

Table ~~40.~~ 38. Values of the DriftCompensation Attribute
Value	Description
0	None
1	Other / Unknown
2	Temperature monitoring
3	Optical luminance monitoring and feedback
4	Optical color monitoring and feedback

3.2.7.7. CompensationText Attribute

The CompensationText attribute holds a textual indication of what mechanism, if any, is in use to compensate for color/intensity drift over time.

3.2.7.8. ColorTemperatureMireds Attribute

The ColorTemperatureMireds attribute contains a scaled inverse of the current value of the color temperature. The unit of ColorTemperatureMireds is the mired (micro reciprocal degree), AKA mirek (micro reciprocal kelvin). It is updated as fast as practical during commands that change the color.

The color temperature value in kelvins SHALL be related to the ColorTemperatureMireds attribute in mireds by the relationship

Color temperature in kelvins = 1,000,000 / ColorTemperatureMireds, where ColorTemperatureMireds is in the range 1 to 65279 mireds inclusive, giving a color temperature range from 1,000,000 kelvins to 15.32 kelvins.

If this attribute is implemented then the ColorMode attribute SHALL also be implemented.

3.2.7.9. ColorMode Attribute

The ColorMode attribute indicates which attributes are currently determining the color of the device.

The value of the ColorMode attribute cannot be written directly - it is set upon reception of any command in section Commands to the appropriate mode for that command.

Table ~~41.~~ 39. Values of the ColorMode Attribute
Value	Attributes that Determine the Color
0	CurrentHue and CurrentSaturation
1	CurrentX and CurrentY
2	ColorTemperatureMireds

3.2.7.10. Options Attribute

Below is the format and description of the Options attribute and temporary Options bitmap and the effect on dependent commands.

Table ~~42.~~ 40. Options Attribute
Bit	Name	Values & Summary
0	ExecuteIfOff	0 – Do not execute command if the On/Off cluster, OnOff attribute is FALSE. 1 – Execute command if the On/Off cluster, OnOff attribute is FALSE.

ExecuteIfOff Options bit: Command execution SHALL NOT continue beyond the Options processing if all of these criteria are true:

The On/Off cluster exists on the same endpoint as this cluster.
The OnOff attribute of the On/Off cluster, on this endpoint, is FALSE.
The value of the ExecuteIfOff bit is 0.

3.2.7.11. EnhancedCurrentHue Attribute

The EnhancedCurrentHue attribute represents non-equidistant steps along the CIE 1931 color triangle, and it provides 16-bits precision.

The upper 8 bits of this attribute SHALL be used as an index in the implementation specific XY lookup table to provide the non-equidistance steps. The lower 8 bits SHALL be used to interpolate between these steps in a linear way in order to provide color zoom for the user.

To provide compatibility with standard ZCL, the CurrentHue attribute SHALL contain a hue value in the range 0 to 254, calculated from the EnhancedCurrentHue attribute.

3.2.7.12. EnhancedColorMode Attribute

The EnhancedColorMode attribute specifies which attributes are currently determining the color of the device, as detailed in Values of the EnhancedColorMode Attribute .

Table ~~43.~~ 41. Values of the EnhancedColorMode Attribute
Value	Attributes That Determine the Color
0	CurrentHue and CurrentSaturation
1	CurrentX and CurrentY
2	ColorTemperatureMireds
3	EnhancedCurrentHue and CurrentSaturation

To provide compatibility with standard ZCL, the original ColorMode attribute SHALL indicate ‘CurrentHue and CurrentSaturation’ when the light uses the EnhancedCurrentHue attribute. If the ColorMode attribute is changed, e.g., due to one of the standard Color Control cluster commands defined in the ZCL, its new value SHALL be copied to the EnhancedColorMode attribute.

3.2.7.13. ColorLoopActive Attribute

The ColorLoopActive attribute specifies the current active status of the color loop. If this attribute has the value 0, the color loop SHALL not be active. If this attribute has the value 1, the color loop SHALL be active. All other values (2 to 254) are reserved.

3.2.7.14. ColorLoopDirection Attribute

The ColorLoopDirection attribute specifies the current direction of the color loop. If this attribute has the value 0, the EnhancedCurrentHue attribute SHALL be decremented. If this attribute has the value 1, the EnhancedCurrentHue attribute SHALL be incremented. All other values (2 to 254) are reserved.

3.2.7.15. ColorLoopTime Attribute

The ColorLoopTime attribute specifies the number of seconds it SHALL take to perform a full color loop, i.e., to cycle all values of the EnhancedCurrentHue attribute (between 0 and 0xfffe).

3.2.7.16. ColorLoopStartEnhancedHue Attribute

The ColorLoopStartEnhancedHue attribute specifies the value of the EnhancedCurrentHue attribute from which the color loop SHALL be started.

3.2.7.17. ColorLoopStoredEnhancedHue Attribute

The ColorLoopStoredEnhancedHue attribute specifies the value of the EnhancedCurrentHue attribute before the color loop was started. Once the color loop is complete, the EnhancedCurrentHue attribute SHALL be restored to this value.

3.2.7.18. ColorCapabilities Attribute

Bits 0-4 of the ColorCapabilities attribute SHALL have the same values as the corresponding bits of the FeatureMap attribute. All other bits in ColorCapabilities SHALL be 0.

3.2.7.19. ColorTempPhysicalMinMireds Attribute

The ColorTempPhysicalMinMireds attribute indicates the minimum mired value supported by the hardware. ColorTempPhysicalMinMireds corresponds to the maximum color temperature in kelvins supported by the hardware. ColorTempPhysicalMinMireds ≤ ColorTemperatureMireds.

3.2.7.20. ColorTempPhysicalMaxMireds Attribute

The ColorTempPhysicalMaxMireds attribute indicates the maximum mired value supported by the hardware. ColorTempPhysicalMaxMireds corresponds to the minimum color temperature in kelvins supported by the hardware. ColorTemperatureMireds ≤ ColorTempPhysicalMaxMireds.

3.2.7.21. CoupleColorTempToLevelMinMireds Attribute

The CoupleColorTempToLevelMinMireds attribute specifies a lower bound on the value of the ColorTemperatureMireds attribute for the purposes of coupling the ColorTemperatureMireds attribute to the CurrentLevel attribute when the CoupleColorTempToLevel bit of the Options attribute of the Level Control cluster is equal to 1. When coupling the ColorTemperatureMireds attribute to the CurrentLevel attribute, this value SHALL correspond to a CurrentLevel value of 0xfe (100%).

This attribute SHALL be set such that the following relationship exists:
ColorTempPhysicalMinMireds ≤ CoupleColorTempToLevelMinMireds ≤ ColorTemperatureMireds

Note that since this attribute is stored as a micro reciprocal degree (mired) value (i.e. color temperature in kelvins = 1,000,000 / CoupleColorTempToLevelMinMireds), the CoupleColorTempToLevelMinMireds attribute corresponds to an upper bound on the value of the color temperature in kelvins supported by the device.

3.2.7.22. StartUpColorTemperatureMireds Attribute

The StartUpColorTemperatureMireds attribute SHALL define the desired startup color temperature value a lamp SHALL use when it is supplied with power and this value SHALL be reflected in the ColorTemperatureMireds attribute. In addition, the ColorMode and EnhancedColorMode attributes SHALL be set to 0x02 (color temperature). The values of the StartUpColorTemperatureMireds attribute are listed in the table below,

Table ~~44.~~ 42. Values of the StartUpColorTemperatureMireds attribute
Value	Action on power up
0 to 0xfeff	Set the ColorTemperatureMireds attribute to this value.
null	Set the ColorTemperatureMireds attribute to its previous value.

3.2.8. Defined Primaries Information Attribute Set

The Defined Primaries Information attribute set contains the attributes summarized in Defined Primaries Information Attribute Set .

Table ~~45.~~ 43. Defined Primaries Information Attribute Set
ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0010	NumberOfPrimaries	uint8	0 to 6	FX	-	R V	M
0x0011	Primary1X	uint16	0 to 0xfeff	F	-	R V	M ⁰
0x0012	Primary1Y	uint16	0 to 0xfeff	F	-	R V	M ⁰
0x0013	Primary1Intensity	uint8	all	FX	-	R V	M ⁰
0x0015	Primary2X	uint16	0 to 0xfeff	F	-	R V	M ¹
0x0016	Primary2Y	uint16	0 to 0xfeff	F	-	R V	M ¹
0x0017	Primary2Intensity	uint8	all	FX	-	R V	M ¹
0x0019	Primary3X	uint16	0 to 0xfeff	F	-	R V	M ²
0x001a	Primary3Y	uint16	0 to 0xfeff	F	-	R V	M ²
0x001b	Primary3Intensity	uint8	all	FX	-	R V	M ²

M ⁱ = Mandatory if the value of the NumberOfPrimaries attribute is greater than i , otherwise optional.

3.2.8.1. NumberOfPrimaries Attribute

The NumberOfPrimaries attribute contains the number of color primaries implemented on this device. A value of null SHALL indicate that the number of primaries is unknown.

Where this attribute is implemented, the attributes below for indicating the “x” and “y” color values of the primaries SHALL also be implemented for each of the primaries from 1 to NumberOfPrimaries, without leaving gaps. Implementation of the Primary1Intensity attribute and subsequent intensity attributes is optional.

3.2.8.2. Primary1X Attribute

The Primary1X attribute contains the normalized chromaticity value x for this primary, as defined in the CIE xyY Color Space.

The value of x SHALL be related to the Primary1X attribute by the relationship

x = Primary1X / 65536 (Primary1X in the range 0 to 65279 inclusive)

3.2.8.3. Primary1Y Attribute

The Primary1Y attribute contains the normalized chromaticity value y for this primary, as defined in the CIE xyY Color Space.

The value of y SHALL be related to the Primary1Y attribute by the relationship

y = Primary1Y / 65536 (Primary1Y in the range 0 to 65279 inclusive)

3.2.8.4. Primary1Intensity Attribute

The Primary1intensity attribute contains a representation of the maximum intensity of this primary as defined in the Dimming Light Curve in the Ballast Configuration cluster (see Ballast Configuration Cluster ), normalized such that the primary with the highest maximum intensity contains the value 0xfe.

A value of null SHALL indicate that this primary is not available.

3.2.8.5. Remaining Attributes

The Primary2X, Primary2Y, Primary2Intensity, Primary3X, Primary3Y and Primary3Intensity attributes are used to represent the capabilities of the 2 ^nd and 3 ^rd primaries, where present, in the same way as for the Primary1X, Primary1Y and Primary1Intensity attributes.

3.2.9. Additional Defined Primaries Information Attribute Set

The Additional Defined Primaries Information attribute set contains the attributes summarized in Additional Defined Primaries Information Attribute Set .

Table ~~46.~~ 44. Additional Defined Primaries Information Attribute Set
ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0020	Primary4X	uint16	0 to 0xfeff	F	-	R V	M ³
0x0021	Primary4Y	uint16	0 to 0xfeff	F	-	R V	M ³
0x0022	Primary4Intensity	uint8	all	FX	-	R V	M ³
0x0024	Primary5X	uint16	0 to 0xfeff	F	-	R V	M ⁴
0x0025	Primary5Y	uint16	0 to 0xfeff	F	-	R V	M ⁴
0x0026	Primary5Intensity	uint8	all	FX	-	R V	M ⁴
0x0028	Primary6X	uint16	0 to 0xfeff	F	-	R V	M ⁵
0x0029	Primary6Y	uint16	0 to 0xfeff	F	-	R V	M ⁵
0x002a	Primary6Intensity	uint8	all	FX	-	R V	M ⁵

M ⁱ = Mandatory if the value of the NumberOfPrimaries attribute is greater than i , otherwise optional.

3.2.9.1. Remaining Attributes

The Primary4X, Primary4Y, Primary4Intensity, Primary5X, Primary5Y, Primary5Intensity, Primary6X, Primary6Y and Primary6Intensity attributes represent the capabilities of the 4 ^th, 5 ^th and 6 ^th primaries, where present, in the same way as the Primary1X, Primary1Y and Primary1Intensity attributes.

3.2.10. Defined Color Points Settings Attribute Set

The Defined Color Points Settings attribute set contains the attributes summarized in Defined Color Points Settings Attribute Set .

Table ~~47.~~ 45. Defined Color Points Settings Attribute Set
ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0030	WhitePointX	uint16	0 to 0xfeff		-	RW VM	O
0x0031	WhitePointY	uint16	0 to 0xfeff		-	RW VM	O
0x0032	ColorPointRX	uint16	0 to 0xfeff		-	RW VM	O
0x0033	ColorPointRY	uint16	0 to 0xfeff		-	RW VM	O
0x0034	ColorPointRIntensity	uint8	all	X	-	RW VM	O
0x0036	ColorPointGX	uint16	0 to 0xfeff		-	RW VM	O
0x0037	ColorPointGY	uint16	0 to 0xfeff		-	RW VM	O
0x0038	ColorPointGIntensity	uint8	all	X	-	RW VM	O
0x003a	ColorPointBX	uint16	0 to 0xfeff		-	RW VM	O
0x003b	ColorPointBY	uint16	0 to 0xfeff		-	RW VM	O
0x003c	ColorPointBIntensity	uint8	all	X	-	RW VM	O

3.2.10.1. WhitePointX Attribute

The WhitePointX attribute contains the normalized chromaticity value x, as defined in the CIE xyY Color Space, of the current white point of the device.

The value of x SHALL be related to the WhitePointX attribute by the relationship

x = WhitePointX / 65536 (WhitePointX in the range 0 to 65279 inclusive)

3.2.10.2. WhitePointY Attribute

The WhitePointY attribute contains the normalized chromaticity value y, as defined in the CIE xyY Color Space, of the current white point of the device.

The value of y SHALL be related to the WhitePointY attribute by the relationship

y = WhitePointY / 65536 (WhitePointY in the range 0 to 65279 inclusive)

3.2.10.3. ColorPointRX Attribute

The ColorPointRX attribute contains the normalized chromaticity value x, as defined in the CIE xyY Color Space, of the red color point of the device.

The value of x SHALL be related to the ColorPointRX attribute by the relationship

x = ColorPointRX / 65536 (ColorPointRX in the range 0 to 65279 inclusive)

3.2.10.4. ColorPointRY Attribute

The ColorPointRY attribute contains the normalized chromaticity value y, as defined in the CIE xyY Color Space, of the red color point of the device.

The value of y SHALL be related to the ColorPointRY attribute by the relationship

y = ColorPointRY / 65536 (ColorPointRY in the range 0 to 65279 inclusive)

3.2.10.5. ColorPointRIntensity Attribute

The ColorPointRIntensity attribute contains a representation of the relative intensity of the red color point as defined in the Dimming Light Curve in the Ballast Configuration cluster (see Ballast Configuration Cluster ), normalized such that the color point with the highest relative intensity contains the value 0xfe.

A value of null SHALL indicate an invalid value.

3.2.10.6. Remaining Attributes

The ColorPointGX, ColorPointGY, ColorPointGIntensity, ColorPointBX, ColorPointBY and, ColorPointBIntensity attributes are used to represent the chromaticity values and intensities of the green and blue color points, in the same way as for the ColorPointRX, ColorPointRY and ColorPointRIntensity attributes.

If any one of these red, green or blue color point attributes is implemented then they SHALL all be implemented.

3.2.11. Commands

The command IDs for the Color Control cluster are listed in Command IDs for the Color Control Cluster .

Table ~~48.~~ 46. Command IDs for the Color Control Cluster
ID	Name	Direction	Response	Access	Conformance
0x00	MoveToHue	client ⇒ server	Y	O	HS
0x01	MoveHue	client ⇒ server	Y	O	HS
0x02	StepHue	client ⇒ server	Y	O	HS
0x03	MoveToSaturation	client ⇒ server	Y	O	HS
0x04	MoveSaturation	client ⇒ server	Y	O	HS
0x05	StepSaturation	client ⇒ server	Y	O	HS
0x06	MoveToHueAndSaturation	client ⇒ server	Y	O	HS
0x07	MoveToColor	client ⇒ server	Y	O	XY
0x08	MoveColor	client ⇒ server	Y	O	XY
0x09	StepColor	client ⇒ server	Y	O	XY
0x0a	MoveToColorTemperature	client ⇒ server	Y	O	CT
0x40	EnhancedMoveToHue	client ⇒ server	Y	O	EHUE
0x41	EnhancedMoveHue	client ⇒ server	Y	O	EHUE
0x42	EnhancedStepHue	client ⇒ server	Y	O	EHUE
0x43	EnhancedMoveToHueAndSaturation	client ⇒ server	Y	O	EHUE
0x44	ColorLoopSet	client ⇒ server	Y	O	CL
0x47	StopMoveStep	client ⇒ server	Y	O	HS \| XY \| CT
0x4b	MoveColorTemperature	client ⇒ server	Y	O	CT
0x4c	StepColorTemperature	client ⇒ server	Y	O	CT

3.2.11.1. Generic Usage Notes

When asked to change color via one of these commands, the implementation SHALL select a color, within the limits of the hardware of the device, which is as close as possible to that requested. The determination as to the true representations of color is out of the scope of this specification. However, as long as the color data fields of the received command are within the permitted range of this specification and no error condition applies, the resulting status code SHALL be SUCCESS.

For example the MoveToColorTemperature command: if the target color temperature is not achievable by the hardware then the color temperature SHALL be clipped at the physical minimum or maximum achievable (depending on the direction of the color temperature transition) when the device reaches that color temperature (which MAY be before the requested transition time).

If a color loop is active (i.e., the ColorLoopActive attribute is equal to 1), it SHALL only be stopped by sending a specific ColorLoopSet command frame with a request to deactivate the color loop (i.e., the color loop SHALL not be stopped on receipt of another command such as the EnhancedMoveToHue command). In addition, while a color loop is active, a manufacturer MAY choose to ignore incoming color commands which affect a change in hue.

3.2.11.2. Note on Change of ColorMode

The first action taken when any one of these commands is received is to change the ColorMode attribute to the appropriate value for the command (see individual commands). Note that, when moving from one color mode to another (e.g., CurrentX/CurrentY to CurrentHue/CurrentSaturation), the starting color for the command is formed by calculating the values of the new attributes (in this case CurrentHue, CurrentSaturation) from those of the old attributes (in this case CurrentX and CurrentY).

When moving from a mode to another mode that has a more restricted color range (e.g., CurrentX/CurrentY to CurrentHue/CurrentSaturation, or CurrentHue/CurrentSaturation to ColorTemperatureMireds) it is possible for the current color value to have no equivalent in the new mode. The behavior in such cases is manufacturer dependent, and therefore it is recommended to avoid color mode changes of this kind during usage.

3.2.11.3. Use of the OptionsMask and OptionsOverride fields

The resulting temporary Options bitmap SHALL then be processed as defined in section Options Attribute .

3.2.11.4. MoveToHue Command

The MoveToHue command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

Hue

uint8

0 to 254

Direction

enum8

desc

TransitionTime

uint16

0 to 65534

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.4.1. Hue Field

The Hue field specifies the hue to be moved to.

3.2.11.4.2. Direction Field

The Direction field SHALL be one of the non-reserved values in Values of the Direction Field .

Table ~~49.~~ 47. Values of the Direction Field
Value	Description
0	Shortest distance
1	Longest distance
2	Up
3	Down

3.2.11.4.3. TransitionTime Field

The TransitionTime field specifies, in 1/10ths of a second, the time that SHALL be taken to move to the new hue.

3.2.11.4.4. OptionsMask and OptionsOverride fields

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.4.5. Effect on Receipt

On receipt of this command, a device SHALL also set the ColorMode attribute to the value 0 and then SHALL move from its current hue to the value given in the Hue field.

The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the new hue SHALL be equal to the TransitionTime field.

As hue is effectively measured on a circle, the new hue MAY be moved to in either direction. The direction of hue change is given by the Direction field. If Direction is 'Shortest distance', the direction is taken that involves the shortest path round the circle. This case corresponds to expected normal usage. If Direction is 'Longest distance', the direction is taken that involves the longest path round the circle. This case can be used for 'rainbow effects'. In both cases, if both distances are the same, the Up direction SHALL be taken.

3.2.11.5. MoveHue Command

The MoveHue command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

MoveMode

enum8

desc

Rate

uint8

all

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.5.1. MoveMode Field

The MoveMode field SHALL be one of the non-reserved values in Values of the MoveMode Field . If the MoveMode field is equal to 0 (Stop), the Rate field SHALL be ignored.

Table ~~50.~~ 48. Values of the MoveMode Field
Value	Description
0	Stop
1	Up
2	Reserved
3	Down

3.2.11.5.2. Rate Field

The Rate field specifies the rate of movement in steps per second. A step is a change in the device’s hue of one unit. If the MoveMode field is set to 1 (up) or 3 (down) and the Rate field has a value of zero, the command has no effect and a response command SHALL be sent in response, with the status code set to INVALID_COMMAND. If the MoveMode field is set to 0 (stop) the Rate field SHALL be ignored.

3.2.11.5.3. OptionsMask and OptionsOverride field

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.5.4. Effect on Receipt

On receipt of this command, a device SHALL set the ColorMode attribute to the value 0 and SHALL then move from its current hue in an up or down direction in a continuous fashion, as detailed in Actions on Receipt for MoveHue Command .

Table ~~51.~~ 49. Actions on Receipt for MoveHue Command
MoveMode	Action on Receipt
Stop	If moving, stop, else ignore the command (i.e., the command is accepted but has no effect). NB This MAY also be used to stop a MoveToHue command, a MoveToSaturation command, or a MoveToHueAndSaturation command.
Up	Increase the device’s hue at the rate given in the Rate field. If the hue reaches the maximum allowed for the device, then wraparound and proceed from its minimum allowed value.
Down	Decrease the device’s hue at the rate given in the Rate field. If the hue reaches the minimum allowed for the device, then wraparound and proceed from its maximum allowed value.

3.2.11.6. StepHue Command

The StepHue command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

StepMode

enum8

desc

StepSize

uint8

all

TransitionTime

uint8

all

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.6.1. StepMode Field

The StepMode field SHALL be one of the non-reserved values in Values of the StepMode Field .

Table ~~52.~~ 50. Values of the StepMode Field
Value	Description
0	Reserved
1	Up
2	Reserved
3	Down

3.2.11.6.2. StepSize Field

The change to be added to (or subtracted from) the current value of the device’s hue.

3.2.11.6.3. TransitionTime Field

The TransitionTime field specifies, in 1/10ths of a second, the time that SHALL be taken to perform the step. A step is a change in the device’s hue of ‘Step size’ units.

Note: Here the TransitionTime data field is of data type uint8, where uint16 is more common for TransitionTime data fields in other clusters / commands.

3.2.11.6.4. OptionsMask and OptionsOverride fields

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.6.5. Effect on Receipt

On receipt of this command, a device SHALL set the ColorMode attribute to the value 0 and SHALL then move from its current hue in an up or down direction by one step, as detailed in Actions on Receipt for StepHue Command .

Table ~~53.~~ 51. Actions on Receipt for StepHue Command
StepMode	Action on Receipt
Up	Increase the device’s hue by one step, in a continuous fashion. If the hue value reaches the maximum value then wraparound and proceed from the minimum allowed value.
Down	Decrease the device’s hue by one step, in a continuous fashion. If the hue value reaches the minimum value then wraparound and proceed from the maximum allowed value.

3.2.11.7. MoveToSaturation Command

The MoveToSaturation command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

Saturation

uint8

0 to 254

TransitionTime

uint16

0 to 65534

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.7.1. OptionsMask and OptionsOverride fields

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.7.2. Effect on Receipt

On receipt of this command, a device set the ColorMode attribute to the value 0 and SHALL then move from its current saturation to the value given in the Saturation field.

The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the new saturation SHALL be equal to the TransitionTime field, in 1/10ths of a second.

3.2.11.8. MoveSaturation Command

The MoveSaturation command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

MoveMode

enum8

desc

Rate

uint8

all

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.8.1. MoveMode Field

The MoveMode field SHALL be one of the non-reserved values in Values of the MoveMode Field . If the MoveMode field is equal to 0 (Stop), the Rate field SHALL be ignored.

Table ~~54.~~ 52. Values of the MoveMode Field
Value	Description
0	Stop
1	Up
2	Reserved
3	Down

3.2.11.8.2. Rate Field

The Rate field specifies the rate of movement in steps per second. A step is a change in the device’s saturation of one unit. If the MoveMode field is set to 1 (up) or 3 (down) and the Rate field has a value of zero, the command has no effect and a response command SHALL be sent in response, with the status code set to INVALID_COMMAND. If the MoveMode field is set to 0 (stop) the Rate field SHALL be ignored.

3.2.11.8.3. OptionsMask and OptionsOverride fields

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.8.4. Effect on Receipt

On receipt of this command, a device SHALL set the ColorMode attribute to the value 0 and SHALL then move from its current saturation in an up or down direction in a continuous fashion, as detailed in Actions on Receipt for MoveSaturation Command .

Table ~~55.~~ 53. Actions on Receipt for MoveSaturation Command
MoveMode	Action on Receipt
Stop	If moving, stop, else ignore the command (i.e., the command is accepted but has no effect). NB This MAY also be used to stop a MoveToSaturation command, a MoveToHue command, or a MoveToHueAndSaturation command.
Up	Increase the device’s saturation at the rate given in the Rate field. If the saturation reaches the maximum allowed for the device, stop.
Down	Decrease the device’s saturation at the rate given in the Rate field. If the saturation reaches the minimum allowed for the device, stop.

3.2.11.9. StepSaturation Command

The StepSaturation command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

StepMode

enum8

desc

StepSize

uint8

all

TransitionTime

uint8

all

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.9.1. StepMode Field

The StepMode field SHALL be one of the non-reserved values in Values of the StepMode Field .

Table ~~56.~~ 54. Values of the StepMode Field
Value	Description
1	Up
2	Reserved
3	Down

3.2.11.9.2. StepSize Field

The change to be added to (or subtracted from) the current value of the device’s saturation.

3.2.11.9.3. TransitionTime Field

The TransitionTime field specifies, in 1/10ths of a second, the time that SHALL be taken to perform the step. A step is a change in the device’s saturation of ‘Step size’ units.

Note: Here the TransitionTime data field is of data type uint8, where uint16 is more common for TransitionTime data fields in other clusters / commands.

3.2.11.9.4. OptionsMask and OptionsOverride fields

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.9.5. Effect on Receipt

On receipt of this command, a device SHALL set the ColorMode attribute to the value 0 and SHALL then move from its current saturation in an up or down direction by one step, as detailed in Actions on Receipt for StepSaturation Command .

Table ~~57.~~ 55. Actions on Receipt for StepSaturation Command
StepMode	Action on Receipt
Up	Increase the device’s saturation by one step, in a continuous fashion. However, if the saturation value is already the maximum value then do nothing.
Down	Decrease the device’s saturation by one step, in a continuous fashion. However, if the saturation value is already the minimum value then do nothing.

3.2.11.10. MoveToHueAndSaturation Command

The MoveToHueAndSaturation command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

Hue

uint8

0 to 254

Saturation

uint8

0 to 254

TransitionTime

uint16

0 to 65534

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.10.1. OptionsMask and OptionsOverride fields

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.10.2. Effect on Receipt

On receipt of this command, a device SHALL set the ColorMode attribute to the value 0 and SHALL then move from its current hue and saturation to the values given in the Hue and Saturation fields.

The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the new color SHALL be equal to the TransitionTime field, in 1/10ths of a second.

The path through color space taken during the transition is not specified, but it is recommended that the shortest path is taken through hue/saturation space, i.e., movement is ‘in a straight line’ across the hue/saturation disk.

3.2.11.11. MoveToColor Command

The MoveToColor command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

ColorX

uint16

0 to 0xfeff

ColorY

uint16

0 to 0xfeff

TransitionTime

uint16

0 to 65534

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.11.1. OptionsMask and OptionsOverride fields

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.11.2. Effect on Receipt

On receipt of this command, a device SHALL set the value of the ColorMode attribute, where implemented, to 1, and SHALL then move from its current color to the color given in the ColorX and ColorY fields.

The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the new color SHALL be equal to the TransitionTime field, in 1/10ths of a second.

The path through color space taken during the transition is not specified, but it is recommended that the shortest path is taken through color space, i.e., movement is 'in a straight line' across the CIE xyY Color Space.

3.2.11.12. MoveColor Command

The MoveColor command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

RateX

int16

all

RateY

int16

all

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.12.1. RateX Field

The RateX field specifies the rate of movement in steps per second. A step is a change in the device’s CurrentX attribute of one unit.

3.2.11.12.2. RateY Field

The RateY field specifies the rate of movement in steps per second. A step is a change in the device’s CurrentY attribute of one unit.

3.2.11.12.3. OptionsMask and OptionsOverride fields

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.12.4. Effect on Receipt

On receipt of this command, a device SHALL set the value of the ColorMode attribute, where implemented, to 1, and SHALL then move from its current color in a continuous fashion according to the rates specified. This movement SHALL continue until the target color for the next step cannot be implemented on this device.

If both the RateX and RateY fields contain a value of zero, no movement SHALL be carried out, and the command execution SHALL have no effect other than stopping the operation of any previously received command of this cluster. This command can thus be used to stop the operation of any other command of this cluster.

3.2.11.13. StepColor Command

The StepColor command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

StepX

int16

all

StepY

int16

all

TransitionTime

uint16

0 to 65534

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.13.1. StepX and StepY Fields

The StepX and StepY fields specify the change to be added to the device’s CurrentX attribute and CurrentY attribute respectively.

3.2.11.13.2. TransitionTime Field

The TransitionTime field specifies, in 1/10ths of a second, the time that SHALL be taken to perform the color change.

3.2.11.13.3. OptionsMask and OptionsOverride fields

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.13.4. Effect on Receipt

On receipt of this command, a device SHALL set the value of the ColorMode attribute, where implemented, to 1, and SHALL then move from its current color by the color step indicated.

The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the new color SHALL be equal to the TransitionTime field, in 1/10ths of a second.

Note also that if the required step is larger than can be represented by signed 16-bit integers then more than one step command SHOULD be issued.

3.2.11.14. MoveToColorTemperature Command

The MoveToColorTemperature command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

ColorTemperatureMireds

uint16

0 to 0xfeff

TransitionTime

uint16

0 to 65534

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.14.1. OptionsMask and OptionsOverride fields

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.14.2. Effect on Receipt

On receipt of this command, a device SHALL set the value of the ColorMode attribute, where implemented, to 2, and SHALL then move from its current color to the color given by the ColorTemperatureMireds field.

The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the new color SHALL be equal to the TransitionTime field, in 1/10ths of a second.

By definition of this color mode, the path through color space taken during the transition is along the ‘Black Body Line'.

3.2.11.15. EnhancedMoveToHue Command

The EnhancedMoveToHue command allows lamps to be moved in a smooth continuous transition from their current hue to a target hue.

The EnhancedMoveToHue command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

EnhancedHue

uint16

all

Direction

enum8

desc

TransitionTime

uint16

0 to 65534

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.15.1. EnhancedHue Field

The EnhancedHue field specifies the target extended hue for the lamp.

3.2.11.15.2. Direction Field

This field is identical to the Direction field of the MoveToHue command of the Color Control cluster (see sub-clause Use of the OptionsMask and OptionsOverride fields ).

3.2.11.15.3. TransitionTime Field

This field is identical to the TransitionTime field of the MoveToHue command of the Color Control cluster (see sub-clause Use of the OptionsMask and OptionsOverride fields ).

3.2.11.15.4. OptionsMask and OptionsOverride fields

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.15.5. Effect on Receipt

On receipt of this command, a device SHALL set the ColorMode attribute to 0 and set the EnhancedColorMode attribute to the value 3. The device SHALL then move from its current enhanced hue to the value given in the EnhancedHue field.

The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the new enhanced hue SHALL be equal to the TransitionTime field.

3.2.11.16. EnhancedMoveHue Command

The EnhancedMoveHue command allows lamps to be moved in a continuous stepped transition from their current hue to a target hue.

The EnhancedMoveHue command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

MoveMode

enum8

desc

Rate

uint16

all

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.16.1. MoveMode Field

This field is identical to the MoveMode field of the MoveHue command of the Color Control cluster (see sub-clause MoveHue Command ). If the MoveMode field is equal to 0 (Stop), the Rate field SHALL be ignored.

3.2.11.16.2. Rate field

The Rate field specifies the rate of movement in steps per second. A step is a change in the extended hue of a device by one unit. If the MoveMode field is set to 1 (up) or 3 (down) and the Rate field has a value of zero, the command has no effect and a response command SHALL be sent in response, with the status code set to INVALID_COMMAND. If the MoveMode field is set to 0 (stop) the Rate field SHALL be ignored.

3.2.11.16.3. OptionsMask and OptionsOverride fields

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.16.4. Effect on receipt

Table ~~58.~~ 56. Actions on Receipt of the EnhancedMoveHueCommand
MoveMode	Action on Receipt
Stop	If moving, stop, else ignore the command (i.e., the command is accepted but has no effect). NB This MAY also be used to stop an EnhancedMoveToHue command or an EnhancedMoveToHueAndSaturation command.
Up	Increase the device’s enhanced hue at the rate given in the Rate field. If the enhanced hue reaches the maximum allowed for the device, wraparound and proceed from its minimum allowed value.
Down	Decrease the device’s enhanced hue at the rate given in the Rate field. If the hue reaches the minimum allowed for the device, wraparound and proceed from its maximum allowed value.

3.2.11.17. EnhancedStepHue Command

The EnhancedStepHue command allows lamps to be moved in a stepped transition from their current hue to a target hue, resulting in a linear transition through XY space.

The EnhancedStepHue command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

StepMode

enum8

desc

StepSize

uint16

all

TransitionTime

uint16

0 to 65534

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.17.1. StepMode Field

This field is identical to the StepMode field of the StepHue command of the Color Control cluster (see sub-clause StepHue Command ).

3.2.11.17.2. StepSize Field

The StepSize field specifies the change to be added to (or subtracted from) the current value of the device’s enhanced hue.

3.2.11.17.3. TransitionTime Field

The TransitionTime field specifies, in units of 1/10ths of a second, the time that SHALL be taken to perform the step. A step is a change to the device’s enhanced hue of a magnitude corresponding to the StepSize field.

Note: Here TransitionTime data field is of data type uint16, while the TransitionTime data field of the StepHue command is of data type uint8.

3.2.11.17.4. OptionsMask and OptionsOverride fields

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.17.5. Effect on Receipt

On receipt of this command, a device SHALL set the ColorMode attribute to 0 and the EnhancedColorMode attribute to the value 3. The device SHALL then move from its current enhanced hue in an up or down direction by one step, as detailed in Actions on Receipt for the EnhancedStepHue Command .

Table ~~59.~~ 57. Actions on Receipt for the EnhancedStepHue Command
StepMode	Action on Receipt
Up	Increase the device’s enhanced hue by one step. If the enhanced hue reaches the maximum allowed for the device, wraparound and proceed from its minimum allowed value.
Down	Decrease the device’s enhanced hue by one step. If the hue reaches the minimum allowed for the device, wraparound and proceed from its maximum allowed value.

3.2.11.18. EnhancedMoveToHueAndSaturation Command

The EnhancedMoveToHueAndSaturation command allows lamps to be moved in a smooth continuous transition from their current hue to a target hue and from their current saturation to a target saturation.

The EnhancedMoveToHueAndSaturation command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

EnhancedHue

uint16

all

Saturation

uint8

0 to 254

TransitionTime

uint16

0 to 65534

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.18.1. EnhancedHue Field

The EnhancedHue field specifies the target extended hue for the lamp.

3.2.11.18.2. Saturation Field

This field is identical to the Saturation field of the MoveToHueAndSaturation command of the Color Control cluster (see sub-clause MoveToHueAndSaturation Command ).

3.2.11.18.3. TransitionTime Field

This field is identical to the TransitionTime field of the MoveToHue command of the Color Control cluster (see sub-clause MoveToHueAndSaturation Command ).

3.2.11.18.4. OptionsMask and OptionsOverride fields

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.18.5. Effect on Receipt

On receipt of this command, a device SHALL set the ColorMode attribute to the value 0 and set the EnhancedColorMode attribute to the value 3. The device SHALL then move from its current enhanced hue and saturation to the values given in the EnhancedHue and Saturation fields.

The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the new color SHALL be equal to the TransitionTime field, in 1/10ths of a second.

The path through color space taken during the transition is not specified, but it is recommended that the shortest path is taken through hue/saturation space, i.e., movement is 'in a straight line' across the hue/saturation disk.

3.2.11.19. ColorLoopSet Command

The Color Loop Set command allows a color loop to be activated such that the color lamp cycles through its range of hues.

The ColorLoopSet command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

UpdateFlags

map8

desc

Action

enum8

desc

Direction

enum8

desc

Time

uint16

all

StartHue

uint16

all

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.19.1. UpdateFlags Field

The UpdateFlags field specifies which color loop attributes to update before the color loop is started. This field SHALL be formatted as illustrated in Format of the UpdateFlags Field of the ColorLoopSet Command .

Table ~~60.~~ 58. Format of the UpdateFlags Field of the ColorLoopSet Command
Bit	Name sub-field
0	UpdateAction
1	UpdateDirection
2	UpdateTime
3	UpdateStartHue
4-7	(Reserved)

The UpdateAction sub-field is 1 bit in length and specifies whether the device SHALL adhere to the action field in order to process the command. If this sub-field is set to 1, the device SHALL adhere to the action field. If this sub-field is set to 0, the device SHALL ignore the Action field.

The UpdateDirection sub-field is 1 bit in length and specifies whether the device SHALL update the ColorLoopDirection attribute with the Direction field. If this sub-field is set to 1, the device SHALL update the value of the ColorLoopDirection attribute with the value of the Direction field. If this sub-field is set to 0, the device SHALL ignore the Direction field.

The UpdateTime sub-field is 1 bit in length and specifies whether the device SHALL update the ColorLoopTime attribute with the Time field. If this sub-field is set to 1, the device SHALL update the value of the ColorLoopTime attribute with the value of the Time field. If this sub-field is set to 0, the device SHALL ignore the Time field.

The UpdateStartHue sub-field is 1 bit in length and specifies whether the device SHALL update the ColorLoopStartEnhancedHue attribute with the StartHue field. If this sub-field is set to 1, the device SHALL update the value of the ColorLoopStartEnhancedHue attribute with the value of the StartHue field. If this sub-field is set to 0, the device SHALL ignore the StartHue field.

3.2.11.19.2. Action Field

The Action field specifies the action to take for the color loop if the UpdateAction sub-field of the UpdateFlags field is set to 1. This field SHALL be set to one of the non-reserved values listed in Values of the Action Field of the ColorLoopSet Command .

Table ~~61.~~ 59. Values of the Action Field of the ColorLoopSet Command
Value	Description
0	De-activate the color loop.
1	Activate the color loop from the value in the ColorLoopStartEnhancedHue field.
2	Activate the color loop from the value of the EnhancedCurrentHue attribute.

3.2.11.19.3. Direction Field

The Direction field specifies the direction for the color loop if the Update Direction field of the UpdateFlags field is set to 1. This field SHALL be set to one of the non-reserved values listed in Values of the Direction Field of the ColorLoopSet Command .

Table ~~62.~~ 60. Values of the Direction Field of the ColorLoopSet Command
Value	Description
0	Decrement the hue in the color loop.
1	Increment the hue in the color loop.

3.2.11.19.4. Time Field

The Time field specifies the number of seconds over which to perform a full color loop if the UpdateTime sub-field of the UpdateFlags field is set to 1.

3.2.11.19.5. Start Hue Field

The StartHue field specifies the starting hue to use for the color loop if the Update StartHue field of the Update Flags field is set to 1.

3.2.11.19.6. OptionsMask and OptionsOverride fields

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.19.7. Effect on Receipt

On receipt of this command, the device SHALL first update its color loop attributes according to the value of the UpdateFlags field, as follows. If the UpdateDirection sub-field is set to 1, the device SHALL set the ColorLoopDirection attribute to the value of the Direction field. If the UpdateTime sub-field is set to 1, the device SHALL set the ColorLoopTime attribute to the value of the Time field. If the UpdateStartHue sub-field is set to 1, the device SHALL set the ColorLoopStartEnhancedHue attribute to the value of the StartHue field. If the color loop is active (and stays active), the device SHALL immediately react on updates of the ColorLoopDirection and ColorLoopTime attributes.

If the UpdateAction sub-field of the UpdateFlags field is set to 1, the device SHALL adhere to the action specified in the Action field, as follows. If the value of the Action field is set to 0 and the color loop is active, i.e. the ColorLoopActive attribute is set to 1, the device SHALL de-active the color loop, set the ColorLoopActive attribute to 0 and set the EnhancedCurrentHue attribute to the value of the ColorLoopStoredEnhancedHue attribute. If the value of the Action field is set to 0 and the color loop is inactive, i.e. the ColorLoopActive attribute is set to 0, the device SHALL ignore the action update component of the command. If the value of the action field is set to 1, the device SHALL set the ColorLoopStoredEnhancedHue attribute to the value of the EnhancedCurrentHue attribute, set the ColorLoopActive attribute to 1 and activate the color loop, starting from the value of the ColorLoopStartEnhancedHue attribute. If the value of the Action field is set to 2, the device SHALL set the ColorLoopStoredEnhancedHue attribute to the value of the EnhancedCurrentHue attribute, set the ColorLoopActive attribute to 1 and activate the color loop, starting from the value of the EnhancedCurrentHue attribute.

If the color loop is active, the device SHALL cycle over the complete range of values of the EnhancedCurrentHue attribute in the direction of the ColorLoopDirection attribute over the time specified in the ColorLoopTime attribute. The level of increments/decrements is application specific.

3.2.11.20. StopMoveStep Command

The StopMoveStep command is provided to allow MoveTo and Step commands to be stopped. (Note this automatically provides symmetry to the Level Control cluster.)

Note: the StopMoveStep command has no effect on an active color loop.

The StopMoveStep command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.20.1. OptionsMask and OptionsOverride fields

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.20.2. Effect on Receipt

Upon receipt of this command, any MoveTo, Move or Step command currently in process SHALL be terminated. The values of the CurrentHue, EnhancedCurrentHue and CurrentSaturation attributes SHALL be left at their present value upon receipt of the StopMoveStep command, and the RemainingTime attribute SHALL be set to zero.

3.2.11.21. MoveColorTemperature Command

The MoveColorTemperature command allows the color temperature of a lamp to be moved at a specified rate.

The MoveColorTemperature command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

MoveMode

map8

desc

Rate

uint16

all

ColorTemperatureMinimumMireds

uint16

0 to 0xfeff

ColorTemperatureMaximumMireds

uint16

0 to 0xfeff

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.21.1. MoveMode Field

3.2.11.21.2. Rate Field

The Rate field specifies the rate of movement in steps per second. A step is a change in the color temperature of a device by one unit. If the MoveMode field is set to 1 (up) or 3 (down) and the Rate field has a value of zero, the command has no effect and a response command SHALL be sent in response, with the status code set to INVALID_COMMAND. If the MoveMode field is set to 0 (stop) the Rate field SHALL be ignored.

3.2.11.21.3. ColorTemperatureMinimumMireds Field

The ColorTemperatureMinimumMireds field specifies a lower bound on the ColorTemperatureMireds attribute (≡ an upper bound on the color temperature in kelvins) for the current move operation such that:

ColorTempPhysicalMinMireds ≤ ColorTemperatureMinimumMireds field ≤ ColorTemperatureMireds

As such if the move operation takes the ColorTemperatureMireds attribute towards the value of the ColorTemperatureMinimumMireds field it SHALL be clipped so that the above invariant is satisfied. If the ColorTemperatureMinimumMireds field is set to 0, ColorTempPhysicalMinMireds SHALL be used as the lower bound for the ColorTemperatureMireds attribute.

3.2.11.21.4. ColorTemperatureMaximumMireds Field

The ColorTemperatureMaximumMireds field specifies an upper bound on the ColorTemperatureMireds attribute (≡ a lower bound on the color temperature in kelvins) for the current move operation such that:

ColorTemperatureMireds ≤ ColorTemperatureMaximumMireds field ≤ ColorTempPhysicalMaxMireds

As such if the move operation takes the ColorTemperatureMireds attribute towards the value of the ColorTemperatureMaximumMireds field it SHALL be clipped so that the above invariant is satisfied. If the ColorTemperatureMaximumMireds field is set to 0, ColorTempPhysicalMaxMireds SHALL be used as the upper bound for the ColorTemperatureMireds attribute.

3.2.11.21.5. OptionsMask and OptionsOverride fields

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.21.6. Effect on Receipt

On receipt of this command, a device SHALL set both the ColorMode and EnhancedColorMode attributes to 2. The device SHALL then move from its current color temperature in an up or down direction in a continuous fashion, as detailed in Actions on Receipt of the MoveColorTemperature Command .

Table ~~63.~~ 61. Actions on Receipt of the MoveColorTemperature Command
MoveMode	Action on Receipt
Stop	If moving, stop the operation, else ignore the command (i.e., the command is accepted but has no effect).
Up	Increase the ColorTemperatureMireds attribute (≡ decrease the color temperature in kelvins) at the rate given in the Rate field. If the ColorTemperatureMireds attribute reaches the maximum allowed for the device (via either the ColorTemperatureMaximumMireds field or the ColorTempPhysicalMaxMireds attribute), the move operation SHALL be stopped.
Down	Decrease the ColorTemperatureMireds attribute (≡ increase the color temperature in kelvins) at the rate given in the Rate field. If the ColorTemperatureMireds attribute reaches the minimum allowed for the device (via either the ColorTemperatureMinimumMireds field or the ColorTempPhysicalMinMireds attribute), the move operation SHALL be stopped.

3.2.11.22. StepColorTemperature Command

The StepColorTemperature command allows the color temperature of a lamp to be stepped with a specified step size.

The StepColorTemperature command SHALL have the following data fields:

Name

Type

Constraint

Quality

Default

Conformance

StepMode

map8

desc

StepSize

uint16

all

TransitionTime

uint16

0 to 65534

ColorTemperatureMinimumMireds

uint16

0 to 0xfeff

ColorTemperatureMaximumMireds

uint16

0 to 0xfeff

OptionsMask

map8

desc

OptionsOverride

map8

desc

3.2.11.22.1. StepMode Field

This field is identical to the StepMode field of the StepHue command of the Color Control cluster (see sub-clause StepHue Command ).

3.2.11.22.2. StepSize Field

The StepSize field specifies the change to be added to (or subtracted from) the current value of the device’s color temperature.

3.2.11.22.3. TransitionTime Field

The TransitionTime field specifies, in units of 1/10ths of a second, the time that SHALL be taken to perform the step. A step is a change to the device’s color temperature of a magnitude corresponding to the StepSize field.

3.2.11.22.4. ColorTemperatureMinimumMireds Field

ColorTempPhysicalMinMireds ≤ ColorTemperatureMinimumMireds field ≤ ColorTemperatureMireds

As such if the step operation takes the ColorTemperatureMireds attribute towards the value of the Color Temperature Minimum Mireds field it SHALL be clipped so that the above invariant is satisfied. If the ColorTemperatureMinimumMireds field is set to 0, ColorTempPhysicalMinMireds SHALL be used as the lower bound for the ColorTemperatureMireds attribute.

3.2.11.22.5. ColorTemperatureMaximumMireds Field

ColorTemperatureMireds ≤ ColorTemperatureMaximumMireds field ≤ ColorTempPhysicalMaxMireds

As such if the step operation takes the ColorTemperatureMireds attribute towards the value of the ColorTemperatureMaximumMireds field it SHALL be clipped so that the above invariant is satisfied. If the ColorTemperatureMaximum Mireds field is set to 0, ColorTempPhysicalMaxMireds SHALL be used as the upper bound for the ColorTemperatureMireds attribute.

3.2.11.22.6. OptionsMask and OptionsOverride fields

The OptionsMask and OptionsOverride fields SHALL be processed according to section Use of the OptionsMask and OptionsOverride fields .

3.2.11.22.7. Effect on Receipt

On receipt of this command, a device SHALL set both the ColorMode and EnhancedColorMode attributes to 2. The device SHALL then move from its current color temperature in an up or down direction by one step, as detailed in Actions on Receipt of the StepColorTemperature Command .

Table ~~64.~~ 62. Actions on Receipt of the StepColorTemperature Command
StepMode	Action on Receipt
Up	Increase the ColorTemperatureMireds attribute (≡ decrease the color temperature in kelvins) by one step. If the ColorTemperatureMireds attribute reaches the maximum allowed for the device (via either the ColorTemperatureMaximumMireds field or the ColorTempPhysicalMaxMireds attribute), the step operation SHALL be stopped.
Down	Decrease the ColorTemperatureMireds attribute (≡ increase the color temperature in kelvins) by one step. If the ColorTemperatureMireds attribute reaches the minimum allowed for the device (via either the ColorTemperatureMinimumMireds field or the ColorTempPhysicalMinMireds attribute), the step operation SHALL be stopped.

3.3. Ballast Configuration Cluster

3.3.1. Introduction

This cluster is used for configuring a lighting ballast.

Note	Support for Ballast Configuration cluster is provisional.

3.3.2. Revision History

The global ClusterRevision attribute value SHALL be the highest revision number in the table below.

Rev	Description
1	mandatory global ClusterRevision attribute added
2	CCB 2104 2193 2230 2393 Deprecated some attributes
3	CCB 2881
4	new data model format and notation

3.3.3. Classification

Hierarchy

Role

PICS Code

Primary Transaction

Base

Application

Type 1 (client to server)

3.3.4. Cluster Identifiers

Identifier

Name

0x0301

Ballast Configuration

3.3.5. Dependencies

If the Alarms server cluster is supported on the same endpoint then the Alarms functionality is enabled and the LampAlarmMode attribute SHALL be supported.

3.3.6. Ballast Configuration Attribute Set

The attributes defined in this specification are arranged into sets of related attributes.

The Ballast Information attribute set contains the attributes summarized in Attributes of the Ballast Information Attribute Set .

Table ~~65.~~ 63. Attributes of the Ballast Information Attribute Set
ID	Name	Type	Constraint	Default	Access	Conformance
0x0000	PhysicalMinLevel	uint8	1 to 254	1	R V	M
0x0001	PhysicalMaxLevel	uint8	1 to 254	254	R V	M
0x0002	BallastStatus	map8	0000 00xx	0	R V	O

3.3.6.1. PhysicalMinLevel Attribute

The PhysicalMinLevel attribute specifies the minimum light output the ballast can achieve according to the dimming light curve (see The Dimming Light Curve ).

3.3.6.2. PhysicalMaxLevel Attribute

The PhysicalMaxLevel attribute specifies the maximum light output the ballast can achieve according to the dimming light curve (see The Dimming Light Curve ).

3.3.6.3. BallastStatus Attribute

The BallastStatus attribute specifies the activity status of the ballast functions. The usage of the bits is specified in Bit Usage of the BallastStatus Attribute . Where a function is active, the corresponding bit SHALL be set to 1. Where a function is not active, the corresponding bit SHALL be set to 0.

Table ~~66.~~ 64. Bit Usage of the BallastStatus Attribute
Bit	Function	Details
0	Ballast Non-operational	0 = The ballast is fully operational 1 = The ballast is not fully operational
1	Lamp Failure	0 = All lamps are operational 1 = One or more lamp is not in its socket or is faulty

3.3.7. Ballast Settings Attribute Set

The Ballast Settings attribute set contains the attributes summarized in Attributes of the Ballast Settings Attribute Set .

Table ~~67.~~ 65. Attributes of the Ballast Settings Attribute Set
ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0010	MinLevel	uint8	1 to 254		PhysicalMinLevel	RW VM	M
0x0011	MaxLevel	uint8	1 to 254		PhysicalMaxLevel	RW VM	M
0x0012	PowerOnLevel	uint8	1 to 254		PhysicalMaxLevel	RW VM	D
0x0013	PowerOnFadeTime	uint16	all		0	RW VM	D
0x0014	IntrinsicBallastFactor	uint8	all	X		RW VM	O
0x0015	BallastFactorAdjustment	uint8	100 to MS	X	null	RW VM	O

3.3.7.1. MinLevel Attribute

The MinLevel attribute specifies the light output of the ballast according to the dimming light curve (see The Dimming Light Curve ) when the Level Control Cluster’s CurrentLevel attribute equals to 1 (and the On/Off Cluster’s OnOff attribute equals to TRUE).

The value of this attribute SHALL be both greater than or equal to PhysicalMinLevel and less than or equal to MaxLevel. If an attempt is made to set this attribute to a level where these conditions are not met, a response SHALL be returned with status code set to CONSTRAINT_ERROR, and the level SHALL not be set.

3.3.7.2. MaxLevel Attribute

The MaxLevel attribute specifies the light output of the ballast according to the dimming light curve (see The Dimming Light Curve ) when the Level Control Cluster’s CurrentLevel attribute equals to 254 (and the On/Off Cluster’s OnOff attribute equals to TRUE).

The value of this attribute SHALL be both less than or equal to PhysicalMaxLevel and greater than or equal to MinLevel. If an attempt is made to set this attribute to a level where these conditions are not met, a response SHALL be returned with status code set to CONSTRAINT_ERROR, and the level SHALL not be set.

3.3.7.3. IntrinsicBallastFactor Attribute

The IntrinsicBallastFactor attribute specifies as a percentage the ballast factor of the ballast/lamp combination, prior to any adjustment.

A value of null indicates in invalid value.

3.3.7.4. BallastFactorAdjustment Attribute

The BallastFactorAdjustment attribute specifies the multiplication factor, as a percentage, to be applied to the configured light output of the lamps. A typical usage of this mechanism is to compensate for reduction in efficiency over the lifetime of a lamp.

The light output is given by

actual light output = configured light output x BallastFactorAdjustment / 100%

The range for this attribute is manufacturer dependent. If an attempt is made to set this attribute to a level that cannot be supported, a response SHALL be returned with status code set to CONSTRAINT_ERROR, and the level SHALL not be set. The value of null indicates that ballast factor scaling is not in use.

3.3.8. Lamp Information Attribute Set

The lamp information attribute set contains the attributes summarized in Attributes of the Lamp Information Attribute Set .

Table ~~68.~~ 66. Attributes of the Lamp Information Attribute Set
ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0020	LampQuantity	uint8	all			R V	M

3.3.8.1. LampQuantity Attribute

The LampQuantity attribute and specifies the number of lamps connected to this ballast. ( Note 1: this number does not take into account whether lamps are actually in their sockets or not).

3.3.9. Lamp Settings Attribute Set

The Lamp Settings attribute set contains the attributes summarized in Attributes of the Lamp Settings Attribute Set . If LampQuantity is greater than one, each of these attributes is taken to apply to the lamps as a set. For example, all lamps are taken to be of the same LampType with the same LampBurnHours.

Table ~~69.~~ 67. Attributes of the Lamp Settings Attribute Set
ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0030	LampType	string	max 16		empty string	RW VM	O
0x0031	LampManufacturer	string	max 16		empty string	RW VM	O
0x0032	LampRatedHours	uint24	all	X	null	RW VM	O
0x0033	LampBurnHours	uint24	all	X	0	RW VM	O
0x0034	LampAlarmMode	map8	0000 000x		0000 0000	RW VM	O
0x0035	LampBurnHoursTripPoint	uint24	all	X	null	RW VM	O

3.3.9.1. LampType Attribute

The LampType attribute specifies the type of lamps (including their wattage) connected to the ballast.

3.3.9.2. LampManufacturer Attribute

The LampManufacturer attribute specifies the name of the manufacturer of the currently connected lamps.

3.3.9.3. LampRatedHours Attribute

The LampRatedHours attribute specifies the number of hours of use the lamps are rated for by the manufacturer.

A value of null indicates an invalid or unknown time.

3.3.9.4. LampBurnHours Attribute

The LampBurnHours attribute specifies the length of time, in hours, the currently connected lamps have been operated, cumulative since the last re-lamping. Burn hours SHALL not be accumulated if the lamps are off.

This attribute SHOULD be reset to zero (e.g., remotely) when the lamp(s) are changed. If partially used lamps are connected, LampBurnHours SHOULD be updated to reflect the burn hours of the lamps.

A value of null indicates an invalid or unknown time.

3.3.9.5. LampAlarmMode Attribute

The LampAlarmMode attribute specifies which attributes MAY cause an alarm notification to be generated, as listed in Values of the LampAlarmMode Attribute . A ‘1’ in each bit position causes its associated attribute to be able to generate an alarm. ( Note: All alarms are also logged in the alarm table – see Alarms cluster).

Table ~~70.~~ 68. Values of the LampAlarmMode Attribute
Bit	Related Attribute
0	LampBurnHours

3.3.9.6. LampBurnHoursTripPoint Attribute

The LampBurnHoursTripPoint attribute specifies the number of hours the LampBurnHours attribute MAY reach before an alarm is generated.

If the Alarms cluster is not present on the same device this attribute is not used and thus MAY be omitted (see Dependencies ).

The Alarm Code field included in the generated alarm SHALL be 0x01.

If this attribute takes the value of null, then this alarm SHALL not be generated.

3.3.10. Commands

No cluster specific commands are received or generated by the server.

3.3.11. The Dimming Light Curve

The dimming curve is recommended to be logarithmic, as defined by the following equation:

Where: %Light is the percent light output of the ballast and

Level is an 8-bit integer between 1 (0.1% light output) and 254 (100% output) that is adjusted for MinLevel and MaxLevel using the following equation:

Level = (MaxLevel – MinLevel) * CurrentLevel / 253 + (254 * MinLevel – MaxLevel) / 253.

Note 1: Value 255 is not used.

Note 2: The light output is determined by this curve together with the IntrinsicBallastFactor and BallastFactorAdjustment attributes.

The table below gives a couple of examples of the dimming light curve for different values of MinLevel, MaxLevel and CurrentLevel.

Table ~~71.~~ 69. Examples of The Dimming Light Curve
MinLevel	MaxLevel	CurrentLevel	Level	%Light
1	254	1	1	0.10%
1	254	10	10	0.13%
1	254	100	100	1.49%
1	254	254	254	100%
170	254	1	170	10.1%
170	254	10	173	11.0%
170	254	100	203	24.8%
170	254	254	254	100%
170	230	1	170	10.1%
170	230	10	172	10.7%
170	230	100	193	19.2%
170	230	254	230	51.9%

4. HVAC

The Cluster Library is made of individual chapters such as this one. References between chapters are made using a X.Y notation where X is the chapter and Y is the sub-section within that chapter.

4.1. General Description

4.1.1. Introduction

The clusters specified in this document are for use typically in HVAC applications, but MAY be used in any application domain.

4.1.2. Terms

Precooling: Cooling a building in the early (cooler) part of the day, so that the thermal mass of the building decreases cooling needs in the later (hotter) part of the day.

4.1.3. Cluster List

This section lists the clusters specified in this document and gives examples of typical usage for the purpose of clarification. The clusters defined in this document are listed in Clusters Specified in the HVAC Functional Domain :

Table ~~72.~~ 70. Clusters Specified in the HVAC Functional Domain
ID	Cluster Name	Description
0x0200	Pump Configuration and Control	An interface for configuring and controlling pumps.
0x0201	Thermostat	An interface for configuring and controlling the functionality of a thermostat
0x0202	Fan Control	An interface for controlling a fan in a heating / cooling system
0x0204	Thermostat User Interface Configuration	An interface for configuring the user interface of a thermostat (which MAY be remote from the thermostat)

Figure 12. Typical Usage of Pump Configuration and Control Cluster

Figure 13. Example Usage of the Thermostat and Related Clusters"

4.2. Pump Configuration and Control Cluster

~~4.2.1. Overview~~

The Pump Configuration and Control cluster provides an interface for the setup and control of pump devices, and the automatic reporting of pump status information. Note that control of pump speed is not included – speed is controlled by the On/Off and Level Control clusters.

4.2.2. 4.2.1. Revision History

The global ClusterRevision attribute value SHALL be the highest revision number in the table below.

Revision	Description
1	~~mandatory~~ Mandatory global ClusterRevision attribute added
2	All Hubs changes
3	New data model format and notation, added additional events
4	Added feature map

4.2.3. 4.2.2. Classification

Hierarchy

Role

~~PICS Code~~ Scope

~~Primary Transaction~~ PICS Code

Base

Application

~~PCC~~ Endpoint

~~Type 2 (server to client)~~ PCC

4.2.4. 4.2.3. Cluster Identifiers ID

Name

0x0200

Pump Configuration and Control

4.2.4. Features

This cluster SHALL support the FeatureMap bitmap attribute as defined below.

Bit

Code

Feature

Conformance

Summary

PRSCONST

ConstantPressure

O.a+

Supports operating in constant pressure mode

PRSCOMP

CompensatedPressure

O.a+

Supports operating in compensated pressure mode

FLW

ConstantFlow

O.a+

Supports operating in constant flow mode

SPD

ConstantSpeed

O.a+

Supports operating in constant speed mode

TEMP

ConstantTemperature

O.a+

Supports operating in constant temperature mode

AUTO

Automatic

Supports operating in automatic mode

LOCAL

LocalOperation

Supports operating using local settings

4.2.5. Dependencies

Where external pressure, flow, and temperature measurements are processed by this cluster (see ~~Values of the~~ ControlMode ~~Attribute~~ ), attribute), these are provided by a Pressure Measurement cluster, a Flow Measurement cluster, and a Temperature Measurement client cluster, respectively. These 3 client clusters are used for connection to a remote sensor device. The pump is able to use the sensor measurement provided by a remote sensor for regulation of the pump speed.

Note that control of the pump setpoint is not included in this cluster – the On/Off and Level Control clusters (see Typical Usage of Pump Configuration and Control Cluster ) MAY be used by a pump device to turn it on and off and control its setpoint. Note that the Pump Configuration and Control cluster MAY override on/off/setpoint settings for specific operation modes (See ~~section~~ OperationMode ~~Attribute~~ attribute for detailed description of the operation and control of the pump.).

4.2.6. Pump Information Attributes Data Types

~~Table 73.~~

4.2.6.1. PumpStatusBitmap

This data type is derived from map16.

Bit

Name

Summary

DeviceFault

A fault related to the system or pump device is detected.

SupplyFault

A fault related to the supply to the pump is detected.

SpeedLow

Setpoint is too low to achieve.

SpeedHigh

Setpoint is too high to achieve.

LocalOverride

Device control is overridden by hardware, such as an external STOP button or via a local HMI.

Running

Pump ~~Information~~ is currently running

RemotePressure

A remote pressure sensor is used as the sensor for the regulation of the pump.

RemoteFlow

A remote flow sensor is used as the sensor for the regulation of the pump.

RemoteTemperature

A remote temperature sensor is used as the sensor for the regulation of the pump.

4.2.6.1.1. DeviceFault Bit

If this bit is set, it MAY correspond to an event in the range 2-16, see Events .

4.2.6.1.2. SupplyFault Bit

If this bit is set, it MAY correspond to an event in the range 0-1 or 13, see Events .

4.2.6.1.3. LocalOverride Bit

While this bit is set, the EffectiveOperationMode is adjusted to Local. Any request changing OperationMode SHALL generate a FAILURE error status until LocalOverride is cleared on the physical device. When LocalOverride is cleared, the device SHALL return to the operation mode set in OperationMode.

4.2.6.1.4. RemotePressure Bit

If this bit is set, EffectiveControlMode is ConstantPressure and the setpoint for the pump is interpreted as a percentage of the range of the remote sensor ([MinMeasuredValue – MaxMeasuredValue]).

4.2.6.1.5. RemoteFlow Bit

If this bit is set, EffectiveControlMode is ConstantFlow, and the setpoint for the pump is interpreted as a percentage of the range of the remote sensor ([MinMeasuredValue – MaxMeasuredValue]).

4.2.6.1.6. RemoteTemperature Bit

If this bit is set, EffectiveControlMode is ConstantTemperature, and the setpoint for the pump is interpreted as a percentage of the range of the remote sensor ([MinMeasuredValue – MaxMeasuredValue])

4.2.6.2. OperationModeEnum

This data type is derived from enum8.

Value

Name

Summary

Conformance

Normal

The pump is controlled by a setpoint, as defined by a connected remote sensor or by the ControlMode attribute.

Minimum

This value sets the pump to run at the minimum possible speed it can without being stopped.

SPD

Maximum

This value sets the pump to run at its maximum possible speed.

SPD

Local

This value sets the pump to run with the local settings of the pump, regardless of what these are.

LOCAL

4.2.6.2.1. Normal Value

If the pump is running in this operation mode the setpoint is an internal variable which MAY be controlled between 0% and 100%, e.g., by means of the Level Control cluster

4.2.6.3. ControlModeEnum

This data type is derived from enum8.

Value

Name

Summary

Conformance

ConstantSpeed

The pump is running at a constant speed.

SPD

ConstantPressure

The pump will regulate its speed to maintain a constant differential pressure over its flanges.

PRSCONST

ProportionalPressure

The pump will regulate its speed to maintain a constant differential pressure over its flanges.

PRSCOMP

ConstantFlow

The pump will regulate its speed to maintain a constant flow through the pump.

FLW

ConstantTemperature

The pump will regulate its speed to maintain a constant temperature.

TEMP

Automatic

The operation of the pump is automatically optimized to provide the most suitable performance with respect to comfort and energy savings.

AUTO

4.2.6.3.1. ConstantSpeed Value

The setpoint is interpreted as a percentage of the range derived from the [MinConstSpeed – MaxConstSpeed] attributes.

4.2.6.3.2. ConstantPressure Value

The setpoint is interpreted as a percentage of the range of the sensor used for this control mode. In case of the internal pressure sensor, this will be the range derived from the [MinConstPressure – MaxConstPressure] attributes. In case of a remote pressure sensor, this will be the range derived from the [MinMeasuredValue – MaxMeasuredValue] attributes of the remote pressure sensor.

4.2.6.3.3. ProportionalPressure Value

The setpoint is interpreted as a percentage of the range derived of the [MinCompPressure – MaxCompPressure] attributes. The internal setpoint will be lowered (compensated) dependent on the flow in the pump (lower flow ⇒ lower internal setpoint).

4.2.6.3.4. ConstantFlow Value

The setpoint is interpreted as a percentage of the range of the sensor used for this control mode. In case of the internal flow sensor, this will be the range derived from the [MinConstFlow – MaxConstFlow] attributes. In case of a remote flow sensor, this will be the range derived from the [MinMeasuredValue – MaxMeasuredValue] attributes of the remote flow sensor.

4.2.6.3.5. ConstantTemperature Value

The setpoint is interpreted as a percentage of the range of the sensor used for this control mode. In case of the internal temperature sensor, this will be the range derived from the [MinConstTemp – MaxConstTemp] attributes. In case of a remote temperature sensor, this will be the range derived from the [MinMeasuredValue – MaxMeasuredValue] attributes of the remote temperature sensor.

4.2.6.3.6. Automatic Value

This behavior is manufacturer defined. The pump can be stopped by setting the setpoint of the level control cluster to 0, or by using the On/Off cluster. If the pump is started (at any setpoint), the speed of the pump is entirely determined by the pump.

4.2.7. Attributes

Name

Type

Constraint

Quality

~~Access~~ Default

~~Default~~ Access

Conformance

0 0x0000

MaxPressure

int16

all

XF X F

~~R V~~ null

~~null~~ R V

1 0x0001

MaxSpeed

uint16

all

XF X F

~~R V~~ null

~~null~~ R V

2 0x0002

MaxFlow

uint16

all

XF X F

~~R V~~ null

~~null~~ R V

3 0x0003

MinConstPressure

int16

all

XF X F

~~R V~~ null

~~null~~ R V

O PRSCONST, [AUTO]

4 0x0004

MaxConstPressure

int16

all

XF X F

~~R V~~ null

~~null~~ R V

O PRSCONST, [AUTO]

5 0x0005

MinCompPressure

int16

all

XF X F

~~R V~~ null

~~null~~ R V

O PRSCOMP, [AUTO]

6 0x0006

MaxCompPressure

int16

all

XF X F

~~R V~~ null

~~null~~ R V

O PRSCOMP, [AUTO]

7 0x0007

MinConstSpeed

uint16

all

XF X F

~~R V~~ null

~~null~~ R V

O SPD, [AUTO]

8 0x0008

MaxConstSpeed

uint16

all

XF X F

~~R V~~ null

~~null~~ R V

O SPD, [AUTO]

9 0x0009

MinConstFlow

uint16

all

XF X F

~~R V~~ null

~~null~~ R V

O FLW, [AUTO]

10 0x000a

MaxConstFlow

uint16

all

XF X F

null

R V

FLW, [AUTO]

0x000b

MinConstTemp

int16

-27315 to max

X F

null

O R V

TEMP, [AUTO]

11 0x000c

~~MinConstTemp~~ MaxConstTemp

int16

-27315 to max

XF X F

null

R V

~~null~~ TEMP, [AUTO]

0x0010

PumpStatus

PumpStatusBitmap

desc

R V

12 0x0011

~~MaxConstTemp~~ EffectiveOperationMode

OperationModeEnum

desc

R V

0x0012

EffectiveControlMode

ControlModeEnum

desc

R V

0x0013

Capacity

int16

~~-27315 to max~~ all

XF X P

null

R V

0x0014

Speed

uint16

all

null

R V

0x0015

LifetimeRunningHours

uint24

all

X N

RW VM

0x0016

Power

uint24

all

null

R V

0x0017

LifetimeEnergyConsumed

uint32

all

X N

RW VM

0x0020

OperationMode

OperationModeEnum

desc

RW VM

0x0021

ControlMode

ControlModeEnum

desc

RW VM

0x0022

AlarmMask

map16

desc

R V

4.2.6.1. 4.2.7.1. MaxPressure Attribute

~~The MaxPressure~~ This attribute specifies the maximum pressure the pump can achieve. It is a physical limit, and does not apply to any specific control mode or operation mode.

Valid range is -3,276.7 kPa to 3,276.7 kPa (steps of 0.1 kPa).
~~The MaxPressure~~ This attribute SHALL be null if the value is invalid.

4.2.6.2. 4.2.7.2. MaxSpeed Attribute

~~The MaxSpeed~~ This attribute specifies the maximum speed the pump can achieve. It is a physical limit, and does not apply to any specific control mode or operation mode.

Valid range is 0 to 65,534 RPM (steps of 1 RPM).
~~The MaxSpeed~~ This attribute SHALL be null if the value is invalid.

4.2.6.3. 4.2.7.3. MaxFlow Attribute

~~The MaxFlow~~ This attribute specifies the maximum flow the pump can achieve. It is a physical limit, and does not apply to any specific control mode or operation mode.

Valid range is 0 m ³ /h to 6,553.4 m ³ /h (steps of 0.1 m ³ /h).
~~The MaxFlow~~ This attribute SHALL be null if the value is invalid.

4.2.6.4. 4.2.7.4. MinConstPressure Attribute

~~The MinConstPressure~~ This attribute specifies the minimum pressure the pump can achieve when it is working with the ControlMode attribute set to ConstantPressure.

Valid range is –3,276.7 kPa to 3,276.7 kPa (steps of 0.1 kPa).
~~The MinConstPressure~~ This attribute SHALL be null if the value is invalid.

4.2.6.5. 4.2.7.5. MaxConstPressure Attribute

~~The MaxConstPressure~~ This attribute specifies the maximum pressure the pump can achieve when it is working with the ControlMode attribute set to ConstantPressure.

Valid range is –3,276.7 kPa to 3,276.7 kPa (steps of 0.1 kPa).
~~The MaxConstPressure~~ This attribute SHALL be null if the value is invalid.

4.2.6.6. 4.2.7.6. MinCompPressure Attribute

~~The MinCompPressure~~ This attribute specifies the minimum compensated pressure the pump can achieve when it is working with the ControlMode attribute set to ProportionalPressure.

Valid range is –3,276.7 kPa to 3,276.7 kPa (steps of 0.1 kPa).
~~The MinCompPressure~~ This attribute SHALL be null if the value is invalid.

4.2.6.7. 4.2.7.7. MaxCompPressure Attribute

~~The MaxCompPressure~~ This attribute specifies the maximum compensated pressure the pump can achieve when it is working with the ControlMode attribute set to ProportionalPressure.

Valid range is –3,276.7 kPa to 3,276.7 kPa (steps of 0.1 kPa).
~~The MaxCompPressure~~ This attribute SHALL be null if the value is invalid.

4.2.6.8. 4.2.7.8. MinConstSpeed Attribute

~~The MinConstSpeed~~ This attribute specifies the minimum speed the pump can achieve when it is working with the ControlMode attribute set to ConstantSpeed.

Valid range is 0 to 65,534 RPM (steps of 1 RPM).
~~The MinConstSpeed~~ This attribute SHALL be null if the value is invalid.

4.2.6.9. 4.2.7.9. MaxConstSpeed Attribute

~~The MaxConstSpeed~~ This attribute specifies the maximum speed the pump can achieve when it is working with the ControlMode attribute set to ConstantSpeed.

Valid range is 0 to 65,534 RPM (steps of 1 RPM).
~~The MaxConstSpeed~~ This attribute SHALL be null if the value is invalid.

4.2.6.10. 4.2.7.10. MinConstFlow Attribute

~~The MinConstFlow~~ This attribute specifies the minimum flow the pump can achieve when it is working with the ControlMode attribute set to ConstantFlow.

Valid range is 0 m ³ /h to 6,553.4 m ³ /h (steps of 0.1 m ³ /h).
~~The MinConstFlow~~ This attribute SHALL be null if the value is invalid.

4.2.6.11. 4.2.7.11. MaxConstFlow Attribute

~~The MaxConstFlow~~ This attribute specifies the maximum flow the pump can achieve when it is working with the ControlMode attribute set to ConstantFlow.

Valid range is 0 m ³ /h to 6,553.4 m ³ /h (steps of 0.1 m ³ /h).
~~The MaxConstFlow~~ This attribute SHALL be null if the value is invalid.

4.2.6.12. 4.2.7.12. MinConstTemp Attribute

~~The MinConstTemp~~ This attribute specifies the minimum temperature the pump can maintain in the system when it is working with the ControlMode attribute set to ConstantTemperature.

Valid range is –273.15 °C to 327.67 °C (steps of 0.01 °C).
~~The MinConstTemp~~ This attribute SHALL be null if the value is invalid.

4.2.6.13. 4.2.7.13. MaxConstTemp Attribute

~~The MaxConstTemp~~ This attribute specifies the maximum temperature the pump can maintain in the system when it is working with the ControlMode attribute set to ConstantTemperature.

~~_MaxConstTemp_~~

MaxConstTemp SHALL be greater than or equal to ~~_MinConstTemp_~~ MinConstTemp

Valid range is –273.15 °C to 327.67 °C (steps of 0.01 °C).
~~The MaxConstTemp~~ This attribute SHALL be null if the value is invalid.

4.2.7. Pump Dynamic Information Attributes Table 74. Pump Dynamic Information Attributes ID Name Type Constraint Quality Access Default Conformance 16 PumpStatus map16 desc P R V 0 O 17 EffectiveOperationMode enum8 desc N R V desc M 18 EffectiveControlMode enum8 desc N R V desc M 19 Capacity int16 all XP R V null M 20 Speed uint16 all X R V null O 21 LifetimeRunningHours uint24 all XN RW VM 0 O 22 Power uint24 all X R V null O 23 LifetimeEnergyConsumed uint32 all XN RW VM 0 O

4.2.7.1. 4.2.7.14. PumpStatus Attribute

~~The PumpStatus~~ This attribute specifies the activity status of the pump functions as listed in ~~Values of the PumpStatus Attribute~~ PumpStatusBitmap . Where a pump controller function is active, the corresponding bit SHALL be set to 1. Where a pump controller function is not active, the corresponding bit SHALL be set to 0.

Table 75. Values of the PumpStatus Attribute Bit Name Description 0 DeviceFault A fault related to the system or pump device is detected (Corresponds to an Event ID in the range 6-16, see Events ) 1 SupplyFault A fault related to the supply to the pump is detected (Corresponds to an Event code in the range 0-5 or 13, see Events ) 2 SpeedLow Setpoint is too low to achieve 3 SpeedHigh Setpoint is too high to achieve 4 LocalOverride Device control is overridden by hardware, such as an external STOP button or via a local HMI. While LocalOverride is set, the EffectiveOperationMode is adjusted to Local. Any request changing OperationMode SHALL generate a FAILURE error status until LocalOverride is cleared on the physical device. When LocalOverride is cleared, the device SHALL return to the operation mode set in OperationMode . 5 Running Pump is currently running 6 RemotePressure A remote pressure sensor is used as the sensor for the regulation of the pump. EffectiveControlMode is ConstantPressure, and the setpoint for the pump is interpreted as a percentage of the range of the remote sensor ([ MinMeasuredValue – MaxMeasuredValue ]) 7 RemoteFlow A remote flow sensor is used as the sensor for the regulation of the pump. EffectiveControlMode is ConstantFlow, and the setpoint for the pump is interpreted as a percentage of the range of the remote sensor ([ MinMeasuredValue – MaxMeasuredValue ]) 8 RemoteTemperature A remote temperature sensor is used as the sensor for the regulation of the pump. EffectiveControlMode is ConstantTemperature, and setpoint is interpreted as a percentage of the range of the remote sensor ([ MinMeasuredValue – MaxMeasuredValue ])

4.2.7.2. 4.2.7.15. EffectiveOperationMode Attribute

~~The EffectiveOperationMode~~ This attribute specifies current effective operation mode of the ~~pump.~~ pump as defined in OperationModeEnum .

The value of the EffectiveOperationMode attribute is the same as the OperationMode attribute, ~~but if~~ unless one of the following points are true:

The pump is physically set to run with the local settings ~~or the~~
The LocalOverride bit in the PumpStatus attribute is set, ~~the value MAY be different from the OperationMode attribute.~~

See ~~section~~ OperationMode ~~Attribute~~ and ControlMode attributes for a detailed description of the operation and control of the pump.

~~This attribute is read only. Valid range is defined by the operation modes listed in Values of the OperationMode Attribute .~~

4.2.7.3. 4.2.7.16. EffectiveControlMode Attribute

~~The EffectiveControlMode~~ This attribute specifies the current effective control mode of the ~~pump.~~ pump as defined in ControlModeEnum .

~~The EffectiveControlMode~~ This attribute contains the control mode that currently applies to the pump. It will have the value of the ControlMode attribute, unless a one of the following points are true:

The ControlMode attribute is set to Automatic. In this case, the value of the EffectiveControlMode SHALL match the behavior of the pump.
A remote sensor is used as the sensor for regulation of the pump. In this case, EffectiveControlMode will display ConstantPressure, ConstantFlow or ConstantTemperature if the remote sensor is a pressure sensor, a flow sensor or a temperature sensor respectively, regardless of the value of the ControlMode attribute.

In case the ControlMode attribute is not included on the device and no remote sensors are connected, the value of the EffectiveControlMode SHALL match the vendor-specific behavior of the pump.

See ~~section~~ OperationMode ~~Attribute~~ and ControlMode attributes for detailed a description of the operation and control of the pump.

~~Valid range is defined by the control modes listed in Values of the ControlMode Attribute .~~

4.2.7.4. 4.2.7.17. Capacity Attribute

~~The Capacity~~ This attribute specifies the actual capacity of the pump as a percentage of the effective maximum setpoint value. It is updated dynamically as the speed of the pump changes.

If the value is not available (the measurement or estimation of the speed is done in the pump), this attribute will indicate the null value.

Valid range is 0 % to 163.835% (0.005 % granularity). Although ~~the Capacity~~ this attribute is a signed value, values of capacity less than zero have no physical meaning.

4.2.7.5. 4.2.7.18. Speed Attribute

~~The Speed~~ This attribute specifies the actual speed of the pump measured in RPM. It is updated dynamically as the speed of the pump changes.

If the value is not available (the measurement or estimation of the speed is done in the pump), this attribute will indicate the null value.

Valid range is 0 to 65.534 RPM.

4.2.7.6. 4.2.7.19. LifetimeRunningHours Attribute

~~The LifetimeRunningHours~~ This attribute specifies the accumulated number of hours that the pump has been powered and the motor has been running. It is updated dynamically as it increases. It is preserved over power cycles of the pump. If LifeTimeRunningHours rises above maximum value it “rolls over” and starts at 0 (zero).

This attribute is writeable, in order to allow setting to an appropriate value after maintenance. If the value is not available, this attribute will indicate the null value.

Valid range is 0 to 16,777,214 hrs.

4.2.7.7. 4.2.7.20. Power Attribute

~~The Power~~ This attribute specifies the actual power consumption of the pump in Watts. The value of ~~the Power~~ this attribute is updated dynamically as the power consumption of the pump changes.

This attribute is read only. If the value is not available (the measurement of power consumption is not done in the pump), this attribute will indicate the null value.

Valid range is 0 to 16,777,214 Watts.

4.2.7.8. 4.2.7.21. LifetimeEnergyConsumed Attribute

~~The LifetimeEnergyConsumed~~ This attribute specifies the accumulated energy consumption of the pump through the entire lifetime of the pump in kWh. The value of the LifetimeEnergyConsumed attribute is updated dynamically as the energy consumption of the pump increases. If LifetimeEnergyConsumed rises above maximum value it “rolls over” and starts at 0 (zero).

This attribute is writeable, in order to allow setting to an appropriate value after maintenance.

Valid range is 0 kWh to 4,294,967,294 kWh.
This attribute SHALL be null if the value is unknown.

4.2.8. Pump Settings Attributes Table 76. Pump Settings Attributes ID Name Type Constraint Quality Access Default Conformance 32 OperationMode enum8 desc N RW VM 0 M 33 ControlMode enum8 desc N RW VM 0 O 34 AlarmMask map16 desc N R V 0 D

4.2.8.1. 4.2.7.22. OperationMode Attribute

~~The OperationMode~~ This attribute specifies the operation mode of the ~~pump. This attribute SHALL have one of the values listed~~ pump as defined in ~~Values of the OperationMode Attribute~~ OperationModeEnum .

The actual operating mode of the pump is a result of the setting of the attributes ~~OperationMode ,~~ OperationMode, ControlMode and the optional connection of a remote sensor. The operation and control is prioritized as shown in the scheme ~~in Priority Scheme of Pump Operation and Control :~~ below:

Priority Scheme of Pump Operation and Control

$C:\work\ZigBee Alliance (2013)\(2013_Z02_004) ZigBee Cluster Library Specification Reformatting\work products\diagrams<<ref_pcc_pump_operation_and_control_figure>> Priority Scheme of Pump Operation and Control.jpg$

If ~~the OperationMode~~ this attribute is Maximum, Minimum or Local, the OperationMode attribute decides how the pump is operated.

If ~~the OperationMode~~ this attribute is Normal and a remote sensor is connected to the pump, the type of the remote sensor decides the control mode of the pump. A connected remote pressure sensor will make the pump run in control mode Constant pressure and vice versa for flow and temperature type sensors. This is regardless of the setting of the ControlMode attribute.

If ~~the OperationMode~~ this attribute is Normal and no remote sensor is connected, the control mode of the pump is decided by the ControlMode attribute.

OperationMode MAY be changed at any time, even when the pump is running. The behavior of the pump at the point of changing the value of ~~the OperationMode~~ this attribute is vendor-specific.

~~Table 77. Values of~~

In the ~~OperationMode Attribute Value Name Description 0 Normal The pump is controlled by~~ case a ~~setpoint, as defined by~~ device does not support a ~~connected remote sensor or by~~ specific operation mode, the ~~ControlMode attribute. (N.B. The setpoint is~~ write interaction to this attribute with an ~~internal variable which MAY~~ unsupported operation mode value SHALL be ~~controlled between 0%~~ ignored and 100%, e.g., by means of the Level Control cluster) 1 Minimum This value sets the pump to run at the minimum possible speed it can without being stopped 2 Maximum This value sets the pump to run at its maximum possible speed 3 Local This value sets the pump to run with the local settings of a response containing the ~~pump, regardless~~ status of ~~what these are~~ CONSTRAINT_ERROR SHALL be returned.

4.2.8.2. 4.2.7.23. ControlMode Attribute

~~The ControlMode~~ This attribute specifies the control mode of the ~~pump. This attribute SHALL have one of the values listed~~ pump as defined in ~~Values of the ControlMode Attribute~~ ControlModeEnum .

See ~~section~~ the OperationMode ~~Attribute~~ attribute for a detailed description of the operation and control of the pump.

In the case a device does not support or implement a specific control mode, a write interaction to the ControlMode attribute with an unsupported control mode value SHALL be ignored and a response containing the status of CONSTRAINT_ERROR SHALL be returned. ControlMode MAY be changed at any time, even when the pump is running. The behavior of the pump at the point of changing is vendor-specific.

Table 78. Values of the ControlMode Attribute Value Name Description 0 ConstantSpeed The pump is running at a constant speed. The setpoint is interpreted as a percentage of the range derived from the [ MinConstSpeed – MaxConstSpeed ] attributes. 1 ConstantPressure The pump will regulate its speed to maintain a constant differential pressure over its flanges. The setpoint is interpreted as a percentage of the range of the sensor used for this control mode.

In ~~case of~~ the ~~internal pressure sensor, this will be the range derived from the [ MinConstPressure – MaxConstPressure ] attributes. In~~ case of a remote pressure sensor, this will be the range derived from the [ MinMeasuredValue – MaxMeasuredValue ] attributes of the remote pressure sensor. 2 ProportionalPressure The pump will regulate its speed to maintain a constant differential pressure over its flanges. The setpoint is interpreted as a percentage of the range derived of the [ MinCompPressure – MaxCompPressure ] attributes. The internal setpoint will be lowered (compensated) dependent on the flow in the pump (lower flow ⇒ lower internal setpoint) 3 ConstantFlow The pump will regulate its speed to maintain a constant flow through the pump. The setpoint is interpreted as device does not support a ~~percentage of the range of the sensor used for this~~ specific control mode. In case of the internal flow sensor, this will be the range derived from the [ MinConstFlow – MaxConstFlow ] attributes. In case of a remote flow sensor, this will be the range derived from the [ MinMeasuredValue – MaxMeasuredValue ] attributes of mode, the ~~remote flow sensor. 5 ConstantTemperature The pump will regulate its speed~~ write interaction to ~~maintain a constant temperature. The setpoint is interpreted as a percentage of the range of the sensor used for~~ this attribute with an unsupported control ~~mode. In case of the internal temperature sensor, this will~~ mode value SHALL be ~~the range derived from the [ MinConstTemp – MaxConstTemp ] attributes. In case of~~ ignored and a ~~remote temperature sensor, this will be the range derived from the [ MinMeasuredValue – MaxMeasuredValue ] attributes of~~ response containing the ~~remote temperature sensor. 7 Automatic The operation~~ status of ~~the pump is automatically optimized to provide the most suitable performance with respect to comfort and energy savings. This behavior is manufacturer defined. The pump can~~ CONSTRAINT_ERROR SHALL be ~~stopped by setting the setpoint of the level control cluster to 0, or by using the On/Off cluster. If the pump is started (at any setpoint), the speed of the pump is entirely determined by the pump.~~ returned.

4.2.9. 4.2.8. Events

~~The events listed in Events MAY be implemented if needed. Table 79. Events~~

Name

Priority

Access

Conformance

0 0x00

SupplyVoltageLow

~~Info~~ INFO

1 0x01

SupplyVoltageHigh

~~Info~~ INFO

2 0x02

PowerMissingPhase

~~Info~~ INFO

3 0x03

SystemPressureLow

~~Info~~ INFO

4 0x04

SystemPressureHigh

~~Info~~ INFO

5 0x05

DryRunning

~~Critical~~ CRITICAL

6 0x06

MotorTemperatureHigh

~~Info~~ INFO

7 0x07

PumpMotorFatalFailure

~~Critical~~ CRITICAL

8 0x08

ElectronicTemperatureHigh

~~Info~~ INFO

9 0x09

PumpBlocked

~~Critical~~ CRITICAL

10 0x0a

SensorFailure

~~Info~~ INFO

11 0x0b

ElectronicNonFatalFailure

~~Info~~ INFO

12 0x0c

ElectronicFatalFailure

~~Critical~~ CRITICAL

13 0x0d

GeneralFault

~~Info~~ INFO

14 0x0e

Leakage

~~Info~~ INFO

15 0x0f

AirDetection

~~Info~~ INFO

16 0x10

TurbineOperation

~~Info~~ INFO

~~There are no data for these events.~~

4.3. Thermostat Cluster

This cluster provides an interface to the functionality of a thermostat.

4.3.1. Revision History

The global ClusterRevision attribute value SHALL be the highest revision number in the table below.

Revision	Description
1	mandatory global ClusterRevision attribute added; fixed some defaults; CCB 1823, 1480
2	CCB 1981 2186 2249 2250 2251; NFR Thermostat Setback
3	CCB 2477 2560 2773 2777 2815 2816 3029
4	All Hubs changes
5	New data model format and notation, added FeatureMap, collapsed attribute sets, clarified edge cases around limits, default value of xxxSetpointLimit now respects AbsxxxSetpointLimit
6	Introduced the LTNE feature and adapted text (spec issue #5778)

4.3.2. Classification

Hierarchy

Role

Context

PICS Code

Primary Transaction

Base

Application

Endpoint

TSTAT

Type 2 (server to client)

4.3.3. Cluster Identifiers

Identifier

Name

0x0201

Thermostat

4.3.3.1. Features

This cluster SHALL support the FeatureMap bitmap attribute as defined below.

Bit

Code

Feature

Description

Conformance

HEAT

Heating

Thermostat is capable of managing a heating device

~~M.a+ | AUTO~~ AUTO, O.a+

COOL

Cooling

Thermostat is capable of managing a cooling device

~~M.a+ | AUTO~~ AUTO, O.a+

OCC

Occupancy

Supports Occupied and Unoccupied setpoints

SCH

Schedule Configuration

Supports remote configuration of a weekly schedule of setpoint transitions

Setback

Supports configurable setback (or span)

AUTO

Auto Mode

Supports a System Mode of Auto

LTNE

Local Temperature Not Exposed

Thermostat does not expose the LocalTemperature Value in the LocalTemperature attribute

4.3.3.1.1. Local Temperature Not Exposed (LTNE) feature

This feature indicates that the LocalTemperature Value used internally is unavailable to report externally, for example due to the temperature control being done by a separate subsystem which does not offer a view into the currently measured temperature, but allows setpoints to be provided.

4.3.4. Units of Temperature

Temperatures within this cluster are represented by types using units of degree Celsius.

While temperature values MUST be transferred over the air using these types, this does not limit how Thermostats may display or store temperature values. Thermostats which display temperature values SHOULD follow the recommendations in Conversion of Temperature Values for Display

Caution

Calculations with temperature attributes

Where calculations or comparisons are performed, attribute values must be converted to a common type. In many cases, it is not sufficient to simply use the integer representation as the scaling from °C to integer value differs.

4.3.5. Setpoint Limits

There are a number of attributes which impose limits on setpoint values. This imposes constraints which MUST be maintained by any mechanism which modifies a limit or setpoint. Individual attribute descriptions detail the actions to be taken should a conflict arise while modifying the value.

User configurable limits must be within device limits:

AbsMinHeatSetpointLimit \$<=\$ MinHeatSetpointLimit \$<=\$ MaxHeatSetpointLimit \$<=\$ AbsMaxHeatSetpointLimit
AbsMinCoolSetpointLimit \$<=\$ MinCoolSetpointLimit \$<=\$ MaxCoolSetpointLimit \$<=\$ AbsMaxCoolSetpointLimit

Setpoints must be within user configurable limits:

MinHeatSetpointLimit \$<=\$ OccupiedHeatingSetpoint \$<=\$ MaxHeatSetpointLimit
MinCoolSetpointLimit \$<=\$ OccupiedCoolingSetpoint \$<=\$ MaxCoolSetpointLimit
MinHeatSetpointLimit \$<=\$ UnoccupiedHeatingSetpoint \$<=\$ MaxHeatSetpointLimit
MinCoolSetpointLimit \$<=\$ UnoccupiedCoolingSetpoint \$<=\$ MaxCoolSetpointLimit

and if, and only if, the AUTO feature is supported, a deadband must be maintained between Heating and Cooling setpoints and limits:

AbsMinHeatSetpointLimit \$<=\$ (AbsMinCoolSetpointLimit - MinSetpointDeadBand)
AbsMaxHeatSetpointLimit \$<=\$ (AbsMaxCoolSetpointLimit - MinSetpointDeadBand)
MinHeatSetpointLimit \$<=\$ (MinCoolSetpointLimit - MinSetpointDeadBand)
MaxHeatSetpointLimit \$<=\$ (MaxCoolSetpointLimit - MinSetpointDeadBand)
OccupiedHeatingSetpoint \$<=\$ (OccupiedCoolingSetpoint - MinSetpointDeadBand)
UnoccupiedHeatingSetpoint \$<=\$ (UnoccupiedCoolingSetpoint - MinSetpointDeadBand)

4.3.6. Dependencies

If the Alarms server cluster is supported on the same endpoint then the Alarms functionality is enabled and the AlarmMask attribute SHALL be supported. For remote temperature sensing, the Temperature Measurement client cluster MAY be included on the same endpoint. For occupancy sensing, the Occupancy Sensing client cluster MAY be included on the same endpoint.

4.3.7. Attributes

Name

Type

Constraint

Quality

Default

Access

Conformance

0x0000

LocalTemperature

all

null

R V

0x0001

OutdoorTemperature

all

null

R V

0x0002

Occupancy

map8

desc

R V

OCC

0x0003

AbsMinHeatSetpointLimit

desc

7°C

R V

[HEAT]

0x0004

AbsMaxHeatSetpointLimit

desc

30°C

R V

[HEAT]

0x0005

AbsMinCoolSetpointLimit

desc

16°C

R V

[COOL]

0x0006

AbsMaxCoolSetpointLimit

desc

32°C

R V

[COOL]

0x0007

PICoolingDemand

uint8

0% to 100%

R V

[COOL]

0x0008

PIHeatingDemand

uint8

0% to 100%

R V

[HEAT]

0x0009

HVACSystemTypeConfiguration

map8

desc

R[W] VM

0x0010

LocalTemperatureCalibration

temp-s8

-2.5°C to 2.5°C

0°C

RW VM

O [!LTNE]

0x0011

OccupiedCoolingSetpoint

desc

26°C

RW VO

COOL

0x0012

OccupiedHeatingSetpoint

desc

20°C

RW VO

HEAT

0x0013

UnoccupiedCoolingSetpoint

desc

26°C

RW VO

COOL & OCC

0x0014

UnoccupiedHeatingSetpoint

desc

20°C

RW VO

HEAT & OCC

0x0015

MinHeatSetpointLimit

desc

AbsMinHeatSetpointLimit

RW VM

[HEAT]

0x0016

MaxHeatSetpointLimit

desc

AbsMaxHeatSetpointLimit

RW VM

[HEAT]

0x0017

MinCoolSetpointLimit

desc

AbsMinCoolSetpointLimit

RW VM

[COOL]

0x0018

MaxCoolSetpointLimit

desc

AbsMaxCoolSetpointLimit

RW VM

[COOL]

0x0019

MinSetpointDeadBand

temp-s8

0°C to 2.5°C

2.5°C

R[W] VM

AUTO

0x001a

RemoteSensing

map8

00000xxx

RW VM

0x001b

ControlSequenceOfOperation

enum8

desc

RW VM

0x001c

SystemMode

enum8

desc

RW VM

0x001d

AlarmMask

map8

desc

R V

0x001e

ThermostatRunningMode

enum8

desc

R V

[AUTO]

0x0020

StartOfWeek

enum8

desc

–

R V

SCH

0x0021

NumberOfWeeklyTransitions

uint8

all

R V

SCH

0x0022

NumberOfDailyTransitions

uint8

all

R V

SCH

0x0023

TemperatureSetpointHold

enum8

desc

RW VM

0x0024

TemperatureSetpointHoldDuration

uint16

0 to 1440

null

RW VM

0x0025

ThermostatProgrammingOperationMode

map8

desc

RW VM

0x0029

ThermostatRunningState

map16

desc

R V

0x0030

SetpointChangeSource

enum8

desc

R V

0x0031

SetpointChangeAmount

temp-diff

all

null

R V

0x0032

SetpointChangeSourceTimestamp

utc

all

R V

0x0034

OccupiedSetback

OccupiedSetbackMin to OccupiedSetbackMax

null

RW VM

0x0035

OccupiedSetbackMin

0 to OccupiedSetbackMax

null

R V

0x0036

OccupiedSetbackMax

OccupiedSetbackMin to 25.4°C

null

R V

0x0037

UnoccupiedSetback

UnoccupiedSetbackMin to UnoccupiedSetbackMax

null

RW VM

SB & OCC

0x0038

UnoccupiedSetbackMin

0 to UnoccupiedSetbackMax

null

R V

SB & OCC

0x0039

UnoccupiedSetbackMax

UnoccupiedSetbackMin to 25.4°C

null

R V

SB & OCC

0x003a

EmergencyHeatDelta

all

25.5°C

RW VM

0x0040

ACType

enum8

desc

RW VM

0x0041

ACCapacity

uint16

all

RW VM

0x0042

ACRefrigerantType

enum8

desc

RW VM

0x0043

ACCompressorType

enum8

desc

RW VM

0x0044

ACErrorCode

map32

all

RW VM

0x0045

ACLouverPosition

enum8

desc

RW VM

0x0046

ACCoilTemperature

all

null

R V

0x0047

ACCapacityFormat

enum8

desc

RW VM

4.3.7.1. LocalTemperature Attribute Value

This ~~attribute~~ value represents the current temperature, as measured locally or remotely (over the network), including any adjustments applied by LocalTemperatureCalibration attribute (if any) as follows:

LocalTemperature = ( measured temperature ) + LocalTemperatureCalibration .

~~The null value indicates that the temperature measurement is invalid.~~ All setpoint attributes in the Thermostat cluster SHALL be triggered based off the LocalTemperature ~~attribute~~ value (i.e., measured temperature and any calibration offset).

If the Local Temperature Not Exposed (LTNE) feature is present, the behavior of the thermostat SHALL be that the equipment’s temperature control uses the LocalTemperature value even if the current value of LocalTemperature is not reported in the LocalTemperature Attribute .

4.3.7.2. LocalTemperature Attribute

This attribute indicates the current LocalTemperature value , when available. The value may be local, or remote, depending on the value of the RemoteSensing attribute when supported.

If the LTNE feature is not supported:
- If the temperature measurement is invalid or currently unavailable, the attribute SHALL report null.
- If the temperature measurement is valid, the attribute SHALL report that value.
Otherwise, if the LTNE feature is supported, there is no feedback externally available for the LocalTemperature value. In that case, the LocalTemperature attribute SHALL always report null.

4.3.7.2. 4.3.7.3. OutdoorTemperature Attribute

This attribute represents the outdoor temperature, as measured locally or remotely (over the network).

4.3.7.3. 4.3.7.4. Occupancy Attribute

This attribute specifies whether the heated/cooled space is occupied or not, as measured locally or remotely (over the network). If bit 0 = 1, the space is occupied, else it is unoccupied. All other bits are reserved.

4.3.7.4. 4.3.7.5. AbsMinHeatSetpointLimit Attribute

This attribute specifies the absolute minimum level that the heating setpoint MAY be set to. This is a limitation imposed by the manufacturer.

Refer to Setpoint Limits for constraints

4.3.7.5. 4.3.7.6. AbsMaxHeatSetpointLimit Attribute

This attribute specifies the absolute maximum level that the heating setpoint MAY be set to. This is a limitation imposed by the manufacturer.

Refer to Setpoint Limits for constraints

4.3.7.6. 4.3.7.7. AbsMinCoolSetpointLimit Attribute

This attribute specifies the absolute minimum level that the cooling setpoint MAY be set to. This is a limitation imposed by the manufacturer.

Refer to Setpoint Limits for constraints

4.3.7.7. 4.3.7.8. AbsMaxCoolSetpointLimit Attribute

This attribute specifies the absolute maximum level that the cooling setpoint MAY be set to. This is a limitation imposed by the manufacturer.

Refer to Setpoint Limits for constraints

4.3.7.8. 4.3.7.9. PICoolingDemand Attribute

This attribute specifies the level of cooling demanded by the PI (proportional integral) control loop in use by the thermostat (if any), in percent. This value is 0 when the thermostat is in “off” or “heating” mode.

This attribute is reported regularly and MAY be used to control a cooling device.

4.3.7.9. 4.3.7.10. PIHeatingDemand Attribute

This attribute specifies the level of heating demanded by the PI loop in percent. This value is 0 when the thermostat is in “off” or “cooling” mode.

This attribute is reported regularly and MAY be used to control a heating device.

4.3.7.10. 4.3.7.11. HVACSystemTypeConfiguration Attribute

This attribute specifies the HVAC system type controlled by the thermostat. If the thermostat uses physical DIP switches to set these parameters, this information SHALL be available read-only from the DIP switches. If these parameters are set via software, there SHALL be read/write access in order to provide remote programming capability. The meanings of individual bits are detailed below. Each bit represents a type of system configuration.

Table ~~80.~~ 71. HVAC System Type Configuration Values
Bit	Name	Description
0 – 1	CoolingStage	00 – Cool Stage 1 01 – Cool Stage 2 10 – Cool Stage 3 11 – Reserved
2 – 3	HeatingStage	00 – Heat Stage 1 01 – Heat Stage 2 10 – Heat Stage 3 11 – Reserved
4	HeatingType	0 – Conventional 1 – Heat Pump
5	HeatingFuel	0 – Electric / B 1 – Gas / O

4.3.7.11. 4.3.7.12. LocalTemperatureCalibration Attribute

This attribute specifies the offset the Thermostat server SHALL make to the measured temperature (locally or remotely) ~~before calculating, displaying, or communicating~~ to adjust the LocalTemperature ~~attribute.~~ Value prior to using, displaying or reporting it.

The purpose of this attribute is to adjust the calibration of the Thermostat server per the ~~user’s~~ user’s preferences (e.g., to match if there are multiple servers displaying different values for the same HVAC area) or compensate for variability amongst temperature sensors.

If a Thermostat client attempts to write LocalTemperatureCalibration attribute to an unsupported value (e.g., out of the range supported by the Thermostat server), the Thermostat server SHALL respond with a ~~Write Attribute Response Command with a~~ status of SUCCESS and set the value of LocalTemperatureCalibration to the upper or lower limit reached.

4.3.7.12. 4.3.7.13. OccupiedCoolingSetpoint Attribute

This attribute specifies the cooling mode setpoint when the room is occupied.

Refer to Setpoint Limits for constraints. If an attempt is made to set this attribute such that these constraints are violated, a response with the status code CONSTRAINT_ERROR SHALL be returned.

If the occupancy status of the room is unknown, this attribute SHALL be used as the cooling mode setpoint.

4.3.7.13. 4.3.7.14. OccupiedHeatingSetpoint Attribute

This attribute specifies the heating mode setpoint when the room is occupied.

Refer to Setpoint Limits for constraints. If an attempt is made to set this attribute such that these constraints are violated, a response with the status code CONSTRAINT_ERROR SHALL be returned.

If the occupancy status of the room is unknown, this attribute SHALL be used as the heating mode setpoint.

4.3.7.14. 4.3.7.15. UnoccupiedCoolingSetpoint Attribute

This attribute specifies the cooling mode setpoint when the room is unoccupied.

Refer to Setpoint Limits for constraints. If an attempt is made to set this attribute such that these constraints are violated, a response with the status code CONSTRAINT_ERROR SHALL be returned.

If the occupancy status of the room is unknown, this attribute SHALL not be used.

4.3.7.15. 4.3.7.16. UnoccupiedHeatingSetpoint Attribute

This attribute specifies the heating mode setpoint when the room is unoccupied.

Refer to Setpoint Limits for constraints. If an attempt is made to set this attribute such that these constraints are violated, a response with the status code CONSTRAINT_ERROR SHALL be returned.

If the occupancy status of the room is unknown, this attribute SHALL not be used.

4.3.7.16. 4.3.7.17. MinHeatSetpointLimit Attribute

This attribute specifies the minimum level that the heating setpoint MAY be set to.

This attribute, and the following three attributes, allow the user to define setpoint limits more constrictive than the manufacturer imposed ones. Limiting users (e.g., in a commercial building) to such setpoint limits can help conserve power.

Refer to Setpoint Limits for constraints. If an attempt is made to set this attribute to a value which conflicts with setpoint values then those setpoints SHALL be adjusted by the minimum amount to permit this attribute to be set to the desired value. If an attempt is made to set this attribute to a value which is not consistent with the constraints and cannot be resolved by modifying setpoints then a response with the status code CONSTRAINT_ERROR SHALL be returned.

4.3.7.17. 4.3.7.18. MaxHeatSetpointLimit Attribute

This attribute specifies the maximum level that the heating setpoint MAY be set to.

4.3.7.18. 4.3.7.19. MinCoolSetpointLimit Attribute

This attribute specifies the minimum level that the cooling setpoint MAY be set to.

4.3.7.19. 4.3.7.20. MaxCoolSetpointLimit Attribute

This attribute specifies the maximum level that the cooling setpoint MAY be set to.

4.3.7.20. 4.3.7.21. MinSetpointDeadBand Attribute

On devices which support the AUTO feature, this attribute specifies the minimum difference between the Heat Setpoint and the Cool Setpoint.

4.3.7.21. 4.3.7.22. RemoteSensing Attribute

This attribute indicates when the local temperature, outdoor temperature and occupancy are being sensed by remote networked sensors, rather than internal sensors.

A bit set to 1 indicates remote sensing of the relevant value.

Table ~~81.~~ 72. RemoteSensing Attribute Bit Values
Bit	Name	Description	Conformance
0	LocalTemperature	When set, LocalTemperature Value is derived from a remote node	M
1	OutdoorTemperature	When set, OutdoorTemperature is derived from a remote node	OutdoorTemperature
2	Occupancy	When set, Occupancy is derived from a remote node	OCC

If the LTNE feature is present in the server, the LocalTemperature RemoteSensing bit value SHALL always report a value of 0.

If the LocalTemperature RemoteSensing bit is written with a value of 1 when the LTNE feature is present, the write SHALL fail and the server SHALL report a CONSTRAINT_ERROR.

4.3.7.22. 4.3.7.23. ControlSequenceOfOperation Attribute

This attribute specifies the overall operating environment of the thermostat, and thus the possible system modes that the thermostat can operate in. It SHALL be set to one of the following values.

Table ~~82.~~ 73. ControlSequenceOfOperation Values
Value	Name	Conformance	Description
0	CoolingOnly	[COOL]	Heat and Emergency are not possible
1	CoolingWithReheat	[COOL]	Heat and Emergency are not possible
2	HeatingOnly	[HEAT]	Cool and precooling (see Terms ) are not possible
3	HeatingWithReheat	[HEAT]	Cool and precooling are not possible
4	CoolingAndHeating	[HEAT & COOL]	All modes are possible
5	CoolingAndHeatingWithReheat	[HEAT & COOL]	All modes are possible

Note

CoolingAndHeating

A thermostat indicating it supports CoolingAndHeating (or CoolingAndHeatingWithReheat) SHOULD be able to request heating or cooling on demand and will usually support the Auto SystemMode.

Systems which support cooling or heating, requiring external intervention to change modes or where the whole building must be in the same mode, SHOULD report CoolingOnly or HeatingOnly based on the current capability.

4.3.7.23. 4.3.7.24. SystemMode Attribute

This attribute specifies the current operating mode of the thermostat, It SHALL be set to one of the following values, as limited by the ControlSequenceOfOperation Attribute .

Note	It is not mandatory to support all values.

Table ~~83.~~ 74. SystemMode Values
Value	Name	Conformance	Description
0	Off	O	The Thermostat does not generate demand for Cooling or Heating
1	Auto	AUTO	Demand is generated for either Cooling or Heating, as required
3	Cool	[COOL]	Demand is only generated for Cooling
4	Heat	[HEAT]	Demand is only generated for Heating
5	EmergencyHeat	[HEAT]	2 ^nd stage heating is in use to achieve desired temperature
6	Precooling	[COOL]	(see Terms )
7	Fan only	O
8	Dry	O
9	Sleep	O

Table ~~84.~~ 75. Interpretation of Heat, Cool and Auto *SystemMode* Values
Attribute Values	Temperature Below Heat Setpoint	Temperature Between Heat Setpoint and Cool Setpoint	Temperature Above Cool Setpoint
Heat	Temperature below target	Temperature on target	Temperature on target
Cool	Temperature on target	Temperature on target	Temperature above target
Auto	Temperature below target	Temperature on target	Temperature above target

4.3.7.24. 4.3.7.25. AlarmMask Attribute

This attribute specifies whether each of the alarms listed below is enabled. When the bit number corresponding to the alarm code is set to 1, the alarm is enabled, else it is disabled. Bits not corresponding to a code in the table are reserved.

When the Alarms cluster is implemented on a device, and one of the alarm conditions included in this table occurs, an alarm notification is generated, with the alarm code field set as listed in the table.

Table ~~85.~~ 76. Alarm Codes
Alarm Code	Alarm Condition
0	Initialization failure. The device failed to complete initialization at power-up.
1	Hardware failure
2	Self-calibration failure

4.3.7.25. 4.3.7.26. Thermostat Running Mode Attribute

This attribute represents the running mode of the thermostat. This attribute uses the SystemMode Values but can only be Off, Cool or Heat. This attribute is intended to provide additional information when the ~~thermostat’s~~ thermostat’s system mode is in auto mode.

4.3.7.26. 4.3.7.27. StartOfWeek Attribute

This attribute represents the day of the week that this thermostat considers to be the start of week for weekly set point scheduling.

Table ~~86.~~ 77. *StartofWeek* Values
Value	Name	Conformance
0	Sunday	M
1	Monday	M
2	Tuesday	M
3	Wednesday	M
4	Thursday	M
5	Friday	M
6	Saturday	M

This attribute MAY be able to be used as the base to determine if the device supports weekly scheduling by reading the attribute. Successful response means that the weekly scheduling is supported.

4.3.7.27. 4.3.7.28. NumberOfWeeklyTransitions Attribute

This attribute determines how many weekly schedule transitions the thermostat is capable of handling.

4.3.7.28. 4.3.7.29. NumberOfDailyTransitions Attribute

This attribute determines how many daily schedule transitions the thermostat is capable of handling.

4.3.7.29. 4.3.7.30. TemperatureSetpointHold Attribute

This attribute specifies the temperature hold status on the thermostat. If hold status is on, the thermostat SHOULD maintain the temperature set point for the current mode until a system mode change. If hold status is off, the thermostat SHOULD follow the setpoint transitions specified by its internal scheduling program. If the thermostat supports setpoint hold for a specific duration, it SHOULD also implement the TemperatureSetpointHoldDuration attribute.

Table ~~87.~~ 78. *TemperatureSetpointHold* Values
Value	Name	Conformance	Description
0	SetpointHoldOff	M	Follow scheduling program
1	SetpointHoldOn	M	Maintain current setpoint, regardless of schedule transitions

4.3.7.30. 4.3.7.31. TemperatureSetpointHoldDuration Attribute

This attribute sets the period in minutes for which a setpoint hold is active. Thermostats that support hold for a specified duration SHOULD implement this attribute. The null value indicates the field is unused. All other values are reserved.

4.3.7.31. 4.3.7.32. ThermostatProgrammingOperationMode Attribute

This attribute determines the operational state of the ~~thermostat’s~~ thermostat’s programming. The thermostat SHALL modify its programming operation when this attribute is modified by a client and update this attribute when its programming operation is modified locally by a user. The thermostat MAY support more than one active ThermostatProgrammingOperationMode . For example, the thermostat MAY operate simultaneously in Schedule Programming Mode and Recovery Mode.

Thermostats which contain a schedule MAY use this attribute to control how that schedule is used, even if they do not support the Schedule Configuration feature.

Table ~~88.~~ 79. *ThermostatProgrammingOperationMode* Attribute Values
Bit	Name	Description
0 ~~ScheduleActive~~	ScheduleActive	Schedule programming mode. This enables any programmed weekly schedule configurations.
1	AutoRecovery	Auto/recovery mode
2	Economy	Economy/EnergyStar mode

When ScheduleActive is not set, the setpoint is altered only by manual up/down changes at the thermostat or remotely, not by internal schedule programming.

Note	Modifying the ScheduleActive bit does not clear or delete previous weekly schedule programming configurations.

4.3.7.32. 4.3.7.33. ThermostatRunningState Attribute

This attribute represents the current relay state of the heat, cool, and fan relays.

Table ~~89.~~ 80. HVAC Relay State Values
Bit	Name	Description
0	Heat	Heat State On
1	Cool	Cool State On
2	Fan	Fan State On
3	HeatStage2	Heat 2 ^nd Stage State On
4	CoolStage2	Cool 2 ^nd Stage State On
5	FanStage2	Fan 2 ^nd Stage State On
6	FanStage3	Fan 3 ^rd Stage Stage On

Unimplemented outputs SHALL be treated as if they were Off.

4.3.7.33. 4.3.7.34. SetpointChangeSource Attribute

This attribute specifies the source of the current active OccupiedCoolingSetpoint or OccupiedHeatingSetpoint (i.e., who or what determined the current setpoint).

This attribute enables service providers to determine whether changes to setpoints were initiated due to occupant comfort, scheduled programming or some other source (e.g., electric utility or other service provider). Because automation services MAY initiate frequent setpoint changes, this attribute clearly differentiates the source of setpoint changes made at the thermostat.

Table ~~90.~~ 81. *SetpointChangeSource* Values
Value	Name	Conformance	Description
0	Manual	O	Manual, user-initiated setpoint change via the thermostat
1	Schedule	[SCH]	Schedule/internal programming-initiated setpoint change
2	External	O	Externally-initiated setpoint change (e.g., DRLC cluster command, attribute write)

4.3.7.34. 4.3.7.35. SetpointChangeAmount Attribute

This attribute specifies the delta between the current active OccupiedCoolingSetpoint or OccupiedHeatingSetpoint and the previous active setpoint. This attribute is meant to accompany the SetpointChangeSource attribute; devices implementing SetpointChangeAmount SHOULD also implement SetpointChangeSource .

The null value indicates that the previous setpoint was unknown.

4.3.7.35. 4.3.7.36. SetpointChangeSourceTimestamp Attribute

This attribute specifies the time in UTC at which the SetpointChangeSourceAmount attribute change was recorded.

4.3.7.36. 4.3.7.37. OccupiedSetback Attribute

This attribute specifies the amount that the Thermostat server will allow the LocalTemperature ~~attribute~~ Value to float above the OccupiedCooling setpoint (i.e., OccupiedCooling + OccupiedSetback ) or below the OccupiedHeating setpoint (i.e., OccupiedHeating – OccupiedSetback ) before initiating a state change to bring the temperature back to the ~~user’s~~ user’s desired setpoint. This attribute is sometimes also referred to as the “span.”

The purpose of this attribute is to allow remote configuration of the span between the desired setpoint and the measured temperature to help prevent over-cycling and reduce energy bills, though this may result in lower comfort on the part of some users.

The null value indicates the attribute is unused.

If the Thermostat client attempts to write OccupiedSetback to a value greater than OccupiedSetbackMax , the Thermostat server SHALL set its OccupiedSetback value to OccupiedSetbackMax and SHALL send a Write Attribute Response command with a Status Code field enumeration of SUCCESS response.

If the Thermostat client attempts to write OccupiedSetback to a value less than OccupiedSetbackMin , the Thermostat server SHALL set its OccupiedSetback value to OccupiedSetbackMin and SHALL send a Write Attribute Response command with a Status Code field enumeration of SUCCESS response.

4.3.7.37. 4.3.7.38. OccupiedSetbackMin Attribute

This attribute specifies the minimum value that the Thermostat server will allow the OccupiedSetback attribute to be configured by a user.

The null value indicates the attribute is unused.

4.3.7.38. 4.3.7.39. OccupiedSetbackMax Attribute

This attribute specifies the maximum value that the Thermostat server will allow the OccupiedSetback attribute to be configured by a user.

The null value indicates the attribute is unused.

4.3.7.39. 4.3.7.40. UnoccupiedSetback Attribute

This attribute specifies the amount that the Thermostat server will allow the LocalTemperature ~~attribute~~ Value to float above the UnoccupiedCooling setpoint (i.e., UnoccupiedCooling + UnoccupiedSetback) or below the UnoccupiedHeating setpoint (i.e., UnoccupiedHeating - UnoccupiedSetback) before initiating a state change to bring the temperature back to the ~~user’s~~ user’s desired setpoint. This attribute is sometimes also referred to as the “span.”

The null value indicates the attribute is unused.

If the Thermostat client attempts to write UnoccupiedSetback to a value greater than UnoccupiedSetbackMax, the Thermostat server SHALL set its UnoccupiedSetback value to UnoccupiedSetbackMax and SHALL send a Write Attribute Response command with a Status Code field enumeration of SUCCESS response.

If the Thermostat client attempts to write UnoccupiedSetback to a value less than UnoccupiedSetbackMin, the Thermostat server SHALL set its UnoccupiedSetback value to UnoccupiedSetbackMin and SHALL send a Write Attribute Response command with a Status Code field enumeration of SUCCESS response.

4.3.7.40. 4.3.7.41. UnoccupiedSetbackMin Attribute

This attribute specifies the minimum value that the Thermostat server will allow the UnoccupiedSetback attribute to be configured by a user.

The null value indicates the attribute is unused.

4.3.7.41. 4.3.7.42. UnoccupiedSetbackMax Attribute

This attribute specifies the maximum value that the Thermostat server will allow the UnoccupiedSetback attribute to be configured by a user.

The null value indicates the attribute is unused.

4.3.7.42. 4.3.7.43. EmergencyHeatDelta Attribute

This attribute specifies the delta between the LocalTemperature Value and the OccupiedHeatingSetpoint or UnoccupiedHeatingSetpoint attributes at which the Thermostat server will operate in emergency heat mode.

If the difference between LocalTemperature Value and Un/OccupiedHeatingSetpoint is greater than or equal to the EmergencyHeatDelta and the Thermostat ~~server’s~~ server’s SystemMode attribute is in a heating-related mode, then the Thermostat server SHALL immediately switch to the SystemMode attribute value that provides the highest stage of heating (e.g., emergency heat) and continue operating in that running state until the OccupiedHeatingSetpoint value is reached. For example:

LocalTemperature = 10.0°C
OccupiedHeatingSetpoint = 16.0°C
EmergencyHeatDelta = 2.0°C

⇒ OccupiedHeatingSetpoint - LocalTemperature ≥? EmergencyHeatDelta

⇒ 16°C - 10°C ≥? 2°C

⇒ TRUE >>> Thermostat server changes its SystemMode to operate in 2 ^nd stage or emergency heat mode

The purpose of this attribute is to provide Thermostat clients the ability to configure rapid heating when a setpoint is of a specified amount greater than the measured temperature. This allows the heated space to be quickly heated to the desired level set by the user.

4.3.7.43. 4.3.7.44. ACType Attribute

This attribute indicates the type of Mini Split ACType of Mini Split AC is defined depending on how Cooling and Heating condition is achieved by Mini Split AC.

Table ~~91.~~ 82. *ACType* Values
Value	Name	Conformance	Description
0	Unknown	O	Unknown AC Type
1	CoolingFixed	O	Cooling and Fixed Speed
2	HeatPumpFixed	O	Heat Pump and Fixed Speed
3	CoolingInverter	O	Cooling and Inverter
4	HeatPumpInverter	O	Heat Pump and Inverter

4.3.7.44. 4.3.7.45. ACCapacity Attribute

This attribute indicates capacity of Mini Split AC in terms of the format defined by the ACCapacityFormat attribute

4.3.7.45. 4.3.7.46. ACRefrigerantType Attribute

This attribute indicates type of refrigerant used within the Mini Split AC.

Table ~~92.~~ 83. *ACRefrigerantType* Values
Value	Name	Conformance	Description
0	Unknown	O	Unknown Refrigerant Type
1	R22	O	R22 Refrigerant
2	R410a	O	R410a Refrigerant
3	R407c	O	R407c Refrigerant

4.3.7.46. 4.3.7.47. ACCompressorType Attribute

This attribute indicates type of Compressor used within the Mini Split AC.

Table ~~93.~~ 84. *ACCompressorType* Values
Value	Name	Conformance	Description
0	Unknown	O	Unknown compressor type
1	T1	O	Max working ambient 43 °C
2	T2	O	Max working ambient 35 °C
3	T3	O	Max working ambient 52 °C

4.3.7.47. 4.3.7.48. ACErrorCode Attribute

This attribute indicates the type of errors encountered within the Mini Split AC. Error values are reported with four bytes values. Each bit within the four bytes indicates the unique error.

Table ~~94.~~ 85. *ACErrorCode* Values
Bit	Name	Description
0	CompressorFail	Compressor Failure or Refrigerant Leakage
1	RoomSensorFail	Room Temperature Sensor Failure
2	OutdoorSensorFail	Outdoor Temperature Sensor Failure
3	CoilSensorFail	Indoor Coil Temperature Sensor Failure
4	FanFail	Fan Failure

4.3.7.48. 4.3.7.49. ACLouverPosition Attribute

This attribute indicates the position of Louver on the AC.

Table ~~95.~~ 86. ACLouverPosition Values
Value	Name	Conformance	Description
1	Closed	O	Fully Closed
2	Open	O	Fully Open
3	Quarter	O	Quarter Open
4	Half	O	Half Open
5	ThreeQuarters	O	Three Quarters Open

4.3.7.49. 4.3.7.50. ACCoilTemperature Attribute

This attribute represents the temperature of the AC coil, as measured locally or remotely (over the network).

4.3.7.50. 4.3.7.51. ACCapacityFormat Attribute

This attribute specifies the format for the ACCapacity attribute.

Table ~~96.~~ 87. ACCapacity Values
Value	Name	Conformance	Description
0	BTUh	O	British Thermal Unit per Hour

4.3.8. Commands

Name

Direction

Response

Access

Conformance

0x00

SetpointRaiseLower

Client ⇒ Server

0x01

SetWeeklySchedule

Client ⇒ Server

SCH

0x02

GetWeeklySchedule

Client ⇒ Server

GetWeeklyScheduleResponse

SCH

0x03

ClearWeeklySchedule

Client ⇒ Server

SCH

0x04

GetRelayStatusLog

Client ⇒ Server

GetRelayStatusLogResponse

0x00

GetWeeklyScheduleResponse

Server ⇒ Client

SCH

0x01

GetRelayStatusLogResponse

Server ⇒ Client

4.3.8.1. Setpoint Raise/Lower Command

Upon receipt, the attributes for the indicated setpoint(s) SHALL have the amount specified in the Amount field added to them. If the resulting value is outside the limits imposed by MinCoolSetpointLimit, MaxCoolSetpointLimit, MinHeatSetpointLimit and MaxHeatSetpointLimit, the value is clamped to those limits. This is not considered an error condition.

Field

Type

Constraint

Quality

Default

Conformance

Mode

enum8

desc

Amount

int8

all

4.3.8.2. Mode Field

The mode field SHALL be set to one of the values below. It specifies which setpoints are to be adjusted.

Table ~~97.~~ 88. Mode Field Values for Setpoint Raise/Lower Command
Value	Name	Conformance	Description
0	Heat	HEAT	Adjust Heat Setpoint
1	Cool	COOL	Adjust Cool Setpoint
2	Both	HEAT \| COOL	Adjust Heat Setpoint and Cool Setpoint

4.3.8.2.1. Heat

If the server does not support the HEAT feature then it SHALL respond with INVALID_ARGUMENT. If the server supports the AUTO feature and the resulting setpoint would be invalid solely due to MinSetpointDeadBand then the Cooling setpoint SHALL be increased sufficiently to maintain the deadband.

4.3.8.2.2. Cool

If the server does not support the COOL feature then it SHALL respond with INVALID_ARGUMENT. If the server supports the AUTO feature and the resulting setpoint would be invalid solely due to MinSetpointDeadBand then the Heating setpoint SHALL be decreased sufficiently to maintain the deadband.

4.3.8.2.3. Both

The client MAY indicate Both regardless of the server feature support. The server SHALL only adjust the setpoint that it supports and not respond with an error.

4.3.8.3. Amount Field

This field indicates the amount (possibly negative) that should be added to the setpoint(s), in steps of 0.1°C.

4.3.8.4. Set Weekly Schedule Command

Upon receipt, the weekly schedule for updating set points SHALL be stored in the thermostat and SHOULD begin at the time of receipt. A status code SHALL be sent in response.

When a command is received that requires a total number of transitions greater than the device supports, the status of the response SHALL be INSUFFICIENT_SPACE.

When any of the set points sent in the sequence is out of range (AbsMin/MaxSetPointLimit), or when the Mode for Sequence field includes a mode not supported by the device, the status of the response SHALL be CONSTRAINT_ERROR and no set points from the entire sequence SHOULD be used.

When an overlapping transition is detected, the status of the response SHALL be FAILURE.

When a device which does not support multiple days in a command receives a command with more than one bit set in the DayOfWeekforSequence field, or when a device which does not support multiple modes in a command receives a command with more than one bit set in the ModeForSequence field, or when the contents of the Transitions field does not agree with NumberOfTransitionsForSequence, DayOfWeekforSequence or ModeForSequence, the status of the response SHALL be INVALID_COMMAND.

When the transitions could be added successfully, the status of the response SHALL be SUCCESS.

Field

Type

Constraint

Quality

Default

Conformance

NumberOfTransitionsForSequence

uint8

all

DayOfWeekforSequence

map8

desc

ModeForSequence

map8

desc

Transitions

list[ ThermostatScheduleTransition ]

max 10

The set weekly schedule command is used to update the thermostat weekly set point schedule from a management system. If the thermostat already has a weekly set point schedule programmed, then it SHOULD replace each daily set point set as it receives the updates from the management system. For example, if the thermostat has 4 set points for every day of the week and is sent a Set Weekly Schedule command with one set point for Saturday then the thermostat SHOULD remove all 4 set points for Saturday and replace those with the updated set point but leave all other days unchanged. If the schedule is larger than what fits in one frame or contains more than 10 transitions, the schedule SHALL then be sent using multiple Set Weekly Schedule Commands.

Each Set Weekly Schedule Command has 3 header bytes – Number of Transitions for Sequence, Day of Week for Sequence, and Mode for Sequence. The application SHALL decode the payload according to what has specified in the 3 header bytes.

4.3.8.5. Number of Transitions for Sequence

The Number of Transitions for Sequence field indicates how many individual transitions to expect for this sequence of commands. If a device supports more than 10 transitions in its schedule they can send this by sending more than 1 “Set Weekly Schedule” command, each containing the separate information that the device needs to set.

4.3.8.6. Day of Week for Sequence

This field represents the day of the week at which all the transitions within the payload of the command SHOULD be associated to. This field is a bitmap and therefore the associated set point could overlap onto multiple days (you could set one transition time for all “week days” or whatever combination of days the implementation requests).

Table ~~98.~~ 89. Day Of Week for Sequence Values
Bit	Name	Description
0	Sunday	Sunday
1	Monday	Monday
2	Tuesday	Tuesday
3	Wednesday	Wednesday
4	Thursday	Thursday
5	Friday	Friday
6	Saturday	Saturday
7	Away	Away or Vacation

Each set point transition will begin with the day of week for this transition. There can be up to 10 transitions for each command.

4.3.8.7. Mode for Sequence

This field determines how the application SHALL decode the Set Point Fields of each transition in the Transitions list.

Table ~~99.~~ 90. Mode for Sequence Values
Bit	Name	Description
0	HeatSetpointPresent	HeatSetpoint Field Present in Payload
1	CoolSetpointPresent	CoolSetpoint Field Present in Payload

If the HeatSetpointPresent bit is On, the HeatSetpoint field SHALL be included in every entry of the Transitions list.

If the HeatSetpointPresent bit is Off, the HeatSetpoint field SHALL NOT be included in any entry of the Transitions list.

If the CoolSetpointPresent bit is On, the CoolSetpoint field SHALL be included in every entry of the Transitions list.

If the CoolSetpointPresent bit is Off, the CoolSetpoint field SHALL NOT be included in any entry of the Transitions list.

At least one of the bits in the Mode For Sequence byte SHALL be on.

Both bits must be respected, even if the HEAT or COOL feature is not supported, to ensure the command is decoded and handled correctly.

4.3.8.8. Transitions Field

This field contains the list of setpoint transitions used to update the specified daily schedules

4.3.8.9. Get Weekly Schedule

Upon receipt, the unit SHOULD send in return the Get Weekly Schedule Response command. The Days to Return and Mode to Return fields are defined as bitmask for the flexibility to support multiple days and multiple modes within one command. If thermostat cannot handle incoming command with multiple days and/or multiple modes within one command, it SHALL send default response of INVALID_COMMAND in return.

Field

Type

Constraint

Quality

Default

Conformance

DaysToReturn

map8

desc

ModeToReturn

map8

desc

4.3.8.9.1. Days To Return

This field indicates the number of days the client would like to return the set point values for and could be any combination of single days or the entire week. This field has the same format as Day Of Week for Sequence Values .

4.3.8.9.2. Mode To Return

This field indicates the mode the client would like to return the set point values for and could be any combination of heat only, cool only or heat&cool. This field has the same format as Mode for Sequence Values .

4.3.8.10. Clear Weekly Schedule

The Clear Weekly Schedule command is used to clear the weekly schedule. The Clear weekly schedule has no payload.

Upon receipt, all transitions currently stored SHALL be cleared and a default response of SUCCESS SHALL be sent in response. There are no error responses to this command.

4.3.8.11. Get Relay Status Log

The Get Relay Status Log command is used to query the thermostat internal relay status log. This command has no payload.

Upon receipt, the unit SHALL respond with Relay Status Log command if the relay status log feature is supported on the unit.

The log storing order is First in First Out (FIFO) when the log is generated and stored into the Queue.

The first record in the log (i.e., the oldest) one, is the first to be replaced when there is a new record and there is no more space in the log. Thus, the newest record will overwrite the oldest one if there is no space left.

The log storing order is Last In First Out (LIFO) when the log is being retrieved from the Queue by a client device.

Once the "Get Relay Status Log Response" frame is sent by the Server, the "Unread Entries" attribute SHOULD be decremented to indicate the number of unread records that remain in the queue.

If the "Unread Entries" attribute reaches zero and the Client sends a new "Get Relay Status Log Request", the Server MAY send one of the following items as a response:

resend the last Get Relay Status Log Response
1. or
generate new log record at the time of request and send Get Relay Status Log Response with the new data

For both cases, the "Unread Entries" attribute will remain zero.

4.3.8.12. Get Weekly Schedule Response

This command has the same payload format as the Set Weekly Schedule. Please refer to the payload detail in Set Weekly Schedule Command .

4.3.8.13. Get Relay Status Log Response

This command is sent from the thermostat cluster server in response to the Get Relay Status Log. After the Relay Status Entry is sent over the air to the requesting client, the specific entry will be cleared from the thermostat internal log.

Field

Type

Constraint

Quality

Default

Conformance

TimeOfDay

uint16

0 to 1439

RelayStatus

map8

desc

LocalTemperature

all

HumidityInPercentage

uint8

0% to 100%

SetPoint

all

UnreadEntries

uint16

all

4.3.8.13.1. Time of Day Field

Represents the sample time of the day, in minutes since midnight, when the relay status was captured for this associated log entry. For example, 6am will be represented by 360 minutes since midnight and 11:30pm will be represented by 1410 minutes since midnight.

4.3.8.13.2. Relay Status Field

Presents the relay status for thermostat when the log is captured. Each bit represents one relay used by the thermostat. If the bit is on, the associated relay is on and active. Each thermostat manufacturer can create its own mapping between the bitmask and the associated relay.

4.3.8.13.3. Local Temperature Field

Presents the ~~local temperature~~ LocalTemperature Value when the log is captured. The null value indicates that LocalTemperature was ~~invalid.~~ invalid or unavailable.

4.3.8.13.4. Humidity Field

This field presents the humidity as a percentage when the log was captured. The null value indicates that the humidity value was invalid or unknown.

4.3.8.13.5. Setpoint Field

Presents the target setpoint temperature when the log is captured.

4.3.8.13.6. Unread Entries Field

This field presents the number of unread entries within the thermostat internal log system.

4.3.9. Data Types

4.3.9.1. Temperature ( `temperature` type)

This type, derived from int16, represents a temperature on the Celsius scale with a resolution of 0.01°C.

value = ( temperature in °C ) x 100

-4°C ⇒ -400
123.45°C ⇒ 12345

The range is constrained by absolute zero: -273.15°C to 327.67°C.

4.3.9.2. Temperature Difference ( `temp-diff` type)

This type, derived from int16, represents a temperature difference with a resolution of 0.01°C.

value = ( temperature in °C ) x 100

-4°C ⇒ -400
123.45°C ⇒ 12345

The full (non-null) range of -327.67°C to 327.67°C may be used.

4.3.9.3. Signed Temperature (°C x 10) ( `temp-s8` type)

This type, derived from int8, represents a temperature from -12.7°C to 12.7°C with a resolution of 0.1°C.

value = ( temperature in °C ) x 10

-4°C ⇒ -40
12.3°C ⇒ 123

This type is employed where compactness of representation is important and where the resolution and range are still satisfactory.

4.3.9.4. Unsigned Temperature (°C x 10) ( `temp-u8` type)

This type, derived from uint8, represents a temperature from 0°C to 25.5°C with a resolution of 0.1°C.

value = ( temperature in °C ) x 10

4°C ⇒ 40
12.3°C ⇒ 123

This type is employed where compactness of representation is important and where the resolution and range are still satisfactory.

4.3.9.5. ThermostatScheduleTransition

This represents a single transition in a Thermostat schedule

Name

Type

Constraint

Quality

Access

Default

Conformance

TransitionTime

uint16

0 to 1439

HeatSetpoint

all

CoolSetpoint

all

4.3.9.5.1. TransitionTime

This field represents the start time of the schedule transition during the associated day. The time will be represented by a 16 bits unsigned integer to designate the minutes since midnight. For example, 6am will be represented by 360 minutes since midnight and 11:30pm will be represented by 1410 minutes since midnight.

4.3.9.6. HeatSetpoint

This field represents the heat setpoint to be applied at this associated transition start time.

4.3.9.7. CoolSetpoint

This field represents the cool setpoint to be applied at this associated transition start time.

4.4. Fan Control

4.4.1. Introduction

This cluster specifies an interface to control the speed of a fan.

Note	Support for Fan Control cluster is provisional.

4.4.2. Revision History

The global ClusterRevision attribute value SHALL be the highest revision number in the table below.

Rev

Description

global mandatory ClusterRevision attribute added

New data model format and notation; Percent, speed and motion settings; General cleanup

4.4.3. Classification

Hierarchy

Role

PICS Code

Primary Transaction

Base

Application

FAN

Type 1 (client to server)

4.4.4. Cluster Identifiers

Identifier

Name

0x0202

Fan Control

4.4.5. Features

This cluster SHALL support the Feature Map global attribute with these bits defined.

Bit

Code

Name

Description

SPD

Multi-Speed

1-100 speeds

AUT

Auto

Automatic mode supported for fan speed

RCK

Rocking

Rocking movement supported

WND

Wind

Wind emulation supported

4.4.5.1. Multi-Speed Feature

Legacy Fan Control cluster revision 0-1 defined 3 speeds (low, medium and high) plus automatic speed control but left it up to the implementer to decide what was supported. Therefore, it is assumed that legacy client implementations are capable of determining, from the server, the number of speeds supported between 1, 2, or 3, and whether automatic speed control is supported.

The Multi-Speed feature includes new attributes that support a running fan speed value from 1 to a maximum of 100. See Section 4.4.6.6.1 for more details.

4.4.6. Attributes

Name

Type

Constraint

Quality

Default

Access

Conformance

0x0000

FanMode

enum8

0 to 6

RW VO

0x0001

FanModeSequence

enum8

0 to 5

R[W] VO

0x0002

PercentSetting

uint8

0 to 100

RW VO

0x0003

PercentCurrent

uint8

0 to 100

desc

R V

0x0004

SpeedMax

uint8

1 to 100

R V

SPD

0x0005

SpeedSetting

uint8

0 to SpeedMax

RW VO

SPD

0x0006

SpeedCurrent

uint8

0 to SpeedMax

desc

R V

SPD

0x0007

RockSupport

map8

desc

R V

RCK

0x0008

RockSetting

map8

desc

RW VO

RCK

0x0009

WindSupport

map8

desc

R V

WND

0x000a

WindSetting

map8

desc

RW VO

WND

4.4.6.1. FanMode Attribute

This attribute SHALL indicate the ~~the~~ current speed mode of the fan. This attribute MAY be written by the client to indicate a new speed mode of the fan. This attribute SHALL be set to one of the values in the table below.

Value

Name

Conformance

Off

Low

desc

Medium

desc

High

desc

Auto

AUT

Smart

4.4.6.1.1. Off

Setting the attribute value to Off SHALL set the values of these attributes to 0 (zero):

PercentSetting
PercentCurrent
SpeedSetting (if present)
SpeedCurrent (if present)

4.4.6.1.2. Low, Medium, High or Unsupported

If the fan only supports 1 speed then:

only the High attribute value SHALL be supported
SpeedMax attribute, if present, SHALL be 1

If the fan only supports 2 speeds then only the Low and High attribute values SHALL be supported.

If a client attempts to write an unsupported value (such as On), the FanMode attribute SHALL be set to High.

If the value is High, Medium, or Low the server SHALL set these percent speed attributes to a single value in the corresponding range as defined in the percent rules :

PercentSetting
PercentCurrent

If the value is High, Medium, or Low the server SHALL set these speed attributes to a single value in the corresponding range as defined in Speed Rules >:

SpeedSetting (if present)
SpeedCurrent (if present)

4.4.6.1.3. Auto

Setting the attribute value to Auto SHALL set the values of these attributes to null:

PercentSetting
SpeedSetting (if present)

These attributes SHALL indicate the current state of the fan while this attribute value is Auto:

PercentCurrent
SpeedCurrent (if present)

4.4.6.2. FanModeSequence Attribute

This indicates the fan speed ranges that SHALL be supported.

Value

Name

Conformance

Off/Low/Med/High

~~M.a~~ O.a

Off/Low/High

~~M.a~~ O.a

Off/Low/Med/High/Auto

~~AUT.a~~ [AUT].a

Off/Low/High/Auto

~~AUT.a~~ [AUT].a

Off/On/Auto

~~AUT.a~~ [AUT].a

Off/On

~~M.a~~ O.a

4.4.6.3. PercentSetting Attribute

This attribute SHALL indicate the speed setting for the fan. This attribute MAY be written by the client to indicate a new fan speed. If the client writes null to this attribute, the attribute value SHALL NOT change. If this is set to 0, the server SHALL set the FanMode attribute value to Off.

4.4.6.3.1. Percent Rules

It is up to the server implementation to map between ranges of the PercentSetting attribute and FanMode attribute enumerated values. Percent values are split into ranges, each range corresponding to a supported FanMode attribute value. Percent ranges SHALL NOT overlap. All percent values in the High speed range SHALL be higher than all percent values in the Medium and Low speed ranges, if supported. All percent values in the Medium speed range SHALL be higher than all percent values in the Low speed range. If the client sets the FanMode attribute to Low, Medium or High, the server SHALL set the PercentSetting attribute to a value within the corresponding range. If the client sets the PercentSetting attribute, the server SHALL set the FanMode attribute to Low, Medium or High, based on the percent value being in the corresponding range.

If the Section 4.4.5.1 feature is supported, the calculation of SpeedSetting or SpeedCurrent (speed) from a percent value change for PercentSetting or PercentCurrent respectively (percent) SHALL hold true:

speed = ceil( SpeedMax * (percent * 0.01) )

For example: If the SpeedMax attribute is 42 (42 speed fan) and PercentSetting is changed to 25, then SpeedSetting and SpeedCurrent become 11 (rounding up 10.5).

4.4.6.4. PercentCurrent Attribute

This attribute SHALL indicate the actual currently operating fan speed, or zero to indicate that the fan is off. See Section 4.4.6.3.1 for more details.

4.4.6.5. SpeedMax Attribute

This attribute SHALL indicate that the fan has one speed (value of 1) or the maximum speed, if the fan is capable of multiple speeds.

4.4.6.6. SpeedSetting Attribute

4.4.6.6.1. Speed Rules

It is up to the server implementation to map between ranges of the SpeedSetting attribute and FanMode attribute enumerated values. Speed values are split into ranges, each range corresponding to a FanMode attribute value. Speed ranges SHALL NOT overlap. All speed values in the High speed range SHALL be higher than all speed values in the Medium and Low speed ranges, if supported. All speed values in the Medium speed range SHALL be higher than all speed values in the Low speed range. If the client sets the FanMode attribute to Low, Medium or High, the server SHALL set the SpeedSetting attribute to a value within the corresponding range. If the client sets the SpeedSetting attribute, the server SHALL set the FanMode attribute to Low, Medium or High, based on the speed value being in the corresponding range.

This calculation for the value of PercentSetting or PercentCurrent (percent) from a speed value change for SpeedSetting or SpeedCurrent respectively (speed) SHALL hold true:

percent = floor( speed/SpeedMax * 100 )

For example: If the SpeedMax attribute is 42 (42 speed fan) and SpeedSetting attribute is changed to 11, then PercentSetting and PercentCurrent become 26.

4.4.6.7. SpeedCurrent Attribute

This attribute SHALL indicate the actual currently operating fan speed, or zero to indicate that the fan is off.

4.4.6.8. RockSupport Attribute

This attribute is a bitmap that indicates what rocking motions the server supports. The bitmap is shown in the table below.

Bit	Name
0	RockLeftRight
1	RockUpDown
2	RockRound

4.4.6.9. RockSetting Attribute

This attribute is a bitmap that indicates the current active fan rocking motion settings. Each bit SHALL only be set to 1, if the corresponding bit in the RockSupport attribute is set to 1, otherwise a status code of CONSTRAINT_ERROR SHALL be returned.

If a combination of supported bits is set by the client, and the server does not support the combination, the lowest supported single bit in the combination SHALL be set and active, and all other bits SHALL indicate zero.

For example: If RockUpDown and RockRound are both set, but this combination is not possible, then only RockUpDown becomes active.

The bitmap is shown in the table below.

Bit	Name
0	RockLeftRight
1	RockUpDown
2	RockRound

4.4.6.10. WindSupport Attribute

This attribute is a bitmap that indicates what wind modes the server supports. At least one wind mode bit SHALL be set. The bitmap is shown in the table below.

Bit

Name

Sleep Wind

Natural Wind

4.4.6.10.1. Sleep Wind

The fan speed, based on current settings, SHALL gradually slow down to a final minimum speed. For this process, the sequence, speeds and duration are MS.

4.4.6.10.2. Natural Wind

The fan speed SHALL vary to emulate natural wind. For this setting, the sequence, speeds and duration are MS.

4.4.6.11. WindSetting Attribute

This attribute is a bitmap that indicates the current active fan wind feature settings. Each bit SHALL only be set to 1, if the corresponding bit in the WindSupport attribute is set to 1, otherwise a status code of CONSTRAINT_ERROR SHALL be returned.

For example: If Sleep Wind and Natural Wind are set, but this combination is not possible, then only Sleep Wind becomes active.

The bitmap is shown in the table below.

Bit

Name

Sleep Wind

Natural Wind

4.5. Thermostat User Interface Configuration

This cluster provides an interface to allow configuration of the user interface for a thermostat, or a thermostat controller device, that supports a keypad and LCD screen.

4.5.1. Revision History

The global ClusterRevision attribute value SHALL be the highest revision number in the table below.

Revision

Description

global mandatory ClusterRevision attribute added

New data model format and notation, added "Conversion of Temperature Values for Display" section

4.5.2. Classification

Hierarchy

Role

Context

PICS Code

Primary Transaction

Base

Application

Endpoint

TSUIC

Type 1 (client to server)

4.5.3. Cluster Identifiers

Identifier

Name

0x0204

Thermostat User Interface Configuration

4.5.4. Conversion of Temperature Values for Display

When converting temperature values for display manufacturers SHOULD ensure that calculations round to the nearest representable value. Particular care is needed when using integer arithmetic.

For example, assuming a display resolution of 0.5:

Attribute value	Temperature		Display as
°C/100	°C	°F	°C	°F
1965	19.65	67.37	19.5	67.5
-545	-5.45	22.19	-5.5	22
-1823	-18.23	-0.81	-18	-1

4.5.4.1. Sample Conversion Code

Sample code provided to ensure consistent Fahrenheit to Celsius and vice-versa conversion between devices and across vendors.

For degF: the value is a int8u representing 2x temperature
value in Fahrenheit (to get 0.5 resolution).

For degC: the value is a int16s representing Celsius in
0.01 resolution as expected by the ZCL format.

/*
 * Function : translateZclTemp()
 * Description : Converts the temperature setpoints in ZCL
 * to the half degF format.
 * The half degF format is 8-bit unsigned,
 * and represents 2x temperature value in
 * Fahrenheit (to get 0.5 resolution).
 * The format used in ZCL is 16-bit signed
 * in Celsius and multiplied by 100
 * to get 0.01 resolution.
 * e.g. 2500 (25.00 deg C) ---> 0x9A (77 deg F)
 * Input Para : Temperature in ZCL (degC) format
 * Output Para: Temperature in half DegF format
 */
int8u translateZclTemp(int16s temperature)
{
  int32s x = temperature;
  // rearrangement of
  // = (x * (9/5) / 100 + 32) * 2;
  // the added 250 is for proper rounding.
  // a rounding technique that only works
  // with positive numbers
  return (int8u) ((x*9*2 + 250)/ (5*100) + 64);
}
/*
 * Function : translateDegFTemp
 * Description : Converts the temperature in DegF
 * protocol to the format
 * expected by the cluster attribute
 * Measured Value in the
 * Temperature Measurement
 * Information Attribute Set.
 * The half deg F format is 8-bit
 * unsigned, and represents
 * 2x temperature value in
 * Fahrenheit (to get 0.5 resolution).
 * The format expected by cluster
 * is 16-bit signed in Celsius and
 * multiplied by 100 to get
 * 0.01 resolution.
 * e.g. 0x9A (77 deg F) ---> 2500 (25.00 deg C)
 * Input Para : temperature in DegF format
 * Output Para: temperature in ZCL format
 */
int16s translateDegFTemp(int8u temperature)
{
  int32s x = temperature;
  // rearrangement of
  // = 100 * (x/2 - 32) * 5/9
  // *1000 (should be 100), +90, then /10,
  // is for rounding.
  return (int16s) (((x - 64)*5*1000 + 90) / (10*2*9));
}

4.5.5. Attributes

Table ~~100.~~ 91. Thermostat User Interface Configuration Cluster Attributes
Id	Name	Type	Constraint	Default	Access	Conformance
0x0000	TemperatureDisplayMode	enum8	desc	0 (Celsius)	RW VO	M
0x0001	KeypadLockout	enum8	desc	0 (no lockout)	RW VM	M
0x0002	ScheduleProgrammingVisibility	enum8	desc	0	RW VM	O

4.5.5.1. TemperatureDisplayMode Attribute

The TemperatureDisplayMode attribute specifies the units of the temperature displayed on the thermostat screen.

Table ~~101.~~ 92. DisplayMode Attribute Values
Value	Name	Conformance	Description
0	Celsius	M	Temperature displayed in °C
1	Fahrenheit	M	Temperature displayed in °F

4.5.5.2. KeypadLockout Attribute

The KeypadLockout attribute specifies the level of functionality that is available to the user via the keypad.

Table ~~102.~~ 93. KeypadLockout Attribute Values
Value	Name	Conformance	Description
0	NoLockout	M	All functionality available to the user
1	Lockout1	M	Level 1 reduced functionality
2	Lockout2	M	Level 2 reduced functionality
3	Lockout3	M	Level 3 reduced functionality
4	Lockout4	M	Level 4 reduced functionality
5	Lockout5	M	Least functionality available to the user

The interpretation of the various levels is device-dependent.

4.5.5.3. ScheduleProgrammingVisibility Attribute

The ScheduleProgrammingVisibility attribute is used to hide the weekly schedule programming functionality or menu on a thermostat from a user to prevent local user programming of the weekly schedule. The schedule programming MAY still be performed via a remote interface, and the thermostat MAY operate in schedule programming mode.

This attribute is designed to prevent local tampering with or disabling of schedules that MAY have been programmed by users or service providers via a more capable remote interface. The programming schedule SHALL continue to run even though it is not visible to the user locally at the thermostat.

Table ~~103.~~ 94. ScheduleProgrammingVisibility Attribute Values
Value	Name	Conformance	Description
0	ScheduleProgrammingPermitted	M	Local schedule programming functionality is enabled at the thermostat
1	ScheduleProgrammingDenied	M	Local schedule programming functionality is disabled at the thermostat

4.5.6. Commands

No cluster specific commands are generated or received by the server.

5. Closures

The Cluster Library is made of individual chapters such as this one. References between chapters are made using a X.Y notation where X is the chapter and Y is the sub-section within that chapter.

5.1. General Description

5.1.1. Introduction

The clusters specified in this document are for use typically in applications involving closures (e.g., shades, windows, doors), but MAY be used in any application domain.

5.1.2. Cluster List

This section lists the clusters specified in this document, and gives examples of typical usage for the purpose of clarification.

The clusters defined in this document are listed in Table ~~104~~ 95 .

Table ~~104.~~ 95. Clusters Specified in the Closures Functional Domain
Cluster ID	Cluster Name	Description
0x0101	Door Lock	An interface to a generic way to secure a door
0x0102	Window Covering	Commands and attributes for controlling a window covering

Figure 14. Typical Usage of the Closures Clusters

5.2. Door Lock

5.2.1. Overview

The door lock cluster provides an interface to a generic way to secure a door. The physical object that provides the locking functionality is abstracted from the cluster. The cluster has a small list of mandatory attributes and functions and a list of optional features.

5.2.1.1. Revision History

The global ClusterRevision attribute value SHALL be the highest revision number in the table below.

Revision	Description
1	mandatory global ClusterRevision attribute added; CCB 1811 1812 1821
2	CCB 2430
3	CCB 2629 2630
4	All Hubs changes and added feature map
5
6	New data model format and notation. Added User features. General cleanup of functionality

5.2.1.2. Classification

Hierarchy

Role

Context

PICS Code

Base

Application

Endpoint

DRLK

5.2.1.3. Cluster Identifiers

Identifier

Name

0x0101

Door Lock

5.2.2. Features

This cluster SHALL support the Feature Map global attribute with these bits defined.

Bit

Code

Feature

Conformance

Description

PIN

PIN Credential

Lock supports PIN credentials (via keypad, or over-the-air)

RID

RFID Credential

Lock supports RFID credentials

FGP

Finger Credentials

P, O

Lock supports finger related credentials (fingerprint, finger vein)

LOG

Logging

Lock supports local/on-lock logging when Events are not supported

WDSCH

Week Day Access Schedules

Lock supports week day user access schedules

DPS

Door Position Sensor

Lock supports a door position sensor that indicates door’s state

FACE

Face Credentials

P, O

Lock supports face related credentials (face, iris, retina)

COTA

Credential Over-the-Air Access

PIN codes over-the-air supported for lock/unlock operations

USR

User

[ PIN | RID | FGP | FACE ]

Lock supports the user commands and database

NOT

Notification

Operation and Programming Notifications

YDSCH

Year Day Access Schedules

Lock supports year day user access schedules

HDSCH

Holiday Schedules

Lock supports holiday schedules

5.2.2.1. PIN Credential Feature

If the User Feature is also supported then any PIN Code stored in the lock SHALL be associated with a User.

A lock MAY support multiple credential types so if the User feature is supported the UserType, UserStatus and Schedules are all associated with a User index and not directly with a PIN index. A User index may have several credentials associated with it.

5.2.2.2. RFID Credential Feature

If the User Feature is also supported then any RFID credential stored in the lock SHALL be associated with a User.

A lock MAY support multiple credential types so if the User feature is supported the UserType, UserStatus and Schedules are all associated with a User index and not directly with a RFID index. A User Index may have several credentials associated with it.

5.2.2.3. Finger Credentials Feature

Currently the cluster only defines the metadata format for notifications when a fingerprint/ finger vein credential is used to access the lock and doesn’t describe how to create fingerprint/finger vein credentials. If the Users feature is also supported then the User that a fingerprint/finger vein is associated with can also have its UserType, UserStatus and Schedule modified.

A lock MAY support multiple credential types so if the User feature is supported the UserType, UserStatus and Schedules are all associated with a User index and not directly with a Finger index. A User Index may have several credentials associated with it.

5.2.2.4. Logging Feature

If Events are not supported the logging feature SHALL replace the Event reporting structure. If Events are supported the logging feature SHALL NOT be supported.

5.2.2.5. Week Day Access Schedules Feature

If the User feature is supported then Week Day Schedules are applied to a User and not a credential.

Week Day Schedules are used to restrict access to a specified time window on certain days of the week. The schedule is repeated each week. When a schedule is cleared this clears the access restrictions and grants unrestricted access to the user. The lock MAY automatically adjust the UserType when a schedule is created or cleared.

5.2.2.6. Door Position Sensor Feature

If this feature is supported this indicates that the lock has the ability to determine the position of the door which is separate from the state of the lock.

5.2.2.7. Face Credentials Feature

Currently the cluster only defines the metadata format for notifications when a face recognition, iris, or retina credential is used to access the lock and doesn’t describe how to create face recognition, iris, or retina credentials. If the Users feature is also supported then the User that a face recognition, iris, or retina credential is associated with can also have its UserType, UserStatus and Schedule modified.

A lock MAY support multiple credential types so if the User feature is supported the UserType, UserStatus and Schedules are all associated with a User and not directly with a credential.

5.2.2.8. Credential Over-the-Air Access Feature

If this feature is supported then the lock supports the ability to verify a credential provided in a lock/unlock command. Currently the cluster only supports providing the PIN credential to the lock/unlock commands. If this feature is supported then the PIN Credential feature SHALL also be supported.

5.2.2.9. User Feature

If the User Feature is supported then a lock employs a User database. A User within the User database is used to associate credentials and schedules to single user record within the lock. This also means the UserType and UserStatus fields are associated with a User and not a credential.

5.2.2.10. Notification Feature

This is a feature used before support of events. This feature supports notification commands and masks used to filter these notifications.

5.2.2.11. Year Day Access Schedules Feature

If the User feature is supported then Year Day Schedules are applied to a User and not a credential.

Year Day Schedules are used to restrict access to a specified date and time window. When a schedule is cleared this clears the access restrictions and grants unrestricted access to the user. The lock MAY automatically adjust the UserType when a schedule is created or cleared.

5.2.2.12. Holiday Schedules Feature

This feature is used to setup Holiday Schedule in the lock device. A Holiday Schedule sets a start and stop end date/time for the lock to use the specified operating mode set by the Holiday Schedule.

5.2.2.12.1. Recommended steps for creating a new User

It is RECOMMENDED that the Administrator query the door lock for what users already exist in its database to find an available UserIndex for creating a new User (see Get User Command ).

Use Set User Command with an available UserIndex to set the user record fields as applicable.
Use Set Credential Command with same UserIndex to add one or more credentials as applicable.
Use Set Week Day Schedule Command or Set Year Day Schedule Command with same UserIndex to add one or more schedule restrictions as applicable.

5.2.3. Attributes

Name

Type

Constraint

Quality

Default

Access

Conformance

0x0000

LockState

enum8

desc

X P S

R V

0x0001

LockType

enum8

desc

R V

0x0002

ActuatorEnabled

bool

all

R V

0x0003

DoorState

enum8

desc

X P

R V

DPS

0x0004

DoorOpenEvents

uint32

all

RW VM

[DPS]

0x0005

DoorClosedEvents

uint32

all

RW VM

[DPS]

0x0006

OpenPeriod

uint16

all

RW VM

[DPS]

0x0010

NumberOfLogRecordsSupported

uint16

all

R V

LOG

0x0011

NumberOfTotalUsersSupported

uint16

all

R V

USR

0x0012

NumberOfPINUsersSupported

uint16

all

R V

0x0013

NumberOfRFIDUsersSupported

uint16

all

R V

RID

0x0014

NumberOfWeekDaySchedulesSupportedPerUser

uint8

all

R V

WDSCH

0x0015

NumberOfYearDaySchedulesSupportedPerUser

uint8

all

R V

YDSCH

0x0016

NumberOfHolidaySchedulesSupported

uint8

all

R V

HDSCH

0x0017

MaxPINCodeLength

uint8

all

R V

0x0018

MinPINCodeLength

uint8

all

R V

0x0019

MaxRFIDCodeLength

uint8

all

R V

RID

0x001a

MinRFIDCodeLength

uint8

all

R V

RID

0x001b

CredentialRulesSupport

map8

all

R V

USR

0x001c

NumberOfCredentialsSupportedPerUser

uint8

all

R V

USR

0x0020

EnableLogging

bool

all

R[W] VA

LOG

0x0021

Language

string

max 3

R[W] VM

0x0022

LEDSettings

uint8

desc

R[W] VM

0x0023

AutoRelockTime

uint32

all

R[W] VM

0x0024

SoundVolume

uint8

desc

R[W] VM

0x0025

OperatingMode

enum8

desc

R[W] VM

0x0026

SupportedOperatingModes

map16

all

0xFFF6

R V

0x0027

DefaultConfigurationRegister

map16

all

R V

0x0028

EnableLocalProgramming

bool

all

R[W] VA

0x0029

EnableOneTouchLocking

bool

all

RW VM

0x002a

EnableInsideStatusLED

bool

all

RW VM

0x002b

EnablePrivacyModeButton

bool

all

RW VM

0x002c

LocalProgrammingFeatures

map8

all

R[W] VA

0x0030

WrongCodeEntryLimit

uint8

1 to 255

R[W] VA

PIN | RID

0x0031

UserCodeTemporaryDisableTime

uint8

1 to 255

R[W] VA

PIN | RID

0x0032

SendPINOverTheAir

bool

all

R[W] VA

[PIN]

0x0033

RequirePINforRemoteOperation

bool

all

R[W] VA

COTA & PIN

0x0034

SecurityLevel

0x0035

ExpiringUserTimeout

uint16

1 to 2880

R[W] VA

[USR]

0x0040

AlarmMask

map16

all

0xFFFF

RW VA

0x0041

KeypadOperationEventMask

map16

all

0xFFFF

RW VA

[NOT & PIN]

0x0042

RemoteOperationEventMask

map16

all

0xFFFF

RW VA

[NOT]

0x0043

ManualOperationEventMask

map16

all

0xFFFF

RW VA

[NOT]

0x0044

RFIDOperationEventMask

map16

all

0xFFFF

RW VA

[NOT & RID]

0x0045

KeypadProgrammingEventMask

map16

all

0xFFFF

RW VA

[NOT & PIN]

0x0046

RemoteProgrammingEventMask

map16

all

0xFFFF

RW VA

[NOT]

0x0047

RFIDProgrammingEventMask

map16

all

0xFFFF

RW VA

[NOT & RID]

AutoRelockTime, OperatingMode and SupportedOperatingModes represent mandatory fields that were previously not present or optional. Implementors should be aware that older devices may not implement them.

5.2.3.1. LockState Attribute

This attribute has the following possible values:

Value

Name

Conformance

Description

Not Fully Locked

Lock state is not fully locked

Locked

Lock state is fully locked

Unlocked

Lock state is fully unlocked

The LockState Attribute may be NULL if the lock hardware does not currently know the status of the locking mechanism. For example, a lock may not know the LockState status after a power cycle until the first lock actuation is completed.

The Not Fully Locked value is used by a lock to indicate that the state of the lock is somewhere between Locked and Unlocked so it is only partially secured. For example, a deadbolt could be partially extended and not in a dead latched state.

If the Scenes server cluster is implemented on the same endpoint, the following extension field SHALL be added to the Scene Table:

LockState

When the LockState attribute is part of a Scene table, the attribute is treated as a writable command; that is, setting the LockState to lock will command the lock to lock, and setting the LockState to unlock will command the lock to unlock. Setting the LockState attribute to “not fully locked” is not supported. The Transition Time field in the Scene table will be treated as a delay before setting the LockState attribute; that is, it is possible to activate a scene with the lock actuation some seconds later.

Locks that do not have an actuation mechanism SHOULD not support the Scene table extension.

5.2.3.2. LockType Attribute

The LockType attribute is indicated by an enumeration:

Value

Name

Description

Dead bolt

Physical lock type is dead bolt

Magnetic

Physical lock type is magnetic

Other

Physical lock type is other

Mortise

Physical lock type is mortise

Rim

Physical lock type is rim

Latch Bolt

Physical lock type is latch bolt

Cylindrical Lock

Physical lock type is cylindrical lock

Tubular Lock

Physical lock type is tubular lock

Interconnected Lock

Physical lock type is interconnected lock

Dead Latch

Physical lock type is dead latch

Door Furniture

Physical lock type is door furniture

5.2.3.3. ActuatorEnabled Attribute

The ActuatorEnabled attribute indicates if the lock is currently able to (Enabled) or not able to (Disabled) process remote Lock, Unlock, or Unlock with Timeout commands.

This attribute has the following possible values:

Boolean Value

Definition

Disabled

Enabled

5.2.3.4. DoorState Attribute

The current door state as defined in DoorStateEnum .

This attribute SHALL be null only if an internal error prevents the retrieval of the current door state.

5.2.3.5. DoorOpenEvents Attribute

This attribute holds the number of door open events that have occurred since it was last zeroed.

5.2.3.6. DoorClosedEvents Attribute

This attribute holds the number of door closed events that have occurred since it was last zeroed.

5.2.3.7. OpenPeriod Attribute

This attribute holds the number of minutes the door has been open since the last time it transitioned from closed to open.

5.2.3.8. NumberOfLogRecordsSupported Attribute

The number of available log records.

5.2.3.9. NumberOfTotalUsersSupported Attribute

Number of total users supported by the lock.

5.2.3.10. NumberOfPINUsersSupported Attribute

The number of PIN users supported.

5.2.3.11. NumberOfRFIDUsersSupported Attribute

The number of RFID users supported.

5.2.3.12. NumberOfWeekDaySchedulesSupportedPerUser Attribute

The number of configurable week day schedule supported per user.

5.2.3.13. NumberOfYearDaySchedulesSupportedPerUser Attribute

The number of configurable year day schedule supported per user.

5.2.3.14. NumberOfHolidaySchedulesSupported Attribute

The number of holiday schedules supported for the entire door lock device.

5.2.3.15. MaxPINCodeLength Attribute

An 8 bit value indicates the maximum length in bytes of a PIN Code on this device.

5.2.3.16. MinPINCodeLength Attribute

An 8 bit value indicates the minimum length in bytes of a PIN Code on this device.

5.2.3.17. MaxRFIDCodeLength Attribute

An 8 bit value indicates the maximum length in bytes of a RFID Code on this device. The value depends on the RFID code range specified by the manufacturer, if media anti-collision identifiers (UID) are used as RFID code, a value of 20 (equals 10 Byte ISO 14443A UID) is recommended.

5.2.3.18. MinRFIDCodeLength Attribute

An 8 bit value indicates the minimum length in bytes of a RFID Code on this device. The value depends on the RFID code range specified by the manufacturer, if media anti-collision identifiers (UID) are used as RFID code, a value of 8 (equals 4 Byte ISO 14443A UID) is recommended.

5.2.3.19. CredentialRulesSupport Attribute

This bitmap contains a bit for every value of CredentialRuleEnum supported on this device.

Bit

CredentialRuleEnum

Definition

Single

Only one credential is required for lock operation

Dual

Any two credentials are required for lock operation

Tri

Any three credentials are required for lock operation

5.2.3.20. NumberOfCredentialsSupportedPerUser Attribute

The number of credentials that could be assigned for each user.

Depending on the value of NumberOfRFIDUsersSupported and NumberOfPINUsersSupported it may not be possible to assign that number of credentials for a user.

For example, if the device supports only PIN and RFID credential types, NumberOfCredentialsSupportedPerUser is set to 10, NumberOfPINUsersSupported is set to 5 and NumberOfRFIDUsersSupported is set to 3, it will not be possible to actually assign 10 credentials for a user because maximum number of credentials in the database is 8.

5.2.3.21. EnableLogging Attribute

Enable/disable event logging. When event logging is enabled, all event messages are stored on the lock for retrieval. Logging events can be but not limited to Tamper Alarm, Lock, Unlock, AutoRelock, User Code Added, User Code Cleared, Schedule Added, and Schedule Cleared. For a full detail of all the possible alarms and events, please refer to the full list in the Alarm and Event Masks Attribute Set.

5.2.3.22. Language Attribute

Modifies the language for the on-screen or audible user interface using a 2-byte language code from ISO-639-1.

5.2.3.23. OperatingMode Attribute

The current operating mode of the lock (see OperatingModeEnum ).

5.2.3.24. SupportedOperatingModes Attribute

This bitmap contains all operating bits of the Operating Mode Attribute supported by the lock. All operating modes NOT supported by a lock SHALL be set to one. The value of the OperatingMode enumeration defines the related bit to be set, as shown below:

Bit

OperatingMode

Conformance

Normal

Vacation

Privacy

NoRemoteLockUnlock

Passage

5.2.3.25. LEDSettings Attribute

The settings for the LED support three different modes, shown below:

Attribute Identifier	Definition
0	Never use LED for signalization
1	Use LED signalization except for access allowed events
2	Use LED signalization for all events

5.2.3.26. AutoRelockTime Attribute

The number of seconds to wait after unlocking a lock before it automatically locks again. 0=disabled. If set, unlock operations from any source will be timed. For one time unlock with timeout use the specific command.

5.2.3.27. SoundVolume Attribute

The sound volume on a door lock has four possible settings: silent, low, high and medium volumes, shown below:

Attribute Identifier	Definition
0	Silent Mode
1	Low Volume
2	High Volume
3	Medium Volume

5.2.3.28. DefaultConfigurationRegister Attribute

This attribute represents the default configurations as they are physically set on the device (example: hardware dip switch setting, etc…) and represents the default setting for some of the attributes within this cluster (for example: LED, Auto Lock, Sound Volume, and Operating Mode attributes).

This is a read-only attribute and is intended to allow clients to determine what changes MAY need to be made without having to query all the included attributes. It MAY be beneficial for the clients to know what the device’s original settings were in the event that the device needs to be restored to factory default settings.

If the Client device would like to query and modify the door lock server’s operating settings, it SHOULD send read and write attribute requests to the specific attributes.

For example, the Sound Volume attribute default value is Silent Mode. However, it is possible that the current Sound Volume is High Volume. Therefore, if the client wants to query/modify the current Sound Volume setting on the server, the client SHOULD read/write to the Sound Volume attribute.

This attribute has the following possible values:

Bit	Description
0	0 - Enable Local Programming Attribute default value is 0 (disabled) 1 - Enable Local Programming Attribute default value is 1 (enabled)
1	0 –Keypad Interface default access is disabled 1 - Keypad Interface default access is enabled
2	0 - Remote Interface default access is disabled 1 - Remote Interface default access is enabled
5	0 – Sound Volume attribute default value is 0 (Silent Mode) 1 – Sound Volume attribute default value is equal to something other than 0
6	0 – Auto Relock Time attribute default value = 0 1 – Auto Relock Time attribute default value is equal to something other than 0
7	0 – Led Settings attribute default value = 0 1 – Led Settings attribute default value is equal to something other than 0

5.2.3.29. EnableLocalProgramming Attribute

Enable/disable local programming on the door lock of certain features (see LocalProgrammingFeatures attribute). If this value is set to TRUE then local programming is enabled on the door lock for all features. If it is set to FALSE then local programming is disabled on the door lock for those features whose bit is set to 0 in the LocalProgrammingFeatures attribute. Local programming SHALL be enabled by default.

5.2.3.30. EnableOneTouchLocking Attribute

Enable/disable the ability to lock the door lock with a single touch on the door lock.

5.2.3.31. EnableInsideStatusLED Attribute

Enable/disable an inside LED that allows the user to see at a glance if the door is locked.

5.2.3.32. EnablePrivacyModeButton Attribute

Enable/disable a button inside the door that is used to put the lock into privacy mode. When the lock is in privacy mode it cannot be manipulated from the outside.

5.2.3.33. LocalProgrammingFeatures Attribute

The local programming features that will be disabled when EnableLocalProgramming attribute is set to False. If a door lock doesn’t support disabling one aspect of local programming it SHALL return CONSTRAINT_ERROR during a write operation of this attribute. If the EnableLocalProgramming attribute is set to True then all local programming features SHALL be enabled regardless of the bits set to 0 in this attribute.

The features that can be disabled from local programming are defined in the following bitmap.

Bit	Description
0	0 - The ability to add Users/credentials/Schedules locally is disabled 1 - The ability to add Users/Credentials/Schedules locally is enabled
1	0 - The ability to modify Users/credentials/Schedules locally is disabled 1 - The ability to modify Users/Credentials/Schedules locally is enabled
2	0 - The ability to clear Users/credentials/Schedules locally is disabled 1 - The ability to clear Users/Credentials/Schedules locally is enabled
3	0 - The ability to adjust lock settings locally is disabled 1 - The ability to adjust lock settings locally is enabled

5.2.3.34. WrongCodeEntryLimit Attribute

The number of incorrect Pin codes or RFID presentment attempts a user is allowed to enter before the lock will enter a lockout state. The value of this attribute is compared to all failing forms of credential presentation, including Pin codes used in an Unlock Command when RequirePINforRemoteOperation is set to true. Valid range is 1-255 incorrect attempts. The lockout state will be for the duration of UserCodeTemporaryDisableTime. If the attribute accepts writes and an attempt to write the value 0 is made, the device SHALL respond with CONSTRAINT_ERROR.

The lock MAY reset the counter used to track incorrect credential presentations as required by internal logic, environmental events, or other reasons. The lock SHALL reset the counter if a valid credential is presented.

5.2.3.35. UserCodeTemporaryDisableTime Attribute

The number of seconds that the lock shuts down following wrong code entry. Valid range is 1-255 seconds. Device can shut down to lock user out for specified amount of time. (Makes it difficult to try and guess a PIN for the device.) If the attribute accepts writes and an attempt to write the attribute to 0 is made, the device SHALL respond with CONSTRAINT_ERROR.

5.2.3.36. SendPINOverTheAir Attribute

Boolean set to True if it is ok for the door lock server to send PINs over the air. This attribute determines the behavior of the server’s TX operation. If it is false, then it is not ok for the device to send PIN in any messages over the air.

The PIN field within any door lock cluster message SHALL keep the first octet unchanged and masks the actual code by replacing with 0xFF. For example (PIN "1234" ): If the attribute value is True, 0x04 0x31 0x32 0x33 0x34 SHALL be used in the PIN field in any door lock cluster message payload. If the attribute value is False, 0x04 0xFF 0xFF 0xFF 0xFF SHALL be used.

If the USR feature is supported by the device then this attribute SHALL NOT be supported.

5.2.3.37. RequirePINForRemoteOperation Attribute

Boolean set to True if the door lock server requires that an optional PINs be included in the payload of remote lock operation events like Lock, Unlock, Unlock with Timeout and Toggle in order to function.

5.2.3.38. ExpiringUserTimeout Attribute

Number of minutes a PIN, RFID, Fingerprint, or other credential associated with a user of type ExpiringUser SHALL remain valid after its first use before expiring. When the credential expires the UserStatus for the corresponding user record SHALL be set to OccupiedDisabled.

5.2.3.39. AlarmMask Attribute

This attribute is only supported if the Alarms cluster is on the same endpoint. The alarm mask is used to turn on/off alarms for particular functions. Alarms for an alarm group are enabled if the associated alarm mask bit is set. Each bit represents a group of alarms. Entire alarm groups can be turned on or off by setting or clearing the associated bit in the alarm mask.

This attribute has the following possible values:

This mask DOES NOT apply to the Events mechanism of this cluster.

Alarm Code	Bit	Alarm Condition	Conformance
0	0	Locking Mechanism Jammed	M
1	1	Lock Reset to Factory Defaults	O
2	2	Reserved	O
3	3	RF Module Power Cycled	O
4	4	Tamper Alarm - wrong code entry limit	PIN \| RID
5	5	Tamper Alarm - front escutcheon removed from main	O
6	6	Forced Door Open under Door Locked Condition	O

5.2.3.40. KeypadOperationEventMask Attribute

Event mask used to turn on and off the transmission of keypad operation events. This mask DOES NOT apply to the storing of events in the event log. This mask only applies to the Operation Event Notification Command.

This attribute has the following possible values:

Operation Event Code	Attribute Bitmask	Event Description
0	BIT(0)	Unknown or manufacturer-specific keypad operation event
1	BIT(1)	Lock, source: keypad
2	BIT(2)	Unlock, source: keypad
3	BIT(3)	Lock, source: keypad, error: invalid PIN
4	BIT(4)	Lock, source: keypad, error: invalid schedule
5	BIT(5)	Unlock, source: keypad, error: invalid code
6	BIT(6)	Unlock, source: keypad, error: invalid schedule
15	BIT(7)	Non-Access User operation event, source keypad.

This mask DOES NOT apply to the Events mechanism of this cluster.

5.2.3.41. RemoteOperationEventMask Attribute

Event mask used to turn on and off the transmission of remote operation events. This mask DOES NOT apply to the storing of events in the event log. This mask only applies to the Operation Event Notification Command.

This attribute has the following possible values:

Event Source	Operation Event Code	Attribute Bitmask	Event Description
1	0	BIT(0)	Unknown or manufacturer-specific remote operation event
1	1	BIT(1)	Lock, source: remote
1	2	BIT(2)	Unlock, source: remote
1	3	BIT(3)	Lock, source: remote, error: invalid code
1	4	BIT(4)	Lock, source: remote, error: invalid schedule
1	5	BIT(5)	Unlock, source: remote, error: invalid code
1	6	BIT(6)	Unlock, source: remote, error: invalid schedule

This mask DOES NOT apply to the Events mechanism of this cluster.

5.2.3.42. ManualOperationEventMask Attribute

Event mask used to turn on and off manual operation events. This mask DOES NOT apply to the storing of events in the event log. This mask only applies to the Operation Event Notification Command.

This attribute has the following possible values:

Event Source	Operation Event Code	Attribute Bitmask	Event Description
2	0	BIT(0)	Unknown or manufacturer-specific manual operation event
2	1	BIT(1)	Thumbturn Lock
2	2	BIT(2)	Thumbturn Unlock
2	7	BIT(3)	One touch lock
2	8	BIT(4)	Key Lock
2	9	BIT(5)	Key Unlock
2	10	BIT(6)	Auto lock
2	11	BIT(7)	Schedule Lock
2	12	BIT(8)	Schedule Unlock
2	13	BIT(9)	Manual Lock (Key or Thumbturn)
2	14	BIT(10)	Manual Unlock (Key or Thumbturn)

This mask DOES NOT apply to the Events mechanism of this cluster.

5.2.3.43. RFIDOperationEventMask Attribute

Event mask used to turn on and off RFID operation events. This mask DOES NOT apply to the storing of events in the event log. This mask only applies to the Operation Event Notification Command.

This attribute has the following possible values:

Event Source	Operation Event Code	Attribute Bitmask	Event Description
3	0	BIT(0)	Unknown or manufacturer-specific keypad operation event
3	1	BIT(1)	Lock, source: RFID
3	2	BIT(2)	Unlock, source: RFID
3	3	BIT(3)	Lock, source: RFID, error: invalid RFID ID
3	4	BIT(4)	Lock, source: RFID, error: invalid schedule
3	5	BIT(5)	Unlock, source: RFID, error: invalid RFID ID
3	6	BIT(6)	Unlock, source: RFID, error: invalid schedule

This mask DOES NOT apply to the Events mechanism of this cluster.

5.2.3.44. KeypadProgrammingEventMask Attribute

Event mask used to turn on and off keypad programming events. This mask DOES NOT apply to the storing of events in the event log. This mask only applies to the Programming Event Notification Command.

This attribute has the following possible values:

Program Event Code	Attribute Bitmask	Event Description
0	BIT(0)	Unknown or manufacturer-specific keypad programming event
1	BIT(1)	Programming PIN code changed, source: keypad User ID: programming user ID. PIN: default or programming PIN code if codes can be sent over the air per attribute. User type: default User Status: default
2	BIT(2)	PIN added, source: keypad User ID: user ID that was added. PIN: code that was added (if codes can be sent over the air per attribute.) User type: default or type added. User Status: default or status added.
3	BIT(3)	PIN cleared, source: keypad User ID: user ID that was cleared. PIN: code that was cleared (if codes can be sent over the air per attribute.) User type: default or type cleared. User Status: default or status cleared.
4	BIT(4)	PIN changed Source: keypad User ID: user ID that was changed PIN: code that was changed (if codes can be sent over the air per attribute.) User type: default or type changed. User Status: default or status changed.

This mask DOES NOT apply to the Events mechanism of this cluster.

5.2.3.45. RemoteProgrammingEventMask Attribute

Event mask used to turn on and off remote programming events. This mask DOES NOT apply to the storing of events in the event log. This mask only applies to the Programming Event Notification Command.

This attribute has the following possible values:

Event Source	Program Event Code	Attribute Bitmask	Event Description
1	0	BIT(0)	Unknown or manufacturer-specific remote programming event.
1	2	BIT(2)	PIN added, source remote Same as keypad source above
1	3	BIT(3)	PIN cleared, source remote Same as keypad source above.
1	4	BIT(4)	PIN changed Source remote Same as keypad source above
1	5	BIT(5)	RFID code added, Source remote
1	6	BIT(6)	RFID code cleared, Source remote

This mask DOES NOT apply to the Events mechanism of this cluster.

5.2.3.46. RFIDProgrammingEventMask Attribute

Event mask used to turn on and off RFID programming events. This mask DOES NOT apply to the storing of events in the event log. This mask only applies to the Programming Event Notification Command.

This attribute has the following possible values:

Event Source	Program Event Code	Attribute Bitmask	Event Description
3	0	BIT(0)	Unknown or manufacturer-specific keypad programming event
3	5	BIT(5)	ID Added, Source: RFID User ID: user ID that was added. ID: ID that was added (if codes can be sent over the air per attribute.) User Type: default or type added. User Status: default or status added.
3	6	BIT(6)	ID cleared, Source: RFID User ID: user ID that was cleared. ID: ID that was cleared (if codes can be sent over the air per attribute.) User Type: default or type cleared. User Status: default or status cleared.

This mask DOES NOT apply to the Events mechanism of this cluster.

5.2.4. Commands

Name

Direction

Response

Access

Conformance

0x00

Lock Door

Client ⇒ Server

T O

0x01

Unlock Door

Client ⇒ Server

T O

0x02

Toggle

Client ⇒ Server

T O

0x03

Unlock with Timeout

Client ⇒ Server

T O

0x04

Get Log Record

Client ⇒ Server

Get Log Record Response

LOG

0x04

Get Log Record Response

Server ⇒ Client

LOG

0x05

Set PIN Code

Client ⇒ Server

T A

!USR & PIN

0x06

Get PIN Code

Client ⇒ Server

Get PIN Code Response

!USR & PIN

0x06

Get PIN Code Response

Server ⇒ Client

!USR & PIN

0x07

Clear PIN Code

Client ⇒ Server

T A

!USR & PIN

0x08

Clear All PIN Codes

Client ⇒ Server

T A

!USR & PIN

0x09

Set User Status

Client ⇒ Server

!USR & (PIN | RID | FGP)

0x0a

Get User Status

Client ⇒ Server

Get User Status Response

!USR & (PIN | RID | FGP)

0x0a

Get User Status Response

Server ⇒ Client

!USR

0x0b

Set Week Day Schedule

Client ⇒ Server

WDSCH

0x0c

Get Week Day Schedule

Client ⇒ Server

Get Week Day Schedule Response

WDSCH

0x0c

Get Week Day Schedule Response

Server ⇒ Client

WDSCH

0x0d

Clear Week Day Schedule

Client ⇒ Server

WDSCH

0x0e

Set Year Day Schedule

Client ⇒ Server

YDSCH

0x0f

Get Year Day Schedule

Client ⇒ Server

Get Year Day Schedule Response

YDSCH

0x0f

Get Year Day Schedule Response

Server ⇒ Client

YDSCH

0x10

Clear Year Day Schedule

Client ⇒ Server

YDSCH

0x11

Set Holiday Schedule

Client ⇒ Server

HDSCH

0x12

Get Holiday Schedule

Client ⇒ Server

Get Holiday Schedule Response

HDSCH

0x12

Get Holiday Schedule Response

Server ⇒ Client

HDSCH

0x13

Clear Holiday Schedule

Client ⇒ Server

HDSCH

0x14

Set User Type

Client ⇒ Server

!USR & (PIN | RID | FGP)

0x15

Get User Type

Client ⇒ Server

Get User Type Response

!USR & (PIN | RID | FGP)

0x15

Get User Type Response

Server ⇒ Client

!USR

0x16

Set RFID Code

Client ⇒ Server

T A

!USR & RID

0x17

Get RFID Code

Client ⇒ Server

Get RFID Code Response

!USR & RID

0x17

Get RFID Code Response

Server ⇒ Client

!USR & RID

0x18

Clear RFID Code

Client ⇒ Server

T A

!USR & RID

0x19

Clear All RFID Codes

Client ⇒ Server

T A

!USR & RID

0x1a

Set User

Client ⇒ Server

T A

USR

0x1b

Get User

Client ⇒ Server

Get User Response

USR

0x1c

Get User Response

Server ⇒ Client

USR

0x1d

Clear User

Client ⇒ Server

T A

USR

0x20

Operating Event Notification

Server ⇒ Client

[NOT]

0x21

Programming Event Notification

Server ⇒ Client

[NOT]

0x22

Set Credential

Client ⇒ Server

Set Credential Response

T A

USR

0x23

Set Credential Response

Server ⇒ Client

USR

0x24

Get Credential Status

Client ⇒ Server

Get Credential Status Response

USR

0x25

Get Credential Status Response

Server ⇒ Client

USR

0x26

Clear Credential

Client ⇒ Server

T A

USR

5.2.4.1. Lock Door Command

This command causes the lock device to lock the door. This command includes an optional code for the lock. The door lock MAY require a PIN depending on the value of the [Require PIN for Remote Operation attribute].

Field

Type

Constraint

Quality

Default

Conformance

PINCode

PIN/RFID Code†

octstr

[COTA & PIN]

† The PIN/RFID Code is an obsolete field name, use PINCode instead.

5.2.4.1.1. PINCode

If the RequirePINforRemoteOperation attribute is True then PINCode field SHALL be provided and the door lock SHALL NOT grant access if it is not provided.

If the PINCode field is provided, the door lock SHALL verify PINCode before granting access regardless of the value of RequirePINForRemoteOperation attribute.

When the PINCode field is provided an invalid PIN will count towards the WrongCodeEntryLimit and the UserCodeTemporaryDisableTime will be triggered if the WrongCodeEntryLimit is exceeded. The lock SHALL ignore any attempts to lock/unlock the door until the UserCodeTemporaryDisableTime expires.

5.2.4.2. Unlock Door Command

This command causes the lock device to unlock the door. This command includes an optional code for the lock. The door lock MAY require a code depending on the value of the [Require PIN for Remote Operation attribute].

Note: If the attribute AutoRelockTime is supported the lock will transition to the locked state when the auto relock time has expired.

Field

Type

Constraint

Quality

Default

Conformance

PINCode

PIN/RFID Code†

octstr

[COTA & PIN]

† The PIN/RFID Code is an obsolete field name, use PINCode instead.

5.2.4.2.1. PINCode

See PINCode .

5.2.4.3. Unlock with Timeout Command

This command causes the lock device to unlock the door with a timeout parameter. After the time in seconds specified in the timeout field, the lock device will relock itself automatically. This timeout parameter is only temporary for this message transition and overrides the default relock time as specified in the AutoRelockTime attribute. If the door lock device is not capable of or does not want to support temporary Relock Timeout, it SHOULD NOT support this optional command.

Field

Type

Constraint

Quality

Default

Conformance

Timeout

uint16

PINCode

PIN/RFID Code†

octstr

[COTA & PIN]

† The PIN/RFID Code is an obsolete field name, use PINCode instead.

5.2.4.3.1. Timeout

The timeout in seconds to wait before relocking the door lock. This value is independent of the AutoRelockTime attribute value.

5.2.4.3.2. PINCode

See PINCode .

5.2.4.4. Get Log Record Command

Request a log record. Log number is between 1 – [Number of Log Records Supported attribute]. If log number 0 is requested then the most recent log entry is returned.

Field

Type

Constraint

Quality

Default

Conformance

Log Index

uint16

desc

Log record format: The log record format is defined in the description of the Get Log Record Response command.

5.2.4.5. Get Log Record Response Command

Returns the specified log record. If an invalid log entry ID was requested, it is set to 0 and the most recent log entry will be returned.

Field

Type

Constraint

Quality

Default

Conformance

Log Entry ID

uint16

desc

Timestamp

epoch-s

all

Event Type

enum8

desc

Source (see Operation Event Sources)

uint8

desc

Event ID/Alarm Code (see Operation Event Codes)

uint8

desc

User ID

uint16

desc

PIN

octstr

Log Entry ID: the index into the log table where this log entry is stored. If the log entry requested is 0, the most recent log is returned with the appropriate log entry ID.

Timestamp: A timestamp for all events and alarms on the door lock in Epoch Time in Seconds with local time offset based on the local timezone and DST offset on the day of the event.

Event Type: Indicates the type of event that took place on the door lock.

0 = Operation

1 = Programming

2 = Alarm

Source: A source value where available sources are:

0x00 = Keypad

0x01 = Remote

0x02 = Manual

0x03 = RFID

0xFF = Indeterminate

If the Event type is 0x02 (Alarm) then the source SHOULD be but does not have to be 0xff (Indeterminate).

Event ID: A one-byte value indicating the type of event that took place on the door lock depending on the event code table provided for a given event type and source.

User ID: A two-byte value indicating the ID of the user who generated the event on the door lock if one is available. If none is available, 0xffff has to be used.

PIN / ID: A string indicating the PIN code or RFID code that was used to create the event on the door lock if one is available.

5.2.4.6. Set PIN Code Command

Set a PIN Code into the lock.

Field

Type

Constraint

Quality

Default

Conformance

User ID

uint16

desc

User Status

uint8

OccupiedEnabled

User Type

enum8

UnrestrictedUser

PIN

octstr

User ID is between 0 - [# of PIN Users Supported attribute]. Only the values 1 (Occupied/Enabled) and 3 (Occupied/Disabled) are allowed for User Status.

Return status is a global status code or a cluster-specific status code from the DoorLockStatus table and SHALL be one of the following values:

Name

Description

SUCCESS

Setting PIN code was successful.

FAILURE

Setting PIN code failed.

CONSTRAINT_ERROR

Setting PIN code failed because User ID requested was out of range.

DUPLICATE

Setting PIN code failed because it would create a duplicate PIN code.

5.2.4.7. Get PIN Code Command

Retrieve a PIN Code. User ID is between 0 - [# of PIN Users Supported attribute].

Field

Type

Constraint

Quality

Default

Conformance

User ID

uint16

desc

5.2.4.8. Get PIN Code Response Command

Returns the PIN for the specified user ID.

Field

Type

Constraint

Quality

Default

Conformance

User ID

uint16

desc

User Status

uint8

Available

User Type

enum8

PIN Code

octstr

empty

If the requested User ID is valid and the Code doesn’t exist, Get RFID Code Response SHALL have the following format:

User ID = requested User ID

UserStatus = 0 (available)

UserType = 0xFF (not supported)

PIN Code = 0 (zero length)

If the requested User ID is invalid, send Default Response with an error status. The error status SHALL be equal to CONSTRAINT_ERROR when User_ID is less than the max number of users supported, and NOT_FOUND if greater than or equal to the max number of users supported.

5.2.4.9. Clear PIN Code Command

Clear a PIN code or all PIN codes.

Field

Type

Constraint

Quality

Default

Conformance

PINSlotIndex

User ID†

uint16

1 to NumberOfPINUsersSupported, 0xFFFE

† The User ID is an obsolete field name, use PINSlotIndex instead.

For each PIN Code cleared whose user doesn’t have a RFID Code or other credential type, then corresponding user record’s UserStatus value SHALL be set to Available, and UserType value SHALL be set to UnrestrictedUser and all schedules SHALL be cleared.

5.2.4.9.1. PINSlotIndex

Specifies a valid PIN code slot index or 0xFFFE to indicate all PIN code slots SHALL be cleared.

5.2.4.10. Clear All PIN Codes Command

Clear out all PINs on the lock.

Note: On the server, the clear all PIN codes command SHOULD have the same effect as the Clear PIN Code command with respect to the setting of user status, user type and schedules.

5.2.4.11. Set User Status Command

Set the status of a user ID. User Status value of 0 is not allowed. In order to clear a user id, the Clear ID Command SHALL be used. For user status value please refer to User Status Value.

Field

Type

Constraint

Quality

Default

Conformance

User ID

uint16

desc

User Status

uint8

5.2.4.12. Get User Status Command

Get the status of a user.

Field

Type

Constraint

Quality

Default

Conformance

User ID

uint16

desc

5.2.4.13. Get User Status Response Command

Returns the user status for the specified user ID. If the requested User ID is invalid, the Status field SHALL be set to FAILURE. If the command is successful, the Status field SHALL be set to SUCCESS.

Field

Type

Constraint

Quality

Default

Conformance

User ID

uint16

desc

User Status

enum8

5.2.4.14. Set Week Day Schedule Command

Set a weekly repeating schedule for a specified user.

Field

Type

Constraint

Quality

Default

Conformance

WeekDayIndex

Schedule ID†

uint8

1 to NumberOfWeekDaySchedulesSupportedPerUser

UserIndex

User ID†

uint16

1 to NumberOfTotalUsersSupported

DaysMask

DaysMaskMap

StartHour

uint8

0 to 23

StartMinute

uint8

0 to 59

EndHour

uint8

0 to 23

EndMinute

uint8

0 to 59

† The Schedule ID and User ID are obsolete field names, use WeekDayIndex and UserIndex instead, respectively.

The associated UserType MAY be changed to ScheduleRestrictedUser by the lock when a Week Day schedule is set.

Return status SHALL be one of the following values:

Name

Description

SUCCESS

Setting Week Day schedule was successful.

FAILURE

Some unexpected internal error occurred setting Week Day schedule.

INVALID_COMMAND

One or more fields violates constraints or is invalid.

Door lock is unable to set Week Day schedule for more than one day in DaysMask map (e.g. need to use separate schedules for each day).

5.2.4.14.1. StartHour

This indicates the starting hour for the Week Day schedule.

5.2.4.14.2. StartMinute

This indicates the starting minute for the Week Day schedule.

5.2.4.14.3. EndHour

The ending hour for the Week Day schedule. EndHour SHALL be equal to or greater than StartHour.

5.2.4.14.4. EndMinute

The ending minute for the Week Day schedule. If EndHour is equal to StartHour then EndMinute SHALL be greater than StartMinute.

If the EndHour is equal to 23 and the EndMinute is equal to 59 the Lock SHALL grant access to the user up until 23:59:59.

5.2.4.15. Get Week Day Schedule Command

Retrieve the specific weekly schedule for the specific user.

Field

Type

Constraint

Quality

Default

Conformance

WeekDayIndex

Schedule ID†

uint8

1 to NumberOfWeekDaySchedulesSupportedPerUser

UserIndex

User ID†

uint16

1 to NumberOfTotalUsersSupported

† The Schedule ID and User ID are obsolete field names, use WeekDayIndex and UserIndex instead, respectively.

5.2.4.16. Get Week Day Schedule Response Command

Returns the weekly repeating schedule data for the specified schedule index.

Field

Type

Constraint

Quality

Default

Conformance

WeekDayIndex

Schedule ID†

uint8

1 to NumberOfWeekDaySchedulesSupportedPerUser

UserIndex

User ID†

uint16

1 to NumberOfTotalUsersSupported

Status

enum8

desc

SUCCESS

DaysMask

DaysMaskMap

StartHour

uint8

0 to 23

StartMinute

uint8

0 to 59

EndHour

uint8

0 to 23

EndMinute

uint8

0 to 59

† The Schedule ID and User ID are obsolete field names, use WeekDayIndex and UserIndex instead, respectively.

5.2.4.16.1. Status

Status SHALL be one of the following values:

SUCCESS if both WeekDayIndex and UserIndex are valid and there is a corresponding schedule entry.

INVALID_COMMAND if either WeekDayIndex and/or UserIndex values are not within valid range

NOT_FOUND if both WeekDayIndex and UserIndex are within the valid range, however, there is not corresponding schedule entry found.

Only if the status is SUCCESS that other remaining fields are included. For other (error) status values, only the fields up to the status field SHALL be present.

5.2.4.16.2. StartHour

This indicates the starting hour for the Week Day schedule.

5.2.4.16.3. StartMinute

This indicates the starting minute for the Week Day schedule.

5.2.4.16.4. EndHour

This indicates the ending hour for the Week Day schedule. EndHour SHALL be equal to or greater than StartHour.

5.2.4.16.5. EndMinute

The ending minute for the Week Day schedule. If EndHour is equal to StartHour then EndMinute SHALL be greater than StartMinute.

5.2.4.17. Clear Week Day Schedule Command

Clear the specific weekly schedule or all weekly schedules for the specific user.

Field

Type

Constraint

Quality

Default

Conformance

WeekDayIndex

Schedule ID†

uint8

1 to NumberOfWeekDaySchedulesSupportedPerUser, 0xFE

UserIndex

User ID†

uint16

1 to NumberOfTotalUsersSupported

† The Schedule ID and User ID are obsolete field names, use WeekDayIndex and UserIndex instead, respectively.

Return status SHALL be one of the following values:

Name

Description

SUCCESS

Clearing Week Day schedule(s) was successful.

FAILURE

Some unexpected internal error occurred clearing Week Day schedule.

INVALID_COMMAND

One or more fields violates constraints or is invalid.

5.2.4.17.1. WeekDayIndex

The Week Day schedule index to clear or 0xFE to clear all Week Day schedules for the specified user.

5.2.4.18. Set Year Day Schedule Command

Set a time-specific schedule ID for a specified user.

Field

Type

Constraint

Quality

Default

Conformance

YearDayIndex

Schedule ID†

uint8

1 to NumberOfYearDaySchedulesSupportedPerUser

UserIndex

User ID†

uint16

1 to NumberOfTotalUsersSupported

LocalStartTime

epoch-s

all

LocalEndTime

epoch-s

all

† The Schedule ID and User ID are obsolete field names, use YearDayIndex and UserIndex instead, respectively.

The associated UserType MAY be changed to ScheduleRestrictedUser by the lock when a Year Day schedule is set.

Return status SHALL be one of the following values:

Name

Description

SUCCESS

Setting Year Day schedule was successful.

FAILURE

Some unexpected internal error occurred setting Year Day schedule.

INVALID_COMMAND

One or more fields violates constraints or is invalid.

5.2.4.18.1. LocalStartTime

The starting time for the Year Day schedule in Epoch Time in Seconds with local time offset based on the local timezone and DST offset on the day represented by the value.

5.2.4.18.2. LocalEndTime

The ending time for the Year Day schedule in Epoch Time in Seconds with local time offset based on the local timezone and DST offset on the day represented by the value. LocalEndTime SHALL be greater than LocalStartTime.

5.2.4.19. Get Year Day Schedule Command

Retrieve the specific year day schedule for the specific schedule and user indexes.

Field

Type

Constraint

Quality

Default

Conformance

YearDayIndex

Schedule ID†

uint8

1 to NumberOfYearDaySchedulesSupportedPerUser

UserIndex

User ID†

uint16

1 to NumberOfTotalUsersSupported

† The Schedule ID and User ID are obsolete field names, use YearDayIndex and UserIndex instead, respectively.

5.2.4.20. Get Year Day Schedule Response Command

Returns the year day schedule data for the specified schedule and user indexes.

Field

Type

Constraint

Quality

Default

Conformance

YearDayIndex

Schedule ID†

uint8

1 to NumberOfYearDaySchedulesSupportedPerUser

UserIndex

User ID†

uint16

1 to NumberOfTotalUsersSupported

Status

enum8

desc

SUCCESS

LocalStartTime

epoch-s

all

LocalEndTime

epoch-s

all

† The Schedule ID and User ID are obsolete field names, use YearDayIndex and UserIndex instead, respectively.

5.2.4.20.1. Status

Status SHALL be one of the following values:

SUCCESS if both YearDayIndex and UserIndex are valid and there is a corresponding schedule entry.

INVALID_COMMAND if either YearDayIndex and/or UserIndex values are not within valid range

NOT_FOUND if both YearDayIndex and UserIndex are within the valid range, however, there is not corresponding schedule entry found.

All fields SHALL be included irrespective of the value of the Status field. For error status values, the LocalStartTime and LocalEndTime fields SHALL be set to null.

5.2.4.20.2. LocalStartTime

The starting time for the Year Day schedule in Epoch Time in Seconds with local time offset based on the local timezone and DST offset on the day represented by the value. This SHALL be null if the schedule is not set for the YearDayIndex and UserIndex provided.

5.2.4.20.3. LocalEndTime

5.2.4.21. Clear Year Day Schedule Command

Clears the specific year day schedule or all year day schedules for the specific user.

Field

Type

Constraint

Quality

Default

Conformance

YearDayIndex

Schedule ID†

uint8

1 to NumberOfYearDaySchedulesSupportedPerUser, 0xFE

UserIndex

User ID†

uint16

1 to NumberOfTotalUsersSupported

† The Schedule ID and User ID are obsolete field names, use YearDayIndex and UserIndex instead, respectively.

Return status SHALL be one of the following values:

Name

Description

SUCCESS

Clearing Year Day schedule(s) was successful.

FAILURE

Some unexpected internal error occurred clearing Year Day schedule.

INVALID_COMMAND

One or more fields violates constraints or is invalid.

5.2.4.21.1. YearDayIndex

The Year Day schedule index to clear or 0xFE to clear all Year Day schedules for the specified user.

5.2.4.22. Set Holiday Schedule Command

Set the holiday Schedule by specifying local start time and local end time with respect to any Lock Operating Mode.

Field

Type

Constraint

Quality

Default

Conformance

HolidayIndex

Holiday Schedule ID†

uint8

1 to NumberOfHolidaySchedulesSupported

LocalStartTime

epoch-s

all

LocalEndTime

epoch-s

all

OperatingMode

OperatingModeEnum

all

† The Holiday Schedule ID is an obsolete field name, use HolidayIndex instead.

Return status SHALL be one of the following values:

Name

Description

SUCCESS

Setting Holiday schedule was successful.

FAILURE

Some unexpected internal error occurred setting Holiday schedule.

INVALID_COMMAND

One or more fields violates constraints or is invalid.

5.2.4.22.1. LocalStartTime

The starting time for the Holiday Day schedule in Epoch Time in Seconds with local time offset based on the local timezone and DST offset on the day represented by the value.

5.2.4.22.2. LocalEndTime

The ending time for the Holiday Day schedule in Epoch Time in Seconds with local time offset based on the local timezone and DST offset on the day represented by the value. LocalEndTime SHALL be greater than LocalStartTime.

5.2.4.22.3. OperatingMode

The operating mode to use during this Holiday schedule start/end time.

5.2.4.23. Get Holiday Schedule Command

Get the holiday schedule for the specified index.

Field

Type

Constraint

Quality

Default

Conformance

HolidayIndex

Holiday Schedule ID†

uint8

1 to NumberOfHolidaySchedulesSupported

† The Holiday Schedule ID is an obsolete field name, use HolidayIndex instead.

5.2.4.24. Get Holiday Schedule Response Command

Returns the Holiday Schedule Entry for the specified Holiday ID.

Field

Type

Constraint

Quality

Default

Conformance

HolidayIndex

Holiday Schedule ID†

uint8

1 to NumberOfHolidaySchedulesSupported

Status

enum8

desc

SUCCESS

LocalStartTime

epoch-s

all

Local End Time

epoch-s

all

OperatingMode

OperatingModeEnum

all

† The Holiday Schedule ID is an obsolete field name, use HolidayIndex instead.

5.2.4.24.1. Status

Status SHALL be one of the following values:

FAILURE if the attribute NumberOfHolidaySchedulesSupported is zero.

SUCCESS if the HolidayIndex is valid and there is a corresponding schedule entry.

INVALID_COMMAND if the HolidayIndex is not within valid range

NOT_FOUND if the HolidayIndex is within the valid range, however, there is not corresponding schedule entry found.

Only if the status is SUCCESS that other remaining fields are included. For other (error) status values, only the fields up to the status field SHALL be present.

5.2.4.24.2. LocalStartTime

The starting time for the Holiday schedule in Epoch Time in Seconds with local time offset based on the local timezone and DST offset on the day represented by the value. This SHALL be null if the schedule is not set for the HolidayIndex provided.

5.2.4.24.3. LocalEndTime

The ending time for the Holiday schedule in Epoch Time in Seconds with local time offset based on the local timezone and DST offset on the day represented by the value. LocalEndTime SHALL be greater than LocalStartTime. This SHALL be null if the schedule is not set for the HolidayIndex provided.

5.2.4.24.4. OperatingMode

The operating mode to use during this Holiday schedule start/end time. This SHALL be null if the schedule is not set for the HolidayIndex provided.

5.2.4.25. Clear Holiday Schedule Command

Clears the holiday schedule or all holiday schedules.

Field

Type

Constraint

Quality

Default

Conformance

HolidayIndex

Holiday Schedule ID†

uint8

1 to NumberOfHolidaySchedulesSupported, 0xFE

† The Holiday Schedule ID is an obsolete field name, use HolidayIndex instead.

5.2.4.25.1. HolidayIndex

The Holiday schedule index to clear or 0xFE to clear all Holiday schedules.

5.2.4.26. Set User Type Command

Set the user type for a specified user.

For user type value please refer to User Type Value.

Field

Type

Constraint

Quality

Default

Conformance

User ID

uint16

desc

User Type

enum8

If UserType is currently YearDayScheduleUser, WeekDayScheduleUser, or ScheduleRestrictedUser and the new UserType is UnrestrictedUser then all existing Year Day and/or Week Day schedules SHALL be ignored or disabled (if this transition is supported by the door lock). If UserType is ScheduleRestrictedUser and the new UserType is ScheduleRestrictedUser then all existing Year Day and/or Week Day schedules SHALL be applied or enabled.

Return status SHALL be one of the following values:

Name

Description

SUCCESS

Setting User Type was successful.

FAILURE

Some unexpected internal error occurred setting User Type.

INVALID_COMMAND

One or more fields violates constraints or is invalid.

Door lock is unable to switch from restricted to unrestricted user (e.g. need to clear schedules to switch).

5.2.4.27. Get User Type Command

Retrieve the user type for a specific user.

Field

Type

Constraint

Quality

Default

Conformance

User ID

uint16

desc

5.2.4.28. Get User Type Response Command

Returns the user type for the specified user ID. If the requested User ID is invalid, send Default Response with an error status equal to FAILURE.

Field

Type

Constraint

Quality

Default

Conformance

User ID

uint16

desc

User Type

enum8

5.2.4.29. Set RFID Code Command

Set an ID for RFID access into the lock.

Field

Type

Constraint

Quality

Default

Conformance

User ID

uint16

desc

User Status

uint8

OccupiedEnabled

User Type

enum8

UnrestrictedUser

RFID Code

octstr

User ID : Between 0 - [# of RFID Users Supported attribute]. Only the values 1 (Occupied/Enabled) and 3 (Occupied/Disabled) are allowed for User Status.

User Status: Used to indicate what the status is for a specific user ID. The values are according to “Set PIN” while not all are supported.

Value

User Status Byte

Conformance

Occupied / Enabled (Access Given)

Occupied / Disabled

User Type: The values are the same as used for “Set PIN Code.”

Return status is a global status code or a cluster-specific status code from the DoorLockStatus table and SHALL be one of the following values:

Name

Description

SUCCESS

Setting RFID code was successful.

FAILURE

Setting RFID code failed.

CONSTRAINT_ERROR

Setting RFID code failed because User ID requested was out of range.

DUPLICATE

Setting RFID code failed because it would create a duplicate RFID code.

5.2.4.30. Get RFID Code Command

Retrieve an RFID code. User ID is between 0 - [# of RFID Users Supported attribute].

Field

Type

Constraint

Quality

Default

Conformance

User ID

uint16

desc

5.2.4.31. Get RFID Code Response Command

Returns the RFID code for the specified user ID.

Field

Type

Constraint

Quality

Default

Conformance

User ID

uint16

desc

User Status

enum8

Available

User Type

enum8

RFID Code

octstr

empty

If the requested User ID is valid and the Code doesn’t exist, Get RFID Code Response SHALL have the following format:

User ID = requested User ID

UserStatus = 0 (available)

UserType = 0xFF (not supported)

RFID Code = 0 (zero length)

If requested User ID is invalid, send Default Response with an error status. The error status shall be equal to CONSTRAINT_ERROR when User_ID is less than the max number of users supported, and NOT_FOUND if greater than or equal to the max number of users supported.

5.2.4.32. Clear RFID Code Command

Clear an RFID code or all RFID codes.

Field

Type

Constraint

Quality

Default

Conformance

RFIDSlotIndex

User ID†

uint16

1 to NumberOfRFIDUsersSupported, 0xFFFE

† The User ID is an obsolete field name, use RFIDSlotIndex instead.

For each RFID Code cleared whose user doesn’t have a PIN Code or other credential type, then the corresponding user record’s UserStatus value SHALL be set to Available, and UserType value SHALL be set to UnrestrictedUser and all schedules SHALL be cleared.

5.2.4.32.1. RFIDSlotIndex

Specifies a valid RFID code slot index or 0xFFFE to indicate all RFID code slots SHALL be cleared.

5.2.4.33. Clear All RFID Codes Command

Clear out all RFIDs on the lock. If you clear all RFID codes and this user didn’t have a PIN code, the user status has to be set to "0 Available", the user type has to be set to the default value, and all schedules which are supported have to be set to the default values.

5.2.4.34. Set User Command

Set User into the lock.

Field

Type

Constraint

Quality

Default

Conformance

OperationType

DataOperationTypeEnum

Add, Modify

UserIndex

uint16

1 to NumberOfTotalUsersSupported

UserName

string

max 10

empty

UserUniqueID

uint32

all

0xFFFFFFFF

UserStatus

OccupiedEnabled, OccupiedDisabled

OccupiedEnabled

UserType

UnrestrictedUser, NonAccessUser, ForcedUser, DisposableUser, ExpiringUser, ScheduleRestrictedUser, RemoteOnlyUser

UnrestrictedUser

CredentialRule

CredentialRuleEnum

desc

Single

Fields used for different use cases:

Use Case

Description

Create a new user record

OperationType SHALL be set to Add.
UserIndex value SHALL be set to a user record with UserType set to Available.
UserName MAY be null causing new user record to use empty string for UserName otherwise UserName SHALL be set to the value provided in the new user record.
UserUniqueID MAY be null causing new user record to use 0xFFFFFFFF for UserUniqueID otherwise UserUniqueID SHALL be set to the value provided in the new user record.
UserStatus MAY be null causing new user record to use OccupiedEnabled for UserStatus otherwise UserStatus SHALL be set to the value provided in the new user record.
UserType MAY be null causing new user record to use UnrestrictedUser for UserType otherwise UserType SHALL be set to the value provided in the new user record.
CredentialRule MAY be null causing new user record to use Single for CredentialRule otherwise CredentialRule SHALL be set to the value provided in the new user record.

CreatorFabricIndex and LastModifiedFabricIndex in the new user record SHALL be set to the accessing fabric index.

A LockUserChange event SHALL be ~~sent~~ generated after successfully creating a new user.

Modify an existing user record

OperationType SHALL be set to Modify.
UserIndex value SHALL be set for a user record with UserType NOT set to Available.
UserName SHALL be null if modifying a user record that was not created by the accessing fabric.
INVALID_COMMAND SHALL be returned if UserName is not null and the accessing fabric index doesn’t match the CreatorFabricIndex in the user record otherwise UserName SHALL be set to the value provided in the user record.
UserUniqueID SHALL be null if modifying the user record that was not created by the accessing fabric.
INVALID_COMMAND SHALL be returned if UserUniqueID is not null and the accessing fabric index doesn’t match the CreatorFabricIndex in the user record otherwise UserUniqueID SHALL be set to the value provided in the user record.
UserStatus MAY be null causing no change to UserStatus in user record otherwise UserStatus SHALL be set to the value provided in the user record.
UserType MAY be null causing no change to UserType in user record otherwise UserType SHALL be set to the value provided in the user record.
CredentialRule MAY be null causing no change to CredentialRule in user record otherwise CredentialRule SHALL be set to the value provided in the user record.

CreatorFabricIndex SHALL NOT be changed in the user record. LastModifiedFabricIndex in the new user record SHALL be set to the accessing fabric index.

A LockUserChange event SHALL be ~~sent~~ generated after successfully modifying ~~credential.~~ a user.

Return status is a global status code or a cluster-specific status code from the DoorLockStatus table and SHALL be one of the following values:

SUCCESS, if setting User was successful.
FAILURE, if some unexpected internal error occurred setting User.
OCCUPIED, if OperationType is Add and UserIndex points to an occupied slot.
INVALID_COMMAND, if one or more fields violate constraints or are invalid or if OperationType is Modify and UserIndex points to an available slot.

5.2.4.34.1. UserName

A string to use as a human readable identifier for the user.

If UserName is null then:

If the OperationType is Add, the UserName in the resulting user record SHALL be set to an empty string.
If the OperationType is Modify, the UserName in the user record SHALL NOT be changed from the current value.

If UserName is not null, the UserName in the user record SHALL be set to the provided value.

5.2.4.34.2. UserUniqueID

A fabric assigned number to use for connecting this user to other users on other devices from the fabric’s perspective.

If UserUniqueID is null then:

If the OperationType is Add, the UserUniqueID in the resulting user record SHALL be set to default value specified above.
If the OperationType is Modify, the UserUniqueID in the user record SHALL NOT be changed from the current value.

If UserUniqueID is not null, the UserUniqueID in the user record SHALL be set to the provided value.

5.2.4.34.3. UserStatus

A UserStatus to assign to this user when created or modified.

If UserStatus is null then:

If the OperationType is Add, the UserStatus in the resulting user record SHALL be set to default value specified above.
If the OperationType is Modify, the UserStatus in the user record SHALL NOT be changed from the current value.

If UserStatus is not null, the UserStatus in the user record SHALL be set to the provided value.

5.2.4.34.4. UserType

A UserType to assign to this user when created or modified.

If UserType is null then:

If the OperationType is Add, the UserType in the resulting user record SHALL be set to default value specified above.
If the OperationType is Modify, the UserType in the user record SHALL NOT be changed from the current value.

If UserType is not null, the UserType in the user record SHALL be set to the provided value.

5.2.4.34.5. CredentialRule

The CredentialRule to use for this user.

The valid CredentialRule enumeration values depends on the bits in the CredentialRulesSupport map. Each bit in the map identifies a valid CredentialRule that can be used.

If CredentialRule is null then:

If the OperationType is Add, the CredentialRule in the resulting user record SHALL be set to default value specified above.
If the OperationType is Modify, the CredentialRule in the user record SHALL NOT be changed from the current value.

If CredentialRule is not null, the CredentialRule in the user record SHALL be set to the provided value.

5.2.4.35. Get User Command

Retrieve User.

Field

Type

Constraint

Quality

Default

Conformance

UserIndex

uint16

1 to NumberOfTotalUsersSupported

An InvokeResponse command SHALL be sent with an appropriate error (e.g. FAILURE, INVALID_COMMAND, etc.) as needed otherwise the Get User Response Command SHALL be sent implying a status of SUCCESS.

5.2.4.36. Get User Response Command

Returns the User for the specified UserIndex.

Field

Type

Constraint

Quality

Default

Conformance

UserIndex

uint16

1 to NumberOfTotalUsersSupported

UserName

string

max 10

empty

UserUniqueID

uint32

all

UserStatus

all

Available

UserType

all

UnrestrictedUser

CredentialRule

CredentialRuleEnum

CredentialRulesSupport

Single

Credentials

list[ CredentialStruct ]

0 to NumberOfCredentialsSupportedPerUser

CreatorFabricIndex

fabric-idx

all

LastModifiedFabricIndex

fabric-idx

all

NextUserIndex

uint16

1 to NumberOfTotalUsersSupported

If the requested UserIndex is valid and the UserStatus is Available for the requested UserIndex then UserName, UserUniqueID, UserStatus, UserType, CredentialRule, Credentials, CreatorFabricIndex, and LastModifiedFabricIndex SHALL all be null in the response.

5.2.4.36.1. CreatorFabricIndex

The user’s creator fabric index. CreatorFabricIndex SHALL be null if UserStatus is set to Available or when the creator fabric cannot be determined (for example, when user was created outside the Interaction Model) and SHALL NOT be null otherwise. This value SHALL be set to 0 if the original creator fabric was deleted.

5.2.4.36.2. LastModifiedFabricIndex

The user’s last modifier fabric index. LastModifiedFabricIndex SHALL be null if UserStatus is set to Available or when the modifier fabric cannot be determined (for example, when user was modified outside the Interaction Model) and SHALL NOT be null otherwise. This value SHALL be set to 0 if the last modifier fabric was deleted.

5.2.4.36.3. NextUserIndex

The next occupied UserIndex in the database which is useful for quickly identifying occupied user slots in the database. This SHALL NOT be null if there is at least one occupied entry after the requested UserIndex in the User database and SHALL be null if there are no more occupied entries.

5.2.4.37. Clear User Command

Clears a User or all Users.

Field

Type

Constraint

Quality

Default

Conformance

UserIndex

uint16

1 to NumberOfTotalUsersSupported, 0xFFFE

For each User to clear, all associated credentials (e.g. PIN, RFID, fingerprint, etc.) SHALL be cleared and the User entry values SHALL be reset to their default values (e.g. UserStatus SHALL be Available, UserType SHALL be UnrestrictedUser) and all associated schedules SHALL be cleared.

A LockUserChange event with the provided UserIndex SHALL be generated after successfully clearing users.

5.2.4.37.1. UserIndex

Specifies a valid User index or 0xFFFE to indicate all User slots SHALL be cleared.

5.2.4.38. Operation Event Notification Command

The door lock server sends out operation event notification when the event is triggered by the various event sources. The specific operation event will only be sent out if the associated bitmask is enabled in the various attributes in the Event Masks Attribute Set.

All events are optional.

Field

Type

Constraint

Quality

Default

Conformance

Operation Event Source

uint8

desc

Operation Event Code

uint8

desc

User ID

uint16

desc

PIN

octstr

LocalTime

epoch-s

all

Data

string

5.2.4.38.1. Operation Event Sources

This field indicates where the event was triggered from.

Value	Source
0	Keypad
1	Remote
2	Manual
3	RFID
0xFF	Indeterminate

5.2.4.38.2. Operation Event Codes

The door lock optionally sends out notifications (if they are enabled) whenever there is a significant operational event on the lock. When combined with a source from the Event Source table above, the following operational event codes constitute an event on the door lock that can be both logged and sent to a bound device using the Operation Event Notification command.

Not all operation event codes are applicable to each of the event source. The following table marks each event code with “A” if the event code is applicable to the event source.

Value

Name

Conformance

Applicable

Keypad

Remote

Manual

RFID

UnknownOrMfgSpecific

Lock

Unlock

LockFailureInvalidPINorRFID

LockFailureInvalidSchedule

UnlockFailureInvalidPINorRFID

UnlockFailureInvalidSchedule

OneTouchLock

KeyLock

KeyUnlock

AutoLock

ScheduleLock

~~WDSCH YDSCH~~ WDSCH|YDSCH

ScheduleUnlock

~~WDSCH YDSCH~~ WDSCH|YDSCH

Manual Lock (Key or Thumbturn)

Manual Unlock (Key or Thumbturn)

Non-access User Operation Event

5.2.4.38.3. User ID

The User ID who performed the event.

5.2.4.38.4. PIN

The PIN that is associated with the User ID who performed the event.

5.2.4.38.5. LocalTime

The time when the event was triggered in Epoch Time in Seconds with local time offset based on the local timezone and DST offset on the day represented by the value. If time is not supported, the field SHALL be populated with default not used value 0xFFFFFFFF.

5.2.4.38.6. Data

The operation event notification command contains a variable string, which can be used to pass data associated with a particular event. Generally this field will be left empty. However, manufacturer can choose to use this field to store/display manufacturer-specific information.

5.2.4.38.7. Keypad Operation Event Notification

Keypad Operation Event Notification feature is enabled by setting the associated bitmasks in the [Keypad Operation Event Mask attribute].

5.2.4.38.8. Remote Operation Event Notification

Remote Operation Event Notification feature is enabled by setting the associated bitmasks in the [Remote Operation Event Mask attribute].

5.2.4.38.9. Manual Operation Event Notification

Manual Operation Event Notification feature is enabled by setting the associated bitmasks in the [Manual Operation Event Mask attribute] attribute.

5.2.4.38.10. RFID Operation Event Notification

RFID Operation Event Notification feature is enabled by setting the associated bitmasks in the [RFID Operation Event Mask attribute].

5.2.4.39. Programming Event Notification Command

The door lock server sends out a programming event notification whenever a programming event takes place on the door lock.

As with operational events, all programming events can be turned on and off by flipping bits in the associated event mask.

The programming event notification command includes an optional string of data that can be used by the manufacturer to pass some manufacturer-specific information if that is required.

Field

Type

Constraint

Quality

Default

Conformance

Program Event Source

uint8

desc

Program Event Code

uint8

desc

User ID

uint16

desc

PIN

octstr

User Type

enum8

desc

User Status

enum8

desc

LocalTime

epoch-s

all

Data

string

5.2.4.39.1. Operation Event Sources

This field indicates where the event was triggered from.

Value	Source
0	Keypad
1	Remote
2	Reserved (Manual in Operation Event)
3	RFID
0xFF	Indeterminate

5.2.4.39.2. Programming Event Codes

The door lock optionally sends out notifications (if they are enabled) whenever there is a significant programming event on the lock. When combined with a source from the Event Source table above, the following programming event codes constitute an event on the door lock that can be both logged and sent to a bound device using the Programming Event Notification command.

Not all event codes are applicable to each of the event source. The following table marks each event code with “A” if the event code is applicable to the event source.

Value

Programming Event Code

Keypad

Remote

RFID

UnknownOrMfgSpecific

ProgrammingCodeChanged

PINCodeAdded

PINCodeCleared

PINCodeChanged

RFIDCodeAdded

RFIDCodeCleared

5.2.4.39.3. User ID

The User ID who performed the event

5.2.4.39.4. PIN

The PIN that is associated with the User ID who performed the event

5.2.4.39.5. User Type

The User Type that is associated with the User ID who performed the event

5.2.4.39.6. User Status

The User Status that is associated with the User ID who performed the event

5.2.4.39.7. LocalTime

5.2.4.39.8. Data

The programming event notification command contains a variable string, which can be used to pass data associated with a particular event. Generally this field will be left empty. However, manufacturer can choose to use this field to store/display manufacturer-specific information.

5.2.4.39.9. Keypad Programming Event Notification

Keypad Programming Event Notification feature is enabled by setting the associated bitmasks in the [Keypad Programming Event Mask attribute].

5.2.4.39.10. Remote Programming Event Notification

Remote Programming Event Notification feature is enabled by setting the associated bitmasks in the [Remote Programming Event Mask attribute].

5.2.4.39.11. RFID Programming Event Notification

RFID Programming Event Notification feature is enabled by setting the associated bitmasks in the [RFID Programming Event Mask attribute].

5.2.4.40. Set Credential Command

Set a credential (e.g. PIN, RFID, Fingerprint, etc.) into the lock for a new user, existing user, or ProgrammingUser.

Field

Type

Constraint

Quality

Default

Conformance

OperationType

DataOperationTypeEnum

Add, Modify

Credential

CredentialStruct

CredentialData

octstr

desc

UserIndex

uint16

1 to NumberOfTotalUsersSupported

UserStatus

OccupiedEnabled, OccupiedDisabled

OccupiedEnabled

UserType