Application#

Defiunition of the application bootloader interface.

Some functions in this file return an EmberStatus value. See error-def.h for definitions of all EmberStatus return values.

See bootloader-interface-app.h for source code.

Functions#

uint8_t

Call this function as part of your application initialization to ensure the storage mechanism is ready to use. Note: some earlier drivers may assert instead of returning an error if initialization fails.

Call this function to get information about the attached storage device and its capabilities.

void

Call this function when you are done accessing the storage mechanism to ensure that it is returned to its lowest power state.

void

Call this function once before checking for a valid image to reset the call flag.

uint16_t

Reads the app image out of storage, calculates the total file CRC to verify the image is intact.

Invokes the bootloader to install the application in storage. This function resets the device to start the bootloader code and does not return!

uint8_t
halAppBootloaderWriteRawStorage(uint32_t address, const uint8_t *data, uint16_t len)

Writes data to the specified raw storage address and length without being restricted to any page size Note: Not all storage implementations support accesses that are not page aligned, refer to the HalEepromInformationType structure for more information. Note: Some storage devices require contents to be erased before new data can be written, and will return an EEPROM_ERR_ERASE_REQUIRED error if write is called on a location that is not already erased. Refer to the HalEepromInformationType structure to see if the attached storage device requires erasing.

uint8_t
halAppBootloaderReadRawStorage(uint32_t address, uint8_t *data, uint16_t len)

Reads data from the specified raw storage address and length without being restricted to any page size Note: Not all storage implementations support accesses that are not page aligned, refer to the HalEepromInformationType structure for more information.

uint8_t
halAppBootloaderEraseRawStorage(uint32_t address, uint32_t len)

Erases the specified region of the storage device. Note: Most devices require the specified region to be page aligned, and will return an error if an unaligned region is specified. Note: Many devices take an extremely long time to perform an erase operation. When erasing a large region, it may be preferable to make multiple calls to this API so that other application functionality can be performed while the erase is in progress. The halAppBootloaderStorageBusy() API may be used to determine when the last erase operation has completed. Erase timing information can be found in the HalEepromInformationType structure.

bool

Determine if the attached storage device is still busy performing the last operation, such as a write or an erase.

uint8_t
halAppBootloaderReadDownloadSpace(uint16_t pageToBeRead, uint8_t *destRamBuffer)

Converts pageToBeRead to an address and the calls storage read function. Note: This function is deprecated. It has been replaced by halAppBootloaderReadRawStorage()

uint8_t
halAppBootloaderWriteDownloadSpace(uint16_t pageToBeWritten, uint8_t *RamPtr)

Converts pageToBeWritten to an address and calls the storage write function. Note: This function is deprecated. It has been replaced by halAppBootloaderWriteRawStorage()

uint8_t
halAppBootloaderGetImageData(uint32_t *timestamp, uint8_t *userData)

Read the application image data from storage.

uint16_t

Returns the application bootloader version.

uint16_t

Returns the recovery image version.

bool

Return a value indicating whether the app bootloader supports IBRs.

Macros#

#define

This is the working unit of data for the app bootloader. We want it as big as possible, but it must be a factor of the NVM page size and fit into a single Zigbee packet. We choose 2^6 = 64 bytes.

#define
BOOTLOADER_SEGMENT_SIZE (1 << BOOTLOADER_SEGMENT_SIZE_LOG2)

This is the working unit of data for the app bootloader. We want it as big as possible, but it must be a factor of the NVM page size and fit into a single Zigbee packet. We choose 2^6 = 64 bytes.

#define
BL_IMAGE_IS_VALID_CONTINUE ((uint16_t)0xFFFF)

Define a numerical value for checking image validity when calling the image interface functions.

Function Documentation#

halAppBootloaderInit#

uint8_t halAppBootloaderInit (void )

Call this function as part of your application initialization to ensure the storage mechanism is ready to use. Note: some earlier drivers may assert instead of returning an error if initialization fails.

Parameters
N/A

Returns


Definition at line 51 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h

halAppBootloaderInfo#

const HalEepromInformationType* halAppBootloaderInfo (void )

Call this function to get information about the attached storage device and its capabilities.

Parameters
N/A

Returns


Definition at line 59 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h

halAppBootloaderShutdown#

void halAppBootloaderShutdown (void )

Call this function when you are done accessing the storage mechanism to ensure that it is returned to its lowest power state.

Parameters
N/A

Definition at line 64 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h

halAppBootloaderImageIsValidReset#

void halAppBootloaderImageIsValidReset (void )

Call this function once before checking for a valid image to reset the call flag.

Parameters
N/A

Definition at line 69 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h

halAppBootloaderImageIsValid#

uint16_t halAppBootloaderImageIsValid (void )

Reads the app image out of storage, calculates the total file CRC to verify the image is intact.

Parameters
N/A

Caller should loop calling this function while it returns BL_IMAGE_IS_VALID_CONTINUE to get final result. This allows caller to service system needs during validation.

Call halAppBootloaderImageIsValidReset() before calling halAppBootloaderImageIsValid() to reset the call flag.

Here is an example application call:

halAppBootloaderImageIsValidReset();
while ( (pages = halAppBootloaderImageIsValid() ) == BL_IMAGE_IS_VALID_CONTINUE) {
  // make app specific calls here, if any
  emberTick();
}

Returns

  • One of the following:

    • Number of pages in a valid image

    • 0 for an invalid image

    • BL_IMAGE_IS_VALID_CONTINUE (-1) to continue to iterate for the final result.


Definition at line 101 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h

halAppBootloaderInstallNewImage#

EmberStatus halAppBootloaderInstallNewImage (void )

Invokes the bootloader to install the application in storage. This function resets the device to start the bootloader code and does not return!

Parameters
N/A

Definition at line 107 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h

halAppBootloaderWriteRawStorage#

uint8_t halAppBootloaderWriteRawStorage (uint32_t address, const uint8_t * data, uint16_t len)

Writes data to the specified raw storage address and length without being restricted to any page size Note: Not all storage implementations support accesses that are not page aligned, refer to the HalEepromInformationType structure for more information. Note: Some storage devices require contents to be erased before new data can be written, and will return an EEPROM_ERR_ERASE_REQUIRED error if write is called on a location that is not already erased. Refer to the HalEepromInformationType structure to see if the attached storage device requires erasing.

Parameters
N/Aaddress

Address to start writing data

N/Adata

A pointer to the buffer of data to write.

N/Alen

Length of the data to write

Returns


Definition at line 129 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h

halAppBootloaderReadRawStorage#

uint8_t halAppBootloaderReadRawStorage (uint32_t address, uint8_t * data, uint16_t len)

Reads data from the specified raw storage address and length without being restricted to any page size Note: Not all storage implementations support accesses that are not page aligned, refer to the HalEepromInformationType structure for more information.

Parameters
N/Aaddress

Address from which to start reading data

N/Adata

A pointer to a buffer where data should be read into

N/Alen

Length of the data to read

Returns


Definition at line 147 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h

halAppBootloaderEraseRawStorage#

uint8_t halAppBootloaderEraseRawStorage (uint32_t address, uint32_t len)

Erases the specified region of the storage device. Note: Most devices require the specified region to be page aligned, and will return an error if an unaligned region is specified. Note: Many devices take an extremely long time to perform an erase operation. When erasing a large region, it may be preferable to make multiple calls to this API so that other application functionality can be performed while the erase is in progress. The halAppBootloaderStorageBusy() API may be used to determine when the last erase operation has completed. Erase timing information can be found in the HalEepromInformationType structure.

Parameters
N/Aaddress

Address to start erasing

N/Alen

Length of the region to be erased

Returns


Definition at line 166 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h

halAppBootloaderStorageBusy#

bool halAppBootloaderStorageBusy (void )

Determine if the attached storage device is still busy performing the last operation, such as a write or an erase.

Parameters
N/A

Returns

  • true if still busy or false if not.


Definition at line 173 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h

halAppBootloaderReadDownloadSpace#

uint8_t halAppBootloaderReadDownloadSpace (uint16_t pageToBeRead, uint8_t * destRamBuffer)

Converts pageToBeRead to an address and the calls storage read function. Note: This function is deprecated. It has been replaced by halAppBootloaderReadRawStorage()

Parameters
N/ApageToBeRead

pass in the page to be read. This will be converted to the appropriate address. Pages are EEPROM_PAGE_SIZE long.

N/AdestRamBuffer

a pointer to the buffer to write to.

Returns


Definition at line 187 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h

halAppBootloaderWriteDownloadSpace#

uint8_t halAppBootloaderWriteDownloadSpace (uint16_t pageToBeWritten, uint8_t * RamPtr)

Converts pageToBeWritten to an address and calls the storage write function. Note: This function is deprecated. It has been replaced by halAppBootloaderWriteRawStorage()

Parameters
N/ApageToBeWritten

pass in the page to be written. This will be converted to the appropriate address. Pages are EEPROM_PAGE_SIZE long.

N/ARamPtr

a pointer to the data to be written.

Returns


Definition at line 202 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h

halAppBootloaderGetImageData#

uint8_t halAppBootloaderGetImageData (uint32_t * timestamp, uint8_t * userData)

Read the application image data from storage.

Parameters
N/Atimestamp

write the image timestamp to this data pointer.

N/AuserData

write the user data field to this buffer.

Returns


Definition at line 213 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h

halAppBootloaderGetVersion#

uint16_t halAppBootloaderGetVersion (void )

Returns the application bootloader version.

Parameters
N/A

Definition at line 217 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h

halAppBootloaderGetRecoveryVersion#

uint16_t halAppBootloaderGetRecoveryVersion (void )

Returns the recovery image version.

Parameters
N/A

Definition at line 221 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h

halAppBootloaderSupportsIbr#

bool halAppBootloaderSupportsIbr (void )

Return a value indicating whether the app bootloader supports IBRs.

Parameters
N/A

Returns

  • true if the app bootloader supports IBRs, false otherwise


Definition at line 227 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h

Macro Definition Documentation#

BOOTLOADER_SEGMENT_SIZE_LOG2#

#define BOOTLOADER_SEGMENT_SIZE_LOG2
Value:
6

This is the working unit of data for the app bootloader. We want it as big as possible, but it must be a factor of the NVM page size and fit into a single Zigbee packet. We choose 2^6 = 64 bytes.


Definition at line 36 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h

BOOTLOADER_SEGMENT_SIZE#

#define BOOTLOADER_SEGMENT_SIZE
Value:
(1 << BOOTLOADER_SEGMENT_SIZE_LOG2)

This is the working unit of data for the app bootloader. We want it as big as possible, but it must be a factor of the NVM page size and fit into a single Zigbee packet. We choose 2^6 = 64 bytes.


Definition at line 42 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h

BL_IMAGE_IS_VALID_CONTINUE#

#define BL_IMAGE_IS_VALID_CONTINUE
Value:
((uint16_t)0xFFFF)

Define a numerical value for checking image validity when calling the image interface functions.


Definition at line 74 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface-app.h