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.

zpal_status_t

zpal_bootloader_erase_storage_slot(void)

Erases the storage slot used by the bootloader.

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.

zpal_bootloader_erase_storage_slot#

zpal_status_t zpal_bootloader_erase_storage_slot (void )

Erases the storage slot used by the bootloader.

Parameters

Type	Direction	Argument Name	Description
void	N/A

This function erases the designated storage slot, typically used for storing firmware images or other data required by the bootloader. After erasure, the storage slot will be empty and ready for new data to be written.

Returns

zpal_status_t Returns a status code indicating the result of the operation. Possible values include:
- ZPAL_STATUS_OK: The storage slot was successfully erased.
- ZPAL_STATUS_ERROR: An error occurred during the erase operation.