6.1. Command Class Control Overview¶
6.1.1. Controlled and Supported Command Classes¶
A node can support and/or control a given Command Class.
If a Command Class is supported:
\requirement{CL:0000.00.11.0D.1}{4}
The node implements all the Command Class functionalities and can be set and read back by other nodes. When a Command Class is supported, the node is REQUIRED to implement the whole Command Class and observe the requirements specified in Section 2, Section 3, Section 4, and Section 5.
If a Command Class is controlled:
\requirement{CL:0000.00.13.01.1}{4}
The node implements the ability to interview, read and/or set other nodes supporting the Command Class. Nodes controlling Command Classes MAY use a subset of the Commands within a Command Class (for example only Set commands).
6.1.1.1. Control via association groups¶
A Basic Set Command sent to Association Group destinations is a form of (static or partial) Command Class control via association groups.
\requirement{CL:0000.00.11.02.1}{0}
Even if using a Command Class for controlling other nodes via association groups, the usage MUST comply with the Command Class description (Section 2, Section 3, Section 4, and Section 5) and the controlling node use properly formed commands.
6.1.1.2. “Full” control¶
\requirement{CL:0000.00.11.03.1}{4}
When a Command Class is marked as fully controlled during certification, the controlling node is said to implement “full” control of the actual Command Class and it MUST observe the requirements for the Command Class defined in this document.
\requirement{CL:0000.00.11.04.1}{4}
Device Type v2 Specification mandates some nodes to control a given set of Command Classes. It means that the controlling node MUST respect the requirements described in this document for the actual Command Classes.
6.1.1.3. Partial Control¶
\requirement{CL:0000.00.13.03.1}{4} \requirement{CL:0000.00.11.10.1}{12}
When a Command Class is marked as partially controlled during certification, the controlling node is said to implement partial control of the actual Command Class and it MAY observe only a subset of the requirements for the Command Class defined in this document. The specific features which are partially controlled MUST be noted during certification.
\requirement{CL:0000.00.13.04.1}{0}
If a Command Class is partially controlled, the controlling node MAY skip steps or perform them in a different order for the mandatory node interview detailed in this document. The controlling node MAY retrieve capabilities from a database based on a node’s manufacturer specific information.
\requirement{CL:0000.00.11.11.1}{4}
Even if the mandatory node interview is not followed, and not all capabilities are queried, the controlling node MUST NOT send commands or values that the supporting node does not support.
\requirement{CL:0000.00.13.05.1}{0} \requirement{CL:0000.00.12.01.1}{4}
If a Command Class is partially controlled, the controlling node MAY implement a subset of the minimum end user functionalities and user interface. A controlling node SHOULD provide functionalities for the lowest non-deprecated, non-obsoleted Command Class version.
\requirement{CL:0000.00.11.12.1}{0}
All Z-Wave commands sent for a partially controlled Command Class MUST be valid Z-Wave commands
\requirement{CL:0000.00.11.13.1}{0}
All Z-Wave commands sent for a partially controlled Command Class MUST be sent at the highest Security Class granted during security bootstrapping.
\requirement{CL:0000.00.11.14.1}{0}
Partial Control MAY be used for Application Command Classes only (Refer to Section 6.2). Management and Transport-Encapsulation Command Class MUST be fully controlled. (Refer to Section 6.3 and Section 6.4).
6.1.2. Command Classes Support Discovery Requirements¶
\requirement{CL:0000.00.11.05.1}{0}
A controlling node MUST read the capabilities and secure capabilities of a node/End Point once before trying to control a given Command Class.
\requirement{CL:0000.00.11.06.2}{0}
A controlling node MUST read the Command Class version number of a supporting node using the Version Command Class prior to controlling the Command Class. There can be 2 exceptions to this rule:
If the controlling node controls only version 1 of a given Command Class, it may skip requesting the supporting node version for the actual Command Class.
A controlling node may issue version 1 commands in the supporting node interview before knowing the supporting node Command Class’ version. (e.g., when interviewing the Version Command Class itself)
\requirement{CL:0000.00.11.07.1}{0}
A node controlling a given command class MUST allow an end user to control the command class in all listening supporting nodes present in the network operating with a security class that is granted to the controlling node.
\requirement{CL:0000.00.11.08.1}{0}
A node controlling a Command Class MUST allow an end user to control a sleeping supporting node if it is the Wake Up destination.
6.1.3. Command Classes Control Requirements¶
This specification defines how to provide full control of Command Classes by specifying:
A required Command Class interview or capability discovery
A minimum required set of actions that an end user can perform or trigger and their associated Z-Wave commands
A minimum required set of information relating to the supporting node that the end user can see or access.
An optional set of additional requirements to controlling nodes
6.1.3.1. Mandatory supporting node interview¶
\requirement{CL:0000.00.21.01.3}{0}
The mandatory node interview specifies the frame flow that MUST be observed on the Z-Wave radio for full control. Set commands MAY be skipped they would have no effect on the supporting node.
\requirement{CL:0000.00.21.02.1}{0}
This interview MUST be performed prior to issuing any control command to the supporting node.
Preferably, it should be done during the commissioning phase of the supporting node or shortly after the inclusion of the controlling node.
\requirement{CL:0000.00.23.01.1}{0} \requirement{CL:0000.00.21.03.1}{8}
A fully controlling node MAY issue additional commands that are not specified in the frame flows and MAY issue some commands in a different order. The mandatory frame flow indicates the minimum set of commands that MUST be transmitted to a destination.
\requirement{CL:0000.00.21.04.1}{0}
A fully controlling node MUST NOT skip or abort the interview of a Command Class if another independent Command Class could not be correctly interviewed.
\requirement{CL:0000.00.23.02.1}{0}
A “partially” controlling node MAY skip steps in the specified frame flow if the queried data would not be used by the controller, or the data is retrieved from a separate source (i.e. database of Manufacturer Specific information and capabilities)
\requirement{CL:0000.00.22.01.1}{0}
The following order for reading Command Class capabilities is RECOMMENDED after discovering the Security Class and encapsulation capabilities of a node:
Version Command Class
Z-Wave Plus Info Command Class
Wake Up Command Class
Association OR Multi Channel Association Command Class
Association Group Information (AGI) Command Class
Actuator Command Classes
Data reporting Command Classes
Multi Channel Command Class (and repeat the above order for each End Point, if any)
\requirement{CL:0000.00.22.02.1}{4}
Some interviews or controlling scenarios may trigger no response in return to get type commands. In this case, it is RECOMMENDED to use timeouts according to Role Type Specification.
6.1.3.2. Minimum end user functionalities¶
The minimum end user functionalities section specifies what minimum set of actions an end user can perform on a supporting node when using the controlling node.
\requirement{CL:0000.00.31.01.1}{0} \requirement{CL:0000.00.33.01.1}{4}
Each section describing a required functionality indicates the command(s) that MUST be transmitted on the Z-Wave radio for full control. Fields not present, not described or marked as “free” in the mandatory command(s) MAY be used freely by the controlling node either automatically or based on user input.
\requirement{CL:0000.00.31.02.1}{0}
Fields indicated as “user defined” MUST be filled based on end user input. In this case, the end user MUST be able to select any value. (e.g. if the field is 2 bytes long, values from 0 to 65535 MUST be available)
\requirement{CL:0000.00.31.03.1}{0}
Fields indicated as “User defined among supported” MUST be filled based on user input and the supported values by the supporting node. The controlling node MUST allow the end user to set values supported by a supporting node even if it does not know what a given value represents.
\requirement{CL:0000.00.31.04.1}{0}
Fields indicated as “User defined among x..y and z” MUST be filled based on user input and MUST be able to select between the indicated values.
\requirement{CL:0000.00.31.06.1}{0}
Fields indicated as “User defined or x” MUST be filled either based on user input or automatically by the controller using the indicated value.
\requirement{CL:0000.00.31.05.1}{0}
The product documentation MUST point out how to perform each action associated to the minimum end user functionalities required by a Command Class.
\requirement{CL:0000.00.31.07.1}{4}
If a Command Class is partially controlled and some minimum end user functionality are not met, the product documentation MUST describe how the partially controlled command class differs from the behavior of a fully controlled command class.
6.1.3.3. Command Class control version¶
\requirement{CL:0000.00.11.09.1}{4}
Like a supporting node implements a version of its supported Command Classes, a controlling node MUST also implement a given version of a Command Class it controls. A node controlling version 3 of a Command Class will be able to control the functionalities of version 1, 2 and 3 supporting nodes.
\requirement{CL:0000.00.11.0A.2}{0}
When issuing commands, a controlling node MUST NOT use the fields described in the mandatory commands sections if they belong to a newer version than the version it claims to control.
\requirement{CL:0000.00.12.02.1}{0}
If a controlling node A controls a node B supporting a lower version, node A SHOULD still use the format (command payload) corresponding to the version node A controls, regardless of the version supported by node B.
\requirement{CL:0000.00.11.0F.1}{0}
A controlling node A sending commands to a node B supporting a lower version MUST NOT use commands introduced in versions that are newer than Node B’s version.
A node controlling a Command Class is not mandated to interview, provide minimum end user functionality or show node properties belonging to a newer version of the actual Command Class.
\requirement{CL:0000.00.11.0B.1}{4}
When a version is indicated in the mandatory interview or mandatory commands for end user functionalities, it MUST represent the minimum common version number between the supporting and controlling node. For example, with a version 4 controlling node and version 2 supporting node, the interview, minimum end user functionalities and properties MUST follow version 1 and 2 indications.
6.1.4. Command Classes not Present in this Document¶
\requirement{CL:0000.00.13.02.1}{0} \requirement{CL:0000.00.11.0C.1}{4}
A node MAY advertise that it controls a Command Class not (yet) defined in this document during certification. In this case, the controlling node MUST comply with the following guidelines:
It MUST use all Get type commands to read the nodes capabilities during the node interview
It SHOULD provide the end user actions using all Set type Commands available in the Command Class
It SHOULD show or let the end user access all relevant state/property/configuration relating to the Command Class using the Report type Commands available in the Command Class.
A controller following this guideline is likely to be compliant when a new control specification is released for an actual Command Class.
