Silicon Labs AN1086 User Manual
AN1086: Using the Gecko Bootloader with
the Silicon Labs Bluetooth® Applications
This application note includes detailed information on using the Silicon Labs Gecko
Bootloader with Silicon Labs Bluetooth applications. It supplements the general Gecko
Bootloader implementation information provided in UG266: Silicon Labs Gecko Boot-
loader User’s Guide. If you are not familiar with the basic principles of performing a
firmware upgrade or want more information about upgrade image files, refer to
UG103.6: Bootloader Fundamentals.
In Gecko SDK Suite v3.0, the Bluetooth API structure was completely updated. Among
other changes, all function calls were renamed. This document covers both the v2.x
and the v3.x variants.
KEY POINTS
• Gecko Bootloader overview
• Using Gecko Bootloader for BGAPI UART
DFU
• Using Gecko Bootloader for Bluetooth
OTA upgrade
• Using Gecko Bootloader to update
firmware from the user application
silabs.com | Building a more connected world. Rev. 1.3
AN1086: Using the Gecko Bootloader with the Silicon Labs Bluetooth® Applications
Overview
1. Overview
The Silicon Labs Gecko Bootloader is a common bootloader for all the newer MCUs and wireless MCUs from Silicon Labs. The Gecko
Bootloader can be configured to perform a variety of bootload functions, from device initialization to firmware upgrades. The Gecko
Bootloader uses a proprietary format for its upgrade images, called GBL (Gecko Bootloader). These images are produced with the file
extension “.gbl”. Additional information on the GBL file format is provided in UG103.6: Bootloader Fundamentals.
The Gecko Bootloader has a two-stage design, where a minimal first stage bootloader is used to upgrade the main bootloader. The first
stage bootloader only contains functionality to read from and write to fixed addresses in internal flash. To perform a main bootloader
upgrade, the running main bootloader verifies the integrity and authenticity of the bootloader upgrade image file. The running main
bootloader then writes the upgrade image to a fixed location in flash and issues a reboot into the first stage bootloader. The first stage
bootloader verifies the integrity of the main bootloader firmware upgrade image, by computing a CRC32 checksum before copying the
upgrade image to the main bootloader location.
The Gecko Bootloader can be configured to perform firmware upgrades in standalone mode (also called a standalone bootloader) or in
application mode (also called an application bootloader), depending on the plugin configuration. Plugins can be enabled and configured
through the Simplicity Studio IDE.
This document describes how to configure and use the Gecko Bootloader for BGAPI UART device firmware upgrades and for Bluetooth
OTA (over-the-air) upgrades.
Unlike the legacy Bluetooth bootloaders, the Gecko Bootloader does not come bundled into the application download image. Therefore,
you must compile and load the bootloader separately from the application image.
silabs.com | Building a more connected world. Rev. 1.3 | 2
AN1086: Using the Gecko Bootloader with the Silicon Labs
Bluetooth® Applications
BGAPI UART Device Firmware Upgrade (DFU)
2. BGAPI UART Device Firmware Upgrade (DFU)
This is the firmware upgrade used in NCP-mode Bluetooth applications. A GBL image containing the new firmware is written to target
device using UART as the physical interface and BGAPI protocol. The BGAPI UART DFU bootloader is a standalone bootloader, so no
storage area needs to be configured. During UART DFU upgrade the bootloader writes the new firmware image directly on top of the
old firmware image and therefore no temporary download area is needed.
2.1 UART DFU Options
The target device must be programmed with the Gecko Bootloader configured as BGAPI UART DFU Bootloader. The default configuration is as follows:
UART Options
• Selected USART: USART0
• Baudrate 115200
• TX pin: PA0
• RX pin: PA1
• HW flow control: disabled
• UART enable port: PA5 (VCOM_ENABLE on WSTK)
GPIO Activation
• GPIO activation is enabled and mapped to button PB0 (active low).
The default settings are suitable for testing with a WSTK (Wireless Starter Kit). These settings can be easily changed by editing the
Plugin parameters. This is done by going to the Plugins tab of the AppBuilder project and selecting the UART driver plugin. Here, Hardware Flow Control can be enabled or disabled, and the baud rate and pinout can be configured.
The GPIO activation plugin is enabled by default, allowing bootloader entry by activating a GPIO through reset. This plugin can be disabled if this functionality is not desired, or the GPIO pin used for this can be configured under the GPIO Activation plugin on the Plugins
tab.
2.2 UART DFU Process
The basic steps involved in the UART DFU are as follows:
1. Boot the target device into DFU mode (by sending dfu_reset(1)).
2. Wait for the DFU boot event.
3. Send the command DFU Flash Set Address to start the firmware upgrade.
4. Send the entire contents of the GBL upgrade image (using the command DFU flash upload).
5. After sending all data, the host sends the command DFU flash upload finish.
6. To finalize the upgrade, the host resets the target device into normal mode (by sending dfu_reset(0)).
A detailed description of the DFU-related BGAPI commands is found in the Bluetooth Software API Reference Manual.
At the beginning of the upgrade, the NCP host uses the command Flash Set Address to define the start address. The start address
shall be always set as zero. During the data upload (step 4 above) the target device calculates the flash offset automatically.
The host does not need to explicitly set any write offset.
silabs.com | Building a more connected world. Rev. 1.3 | 3
AN1086: Using the Gecko Bootloader with the Silicon Labs Bluetooth® Applications
BGAPI UART Device Firmware Upgrade (DFU)
2.3 Creating Upgrade Images for the Bluetooth NCP Application
Building a C-based NCP project in Simplicity Studio does not generate the UART DFU upgrade images (GBL files) automatically. The
GBL files need to be created separately by running a script located in the project's root folder. Two scripts are provided in the SDK
examples:
• create_bl_files.bat (for Windows)
• create_bl_files.sh (for Linux / Mac)
The GBL files can be generated by invoking the script from the project directory.
If you are using Gecko SDK Suite v3.x, you need to define two environmental variables, PATH_SCMD and PATH_GCCARM before running
the script, as shown in the following table.
Variable Name Variable Value
PATH_SCMD C:\SiliconLabs\SimplicityStudio\v5\developer
\adapter_packs\commander
PATH_GCCARM C:\SiliconLabs\SimplicityStudio\v5\developer
\toolchains\gnu_arm\7.2_2017q4
Running the create_bl_files script creates multiple GBL files in a subfolder named output_gbl. The file named full.gbl is the upgrade
image used for UART DFU. The other files are related to OTA upgrades and they can be ignored.
If signing and/or encryption keys (named app-sign-key.pem, app-encrypt-key.txt) are present in the same directory, then the script
also creates secure variants of the GBL files.
Note: Depending on the SDK version, the script may also generate EBL files. EBL is the file format that is used in Bluetooth SDK versions 2.1.1 and earlier. The generated EBL files are stored in the subfolder output_ebl. These files can be ignored when working with
Gecko Bootloader.
silabs.com | Building a more connected world. Rev. 1.3 | 4
AN1086: Using the Gecko Bootloader with the Silicon Labs Bluetooth® Applications
BGAPI UART Device Firmware Upgrade (DFU)
2.4 UART DFU Host Example
The UART DFU host example is a C program that is located under the SDK examples in the following directory (the exact path depends
on the installed SDK version):
v3.x:
C:\SiliconLabs\SimplicityStudio\v5\developer\sdks\gecko_sdk_suite\<version>\app\bluetooth\example_host\uart_dfu
v2.x:
C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\<version>\app\bluetooth\example_ncp_host
\uart_dfu
In Windows this program can be built using, for example, MinGW or Cygwin. In Linux or Mac the program can be built using the GCC
toolchain.
The project is built by running make (or mingw32-make) in the project root directory. After a successful build, an executable is created
in the subfolder named exe. The executable filename is:
• uart_dfu.exe in v3.x
• uart-dfu.exe in v2.x
Before running the example you need to check the COM port number associated with your NCP target. For more details, see AN1259:
Using the v3.x Silicon Labs Bluetooth® Stack in Network Co-Processor Mode or AN1042: Using the v2.x Silicon Labs Bluetooth® Stack
in Network Co-Processor Mode.
The uart_dfu.exe program requires three command line arguments:
• COM port number
• Baud rate
• Name of the (full) GBL file
Example usage and expected output in v3.x:
./uart_dfu.exe COM42 115200 full.gbl
Syncing..DFU OK
Bootloader version: ***
........
........
finish
The procedure is the same in v2.x, except the executable filename is uart-dfu.exe.
The number of bytes uploaded in one DFU flash upload command is configurable. The UART DFU host example included in the SDK
uses a 48-byte payload. The maximum usable payload length is 128 bytes. The maximum number of bytes sent in one command is
specified using a C preprocessor directive named MAX_DFU_PACKET. The value of MAX_DFU_PACKET must be divisible by four.
silabs.com | Building a more connected world. Rev. 1.3 | 5
AN1086: Using the Gecko Bootloader with the Silicon Labs Bluetooth® Applications
Bluetooth OTA Upgrade
3. Bluetooth OTA Upgrade
To enable Bluetooth OTA upgrade, the target device must be programmed with Gecko Bootloader that is configured as Internal Storage Bootloader. This is an application bootloader and it requires that the new firmware image acquisition is managed by application.
3.1 AppLoader
A Bluetooth application developed with Silicon Labs Bluetooth SDK comprises two parts: AppLoader and the user application. AppLoader is a small standalone application that is required to support in-place OTA updates. AppLoader can run independently of the
user application. It contains a minimal version of the Bluetooth stack, including only those features that are necessary to perform the
OTA update. Any Bluetooth features that are not necessary to support OTA updates are disabled in AppLoader to minimize the flash
footprint.
The AppLoader features and limitations are summarized below:
• Enables OTA updating of user application.
• The AppLoader itself can also be updated.
• Only one Bluetooth connection is supported, GATT server role only.
• Encryption and other security features such as bonding are not supported.
• PTI is not enabled so it is not possible to use the Network Analyzer with the AppLoader
Note: AppLoader in SDK v3.x requires that the Gecko Bootloader version must be v1.11 or later to support OTA.
The user application is placed in code flash after AppLoader. The default linker script provided in the SDK places the user application
so that it starts at the next flash sector following AppLoader. The user application contains a full-featured version of the Bluetooth stack
and it can run independently of the AppLoader. If in-place OTA update does not need to be supported then the AppLoader can be
removed completely to free up flash for other use (code space or data storage). Section 4. Implementing Device Firmware Update in
the User Application describes how OTA can be implemented in application code, without any involvement of AppLoader.
For more details on AppLoader and the overall structure of a Bluetooth application see UG434: Silicon Labs Bluetooth® C Application
Developers Guide for SDK v3.x or UG136: Silicon Labs Bluetooth® C Application Developers Guide for SDK v2.x.
silabs.com | Building a more connected world. Rev. 1.3 | 6
AN1086: Using the Gecko Bootloader with the Silicon Labs
Bluetooth® Applications
Bluetooth OTA Upgrade
3.2 Gecko Bootloader Configuration
The Gecko Bootloader must be configured as an application bootloader. The OTA functionality is implemented almost entirely in the
AppLoader, or alternatively in the user application. The Gecko Bootloader takes care of copying data from the download area to the
final destination in flash. Additionally, AppLoader takes advantage of some features supported by Gecko Bootloader, for example, parsing the incoming GBL image.
Note: Gecko Bootloader has Application upgrade version check feature that can be included in Plugin configuration of the Bootloader
project. This feature is used to check the version number and product ID of the application upgrade before applying it. However, this
should not be used with Apploader because the version comparison is done to Apploader instead of the application.
For EFR32xG1, the Bluetooth in-place OTA DFU Bootloader configuration is used as a default. In this configuration, the upper half of
the main flash, normally used to hold the Bluetooth application, is re-purposed as a storage area while a Bluetooth stack upgrade is
downloaded.
For EFR32xG12 and later, any application bootloader configuration may be used that uses internal storage. The default example application configurations are suitable for Bluetooth OTA upgrades, and may be modified to fit the needs of the application. The following
figure shows an example flash layout for EFR32xG1 and EFR32xG12 devices. For more information on flash organization, see UG434:
Silicon Labs Bluetooth® C Application Developers Guide for SDK v3.x or UG136: Silicon Labs Bluetooth® C Application Developers
Guide for SDK v2.x.
Figure 3.1. Examples of Main Flash Layout when Using Gecko Bootloader with Bluetooth OTA DFU
Note that on series 2 devices (EFR32xG2x) the default NVM solution is NVM3, and NVM3 might also be used instead of PSStore on
series 1 devices. In this case the NVM area is larger than 4 kB, and therefore the slot size in the bootloader configuration must be
reduced accordingly to avoid overwriting the NVM area.
silabs.com | Building a more connected world. Rev. 1.3 | 7
AN1086: Using the Gecko Bootloader with the Silicon Labs
Bluetooth® Applications
Bluetooth OTA Upgrade
3.3 In-Place OTA Process
Most of the OTA functionality is handled autonomously by the AppLoader, which greatly simplifies application development. The minimum requirement for the user application is for a way to trigger a reboot into DFU mode. Rebooting into DFU mode in this context
means that after the device is reset, the AppLoader is run instead of the user application. After the upload is complete, AppLoader will
reboot the device back into normal mode.
Reboot into DFU mode can be triggered in a variety of ways. It is up to the application developer to decide which is most applicable.
Most of the example applications provided in the Bluetooth SDK already have OTA support built into the code. In these examples, the
DFU mode is triggered through the Silicon Labs OTA service that is included as part of the application’s GATT database. The following
sections explain in detail how this is done in the user application.
AppLoader supports two types of update:
• Full update: both AppLoader and the user application are updated
• Partial update: only the user application is updated
Note: In earlier stack versions (SDK v2.6.x and earlier), the meaning of partial and full update is different compared to the current OTA
implementation. To avoid confusion, the main differences between the old and new OTA are summarized below.
SDK v2.6.x and older SDK v2.7.x and later
OTA update files generated stack.gbl: Bluetooth stack and OTA update part
(supervisor)
app.gbl: User application
apploader.gbl: AppLoader (including minimal
Bluetooth stack)
application.gbl: user application (including
full Bluetooth stack)
Partial update Only user application is updated. Bluetooth
stack remains the same. Application must be
built with same SDK version that is currently installed in the target device.
Full update Both the Bluetooth stack and the user applica-
tion are updated in two phases (first stack, then
application)
1
A full update is always recommended when moving from one SDK version to another. The size of AppLoader can vary depending on
User application is updated. The Bluetooth
stack is part of the user application, therefore
the stack is also updated. The user application
and AppLoader do not need to be built from the
same SDK.
1
Both the AppLoader and user application (including Bluetooth stack) are updated in two
phases (first AppLoader, then user application)
the SDK version. This may prevent a partial OTA update if the new application image overlaps with the old AppLoader version.
From the OTA client viewpoint, the overall OTA process is the same in both old and new versions. Full update is performed by uploading two GBL files into the target device. Partial update requires only one file. Because the mechanism of uploading GBL files over the
air is identical, the OTA solution introduced in SDK 2.7.0 is backwards-compatible:
• Device running an application from SDK v2.6.x (or older, down to 2.0.x) can be upgraded to 2.7.x using OTA
• Device running v2.7.x firmware can be downgraded to 2.6.x or older using OTA
• Device running an application from SDK v2.7.x firmware and Gecko Bootloader v1.11 or later can be upgraded to SDK v3.x using
OTA
The partial update process using AppLoader consists of following steps:
1. OTA client connects to target device.
2. Client requests target device to reboot into DFU mode.
3. After reboot, client connects again.
4. During the 2nd connection, target device is running AppLoader (not the user application).
5. New firmware image (application.gbl) is uploaded to the target.
6. AppLoader copies the new application on top of the existing application.
7. When upload is finished and connection closed, AppLoader reboots back to normal mode.
8. Update complete.
With partial update, it is possible to update the Bluetooth stack and user application. AppLoader is not modified during partial update.
Full update enables updating both the AppLoader and the user application. Full update is done in two steps. Updating the AppLoader
always erases the user application and therefore AppLoader update must always be followed by application update.
The first phase of full update updates the AppLoader and it consists of following steps:
1. OTA client connects to target device.
silabs.com | Building a more connected world. Rev. 1.3 | 8
AN1086: Using the Gecko Bootloader with the Silicon Labs Bluetooth® Applications
Bluetooth OTA Upgrade
2. Client requests target device to reboot into DFU mode.
3. After reboot, client connects again.
4. During the 2nd connection, target device is running AppLoader (not the user application).
5. New AppLoader image (apploader.gbl) is uploaded to the target.
6. AppLoader copies the image into the download area (specified in Gecko bootloader configuration).
7. When upload is finished and connection closed, AppLoader reboots and requests Gecko Bootloader to install the downloaded image.
8. Gecko Bootloader updates AppLoader using the downloaded image and reboots.
9. After reboot, the new AppLoader is started.
At the end of the AppLoader update, the device does not contain a valid user application and therefore AppLoader will remain in DFU
mode. To complete the update, a new user application is uploaded following the same sequence of operations that were described for
the partial update.
The SDK includes an example OTA client implementation that can be used to perform both full and partial updates. This example app is
described in section 3.11 OTA DFU Host Example. Full and partial OTA can also be performed using the EFR Connect smartphone
app.
silabs.com | Building a more connected world. Rev. 1.3 | 9
Loading...