2.2.33. Configuration Command Class, version 3

The Configuration Command Class, version 3 allows product specific configuration parameters to be changed. Examples include the default dimming rate of a light dimmer and the endpoints of a window covering device.

\requirement{CC:0070.03.00.11.001}{0}

Configuration parameters accessed via this command class MUST NOT replace similar commands provided by other existing application Command Classes.

\requirement{CC:0070.03.00.11.002}{0}

Configuration parameter documentation MUST be provided in the product documentation.

\requirement{CC:0070.03.00.12.001}{0}

Configuration parameter documentation SHOULD be provided via Z-Wave via this command class version.

\requirement{CC:0070.03.00.11.003}{0}

A device MUST be able to operate with default factory configuration parameter values.

\requirement{CC:0070.03.00.12.002}{0}

It is RECOMMENDED that configuration parameters can be manipulated via a local user interface.

\requirement{CC:0070.03.00.12.003}{0}

It is RECOMMENDED that default factory configuration parameter values can be restored via a local user interface.

2.2.33.1. Compatibility considerations

The following additions are made to the Configuration Command Class, version 3:

  • Configuration Name Get Command

  • Configuration Name Report Command

  • Configuration Info Get Command

  • Configuration Info Report Command

  • Configuration Properties Get Command

  • Configuration Properties Report Command

The purpose of the above commands is to allow a manufacturer to advertise information relating to the use of a specific configuration parameter directly from the configuration interface. The advertised information should be the same as can be found in the printed documentation.

It should be emphasized that, just like versions 1 and 2, the Configuration Command Class, version 3 is intended only for access to product specific configuration parameters. The access to parameter information is only meant to facilitate access via Z-Wave to information which can also be found in the printed documentation.

Configuration Command Class versions 1 and 2 explicitly require that the binary value of all configuration parameters are represented as signed values encoded as binary 2’s complement.

Configuration Command Class v3 allows for bit field, signed integer or unsigned integer representations of each individual parameter.

\requirement{CC:0070.03.00.21.001}{0} \requirement{CC:0070.03.00.21.002}{8}

A device supporting the Configuration Command Class v3 MUST respond to a Configuration Properties Get command. If a Configuration Properties Report command is not returned in response to a Configuration Properties Get command, a controlling device MUST treat the parameter value as a signed integer.

Configuration Command Class version 2 extended the possible parameter range from 1..255 to 1..65535. The first 255 parameters of the two ranges are identical. Parameters in the range 1..255 can be addressed using either the Bulk Set/Get Commands or Set/Get Commands while parameters in the range 256..65535 can only be addressed using the Bulk Set/Get Commands.

2.2.33.1.1. “Default” flag

Refer to Section 2.2.31.1.1.

2.2.33.1.2. Configuration Properties Report

\requirement{CC:0070.03.00.21.003}{4}

Earlier text revisions of the Configuration Command Class, version 3 did not explicitly specify that the “Min Value”, “Max Value” and “Default Value” fields MUST be omitted if the advertised size is 0 in the Configuration Properties Report Command.

\requirement{CC:0070.03.00.22.001}{0} \requirement{CC:0070.03.00.22.002}{8}

Controlling nodes SHOULD be aware that some legacy nodes supporting version 3 could by error include the “Min Value”, “Max Value” and “Default Value” fields and set them to 0x00 with an arbitrary size. If a controlling node receives a Report in which the “Next Parameter Number” field seems to be set to 0x0000 when requesting parameter number 0, the controlling node SHOULD inspect the last 2 bytes of the command frame in order to find out what is the Next Parameter Number.

2.2.33.2. Interoperability considerations

\requirement{CC:0070.03.00.32.001}{0}

It is RECOMMENDED that the name and information stored in a supporting device are in English.

\requirement{CC:0070.03.00.32.002}{0}

It is RECOMMENDED that the last line of the information field presents an Internet URL which points to updated information for the actual configuration parameter as well as other language variants.

2.2.33.3. Configuration Name Get Command

This command is used to request the name of a configuration parameter.

\requirement{CC:0070.03.0A.11.001}{0}

The Configuration Name Report Command MUST be returned in response to this command.

\requirement{CC:0070.03.0A.11.002}{0}

This command MUST NOT be issued via multicast addressing.

\requirement{CC:0070.03.0A.11.003}{0}

A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods.

Table 2.164 Configuration Name Get Command

7

6

5

4

3

2

1

0

Command Class = COMMAND_CLASS_CONFIGURATION (0x70)

Command = CONFIGURATION_NAME_GET (0x0A)

Parameter Number 1 (MSB)

Parameter Number 2 (LSB)

Parameter Number (16 bits)

This field is used to specify the requested configuration parameter.

\requirement{CC:0070.03.0A.11.004}{0}

The first byte MUST carry the most significant byte of the 16 bit value.

2.2.33.4. Configuration Name Report Command

This command is used to advertise the name of a parameter.

Table 2.165 Configuration Name Report Command

7

6

5

4

3

2

1

0

Command Class = COMMAND_CLASS_CONFIGURATION (0x70)

Command = CONFIGURATION_NAME_REPORT (0x0B)

Parameter Number 1 (MSB)

Parameter Number 2 (LSB)

Reports to follow

Name 1

…

Name N

Parameter Number (16 bits)

This field is used to advertise the actual configuration parameter.

\requirement{CC:0070.03.0B.11.001}{0}

The first byte MUST carry the most significant byte of the 16 bit value.

\requirement{CC:0070.03.0B.13.001}{0} \requirement{CC:0070.03.0B.12.001}{8}

If a non-existing parameter is specified in a Configuration Name Get Command, a receiving node MAY return a zero-length Name field in the Configuration Name Report Command. The receiving node SHOULD however return an error message e.g. “Unassigned parameter”.

Parameter numbers above 255 can only be addressed using the Bulk Set/Get Commands. Parameter numbers in the range 1..255 can be addressed using either the Bulk Set/Get Commands or the Set/Get Commands.

Reports to follow (8 bits)

This field is used to advertise the number of reports left before all parts of the command have been transferred.

\requirement{CC:0070.03.0B.11.002}{0}

The value 0 MUST indicate that this is the last report.

Name (N bytes)

\requirement{CC:0070.03.0B.12.002}{0}

This field is used to advertise the name of the parameter. It is RECOMMENDED that the Name field advertises the name found in the documentation.

\requirement{CC:0070.03.0B.11.003}{0}

The field MUST carry a byte string with no zero termination. The Name field MAY span multiple reports. The number of Name bytes transmitted MUST be determined from the length field in the frame.

\requirement{CC:0070.03.0B.11.004}{0}

Bytes MUST be encoded in UTF-8 format.

\requirement{CC:0070.03.0B.12.003}{0}

It is RECOMMENDED that the name stored in a supporting device is in English.

2.2.33.5. Configuration Info Get Command

This command is used to request usage information for a configuration parameter.

\requirement{CC:0070.03.0C.11.001}{0}

The Configuration Info Report Command MUST be returned in response to this command.

\requirement{CC:0070.03.0C.11.002}{0}

This command MUST NOT be issued via multicast addressing.

\requirement{CC:0070.03.0C.11.003}{0}

A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods.

Table 2.166 Configuration Info Get Command

7

6

5

4

3

2

1

0

Command Class = COMMAND_CLASS_CONFIGURATION (0x70)

Command = CONFIGURATION_INFO_GET (0x0C)

Parameter Number 1 (MSB)

Parameter Number 2 (LSB)

Parameter Number (16 bits)

This field is used to specify the requested configuration parameter.

\requirement{CC:0070.03.0C.11.004}{0}

The first byte MUST carry the most significant byte of the 16 bit value.

2.2.33.6. Configuration Info Report Command

This command is used to advertise usage information for a configuration parameter.

Table 2.167 Configuration Info Report Command

7

6

5

4

3

2

1

0

Command Class = COMMAND_CLASS_CONFIGURATION (0x70)

Command = CONFIGURATION_INFO_REPORT (0x0D)

Parameter Number 1 (MSB)

Parameter Number 2 (LSB)

Reports to follow

Info 1

…

Info N

Parameter Number (16 bits)

This field is used to advertise the actual configuration parameter.

\requirement{CC:0070.03.0D.11.001}{0}

The first byte MUST carry the most significant byte of the 16 bit value.

\requirement{CC:0070.03.0D.13.001}{0} \requirement{CC:0070.03.0D.12.001}{4}

If a non-existing parameter is specified in a Configuration Info Get Command, a receiving node MAY return a zero-length Info field in the Configuration Info Report Command. The receiving node SHOULD however return an error message, e.g. “Unassigned parameter”.

Parameter numbers above 255 can only be addressed using the Bulk Set/Get Commands. Parameter numbers in the range 1..255 can be addressed using either the Bulk Set/Get Commands or the Set/Get Commands

Reports to follow (8 bits)

This field is used to advertise the number of reports left before all parts of the command have been transferred.

\requirement{CC:0070.03.0D.11.002}{0}

The value 0 MUST indicate that this is the last report.

Info (N bytes)

\requirement{CC:0070.03.0D.12.002}{0}

This field is used to advertise the detailed information available for the parameter. It is RECOMMENDED that the Info field carries all information found in the documentation.

\requirement{CC:0070.03.0D.11.003}{0}

The field MUST carry a byte string with no zero termination.

\requirement{CC:0070.03.0D.11.004}{0}

The number of Info bytes transmitted MUST be determined from the length field in the frame.

\requirement{CC:0070.03.0D.13.002}{0}

The Info field MAY span multiple reports. The number of Info bytes MAY be zero.

\requirement{CC:0070.03.0D.11.005}{0}

Bytes MUST be encoded in UTF-8 format.

\requirement{CC:0070.03.0D.12.003}{0}

It is RECOMMENDED that the information stored in a supporting device is in English.

\requirement{CC:0070.03.0D.12.004}{0}

It is RECOMMENDED that the last line of the information field presents an Internet URL which points to updated information for the actual configuration parameter as well as other language variants.

2.2.33.7. Configuration Properties Get Command

This command is used to request the properties of a configuration parameter.

The Configuration Properties Report Command MUST be returned in response to this command.

This command MUST NOT be issued via multicast addressing.

A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods.

Table 2.168 Configuration Properties Get Command

7

6

5

4

3

2

1

0

Command Class = COMMAND_CLASS_CONFIGURATION (0x70)

Command = CONFIGURATION_PROPERTIES_GET (0x0E)

Parameter Number 1 (MSB)

Parameter Number 2 (LSB)

Parameter Number (16 bits)

This field is used to specify the requested configuration parameter.

\requirement{CC:0070.03.0E.11.001}{0}

The first byte MUST carry the most significant byte of the 16 bit value.

\requirement{CC:0070.03.0E.11.002}{0} \requirement{CC:0070.03.0E.11.003}{4}

If a non-existing parameter is specified in this command, a receiving node MUST advertise zero values in the Format and Size fields. The Next Parameter Number field MUST advertise the next available configuration parameter.

\requirement{CC:0070.03.0E.12.001}{0}

It is RECOMMENDED that a controlling device initiates probing of supported configuration parameters by issuing this command for parameter number 0.

\requirement{CC:0070.03.0E.12.002}{0}

If a Size field value of zero is returned, a controlling device SHOULD issue a Configuration Properties Get Command for the parameter advertised in the Next Parameter Number field.

2.2.33.8. Configuration Properties Report Command

This command is used to advertise the properties of a configuration parameter.

Table 2.169 Configuration Properties Report Command

7

6

5

4

3

2

1

0

Command Class = COMMAND_CLASS_CONFIGURATION (0x70)

Command = CONFIGURATION_PROPERTIES_REPORT (0x0F)

Parameter Number 1 (MSB)

Parameter Number 2 (LSB)

Reserved

Format

Size

Min Value 1 (MSB)

…

Min Value N (LSB)

Max Value 1 (MSB)

…

Max Value N (LSB)

Default Value 1 (MSB)

…

Default Value N (LSB)

Next Parameter Number 1 (MSB)

Next Parameter Number 2 (LSB)

Parameter Number (16 bits)

This field is used to advertise the actual configuration parameter.

\requirement{CC:0070.03.0F.11.001}{0}

The first byte MUST carry the most significant byte of the 16 bit value.

\requirement{CC:0070.03.0F.11.002}{0} \requirement{CC:0070.03.0F.11.003}{4}

If this field advertises a non-existing parameter , a receiving node MUST advertise zero values in the Format and Size fields. The Next Parameter Number field MUST advertise the next available configuration parameter.

Parameter numbers above 255 can only be addressed using the Bulk Set/Get Commands. Parameter numbers in the range 1..255 can be addressed using either the Bulk Set/Get Commands or the Set/Get Commands.

Reserved

\requirement{CC:0070.03.0F.11.004}{0}

This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node.

Format (3 bits)

This field is used to advertise the format of the parameter.

\requirement{CC:0070.03.0F.11.005}{0}

The value of this field MUST comply with Table 2.170.

Table 2.170 Configuration Properties Report::Format encoding

Value

Parameter format and presentation

0x00

Signed Integer

0x01

Unsigned Integer

0x02

Enumerated (Radio buttons)

0x03

Bit field (Checkboxes)

\requirement{CC:0070.03.0F.11.006}{0}

All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node.

\requirement{CC:0070.03.0F.11.007}{0}

If the parameter format is “Unsigned integer”, normal binary integer encoding MUST be used.

\requirement{CC:0070.03.0F.11.008}{0}

If the parameter format is “Signed integer”, the binary encoding MUST comply with Table 2.12.

\requirement{CC:0070.03.0F.11.009}{0}

If the parameter format is “Enumerated”, the parameter MUST be treated as an unsigned integer.

\requirement{CC:0070.03.0F.12.001}{0}

A graphical configuration tool SHOULD present this parameter as a series of radio buttons [22].

\requirement{CC:0070.03.0F.11.00A}{0}

If the parameter format is “Bit field” the parameter MUST be treated as a bit field where each individual bit can be set or reset.

\requirement{CC:0070.03.0F.12.002}{0}

A graphical configuration tool SHOULD present this parameter as a series of checkboxes [22].

Size (3 bits)

This field is used to advertise the size of the actual parameter.

\requirement{CC:0070.03.0F.11.00B}{0}

The advertised size MUST also apply to the fields “Min Value”, “Max Value”, “Default Value” carried in this command.

\requirement{CC:0070.03.0F.11.00C}{0}

The value of this field MUST comply with Table 2.171.

Table 2.171 Configuration Properties Report::Size encoding

Size

Size of parameter

0

0 bit (Unassigned parameter, Value fields omitted)

1

8 bit

2

16 bit

4

32 bit

\requirement{CC:0070.03.0F.11.00D}{0}

All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node.

Min Value (N bytes)

\requirement{CC:0070.03.0F.11.00E}{0}

This field MUST advertise the minimum value that the actual parameter can assume.

\requirement{CC:0070.03.0F.11.00F}{0}

If the parameter is “Bit field”, this field MUST be set to 0.

\requirement{CC:0070.03.0F.11.010}{0}

The size of the field MUST comply with the size advertised by the Size field. This field MUST be omitted if the Size field is set to 0.

\requirement{CC:0070.03.0F.11.011}{0}

The sign encoding MUST comply with the mode advertised by the Signed field.

Max Value (N bytes)

\requirement{CC:0070.03.0F.11.012}{0}

This field MUST advertise the maximum value that the actual parameter can assume.

\requirement{CC:0070.03.0F.11.013}{0}

If the parameter is “Bit field”, each individual supported bit MUST be set to ‘1’, while each un-supported bit of MUST be set to ‘0’.

\requirement{CC:0070.03.0F.12.003}{0}

A graphical configuration tool SHOULD NOT present checkboxes for un-supported bits.

\requirement{CC:0070.03.0F.11.014}{0}

The size of the field MUST comply with the size advertised by the Size field. This field MUST be omitted if the Size field is set to 0.

\requirement{CC:0070.03.0F.11.015}{0}

The sign encoding MUST comply with the mode advertised by the Signed field.

Default Value (N bytes)

\requirement{CC:0070.03.0F.11.016}{0}

This field MUST advertise the default value of the actual parameter.

\requirement{CC:0070.03.0F.11.017}{0}

The size of the field MUST comply with the size advertised by the Size field. This field MUST be omitted if the Size field is set to 0.

\requirement{CC:0070.03.0F.11.018}{0}

The sign encoding MUST comply with the mode advertised by the Signed field.

Next Parameter Number (16 bits)

Configuration parameter identifiers may be assigned in a non-sequential order.

\requirement{CC:0070.03.0F.11.019}{0}

This field MUST advertise the next available configuration parameter.

The value 0x0000 MUST indicate that this is the last available configuration parameter.

\requirement{CC:0070.03.0F.11.01A}{0}

The first byte MUST carry the most significant byte of the 16 bit value.