Defines a platform abstraction layer for the Z-Wave bootloader. More...

Collaboration diagram for Zpal-bootloader:

Topics
	Zpal-bootloader-info-version

Data Structures
struct	zpal_bootloader_info_t
	Information about the current bootloader. More...

Macros
#define	ZPAL_BOOTLOADER_CAPABILITY_STORAGE (1 << 0)
	Bootloader has the capability of storing data in an internal or external storage medium.

Enumerations
enum	zpal_bootloader_type_t { ZPAL_BOOTLOADER_NOT_PRESENT = 0 , ZPAL_BOOTLOADER_PRESENT = 1 }
	Type of bootloader. More...

Functions
void	zpal_bootloader_get_info (zpal_bootloader_info_t *info)
	Get information about the bootloader on this device. The information returned is fetched from the main bootloader information table.
zpal_status_t	zpal_bootloader_init (void)
	Initialize components of the bootloader so the app can use the interface. This typically includes initializing serial peripherals for communication with external SPI flashes, and so on.
void	zpal_bootloader_reboot_and_install (void)
	Reboot into the bootloader to install something. If there is a storage component and a slot is marked for bootload, install the image in that slot after verifying it. If a communication component is present, open the communication channel and receive an image to be installed.
zpal_status_t	zpal_bootloader_verify_image (void)
	Verify that the image is valid.
zpal_status_t	zpal_bootloader_write_data (uint32_t offset, uint8_t *data, uint16_t length)
	Writes a fragment of a firmware image to the bootloader storage.
bool	zpal_bootloader_is_first_boot (bool *updated_successfully)
	Returns whether the software is running on the first boot after a new firmware image was written.
zpal_status_t	zpal_bootloader_get_status (void)
	Returns the status of the bootloader's latest attempt to upgrade the application.
void	zpal_bootloader_reset_page_counters (void)
	Resets the bootloader page counters. Used when initiating an upgrade to jump back to the start of the storage slot.

Detailed Description

Defines a platform abstraction layer for the Z-Wave bootloader.

How to use the bootloader API

The ZPAL bootloader API is required if an application would like to store and use a new firmware image.

zpal_bootloader_init() and zpal_bootloader_get_info() must be implemented as Z-Wave always invokes these. The remaining API functions are optional in case a bootloader is not present in the ZPAL implementation.

The following outlines an example of use:

To enable the bootloader functionality, invoke zpal_bootloader_init().
zpal_bootloader_get_info() must be invoked to check whether a bootloader is present.
For every received fragment, zpal_bootloader_write_data() must be invoked to store the new firmware image.
When all fragments are received, zpal_bootloader_verify_image() must be invoked to verify the integrity of the received firmware image.
If the received firmware image is valid, invoke zpal_bootloader_reboot_and_install() install and boot from the new firmware image.

Requirements:

The ZPAL bootloader requires that a storage is available for storing a received firmware image. Z-Wave has no requirements on how and where the image is stored.

Macro Definition Documentation

◆ ZPAL_BOOTLOADER_CAPABILITY_STORAGE

#define ZPAL_BOOTLOADER_CAPABILITY_STORAGE (1 << 0)

Bootloader has the capability of storing data in an internal or external storage medium.

Enumeration Type Documentation

◆ zpal_bootloader_type_t

enum zpal_bootloader_type_t

Type of bootloader.

Enumerator
ZPAL_BOOTLOADER_NOT_PRESENT	No bootloader present.
ZPAL_BOOTLOADER_PRESENT	Bootloader present.

Function Documentation

◆ zpal_bootloader_get_info()

void zpal_bootloader_get_info ( zpal_bootloader_info_t * info )

Get information about the bootloader on this device. The information returned is fetched from the main bootloader information table.

//zpal-bootloader-info-version

Parameters

[out] info Pointer to the bootloader information struct.

◆ zpal_bootloader_get_status()

zpal_status_t zpal_bootloader_get_status ( void )

Returns the status of the bootloader's latest attempt to upgrade the application.

This status can only be considered valid if a previous call to zpal_bootloader_is_first_boot() returned true.

Returns: One of the values from zpal_status_t indicating the status of the firmware update.

Return values

ZPAL_STATUS_BOOTLOADER_INVALID_CHECKSUM	The checksum of the firmware image is invalid.
ZPAL_STATUS_BOOTLOADER_UNABLE_TO_DECRYPT	The bootloader was unable to decrypt the firmware image.
ZPAL_STATUS_BOOTLOADER_DOWNGRADE_NOT_SUPPORTED	The version of the new firmware image is less than or equal to the current firmware image.
ZPAL_STATUS_BOOTLOADER_INVALID_SIGNATURE	The signature of the new firmware image is invalid.
ZPAL_STATUS_BOOTLOADER_DECOMPRESSION_FAILED	The bootloader failed to decompress the new firmware image.

◆ zpal_bootloader_init()

zpal_status_t zpal_bootloader_init ( void )

Initialize components of the bootloader so the app can use the interface. This typically includes initializing serial peripherals for communication with external SPI flashes, and so on.

Returns: Error code. ZPAL_STATUS_OK on success, else ZPAL_STATUS_FAIL

◆ zpal_bootloader_is_first_boot()

bool zpal_bootloader_is_first_boot ( bool * updated_successfully )

Returns whether the software is running on the first boot after a new firmware image was written.

Parameters

[in] updated_successfully Set to true if update was successful, false otherwise. Valid only when it's the first boot.

Returns: True if it's the first boot, false otherwise.

◆ zpal_bootloader_reboot_and_install()

void zpal_bootloader_reboot_and_install ( void )

Reboot into the bootloader to install something. If there is a storage component and a slot is marked for bootload, install the image in that slot after verifying it. If a communication component is present, open the communication channel and receive an image to be installed.

◆ zpal_bootloader_reset_page_counters()

void zpal_bootloader_reset_page_counters ( void )

Resets the bootloader page counters. Used when initiating an upgrade to jump back to the start of the storage slot.

◆ zpal_bootloader_verify_image()

zpal_status_t zpal_bootloader_verify_image ( void )

Verify that the image is valid.

Returns: ZPAL_STATUS_OK if the image is valid, else ZPAL_STATUS_FAIL.

◆ zpal_bootloader_write_data()

zpal_status_t zpal_bootloader_write_data	(	uint32_t	offset,
		uint8_t *	data,
		uint16_t	length )

Writes a fragment of a firmware image to the bootloader storage.

Parameters

[in]	offset	Offset from the storage start.
[in]	data	Pointer to fragment of firmware image.
[in]	length	Length of firmware image fragment.

Returns: ZPAL_STATUS_OK on success, and ZPAL_STATUS_FAIL otherwise.

Trident IoT Z-Wave SDK

Topics

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ ZPAL_BOOTLOADER_CAPABILITY_STORAGE

Enumeration Type Documentation

◆ zpal_bootloader_type_t

Function Documentation

◆ zpal_bootloader_get_info()

◆ zpal_bootloader_get_status()

◆ zpal_bootloader_init()

◆ zpal_bootloader_is_first_boot()

◆ zpal_bootloader_reboot_and_install()

◆ zpal_bootloader_reset_page_counters()

◆ zpal_bootloader_verify_image()

◆ zpal_bootloader_write_data()