Zpal-bootloader

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.
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:

1. To enable the bootloader functionality, invoke zpal_bootloader_init().
2. zpal_bootloader_get_info() must be invoked to check whether a bootloader is present.
3. For every received fragment, zpal_bootloader_write_data() must be invoked to store the new firmware image.
4. When all fragments are received, zpal_bootloader_verify_image() must be invoked to verify the integrity of the received firmware image.
5. 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_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.