2.2.73. Multilevel Switch Command Class, version 3

Warning

The Secondary Switch Type of the Multilevel Switch Command Class, version 3 has been DEPRECATED.

The Primary Switch Type 0x00, indicating “Not supported”, of the Multilevel Switch Command Class, version 3 has been OBSOLETED.

The implementation of Secondary Switch Type functionality is NOT RECOMMENDED.

While the functionality related to the Secondary Switch Type of the Multilevel Switch Command Class, version 3 is deprecated, a supporting device claiming compliance with this version MUST implement support for the Multilevel Switch Supported Get Command.

For backwards compatibility reasons, a device MAY implement Secondary Switch Type functionality. It is however RECOMMENDED that Multi Channel Command Class support is also implemented if a device provides multiple controllable resources in the same physical entity.

The Multilevel Switch Command Class is used to control devices with multilevel capability.

The Multilevel Switch Command Class is an actuator control Command Class. Refer to Section 2.1.6

Multilevel Switch CC, version 3 adds two-dimensional resource control capabilities to the Multilevel Switch Start/Stop Level Change commands and introduces two new commands for the discovery of those capabilities.

The Secondary Switch Type is intended for devices providing two-dimensional control, e.g. Window blinds, where the Primary Switch Type is used for Up/Down control and the Secondary Switch Type is used for controlling the slat tilt angle.

The Multilevel Switch Set, Get and Report commands MUST address the primary device functionality. The Multilevel Switch Start/Stop Level Change commands MUST manipulate the Primary Switch Type functionality based on the Up/Down parameter.

The Multilevel Switch Start/Stop Level Change commands MUST manipulate the Secondary Switch Type functionality based on the Inc/Dec parameter.

If the Secondary Switch Type is 0x00 (Undefined / Not supported), the Multilevel Switch Start/Stop Level Change (Inc/Dec) command parameter MUST be ignored.

2.2.73.1. Compatibility considerations

A device supporting Multilevel Switch CC, version 3 MUST support Multilevel Switch CC, version 2.

A device supporting Multilevel Switch CC, version 3 MUST implement the Primary Switch type.

Commands not described in Version 3 remain unchanged from Version 2.

2.2.73.2. Multilevel Switch Supported Get Command

This command is used to request the supported Switch Types of a supporting device.

The Multilevel Switch Supported 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.423 Multilevel Switch Supported Get Command

7

6

5

4

3

2

1

0

Command Class = COMMAND_CLASS_SWITCH_MULTILEVEL (0x26)

Command = SWITCH_MULTILEVEL_SUPPORTED_GET (0x06)

2.2.73.3. Multilevel Switch Supported Report Command

This command is used to advertise the supported Switch Types implemented by a supporting device.

Table 2.424 Multilevel Switch Supported Report Command

7

6

5

4

3

2

1

0

Command Class = COMMAND_CLASS_SWITCH_MULTILEVEL (0x26)

Command = SWITCH_MULTILEVEL_SUPPORTED_REPORT (0x07)

Reserved

Primary Switch Type

Reserved

Secondary Switch Type

Reserved

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

Primary Switch Type (5 bits)

The Primary Switch Type field MUST represent the primary device functionality.

Warning

Primary Switch Type 0x00, indicating “Not supported”, has been OBSOLETED.

Previous revisions of this specification allowed that a device may (theoretically) be implemented with no primary device functionality, i.e. Primary Switch Type 0x00, and specified that such a device should indicate this situation by returning Multilevel Switch Report commands carrying the value 0xFE. The value 0xFE is incompatible with Versions 1 and 2 of the Multilevel Switch Command Class and MUST NOT be used in a Multilevel Switch Report.

The Primary Switch Type MUST comply with Table 2.425.

A supporting device MUST implement the Primary Switch type.

The Primary Switch Type SHOULD be 0x02 (Up/Down).

The Primary Switch Type MUST NOT be 0x00 (Undefined).

Table 2.425 Encoding of Primary and Secondary Switch Types

Switch Value Type

0x00 (Direction/Endpoint A)

0x63/0xFF (Direction/Endpoint B)

0x00

Undefined / Not supported (Secondary only)

0x01

Off

On

0x02

Down

Up

0x03

Close

Open

0x04

Counter-Clockwise

Clockwise

0x05

Left

Right

0x06

Reverse

Forward

0x07

Pull

Push

0x08-0x1F

Reserved

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

Secondary Switch Type (5 bits)

The Secondary Switch Type field MUST represent the secondary device functionality. The Secondary Switch Type MUST comply with Table 2.425.

A supporting device MAY implement the Secondary Switch type.

2.2.73.4. Multilevel Switch Start Level Change Command

This command is used to initiate a transition to a new level.

The Multilevel Switch Command Class, version 3 adds a “Secondary Switch Inc/Dec” and a “Secondary Switch Step Size” field to this command to support motor controlled devices featuring two-dimensional motion.

Table 2.426 Multilevel Switch Start Level Change Command, version 3

7

6

5

4

3

2

1

0

Command Class = COMMAND_CLASS_SWITCH_MULTILEVEL (0x26)

Command = SWITCH_MULTILEVEL_START_LEVEL_CHANGE (0x04)

Primary Switch Up/Down

Ignore Start Level

Secondary Switch Inc/Dec

Reserved

Start Level

Duration

Secondary Switch Step Size

Primary Switch Up/Down (2 bits)

The Up/Down field MUST be used for manipulating the primary device functionality.

This field MUST be encoded according to Table 2.427.

Table 2.427 Encoding of the Up/Down field

Value

Description

Details

0x00

Up

Increase level for Primary Switch Type

0x01

Down

Decrease level for Primary Switch Type

0x02

Reserved

0x03

No Up/Down motion

Maintain current level for Primary Switch Type

Ignore Start Level (1 bit)

A receiving device SHOULD respect the start level if the Ignore Start Level bit is 0.

A receiving device MUST ignore the start level if the Ignore Start Level bit is 1.

Secondary Switch Inc/Dec (2 bits)

The Inc/Dec field MUST be used for controlling the secondary device functionality.

If the Secondary Switch Type is 0x00 (Undefined / Not supported), the Inc/Dec field MUST be ignored.

This field MUST be encoded according to Table 2.428.

Table 2.428 Encoding of the Inc/Dec field

Value

Description

Details

0x00

Increment

Increase level for Secondary Switch Type

0x01

Decrement

Decrease level for Secondary Switch Type

0x02

Reserved

0x03

No Inc/Dec

Maintain current level for Secondary Switch Type

As this field defines the value “00” of two previously reserved bits as the code “Increment”, a supporting device implementing Multilevel Switch CC, version 3 MUST correctly identify the Multilevel Switch Start Level Change command to be version 3 (by the presence of the <Secondary Switch Step Size> field) before interpreting the <Secondary Switch Inc/Dec> field. Failing to do so will cause a device to start incrementing the Secondary Switch Type in response to version 1 and version 2 variants of the Multilevel Switch Start Level Change command.

Reserved

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

Primary Switch Start Level (8 bits)

The Start Level field MUST be used for controlling the primary device functionality.

Duration (8 bits)

This field is unchanged from version 2.

Secondary Switch Step Size (8 bits)

The Step Size field MAY be used for controlling a secondary device functionality.

If the Secondary Switch Type is 0x00 (Undefined / Not supported), the Step Size field MUST be ignored. If the Secondary Switch Type is not 0x00, the Step Size field MUST be used for controlling the secondary device functionality.

If the Inc/Dec field is set to 3 (No Inc/Dec), the Step Size field MUST be set to 0.

This field MUST carry a value in the range {0x00..0x63, 0xFF}. All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node.

A receiving device MUST accept any of the values in the above range. 0x01 MUST represent the lowest non-zero level and 0x63 MUST represent the highest level

A device MAY implement 100 hardware levels (including 0). If a device implements less than 100 hardware levels, the mapping to hardware levels SHOULD be distributed equally over the entire range of 1..99 (0x01..0x63).

The mapping of command values to hardware levels MUST be monotonous, i.e. a higher value MUST be mapped to either the same or a higher hardware level.

An implementation MUST interpret the combined Inc/Dec and Step Size fields as outlined in Table 2.429.

Table 2.429 Interpretation of the Inc/Dec and Step Size fields

(Secondary Switch Type)

Inc/Dec

Step Size

Interpretation

(undefined)

(ignore)

(ignore)

Secondary Switch Type is undefined -> ignore fields

0x01..0x07

No Inc/Dec

(ignore)

No Inc/Dec -> Maintain current Secondary Switch level

0x01..0x07

Increment

x

Increase Secondary Switch level by x steps

0x01..0x07

Decrement

y

Decrease Secondary Switch level by y steps

The requested level change SHOULD take the time specified by the Duration field.