3.2.47. Version Command Class, version 4¶

The Version Command Class, version 4 allows supporting nodes to advertise capabilities related to the Version Command Class and optionally provide functionality for a supporting node to advertise support for migrating legacy functionality to later functionality without losing data or information.

3.2.47.1. Compatibility Considerations¶

The Version Command Class, version 4 is backwards compatible with the Version Command Class, version 3. A node supporting the Version Command Class, version 4 MUST also support the Version Command Class, version 3.

All commands and fields not described in this version remain unchanged from version 3.

The Version Command Class, version 4 introduces the possibility for a node to advertise its supported Version Command Class capabilities by extending the following command introduced in Version Command Class, version 3:

Version Capabilities Report Command

The changes introduced in the above command provide mechanisms for a node to advertise support for migration.

Additional commands introduced in version 4 advertise support a discrete number of migration operations, triggering a migration process along those operations, and getting or reporting the status of a migration process.

\requirement{CC:0086.04.00.21.001}{0}

Supporting nodes MUST advertise support for commands present in previous versions of this Command Class for backwards compatibility.

The following commands are optionally implemented by supporting nodes if migration is supported:

Version Migration Capabilities Get
Version Migration Capabilities Report
Version Migration Set
Version Migration Report

3.2.47.2. Terminology¶

3.2.47.2.1. Migration¶

As the Z-Wave ecosystem continues to grow and evolve, new Command Classes are introduced that supersede functionality originally administered by an older, legacy command class beyond introducing new revisions. When this occurs, to preserve backwards compatibility, supporting nodes will need to advertise support for these legacy command classes so older controlling nodes can still control these supporting nodes normally, in addition to advertising support for the new command classes that provide expanded functionality for newer controlling nodes to utilize. However, due to a number of reasons it is not always practical, or even possible, for a device to actively support both the new and legacy CCs simultaneously. Rather, it may be more practical, or even necessary, for a supporting node to dynamically configure itself to only allow control through one of the overlapping (new and/or legacy) CCs based on which CC the controlling node uses.

Migration was introduced to allow a controller to verify and explicitly control which of these overlapping CCs are being used to control a particular functionality.

3.2.47.2.2. Operation¶

A device can support migrating its internal configuration using a number of discrete migration operations. These operations define how stored configuration data on a node will change, and how the functionality of the node changes in accordance with the new configuration. Some functionally enmeshed command classes, such as User Code Command Class, version 2 and Schedule Entry Lock Command Class, version 3 are both affected by a single migration operation. These discrete Operations are defined below in Table 3.174. Each migration operation’s specific requirements and detailed descriptions will be included in the specification for the command class (CC) listed under the Defining CC column in the table.

Table 3.174 Migration Operation Definitions¶
ID (Identifier)	Name	Description	Defining CC
0x01	User Code to User Credential migration	This operation will trigger a migration for a supporting node that converts the existing User Code Command Class, version 2 User Codes in a user management database to equivalent Users and PIN Codes from User Credential Command Class, version 1.	User Credential Command Class, version 1
0x02	User Credential to User Code migration	This operation will trigger a migration for a supporting node that converts the existing Users and PIN codes in a credential database to equivalent User Codes from the User Code Command Class.	User Credential Command Class, version 1

Migration operation requirements will describe how functionality on the device changes after Migration, and will provide methods to functionally disable the overlapping portions of a command class(es) without removing support of the CC from the NIF.

3.2.47.3. Version Capabilities Report Command¶

This command is used to advertise the version commands supported by the sending node.

Unless otherwise specified, all fields and requirements are unchanged from the Version Capabilities Report Command, version 3.

Table 3.175 Version Capabilities Report Command, Version 4¶
7	3	2	1	0
Command Class = COMMAND_CLASS_VERSION (0x86)
Command = VERSION_CAPABILITIES_REPORT (0x16)
Reserved	M	ZWS	CC	V

M (Migration Support) (1 bit)

This field is used to advertise support for data migration, and by extension, the Version Migration Capabilities Get Command.

3.2.47.4. Version Migration Capabilities Get Command¶

This command is for a node to request the migration capabilities of a supporting node.

Table 3.176 Version Migration Capabilities Get Command¶
7	6	5	4	3	2	1	0
Command Class = COMMAND_CLASS_VERSION (0x86)
Command = VERSION_MIGRATION_CAPABILITIES_GET (0x19)

\requirement{CC:0086.04.19.11.001}{0}

If a receiving node advertises Migration Support in the Version Capabilities Report Command, a Version Migration Capabilities Report Command MUST be sent to the sending node in response to this command.

3.2.47.5. Version Migration Capabilities Report Command¶

This command is used to advertise which migration operations (if any) are supported by the supporting node.

Table 3.177 Version Migration Capabilities Report Command¶
7	6	5	4	3	2	1	0
Command Class = COMMAND_CLASS_VERSION (0x86)
Command = VERSION_MIGRATION_CAPABILITIES_REPORT (0x1A)
Number of Supported Migration Operations
Migration Operation ID 1
…
Migration Operation ID N

Number of Supported Migration Operations (8 bits)

This field advertises how many discrete migration operations are supported by the sending node.

Migration Operation ID

This field lists, one per 8 bits, which migration operations as defined in Table 3.174 are supported by the sending node.

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

The length of this field MUST equal the value of the Number of Supported Migration Operations field.

\requirement{CC:0086.04.1A.13.002}{0}

The body of this report MAY change as the result of one or more migrations.

3.2.47.6. Version Migration Set Command¶

This command is used to trigger a specific migration operation.

Table 3.178 Version Migration Set Command¶
7	6	5	4	3	2	1	0
Command Class = COMMAND_CLASS_VERSION (0x86)
Command = VERSION_MIGRATION_SET (0x1B)
Migration Operation ID

Migration Operation ID (8 Bits)

Operation ID as defined in Table 3.174.

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

This command MUST be ignored by the receiving node if the Migration Operation ID is not listed in the Version Migration Capabilities Report Command.

3.2.47.7. Version Migration Get Command¶

This command is used to get the status of a migration operation.

Table 3.179 Version Migration Get Command¶
7	6	5	4	3	2	1	0
Command Class = COMMAND_CLASS_VERSION (0x86)
Command = VERSION_MIGRATION_GET (0x1C)
Migration Operation ID

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

If a receiving node advertises Migration Support in the Version Capabilities Report Command, a Version Migration Report Command MUST be sent to the sending node in response to this command.

Other fields and requirements mirror those described in the Version Migration Set Command.

3.2.47.8. Version Migration Report Command¶

This command is used to report the status of a migration.

Table 3.180 Version Migration Report Command¶
7	6	5	4	3	2	1	0
Command Class = COMMAND_CLASS_VERSION (0x86)
Command = VERSION_MIGRATION_REPORT (0x1D)
Migration Operation ID
Migration Status
Estimated Time of Completion (s) (MSB)
Estimated Time of Completion (s) (LSB)

Migration Status (8 Bits)

Reports the status of a current migration operation based on Table 3.181

Table 3.181 Migration Operation Status¶
ID (Identifier)	Name	Description
0x00	Ready	The node is ready to run this migration operation.
0x01	In Progress	The node is currently running this migration operation.
0x02	Migration Complete - Success	The node successfully completed this migration operation.
0x03	Migration Complete - Failure	The node failed to complete this migration operation.
0x04	Unsupported	The node does not, or no longer, supports this migration operation.

\requirement{CC:0086.04.1D.12.001}{0}

Any node that receives a report with an Unsupported status SHOULD re-interview the node in accordance with the Mandatory node interview as the node capabilities may have changed.

Estimated Time of Completion (16 Bits)

This field reports the amount of time, in seconds, for the migration operation to complete.

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

This field MUST be set to zero by the sending node if the Migration Status is not In Progress. The receiving node MUST ignore this field if the status is not In Progress.