Zpal-bootloader#

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.

Modules#

zpal_bootloader_info_t

Zpal-bootloader-info-version

Enumerations#

enum

zpal_bootloader_type_t {

ZPAL_BOOTLOADER_NOT_PRESENT = 0

ZPAL_BOOTLOADER_PRESENT = 1

}

Type of bootloader.

Functions#

void

zpal_bootloader_get_info(zpal_bootloader_info_t *info)

//zpal-bootloader-info-version

zpal_status_t

zpal_bootloader_init(void)

Initialize components of the bootloader so the app can use the interface.

void

zpal_bootloader_reboot_and_install(void)

Reboot into the bootloader to install something.

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.

void

zpal_bootloader_reset_page_counters(void)

Resets the bootloader page counters.

Macros#

#define

ZPAL_BOOTLOADER_CAPABILITY_STORAGE (1 << 0)

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

Enumeration Documentation#

zpal_bootloader_type_t#

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)

//zpal-bootloader-info-version

Parameters

Type	Direction	Argument Name	Description
zpal_bootloader_info_t *	[out]	info	Pointer to the bootloader information struct.

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

zpal_bootloader_init#

zpal_status_t zpal_bootloader_init (void )

Initialize components of the bootloader so the app can use the interface.

Parameters

Type	Direction	Argument Name	Description
void	N/A

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_reboot_and_install#

void zpal_bootloader_reboot_and_install (void )

Reboot into the bootloader to install something.

Parameters

Type	Direction	Argument Name	Description
void	N/A

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_verify_image#

zpal_status_t zpal_bootloader_verify_image (void )

Verify that the image is valid.

Parameters

Type	Direction	Argument Name	Description
void	N/A

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

Type	Direction	Argument Name	Description
uint32_t	[in]	offset	Offset from the storage start.
uint8_t *	[in]	data	Pointer to fragment of firmware image.
uint16_t	[in]	length	Length of firmware image fragment.

Returns

ZPAL_STATUS_OK on success, and ZPAL_STATUS_FAIL otherwise.

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

Type	Direction	Argument Name	Description
bool *	[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_reset_page_counters#

void zpal_bootloader_reset_page_counters (void )

Resets the bootloader page counters.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Used when initiating an upgrade to jump back to the start of the storage slot.