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

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().

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().

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

Type	Direction	Argument Name	Description
uint16_t	N/A	fwId	ID of the firmware.
uint16_t	N/A	CRC	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.

CC_FirmwareUpdate_SetFinishCallback#

void CC_FirmwareUpdate_SetFinishCallback (OTA_STATUS pOtaFinish)

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

Parameters

Type	Direction	Argument Name	Description
OTA_STATUS	N/A	pOtaFinish	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.

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

Type	Direction	Argument Name	Description
CC_FirmwareUpdate_start_callback_t	[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.
CC_FirmwareUpdate_finish_callback_t	[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.
bool	[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.

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

Type	Direction	Argument Name	Description
transmission_result_t *	N/A	pTxResult	: TRANSMIT_COMPLETE_OK, TRANSMIT_COMPLETE_NO_ACK, TRANSMIT_COMPLETE_FAIL...

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

Type	Direction	Argument Name	Description
ZW_FIRMWARE_UPDATE_ACTIVATION_SET_V5_FRAME *	N/A	pFrame	The Activation Set frame.
uint8_t *	N/A	pStatus	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.

handleCommandClassFirmwareUpdateMaxFragmentSize#

uint16_t handleCommandClassFirmwareUpdateMaxFragmentSize (void )

Returns the maximum fragment size.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns

Maximum fragment size.

getFWUpdateMDGetNumberOfReports#

uint8_t getFWUpdateMDGetNumberOfReports (void )

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

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns

Number of Reports, greater of equal to 1.

handleFirmWareIdGetExtended#

uint16_t handleFirmWareIdGetExtended (uint8_t n)

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

Parameters

Type	Direction	Argument Name	Description
uint8_t	[in]	n	the target index (0,1..N-1)

Returns

target n firmware ID

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

Type	Direction	Argument Name	Description
RECEIVE_OPTIONS_TYPE_EX *	[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.
ZW_FIRMWARE_UPDATE_MD_REQUEST_GET_V5_FRAME *	[in]	pFrame	Pointer to the Firmware Update MD Request Get frame.
uint8_t	[in]	cmdLength	Length of the frame.
uint8_t *	[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

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

Type	Direction	Argument Name
uint16_t	N/A	crc16Result
uint16_t	N/A	firmwareUpdateReportNumber
uint8_t	N/A	properties
uint8_t *	N/A	pData
uint8_t	N/A	fw_actualFrameSize