Upgrading Gecko Bootloader#

Introduction#

Gecko Bootloader consists of two stages:

The first stage is a dummy stage. It can only start the second stage and it can overwrite the second stage with an already uploaded upgrade image. The first stage can only be flashed to the device and can't be upgraded.
The second stage starts the application and it can upgrade the application in several ways, such as using UART, SPI, Bluetooth, and so on. It has other features as well, such as handling multiple storage slots, verifying images, and so on. The second stage can be upgraded, in case you want to add a new feature, apply a security patch or change configuration.

Upgrading Using UART#

This section describes upgrading the second stage by using UART and the BGAPI UART DFU type Gecko Bootloader.

First, flash both the first and the second stage of the bootloader to your device. To flash the first and second stage bootloader with a Bluetooth application, follow the steps described in Adding Gecko Bootloader to Bluetooth Projects.

If you have already flashed the bootloader, the second stage can be upgraded in three steps:

Upload new second stage image in the device (it will be put to a predefined address).
Reset the device -> the first stage will overwrite the second stage with the new image.
Upload the application again because some part of it may have been corrupted when the second stage image was uploaded.

Follow these steps to upgrade the second stage:

Create a new bootloader project to upgrade to.
The bootloader can only be upgraded and not downgraded. As a result, increment the version number up with every upgrade. If you want to upload the same bootloader version with another configuration, increase BOOTLOADER_VERSION_MAIN_CUSTOMER. Find the "Other" tab in the AppBuilder of the Bootloader project (opening .isc file), and add BOOTLOADER_VERSION_MAIN_CUSTOMER to the defines. Define a value greater than 0 and increment it with every upgrade.
Generate and build the bootloader project.
Create a bootloader upgrade file (.gbl) from the .s37 output file (*). For example,
```
commander gbl create bootloader.gbl --bootloader bootloader-uart-bgapi.s37
```
Use the .s37 file which does not end with "–combined”. The combined image contains first and second stage, but only the second stage is needed at this point.
Upload the upgrade image. For example, if you have an BGAPI UART DFU type bootloader, use the uart-dfu application (**) to do this:
```
uart-dfu COMn 115200 bootloader.gbl
```
The bootloader image temporarily overwrites the application image, hence you have to upload the application again.
Build your Bluetooth application.
Create an application upgrade file (.gbl) from the .s37 output file, as described in Note 1 below. For example,
```
commander gbl create application.gbl --app my_bluetooth_project.s37
```
Upload the upgrade image. For example, if the upgraded bootloader is an BGAPI UART DFU type bootloader, use the uart-dfu application (as described in Note 2 below) to do this:
```
uart-dfu COMn 115200 application.gbl
```

Now your bootloader is upgraded and your application is restored.

Note: (1) commander.exe can be found under C:\SiliconLabs\SimplicityStudio\vX\developer\adapter_packs\commander (2) uart-dfu.exe can be found under C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.x\app\bluetooth\examples_ncp_host\uart_dfu\exe (after building the project with make in the uart_dfu folder)

Upgrading Over-the-Air (OTA)#

This section describes upgrading the second stage using the Bluetooth connection OTA and a Bluetooth in-place OTA DFU type Gecko Bootloader. You also have to upgrade to stack version 2.7 or later. Note that if you already have an older stack version running on the device, upgrade is necessary.)

If you have already flashed the bootloader, the second stage can be upgraded in four steps:

Upload the new second stage image along with an apploader image. Note that this will overwrite the current application image.
Reset the device -> the first stage will upgrade the second stage with the new bootloader image. Note that this process will overwrite some part of the current apploader image.
Reset the device -> the second stage will upgrade the corrupted apploader image with the newly uploaded apploader image.
Upload the application image again. This will upgrade the corrupted application image.

Follow these steps to upgrade the second stage:

Create a new bootloader project to upgrade to. If you upgrade the bootloader OTA (not via UART), the address of Slot0 should match in the upgraded and in the old bootloader version!! If you need to change your slot configuration, follow the instructions in section: Upgrading Bootloader with Slot Address Change.
The bootloader can only be upgraded and not downgraded. As a result, increment the version number up with every upgrade. To upload the same bootloader version with another configuration, increase BOOTLOADER_VERSION_MAIN_CUSTOMER. Find the "Other" tab in the AppBuilder of the Bootloader project (opening .isc file), and add BOOTLOADER_VERSION_MAIN_CUSTOMER to the definitions. Define a value greater than 0 and increment it with every upgrade.
Generate and build the bootloader project.
Open your Bluetooth application project or create a new one (SDK v2.7 or later).
Build your project if you haven’t done so yet.
Copy the second stage bootloader image bootloader-storage-internal-ble.s37 (the .s37 file that does not end with –combined.s37) from your Bootloader project into your Bluetooth application project.

Find the following line in create_bl_files.bat (which can be found in the Bluetooth project):

%COMMANDER% gbl create "%PATH_GBL%\%OTA_APPLO_NAME%.gbl" --app "%PATH_GBL%\%OTA_APPLO_NAME%.srec"

And add the following line under it:

%COMMANDER% gbl create "%PATH_GBL%\%OTA_APPLO_NAME%+bootloader.gbl" --app "%PATH_GBL%\%OTA_APPLO_NAME%.srec" --bootloader bootloader.s37

Repeat this for signed and encrypted images if you use signed/encrypted images.
Run the create_bl_files.bat file, which creates the GBL files in the output_gbl folder.
Do a full OTA update on your devices the same way as a full OTA for upgrading the stack/apploader and application, but use these two files:

apploader+bootloader.gbl
application.gbl

During the OTA process the device resets itself twice, so there is no need for user interaction. After the OTA update, your bootloader is updated. You can check its version in the system_boot event of the Bluetooth stack or in the Gecko Bootloader version characteristic of the Silicon Labs OTA service (see AN1086).

Upgrading Bootloader with Slot Address Change#

The following section discusses the special case when you want to upgrade your Gecko Bootloader via Bluetooth with an image that has a different slot configuration than the previous Gecko Bootloader you used on your device.

To upgrade the bootloader with a new slot configuration is problematic because the upgrade image is uploaded by the old bootloader to the old slot address, but after the bootloader upgrade the new bootloader tries to load the apploader image from the new address – this will definitely fail.

The following workaround can be used to solve this issue:

To upgrade from bootloader A that has Slot0 address A, to bootloader B that has Slot0 address B, follow these steps:

You have a bootloader with Slot0 address A in your device. This will upload the upgrade image to address A.
First, upgrade to a temporary multi-slot bootloader with Slot0 address B and Slot1 address A. This can load images from address A but will upload the next upgrade image to address B.
Finally, upgrade to the single slot bootloader with Slot0 address B, as originally intended. This can load images from address B.

Configuring the temporary multi-slot bootloader:

Create a new bootloader project. Use Bluetooth in-place OTA DFU Bootloader or Internal/External storage bootloader, as you normally do.
Define the customer version string to N+1, where N is the version number of the original bootloader. You can do this by defining BOOTLOADER_VERSION_MAIN_CUSTOMER on the Other tab in the AppBuilder.
On the Storage tab, define the slots. Define Slot0 to the new address (with the new slot size), and Slot1 to the old address (with the old slot size). The slots can overlap in this case.
The multi-slot configuration needs a bootload info table that takes 8kB, which has to be defined somewhere outside of Slots and outside of the bootloader and apploader area. Go to Plugins page, select Common Storage, and define the Start address for bootload info to e.g., 8kB before the Slot with lower address. Make sure that the start address is aligned with the flash page size.
Press Generate to generate your project.
Finally, the bootload info table should be normally initialized by the app. This table tells which slots should be bootloaded in which order. However, because there is no valid application image after the bootloader upgrade, modify the bootloader code, as follows:
- Find storage-common/btl_storage.c in your project.
- Right click on it and select „Copy Linked File into Project”. This will copy btl_storage.c and btl_storage.h into the project from the SDK.
- In storage-common_inc/btl_storage.h, change the following line
```
  #include "bootloadinfo/btl_storage_bootloadinfo.h"
```
  to
```
  #include "plugin/storage/bootloadinfo/btl_storage_bootloadinfo.h"
```
- In storage-common/btl_storage.c, change the following lines
```
ret = storage_getBootloadList(slotIds, BTL_STORAGE_BOOTLOAD_LIST_LENGTH);
if (ret != BOOTLOADER_OK) {
  BTL_DEBUG_PRINTLN("BI err");
  return ret;
}
```
  to
```
ret = storage_getBootloadList(slotIds, BTL_STORAGE_BOOTLOAD_LIST_LENGTH);
if (ret != BOOTLOADER_OK) {
  BTL_DEBUG_PRINTLN("BI err");
  slotIds[0] = 0;
  slotIds[1] = 1;
}
```
This will ensure, that the bootloader will try to bootload from Slot0 first and then from Slot1.
Build your project and upgrade to this bootloader normally, before upgrading to the final bootloader.

The final bootloader can be configured as expected, but make sure that its version number is N+2.

For more information about the Gecko Bootloader, see UG266: Gecko Bootloader User Guide.