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:

  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.

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.


Definition at line 56 of file /mnt/raid/workspaces/ws.WH1KakGoP/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_bootloader.h

Function Documentation#

zpal_bootloader_get_info#

void zpal_bootloader_get_info (zpal_bootloader_info_t * info)

//zpal-bootloader-info-version

Parameters
[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.


Definition at line 116 of file /mnt/raid/workspaces/ws.WH1KakGoP/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_bootloader.h

zpal_bootloader_init#

zpal_status_t zpal_bootloader_init (void )

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

Parameters
N/A

This typically includes initializing serial peripherals for communication with external SPI flashes, and so on.

Returns


Definition at line 125 of file /mnt/raid/workspaces/ws.WH1KakGoP/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_bootloader.h

zpal_bootloader_reboot_and_install#

void zpal_bootloader_reboot_and_install (void )

Reboot into the bootloader to install something.

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


Definition at line 134 of file /mnt/raid/workspaces/ws.WH1KakGoP/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_bootloader.h

zpal_bootloader_verify_image#

zpal_status_t zpal_bootloader_verify_image (void )

Verify that the image is valid.

Parameters
N/A

Returns


Definition at line 141 of file /mnt/raid/workspaces/ws.WH1KakGoP/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_bootloader.h

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


Definition at line 151 of file /mnt/raid/workspaces/ws.WH1KakGoP/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_bootloader.h

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.


Definition at line 159 of file /mnt/raid/workspaces/ws.WH1KakGoP/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_bootloader.h

zpal_bootloader_reset_page_counters#

void zpal_bootloader_reset_page_counters (void )

Resets the bootloader page counters.

Parameters
N/A

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


Definition at line 165 of file /mnt/raid/workspaces/ws.WH1KakGoP/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_bootloader.h

Macro Definition Documentation#

ZPAL_BOOTLOADER_CAPABILITY_STORAGE#

#define ZPAL_BOOTLOADER_CAPABILITY_STORAGE
Value:
(1 << 0)

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


Definition at line 75 of file /mnt/raid/workspaces/ws.WH1KakGoP/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_bootloader.h