Using the Gecko Application Bootloader#

Acquiring a New Image#

The application bootloader relies on application code to obtain new code images. The bootloader itself only knows how to read a GBL image stored in the download space and copy the relevant portions to the main flash block. This approach means that the application developer is free to acquire the new code image in any way that makes sense (serial, OTA, and so on).

Typically, application developers choose to acquire the new code image over-the-air (OTA) since this is readily available on all devices. For OTA bootloading in Zigbee networks, Silicon Labs recommends using the standard OTA Upgrade cluster defined in the Zigbee Cluster Library (ZCL). Code for this cluster is available in the Silicon Labs Zigbee application framework as several different components. AN728: Over-the-Air Bootload Server and Client Setup walks through how this can be set up and run in SDK versions 6.10.0 and lower and AN1384: Over-the-Air Bootload Server and Client Setup for Zigbee SDK 7.0 and Higher provides the same information for more recent versions. For OTA bootloading in non-Zigbee networks where a ZCL-based application layer is not available, the application layer may define its own means of conveying firmware data over the networking protocol, or the application developer may define a proprietary means of accomplishing an OTA image transfer between a source device and a target.

For customers who want to design their own application to acquire an image rather than using the Silicon Labs Zigbee application framework's components, routines for interfacing with the download space are provided. These routines allow you to get information about the storage device and interact with it. Code and documentation for these routines are in the source files bootloader-interface-app.c and bootloader-interface-app.h in the platform/service/legacy_hal directory. If you do want to call these routines directly, it may be helpful to look at how the OTA Cluster Platform Bootloader component code works to ensure that these routines are used correctly. (See related files in the app/framework/plugin/ota-bootload directory of the EmberZNet PRO installation for more information.)

Performing an Application Upgrade#

The application and the bootloader have limited indirect contact. Their only interaction is through passing non-volatile data across module reboots.

Once the application decides to install a new image saved in the download space it calls the Ember HAL API halAppBootloaderInstallNewImage(). This call indicates to the bootloader that it should attempt to perform a firmware upgrade from storage slot 0, and reboots the device. This API is backwards-compatible with the legacy Ember bootloader. If performing a firmware upgrade from a different storage slot than slot 0 is desired, the Gecko Bootloader API should be used instead, by calling bootloader_setBootloadList(). If the bootloader fails to install the new image, it sets the reset cause to RESET_BOOTLOADER_BADIMAGE and resets the module. Upon startup, the application should read the reset cause with halGetExtendedResetInfo(). If the reset cause is set to RESET_BOOTLOADER_BADIMAGE, the application knows the install process failed and can attempt to obtain a new image. A printable error string can be acquired by calling halGetExtendedResetString(). Under normal circumstances, the application bootloader does not print anything on the serial line.

Example Application Bootload#

For details on how to set up and run an application bootload, see AN1384: Over-the-Air Bootload Server and Client Setup for Zigbee SDK 7.0 and Higher. If you are using an earlier version, see AN728: Over-the-Air Bootload Server and Client Setup.

External Storage Application Bootloader#

See the Silicon Labs Gecko Bootloader User’s Guide for your GSDK version for information about memory configuration for external storage bootloaders. Note that, at the time of this writing, the OTA Simple Storage Module component code in the EmberZNet stack only supports storage configurations with a single storage slot. The start address of the storage slot in the bootloader needs to be configured to the same value as the OTA Storage Start Offset of the OTA Simple Storage EEPROM Driver component in the Silicon Labs Zigbee application framework. The application developer is responsible for ensuring that this value is consistent across the stack and bootloader projects. Also, keep in mind that the start address of the first storage slot in the bootloader should be offset from the beginning of the storage area by two times the page size of the underlying storage medium if more than one storage slot is configured.

Application bootloaders typically use a remote device to store the downloaded application image. This device can be accessed over either an I2C or SPI serial interface. Refer to the Silicon Labs Gecko Bootloader User’s Guide for your GSDK version for a list of supported dataflash/EEPROM devices. It is important to select a device whose size is at least the size of your flash in order to fit the application image being used by the bootloader.

The default recommendation for external SPI serial flash is the MX25R, as this is available in standard and smaller packages, is supported by standard drivers, and has very low software-enabled sleep current without the need for an external shutdown control circuit. Most radio boards from Silicon Labs are populated with the MX25R8035F for evaluation purposes. In general, customers should use parts that have low sleep current, don't require external shutdown control circuitry, and have software shutdown control. When using components with high idle/sleep current and no software shutdown control, an external shutdown control circuit is recommended to reduce sleep current.

For EFR32MG-based devices using the EFR32MG1, only the serial dataflash option is available; no local storage application bootloader is presently offered. However, some EFR32MG ICs contain an integrated serial flash that can be utilized just like off-chip serial dataflash but without any additional components. EFR32MG-based devices using the EFR32MG12 and higher platforms support local storage application bootloaders.

Note that some of these chips have compatible pinouts with others, but there are several incompatible variations. Contact Silicon Labs for details on connecting I2C or other SPI dataflash chips to an EFR32.

Read-Modify-Write pertains to a feature of certain dataflash chips that their corresponding driver exposes, and that is exploited by the bootloader library. Chips without this feature require a page erase to be performed before writing to that page, which precludes random-access writes by an application. When using the Silicon Labs Zigbee application framework, the OTA Simple Storage EEPROM Driver component needs to be configured to take this into consideration.

Local Storage Application Bootloader#

The local storage bootloader is essentially an application bootloader with a dataflash driver that uses a portion of the on-chip flash for image storage instead of an external storage chip. See the Silicon Labs Gecko Bootloader User’s Guide for your GSDK version for information about memory configuration for internal storage. Note that the OTA Simple Storage Module component code in the EmberZNet stack only supports storage configurations with a single storage slot at the time of this writing. The start address of the storage slot in the bootloader needs to be configured to the same value as the OTA Storage Start Offset of the OTA Simple Storage EEPROM component in the Silicon Labs Zigbee application framework. The application developer is responsible for ensuring that this value is consistent across the stack and bootloader projects. Also, keep in mind that the start address of the first storage slot in the bootloader should be offset from the beginning of the storage area by two times the page size of the underlying storage medium if more than one storage slot is configured.

Since the local storage application bootloader changes the chip’s flash memory layout you must build your application with knowledge of this. To accomplish this, the LOCAL_STORAGE_BTL global define must be in your project file. In Ember Zigbee SDK v6.10.x and lower, this is done for you when you select Local Storage from AppBuilder's bootloader dropdown. In SDK v7.0 and higher, local storage is set as the default.

Note: On EFR32 Series 2 devices, the application is offset by 16 kB to accommodate the bootloader at the bottom of main flash. On other Series 1 EFR32 devices, the Gecko Bootloader resides in the bootloader flash region outside of main flash block.