3.2.17. Firmware Update Meta Data Command Class, version 3

The Firmware Update Meta Data Command Class, version 3 allows a Z-Wave enabled device to receive one out of several firmware images.

As an example, one may construct a product comprising a Z-Wave chip and a secondary host processor that maintains a security certificate. With the capability to handle multiple firmware images enables the Z-Wave chip, the host processor and the security certificate may all be updated via individual firmware IDs.

3.2.17.1. Compatibility considerations

\requirement{CC:007A.03.00.21.001}{0}

A device implementing Firmware Update Meta Data Command Class, version 3 MUST also implement Firmware Update Meta Data Command Class, version 2.

\requirement{CC:007A.03.00.21.002}{4}

While support for version 1 has been deprecated, a controlling device implementing Firmware Update Meta Data Command Class, version 2 MUST also be able to control Firmware Update Meta Data Command Class, version 1 based devices.

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

Note that the minimum granted firmware size that can be transferred using Firmware Update Meta Data Report command is around 900 kB.

3.2.17.1.1. New fields and values

The Firmware Update Meta Data Command Class, Version 3, introduces WaitTime parameter and a new Status code 0xFE for the Firmware Update Meta Data Status Report Command.

\requirement{CC:007A.03.00.21.003}{12}

The status code 0xFE is intended for confirming the successful transfer of images which do not necessitate a restart, e.g. security certificates. If this code was returned to a controller implementing a previous version, the controller would report that an error had occurred. Therefore, a supporting node MUST NOT return this code after having updated the firmware image for the Z-Wave chip image, i.e. the Firmware ID 0 target.

3.2.17.2. Interoperability considerations

\requirement{CC:007A.03.00.32.001}{0}

Unintended modification of a firmware image SHOULD be prevented. It is RECOMMENDED that firmware update is enabled by out-of-band authentication (e.g. physical activation of a pushbutton).

\requirement{CC:007A.03.00.31.001}{0} \requirement{CC:007A.03.00.32.002}{4}

A checksum MUST be appended to the Firmware 0 image to ensure the integrity of the image. A receiving device SHOULD verify the integrity of the received Firmware 0 image by matching the received Firmware 0 image checksum and the Firmware 0 image checksum that is indicated by the Firmware Meta Data Report when the firmware update is initiated.

\requirement{CC:007A.03.00.32.003}{0} \requirement{CC:007A.03.00.31.002}{8}

Any image transferred via the Firmware Update Meta Data Command Class SHOULD include a fingerprint value for validation of the integrity of the entire image after the transfer. The image and the fingerprint value MUST be packed in one entity which can be stored in one file and transferred as one entity.

\requirement{CC:007A.03.00.31.003}{0}

A manufacturer MUST assign a unique Firmware ID to each existing product variant. A product variant may be a particular hardware version for a particular world region. The combination of Manufacturer ID and Firmware ID provides unique identification of a firmware image that is guaranteed to work with a particular component of a particular product.

3.2.17.2.1. Interoperability with v1 devices

Version 2 of the Firmware Update Meta Data Report command introduces a 16-bit Checksum field to follow the variable-length Data field. No fields follow the variable-length Data field in Version 1 of the Firmware Update Meta Data Report command. Version 3 of the Firmware Update Meta Data Report command uses the v2 format.

At the same time, the specified method for determining the length of the variable-length Data field is that the length must be calculated from the length of the received frame.

The unintended consequence is that a version 1 implementation receiving a Firmware Update Meta Data Report v2 command will consider the 16-bit Checksum field to be the last two bytes of the Data field.

Similarly, a version 2 implementation receiving a Firmware Update Meta Data Report v1 command will consider the last two bytes of the Data field to be the 16-bit Checksum field.

In either case, the transfer will fail.

\requirement{CC:007A.03.00.31.004}{0}

Therefore, a node controlling the Firmware Update Meta Data Command Class, version 3 MUST do the following when initiating the transfer of a firmware image:

  1. Request the version of the Firmware Update Meta Data Command Class from the target device

  2. Use the version of the Firmware Update Meta Data Report implemented by the target device

  3. Determine the number of Data bytes that can fit into the Firmware Update Meta Data Report command so that the complete command can still fit into the payload field of the transport frame. The number of available payload bytes in the frame depends on the actual bit rate, the use of security encapsulation as well as the presence of Checksum bytes in the Firmware Update Meta Data Report

3.2.17.2.2. Checksum calculation

Version 1 of the Firmware Update Meta Data Command Class introduced a 16-bit Checksum field used to verify firmware image integrity. It has been a recommendation to use the CRC-CCITT polynomial for calculating checksums. Nodes having implemented another method for calculating the checksum will find a non-matching checksum.

From Version 5 onwards, the checksum calculation method is mandatory.

For more details about the checksum calculation, refer to CRC-CCITT Source Code.

3.2.17.3. Firmware Meta Data Report Command

This command is used to advertise the status of the current firmware in the device.

Table 3.56 Firmware Meta Data Report Command version 3

7

6

5

4

3

2

1

0

Command Class = COMMAND_CLASS_FIRMWARE_UPDATE_MD (0x7A)

Command = FIRMWARE_MD_REPORT (0x02)

Manufacturer ID 1

Manufacturer ID 2

Firmware 0 ID 1

Firmware 0 ID 2

Firmware 0 Checksum 1

Firmware 0 Checksum 2

Firmware Upgradable

Number of Firmware Targets

Max Fragment Size 1

Max Fragment Size 2

Firmware 1 ID 1

Firmware 1 ID 2

…

Firmware N ID 1

Firmware N ID 2

Fields not described below remain unchanged from version 2

Firmware 0 ID (16 bits)

The Firmware 0 ID field is dedicated to target 0, i.e. the Z-Wave chip.

\requirement{CC:007A.03.02.11.001}{0}

A manufacturer MUST assign a unique Firmware ID to each existing product variant. A product variant may be a particular hardware version for a particular world region. The combination of Manufacturer ID and Firmware ID provides unique identification of a firmware image that is guaranteed to work with a particular component of a particular product.

\requirement{CC:007A.03.02.11.002}{0}

The first byte MUST be the most significant byte.

A user may request Manufacturer Specific information to get more detailed information on the product.

\requirement{CC:007A.03.02.12.001}{0}

A controlling node SHOULD match the advertised firmware ID for the existing firmware image to the firmware ID provided for a new image. If the firmware IDs do not match, the controlling device SHOULD abort the firmware update operation.

Firmware 0 Checksum (16 bits)

\requirement{CC:007A.03.02.11.003}{0}

The checksum field is used to ensure consistency of the Firmware 0 image currently in the device.

Supporting nodes MAY set this field to 0x00. In this case the field is unused.

Values in the range 0x0001..0xFFFF indicate that the supporting node advertises the checksum of its firmware image.

\requirement{CC:007A.03.02.11.004}{0}

The first byte MUST be the most significant byte.

\requirement{CC:007A.03.02.12.002}{0}

It is RECOMMENDED to use a checksum algorithm that implements a CRC-CCITT polynomial using initialization value equal to 0x1D0F and 0x1021 (normal representation).

Firmware Upgradable (8 bits)

This field defines whether the Z-Wave chip is firmware upgradable.

\requirement{CC:007A.03.02.11.005}{0}

The value 0x00 MUST indicate that the firmware 0 image is not upgradable.

The value 0xFF MUST indicate that the firmware 0 image is upgradable.

Number of Firmware Targets (8 bits)

\requirement{CC:007A.03.02.11.006}{0}

The Number of Firmware Targets field MUST report the number of firmware IDs following this field.

\requirement{CC:007A.03.02.11.007}{0}

The Firmware 0 ID field is not included. The field MUST be zero if the device only implements a Firmware 0 target, i.e. the Z-Wave chip.

Max Fragment Size (16 bits)

\requirement{CC:007A.03.02.11.008}{0} \requirement{CC:007A.03.02.13.001}{4}

The Max Fragment Size field MUST report the maximum number of Data bytes that a device is able to receive at a time. A sending node MAY send shorter fragments. The fragment size actually used is indicated in the Firmware Update Meta Data Request Get Command and confirmed in the Firmware Update Meta Data Request Report Command.

\requirement{CC:007A.03.02.11.009}{4}

The Max Fragment Size may be longer than the supported frame length of Z-Wave if the image is to be transferred over e.g. IP. If the image is to be transferred over Z-Wave, the sending node MUST use a fragment size which matches the actual number of available Data bytes. The number of available Data bytes depends on the actual bit rate, the use of security encapsulation as well as the presence of Checksum bytes in the Firmware Update Meta Data Report.

Firmware n ID (16 bits)

\requirement{CC:007A.03.02.11.00A}{0}

The Firmware 1 ID field indicates the Firmware ID that MUST be used for target 1. The Firmware 2 ID field represents target 2. And so on.

\requirement{CC:007A.03.02.11.00B}{0}

The first byte MUST be the most significant byte.

\requirement{CC:007A.03.02.12.003}{0}

A controlling device SHOULD match the advertised firmware ID for the existing firmware image to the firmware ID provided for a new image. If the firmware IDs do not match, the controlling device SHOULD abort the firmware update operation.

3.2.17.4. Firmware Update Meta Data Request Get Command

The Firmware Update Meta Data Request Get Command is used to request that a firmware update is initiated by the node receiving this command.

\requirement{CC:007A.03.03.11.001}{0}

The Firmware Update Meta Data Request Report Command MUST be returned in response to this command.

\requirement{CC:007A.03.03.11.002}{0}

This command MUST NOT be issued via multicast addressing.

\requirement{CC:007A.03.03.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.

\requirement{CC:007A.03.03.11.004}{0}

The firmware update MUST NOT be initiated if the Manufacturer ID and the Firmware ID do not match the actual firmware image values for the specified Firmware Target.

\requirement{CC:007A.03.03.11.005}{0}

The firmware update MUST be aborted if the checksum does not match the calculated checksum after the firmware image has been transferred.

\requirement{CC:007A.03.03.12.001}{0}

It is RECOMMENDED that firmware update is enabled by out-of-band authentication (e.g. physical activation of a pushbutton) prior to the transmission of this command.

\requirement{CC:007A.03.03.12.002}{0} \requirement{CC:007A.03.03.11.006}{8}

Any image transferred via the Firmware Update Meta Data Command Class SHOULD include a fingerprint value to enable the validation of the integrity of the entire image after the transfer. The image and the fingerprint value MUST be packed in one entity which can be stored in one file and transferred as one entity.

Table 3.57 Firmware Meta Data Request Get Command version 3

7

6

5

4

3

2

1

0

Command Class = COMMAND_CLASS_FIRMWARE_UPDATE_MD (0x7A)

Command = FIRMWARE_UPDATE_MD_REQUEST_GET (0x03)

Manufacturer ID 1

Manufacturer ID 2

Firmware ID 1

Firmware ID 2

Checksum 1

Checksum 2

Firmware Target

Fragment Size 1

Fragment Size 2

All fields not described below remain unchanged from version 2.

Firmware ID (16 bits)

\requirement{CC:007A.03.03.11.007}{0}

The Firmware ID MUST match the specified target of the actual device.

\requirement{CC:007A.03.03.11.008}{0}

The firmware update MUST NOT be initiated if the Firmware ID does not match the specified target of the actual device.

\requirement{CC:007A.03.03.11.009}{0}

The first byte MUST be the most significant byte.

Firmware Target (8 bits)

\requirement{CC:007A.03.03.11.00A}{0}

This field MUST be used to identify the firmware image to be updated. The firmware images MUST be identified as follows:

Table 3.58 Firmware Target (8 bits)

Firmware Target

Description

0x00

Firmware image targeted for the Z-Wave chip.

0x01

Firmware image intended for target 1 defined by the manufacturer.

…

…

0xFF

Firmware image intended for target 255 defined by the manufacturer.

Fragment Size (16 bits)

\requirement{CC:007A.03.03.11.00B}{0}

The Fragment Size field MUST report the fragment size that is to be used for firmware fragments. A receiving device MUST use this fragment size for the firmware update. The fragment size is not exchanged during the actual firmware update.

\requirement{CC:007A.03.03.11.00C}{0}

The Fragment Size MUST NOT exceed the Max Fragment Size value of the Firmware Meta Data Report.

\requirement{CC:007A.03.03.11.00D}{4}

A version 1 Firmware Update Meta Data Request Get Command does not carry a Fragment Size field. A receiving node MUST determine the number of Data bytes from the length of the first received frame, the use of security encapsulation as well as the presence of Checksum bytes in the Firmware Update Meta Data Report.

3.2.17.5. Firmware Update Meta Data Request Report Command

This command is used to advertise if the firmware update will be initiated.

Table 3.59 Firmware Update Meta Data Request Report Command version 3

7

6

5

4

3

2

1

0

Command Class = COMMAND_CLASS_FIRMWARE_UPDATE_MD (0x7A)

Command = FIRMWARE_UPDATE_MD_REQUEST_REPORT (0x04)

Status

Status (8 bits)

\requirement{CC:007A.03.04.11.001}{0}

This field MUST comply with Table 3.81.

3.2.17.6. Firmware Update Meta Data Get Command

The Firmware Update Meta Data Get Command is used to request one or more Firmware Update Meta Data Report Commands.

\requirement{CC:007A.03.05.11.001}{0}

One or more Firmware Update Meta Data Report Commands MUST be returned in response to this command.

\requirement{CC:007A.03.05.11.002}{0}

This command MUST NOT be issued via multicast addressing.

\requirement{CC:007A.03.05.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.

\requirement{CC:007A.03.05.11.004}{0}

A node MUST verify the Manufacturer ID and Firmware ID fields received in a Firmware Update Meta Data Request Get Command before sending any Firmware Update Meta Data Get Commands.

\requirement{CC:007A.03.05.11.005}{0}

A controlling node receiving a Firmware Update Meta Data Get Command MUST return fragments of the firmware image that was previously identified by the Manufacturer ID and Firmware ID fields received in a Firmware Update Meta Data Request Get Command.

\requirement{CC:007A.03.05.13.001}{0} \requirement{CC:007A.03.05.13.002}{4}

The transmission of the next Firmware Update Meta Data Get Command MAY be delayed if time is required to store the most recent firmware fragment in temporary non-volatile memory. A node MAY request multiple Firmware Update Meta Data Report Commands to improve throughput.

\requirement{CC:007A.03.05.13.003}{0}

RAM may be a limited resource. A node MAY adjust the size of incoming Firmware Update Meta Data Report Commands to the available first level RAM receive buffer by reporting the desired Max Fragment Size when returning a Firmware Meta Data Report Command in response to a Firmware Update Meta Data Get Command.

Two exceptions may apply: A noise burst may interfere the transmission or the data source may stop returning Firmware Update Meta Data Report Commands.

\requirement{CC:007A.03.05.12.001}{0}

To accommodate for bursts of RF noise, a device receiving data SHOULD repeatedly retransmit the same Firmware Update Meta Data Get Command every 10 seconds in case no Firmware Update Meta Data Report Commands are received.

\requirement{CC:007A.03.05.12.002}{0}

A device receiving data SHOULD stop retransmitting Firmware Update Meta Data Get commands 2 minutes after the last successful reception of a Firmware Update Meta Data Report Command.

Table 3.60 Firmware Update Meta Data Get Command version 3

7

6

5

4

3

2

1

0

Command Class = COMMAND_CLASS_FIRMWARE_UPDATE_MD (0x7A)

Command = FIRMWARE_UPDATE_MD_GET (0x05)

Number of Reports

Res

Report Number 1

Report Number 2

Res

\requirement{CC:007A.03.05.11.006}{0}

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

Number of Reports (8 bits)

Number of Firmware Update Meta Data Report Commands to be received in response to a single Firmware Update Meta Data Get Command.

\requirement{CC:007A.03.05.11.007}{0}

The requesting node MUST keep track of missing Firmware Update Meta Data Report Commands.

Report Number (15 bits)

\requirement{CC:007A.03.05.11.008}{4}

The Report number field indicates the sequence number of the requested firmware fragment. The first firmware fragment MUST be identified by the Report Number value 1.

\requirement{CC:007A.03.05.11.009}{0}

Report number 1 MUST be the most significant byte.

\requirement{CC:007A.03.05.11.00A}{0}

If the Number of Reports field is larger than 1, the Report Number MUST identify the first firmware fragment in the requested sequence of firmware fragments.

3.2.17.7. Firmware Update Meta Data Report Command

The Firmware Update Meta Data Report command is used to transfer a firmware image fragment.

\requirement{CC:007A.03.06.11.001}{0}

If sending more than a single Firmware Update Meta Data Report Command at a time, a node MUST apply a delay between each transmitted command. The minimum required time delay and number of frames before a delay must be inserted depends on the actual bit rate.

  • 40 kbit/s: At least 35 ms if sending more than 1 frame back-to-back

  • 100 kbit/s: At least 15 ms if sending more than 2 frames back-to-back

After receiving all Firmware Update Meta Data Report Commands required for a complete firmware image, a receiving node MUST store the firmware image in the Firmware Target specified in a previously received Firmware Update Meta Data Request Get Command.

\requirement{CC:007A.03.06.12.001}{0}

If needed, a controlling node SHOULD abort an ongoing transfer by responding to a Firmware Update Meta Data Get Command with a Firmware Update Meta Data Report Command with the Last bit enabled and the Data fields intentionally corrupted while the Checksum field of the Firmware Update Meta Data Report Command is valid, i.e. calculated over the corrupted Data fields.

This will invalidate the calculated firmware checksum, which should eventually cause the receiving device to return a Firmware Update Meta Data Status Report Command with the status code <checksum error>.

Table 3.61 Firmware Update Meta Report Command version 3

7

6

5

4

3

2

1

0

Command Class = COMMAND_CLASS_FIRMWARE_UPDATE_MD (0x7A)

Command = FIRMWARE_UPDATE_MD_REPORT (0x06)

Last

Report Number 1

Report Number 2

Data 1

…

Data N

Checksum 1

Checksum 2

All fields not described below remain unchanged from version 2.

Last (1 bit)

This field indicates if the Firmware Update Meta Data Report Command is the last one.

\requirement{CC:007A.03.06.11.002}{0}

The value 1 MUST indicate that this is the last report. Otherwise the field MUST be set to 0.

\requirement{CC:007A.03.06.11.003}{0}

On the reception of the last image fragment, the receiving node MUST verify that the transferred image does match the indicated Manufacturer ID, Firmware ID and Firmware Target values.

Checksum (16 bits)

\requirement{CC:007A.03.06.11.004}{0}

The checksum field MUST be used to ensure the consistency of the entire command; including the command class and command identifiers.

\requirement{CC:007A.03.06.12.002}{0}

It is RECOMMENDED to use a checksum algorithm that implements the CRC-CCITT polynomium using initialization value equal to 0x1D0F and 0x1021 (normal representation).

\requirement{CC:007A.03.06.11.005}{0}

The checksum algorithm used for the Firmware Update Meta Data Command Class, version 3 MUST be the same as the algorithm used for the Firmware Update Meta Data Command Class, version 2 in the actual product.

The Checksum field is known to cause compatibility issues with version 1 devices. Refer to Section 3.2.16.1.

3.2.17.8. Firmware Update Meta Data Status Report Command

This command is used to advertise the firmware update status.

\requirement{CC:007A.03.07.11.001}{0}

The command MUST be issued when the firmware update is completed or aborted by the device receiving the firmware.

\requirement{CC:007A.03.07.11.002}{0}

A node MUST NOT issue the Firmware Update Meta Data Get Command after receiving a Firmware Update Meta Data Status Report.

Table 3.62 Firmware Update Meta Data Status Report Command version 3

7

6

5

4

3

2

1

0

Command Class = COMMAND_CLASS_FIRMWARE_UPDATE_MD (0x7A)

Command = FIRMWARE_UPDATE_MD_STATUS_REPORT (0x07)

Status

WaitTime MSB

WaitTime LSB

Status (8 bits)

\requirement{CC:007A.03.07.11.003}{0}

This field MUST comply with Table 3.71.

\requirement{CC:007A.03.07.13.001}{0}

The status code 0xFE MAY be used for confirming the successful transfer of images which do not necessitate a restart, e.g. security certificates.

\requirement{CC:007A.03.07.11.004}{0}

The status code 0xFE MUST NOT be advertised after the transfer of an image for the Firmware ID 0 target (the “Z-Wave chip” image).

\requirement{CC:007A.03.07.11.005}{8}

Controlling nodes implementing earlier versions of the Firmware Update Meta Data CC do not support status codes defined for newer versions. Therefore, a node returning the Firmware Update Meta Data Status Report Command MUST comply with the version implemented on the controlling device (device sending the image). The device returning the Firmware Update Meta Data Status Report can identify the version of the controlling device based on the Firmware Update Meta Data Request Get. This may be done as follows:

  • If the Firmware Update Meta Data Request Get does not include Firmware Target and Fragment Size (8 bytes), the controller is version 1 or 2

  • If the Firmware Update Meta Data Request Get includes Firmware Target and Fragment Size but not Activation (11 bytes), the controller is version 3

WaitTime (16 bits)

\requirement{CC:007A.03.07.11.006}{0}

The WaitTime field MUST report the time that is needed before the receiving node again becomes available for communication after the transfer of an image. The unit is the second.

\requirement{CC:007A.03.07.11.007}{0}

The value 0 (zero) MUST indicate that the node is ready (it SHOULD have rebooted if needed and applied the Firmware Image).

The value 0xFFFF is reserved and MUST NOT be returned.

\requirement{CC:007A.03.07.12.001}{0} \requirement{CC:007A.03.07.12.002}{8}

A controlling node receiving this command SHOULD wait for the number of seconds specified in this field before trying to resume communication. When resuming communication, the controlling application SHOULD issue a NOP command and wait for acknowledgement.

\requirement{CC:007A.03.07.13.002}{0} \requirement{CC:007A.03.07.11.008}{4}

The controlling application MAY attempt resuming communication repeatedly. In that case, the NOP interval SHOULD be five seconds and MUST be at least one second.