Firmware Update Meta Data#

Command Class Firmware Update Meta Data enables a device to have its firmware updated remotely.

CC Firmware Update MD can be configured in cc_firmware_update_config.h.

This CC offers the option to define two functions in the application that will override the weak implementations:

The specification of CC Firmware Update MD can be found in https://github.com/Z-Wave-Alliance/AWG/tree/main/source/management_command_classes/command_class_definitions

Enumerations#

enum
OTA_STATUS {
OTA_STATUS_DONE = 0
OTA_STATUS_ABORT = 1
OTA_STATUS_TIMEOUT = 2
}

enum type OTA_STATUS use to

Typedefs#

typedef bool(*
CC_FirmwareUpdate_start_callback_t)(uint16_t fwId, uint16_t CRC)

Please see description of CC_FirmwareUpdate_Init().

typedef void(*
CC_FirmwareUpdate_finish_callback_t)(OTA_STATUS status)

Please see description of CC_FirmwareUpdate_Init().

Functions#

bool
CC_FirmwareUpdate_SetStartCallback(uint16_t fwId, uint16_t CRC)

Invoked when another node initiates a firmware update of this device.

void
CC_FirmwareUpdate_SetFinishCallback(OTA_STATUS pOtaFinish)

Invoked when the firmware update process finishes either successfully or with an error.

bool
CC_FirmwareUpdate_Init(CC_FirmwareUpdate_start_callback_t pOtaStart, CC_FirmwareUpdate_finish_callback_t pOtaFinish, bool support_activation)

Initializes the Firmware Update Meta Data Command Class.

void
ZCB_CmdClassFwUpdateMdReqReport(transmission_result_t *pTxResult)

ZCB_CmdClassFwUpdateMdReqReport Callback function receive status on Send data FIRMWARE_UPDATE_MD_REQUEST_REPORT_V3.

bool
CC_FirmwareUpdate_ActivationSet_handler(ZW_FIRMWARE_UPDATE_ACTIVATION_SET_V5_FRAME *pFrame, uint8_t *pStatus)

Handles an Activation Set command.

uint16_t
handleCommandClassFirmwareUpdateMaxFragmentSize(void)

Returns the maximum fragment size.

uint8_t
getFWUpdateMDGetNumberOfReports(void)

Gets maximum number of reports that can be sent in FW Update MD Get.

uint16_t
handleFirmWareIdGetExtended(uint8_t n)

This function returns a firmware ID based on a given target index.

void
handleCmdClassFirmwareUpdateMdReqGet(RECEIVE_OPTIONS_TYPE_EX *rxOpt, ZW_FIRMWARE_UPDATE_MD_REQUEST_GET_V5_FRAME *pFrame, uint8_t cmdLength, uint8_t *pStatus)

Initiates a firmware update.

void
handleCmdClassFirmwareUpdateMdReport(uint16_t crc16Result, uint16_t firmwareUpdateReportNumber, uint8_t properties, uint8_t *pData, uint8_t fw_actualFrameSize)

handleCmdClassFirmwareUpdateMdReport Application function to handle incoming frame Firmware update MD Report

Macros#

#define
WAITTIME_FWU_FAIL 2

Defines for WaitTime field used in commmand = FIRMWARE_UPDATE_MD_STATUS_REPORT.

Enumeration Documentation#

OTA_STATUS#

OTA_STATUS

enum type OTA_STATUS use to

Enumerator
OTA_STATUS_DONE
OTA_STATUS_ABORT
OTA_STATUS_TIMEOUT

Definition at line 52 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/FirmwareUpdate/inc/CC_FirmwareUpdate.h

Typedef Documentation#

CC_FirmwareUpdate_start_callback_t#

typedef bool(* CC_FirmwareUpdate_start_callback_t) (uint16_t fwId, uint16_t CRC) )(uint16_t fwId, uint16_t CRC)

Please see description of CC_FirmwareUpdate_Init().


Definition at line 44 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/FirmwareUpdate/src/ota_util.h

CC_FirmwareUpdate_finish_callback_t#

typedef void(* CC_FirmwareUpdate_finish_callback_t) (OTA_STATUS status) )(OTA_STATUS status)

Please see description of CC_FirmwareUpdate_Init().


Definition at line 50 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/FirmwareUpdate/src/ota_util.h

Function Documentation#

CC_FirmwareUpdate_SetStartCallback#

bool CC_FirmwareUpdate_SetStartCallback (uint16_t fwId, uint16_t CRC)

Invoked when another node initiates a firmware update of this device.

Parameters
N/AfwId

ID of the firmware.

N/ACRC

CRC of the firmware.

If the function returns true, the process will continue. If the function returns false, the node will report to the initiator that the firmware update requires authentication.

The function must take two arguments where the first one is the firmware ID and the second one is the CRC value of the firmware.

Note

  • This function is weakly defined to return true, but can be defined by the application if desired.

Returns

  • Return true to continue the firmware update process and false to cancel it.


Definition at line 75 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/FirmwareUpdate/inc/CC_FirmwareUpdate.h

CC_FirmwareUpdate_SetFinishCallback#

void CC_FirmwareUpdate_SetFinishCallback (OTA_STATUS pOtaFinish)

Invoked when the firmware update process finishes either successfully or with an error.

Parameters
N/ApOtaFinish

Status of the firmware update.

If the device reboots right after the firmware update, the function is invoked before the reboot.

The function must take an argument that is the status of the firmware update.

Note

  • This function is weakly defined to do nothing and can be defined by the application if desired.


Definition at line 89 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/FirmwareUpdate/inc/CC_FirmwareUpdate.h

CC_FirmwareUpdate_Init#

bool CC_FirmwareUpdate_Init (CC_FirmwareUpdate_start_callback_t pOtaStart, CC_FirmwareUpdate_finish_callback_t pOtaFinish, bool support_activation)

Initializes the Firmware Update Meta Data Command Class.

Parameters
[in]pOtaStart

Pointer to a function that is invoked when another node initiates a firmware update. If the function returns true, the process will continue. If the function returns false, the node will report to the initiator that the firmware update requires authentication. The function must take two arguments where the first one is the firmware ID and the second one is the CRC value of the firmware. The argument is not required and can be set to NULL. In that case the firmware update process will continue without invoking the function.

[in]pOtaFinish

Pointer to a function that is invoked when the firmware update process finishes either successfully or with an error. If the device reboots right after the firmware update, the function is invoked before the reboot. The function must take an argument that is the status of the firmware update. The argument is not required and can be set to NULL.

[in]support_activation

Lets the application decide whether delayed activation of the firmware is supported. If set to true and the Activation bit in Request Get is set to 1, the node will not reboot to the new firmware image, but will instead wait for an Activation Set command.

This function must be invoked before a firmware update can be initiated.

Returns

  • 1 if NVM is supported else 0.


Definition at line 81 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/FirmwareUpdate/src/ota_util.h

ZCB_CmdClassFwUpdateMdReqReport#

void ZCB_CmdClassFwUpdateMdReqReport (transmission_result_t * pTxResult)

ZCB_CmdClassFwUpdateMdReqReport Callback function receive status on Send data FIRMWARE_UPDATE_MD_REQUEST_REPORT_V3.

Parameters
N/ApTxResult

: TRANSMIT_COMPLETE_OK, TRANSMIT_COMPLETE_NO_ACK, TRANSMIT_COMPLETE_FAIL...


Definition at line 92 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/FirmwareUpdate/src/ota_util.h

CC_FirmwareUpdate_ActivationSet_handler#

bool CC_FirmwareUpdate_ActivationSet_handler (ZW_FIRMWARE_UPDATE_ACTIVATION_SET_V5_FRAME * pFrame, uint8_t * pStatus)

Handles an Activation Set command.

Parameters
N/ApFrame

The Activation Set frame.

N/ApStatus

Status if the activation failed.

If the fields in the frame match the firmware that is ready to be activated, the device will reboot into the new image and transmit an Activation Report. If the fields do not match, the function will return false. Returns

  • Returns false if the received values do not match with the stored firmware image. If they match, the function will not return, but the device will reboot from the new image.


Definition at line 106 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/FirmwareUpdate/src/ota_util.h

handleCommandClassFirmwareUpdateMaxFragmentSize#

uint16_t handleCommandClassFirmwareUpdateMaxFragmentSize (void )

Returns the maximum fragment size.

Parameters
N/A

Returns

  • Maximum fragment size.


Definition at line 115 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/FirmwareUpdate/src/ota_util.h

getFWUpdateMDGetNumberOfReports#

uint8_t getFWUpdateMDGetNumberOfReports (void )

Gets maximum number of reports that can be sent in FW Update MD Get.

Parameters
N/A

Returns

  • Number of Reports, greater of equal to 1.


Definition at line 122 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/FirmwareUpdate/src/ota_util.h

handleFirmWareIdGetExtended#

uint16_t handleFirmWareIdGetExtended (uint8_t n)

This function returns a firmware ID based on a given target index.

Parameters
[in]n

the target index (0,1..N-1)

Returns

  • target n firmware ID


Definition at line 131 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/FirmwareUpdate/src/ota_util.h

handleCmdClassFirmwareUpdateMdReqGet#

void handleCmdClassFirmwareUpdateMdReqGet (RECEIVE_OPTIONS_TYPE_EX * rxOpt, ZW_FIRMWARE_UPDATE_MD_REQUEST_GET_V5_FRAME * pFrame, uint8_t cmdLength, uint8_t * pStatus)

Initiates a firmware update.

Parameters
[in]rxOpt

The options that the Firmware Update MD Request Get was received with. The options must be passed because they are used later when sending a status report.

[in]pFrame

Pointer to the Firmware Update MD Request Get frame.

[in]cmdLength

Length of the frame.

[out]pStatus

Pointer to a value where the status of the initiation can be written. The status can take one of the following values: FIRMWARE_UPDATE_MD_REQUEST_REPORT_INVALID_COMBINATION_V5, FIRMWARE_UPDATE_MD_REQUEST_REPORT_REQUIRES_AUTHENTICATION_V5, FIRMWARE_UPDATE_MD_REQUEST_REPORT_INVALID_FRAGMENT_SIZE_V5, FIRMWARE_UPDATE_MD_REQUEST_REPORT_NOT_UPGRADABLE_V5, FIRMWARE_UPDATE_MD_REQUEST_REPORT_INVALID_HARDWARE_VERSION_V5, or FIRMWARE_UPDATE_MD_REQUEST_REPORT_VALID_COMBINATION_V5


Definition at line 150 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/FirmwareUpdate/src/ota_util.h

handleCmdClassFirmwareUpdateMdReport#

void handleCmdClassFirmwareUpdateMdReport (uint16_t crc16Result, uint16_t firmwareUpdateReportNumber, uint8_t properties, uint8_t * pData, uint8_t fw_actualFrameSize)

handleCmdClassFirmwareUpdateMdReport Application function to handle incoming frame Firmware update MD Report

Parameters
N/Acrc16Result
N/AfirmwareUpdateReportNumber
N/Aproperties
N/ApData
N/Afw_actualFrameSize

Definition at line 167 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/FirmwareUpdate/src/ota_util.h

Macro Definition Documentation#

WAITTIME_FWU_FAIL#

#define WAITTIME_FWU_FAIL
Value:
2

Defines for WaitTime field used in commmand = FIRMWARE_UPDATE_MD_STATUS_REPORT.

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.


Definition at line 37 of file /mnt/raid/workspaces/ws.H9QSi59DS/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/FirmwareUpdate/src/ota_util.h