Gecko Bootloader Lab Worksheet

This lab demonstrates configuring, programming, and usage ofthe Gecko Bootloader on EFR32xG21 devices.

1. Plug in your EFR32xG21 Wireless Starter Kit.2. Flash Gecko Bootloader.3. Configure security features:

a. Image signingb. Encryptionc. Secure Boot

KEY POINTS

• Follow a few simple steps to utilize GeckoBootloader on your EFR32xG21 device.

• Use AppBuilder to enable securityfeatures.

silabs.com | Building a more connected world. Rev. 0.1

1. Getting Started

Simplicity Studio v4 with EFR32xG21 support must already be installed.1. Setup your kit

a. Provide power to the EFR32xG21 WSTK board by connecting the USB J-Link debugger connector to the PC using the pro-vided USB cable.

b. Move the Power Source Select switch to the AEM position.

2. Detect your device

a. Click [Refresh] button if the WSTK information does not display. The board may take some time to appear due to driver instal-lations for the debug adapter.

b. Click the EFR32xG21 2.4 GHz 20 dBm Radio Board (BRD4180A). This will verify that the installation was successful, identifythe device on the kit hardware, and automatically configure the software tools for use with your device. It may use a differentEFR32xG21 radio board (e.g. BRD4181A) on your lab.

3. Install a terminal program capable of sending XMODEM-CRC data. (Tera Term is used in this lab. Tera Term can be downloadedfrom https://osdn.net/dl/ttssh2/teraterm-4.101.zip ).

4. Download the simpleApp project to be used in the exercises: https://www.dropbox.com/s/w09e8l3kq0jfuvl/simpleApp.sls?dl=0

Gecko Bootloader Lab WorksheetGetting Started

silabs.com | Building a more connected world. Rev. 0.1 | 2

2. Flashing the Bootloader

In this exercise, we will flash the gecko bootloader onto a device, as well as flash a user application to a device, and observe how toswitch between bootloader mode and the application using GPIO bootload entry.

Gecko Bootloader Lab WorksheetFlashing the Bootloader

silabs.com | Building a more connected world. Rev. 0.1 | 3

1. Select the EFR32MG21 kit (BRD4181A) and select the [UART XMODEM Gecko Bootloader] sample application from Launcher.This example is found under Software Examples, under the [Gecko Bootloader x.x.x] tab, under [Gecko Bootloader Examples].

This will launch AppBuilder. We will use GNU ARM v7.2.1 to build this application.

Make sure that you have the latest SDK selected (2.51 or later) – if not, you can change the SDK version at the top of the launcherpage:

Note:

If you are using SDK version v2.5.1, you will need to download Commander version 1.7.1 for the last exercise. A download link isavailable at the end of section 4. Adding Signing and Encryption.

If you are using SDK version v2.5.2, you will need Commander version 1.7.2. This is the latest release, but there is also a down-load link available at the end of section 4. Adding Signing and Encryption

Gecko Bootloader Lab WorksheetFlashing the Bootloader

silabs.com | Building a more connected world. Rev. 0.1 | 4

2. Verify that the correct compiler is selected by inspecting the General tab.

3. Generate, build and program the bootloader to Flash.

We will use the default configuration in this first build. Hit [Generate], then [Build].

Under the [GNU ARM v7.2.1 – Default] directory in [Project Explorer], select the file bootloader-uart-xmodem.s37. This filecontains the second stage bootloader, since the first stage is contained within Secure Element on Series 2 devices (on deviceswith a bootloader area, the combined image will be named bootloader-uart-xmodem-combined.s37. Right click on the file andselect [Flash To Device…. ]. This will open the Flash Programmer tool. Click [Erase] to erase any program that may be on thedevice, then click [Program].

Gecko Bootloader Lab WorksheetFlashing the Bootloader

silabs.com | Building a more connected world. Rev. 0.1 | 5

4. Verify bootloader operation without a user application.

Open a terminal window and access VCOM (JLink CDC UART). The default settings for the bootloader project are Baudrate =115200, 8-n-1 (in Tera-term, you can configure this under [Setup] > [Serial Port...]). Press the RESET button on the WSTK mainboard. The bootloader should enter shell mode because there is no valid application.

Gecko Bootloader Lab WorksheetFlashing the Bootloader

silabs.com | Building a more connected world. Rev. 0.1 | 6

5. Import, build, and program a user application.

In Simplicity Studio, navigate to [File] > [Import], the [Browse] to the simpleApp.sls project file.

This project contains a simple program to be used for the bootloader exercises.

The project has its linker settings modified to place the start of the program at address 0x00004000, the beginning of the applica-tion space after the bootloader.

The project also includes an application properties structure, required for the bootloader's security features. By default, wirelessstack projects include this structure, but MCU and RAIL projects do not, so it must be added manually when creating theseprojects.

In the main function, an instruction turns on LED1, then waits in a while loop. A reference is made to the application propertiesstructure, to keep the linker from removing this otherwise unused section (there are other ways to do this, such as creating a cus-tom linker script, but this is a simple way used for the purposes of this exercise).

6. Generate and program the application to the device.

Once the project is open, build it and download the application to the device. The application can be programmed using either anormal debug session or through the Flash Programmer.

Gecko Bootloader Lab WorksheetFlashing the Bootloader

silabs.com | Building a more connected world. Rev. 0.1 | 7

7. Verify bootloader operation with user application.

Open a terminal window and access VCOM (JLink CDC UART). Hold PB0 and press RESET. You should see the bootloader shellagain.

Press the RESET button only. The bootloader should now enter directly into the application. LED1 should turn on.

8. Re-configure the GPIO activation plugin.

Return to the Configurator in Studio in the bootloader-uart-xmodem project (if closed, click bootloader-uart-xmodem.isc).

Select the Plugins tab. Change the configuration of the activation pin from PD02 (BTN0) to PD03 (BTN1). Save and hit Generate,build and program the updated bootloader.

Verify bootloader entry with PB1.

Gecko Bootloader Lab WorksheetFlashing the Bootloader

silabs.com | Building a more connected world. Rev. 0.1 | 8

3. Updating an Application through the Gecko Bootloader

In this exercise we are going to look at creation of a GBL files from an application project and then update the application present inFlash through the XMODEM bootloader.

1. Return to the [simpleApp] project in Simplicity IDE.

We are now going to make some modifications to the application to make the update observable.

Add an additional line to main.c to also turn on LED0, where we previously turned on LED1:

GPIO_PinModeSet(BSP_LED0_PORT, BSP_LED0_PIN, gpioModePushPull, 1);

Rebuild the application, but do not program it to flash.

2. Create a GBL file.

Note: No GBL operations are currently supported through the Studio UI.

Under [GNU ARM v7.2.1 - Debug], right click on simpleApp.s37 and select [Open Command Line Here].

Run: commander gbl create simpleApp.gbl --app simpleApp.s37

If commander isn’t in your PATH, you can simply copy the simpleApp.s37 file to your commander directory, and run the commandthere. Commander can be found in the Simplicity Studio install directory under developer\adapter_packs\commander.

Gecko Bootloader Lab WorksheetUpdating an Application through the Gecko Bootloader

silabs.com | Building a more connected world. Rev. 0.1 | 9

3. Update the application in Flash through XMODEM.

Enter the Gecko Bootloader console through GPIO activation. Then send simpleApp.gbl to the bootloader by pressing 1, thentransfer by send as XMODEM through your terminal application.

Note: some terminal applications support multiple protocols. Make sure to use XMODEM.

Press 2 or reset the kit to start the application.

Verify that the two LEDs are constantly set to ON.

Gecko Bootloader Lab WorksheetUpdating an Application through the Gecko Bootloader

silabs.com | Building a more connected world. Rev. 0.1 | 10

4. Adding Signing and Encryption

To enable security features, we must make sure a valid application properties structure exists in the project. The [simpleApp] projectalready includes this structure, but, for reference, an example of this structure exists in section 5. Appendix.

1. Make an observable change to the application such as clearing one of the LEDs instead of setting both in the main function.

2. Generate the signing keys.

Execute the following command to generate a key-pair for signing.

Run: commander gbl keygen --type ecc-p256 --outfile signing-key

The following files are generated:signing-key This file contains the secret private key. This key will later be

used to sign images and GBL files.

signing-key.pub This file contains the public key. This key can be used to veri-fy GBL files using commander gbl parse.

signing-key-tokens.txt This file contains the public key in token format, suitable forwriting to the EFR32 device.

3. Generate the encryption key.

Execute the following command to generate an encryption key.

Run: commander gbl keygen --type aes-ccm --outfile encryption-key

The file encryption-key is generated.

4. Write the encryption key and public signing key to the EFR32 device.

Run: commander flash --tokengroup znet --tokenfile encryption-key --tokenfile signing-key-tokens.txt

5. Sign the application image to enable secure boot of the application image.

Run: commander convert simpleApp.s37 --secureboot --keyfile signing-key --outfile simpleApp_signed.s37

Note: The purpose of signing is to prevent execution of untrusted images on the device.

6. Create a signed and encrypted GBL file.

Run: commander gbl create simpleApp_secure.gbl --app simpleApp_signed.s37 --sign signing-key --encrypt

encryption-key

Note: By signing and encrypting the image, we are protecting software IP or private data within the image.

7. Enable security features in AppBuilder.

We now need to enable the corresponding features in Configurator.

Security option Required GBL processingstep

Advantage Disadvantage

Require signed firmware up-grade files

6 Protection against untrustedapplication updates

Added GBL update time andkey management complexity

Require encrypted firmwareupgrade files

6 Protect software IP or privatedata within the image

Added GBL update time andkey management complexity

Enable secure boot 5 Prevent execution of untrus-ted images

Adds application startup time

Gecko Bootloader Lab WorksheetAdding Signing and Encryption

silabs.com | Building a more connected world. Rev. 0.1 | 11

Security option Required GBL processingstep

Advantage Disadvantage

Prevent bootloader write/erase

None Protects the bootloader itselfagainst malware in the appli-cation

Limitations on debug access(rewrite) of main bootloader.Simplicity Commander / de-bugger is unable to erasebootloader space.

From Plugin [Bootloader Core], enable all except bootloader write/erase protection.

8. Generate, build, and flash the updated bootloader.

Gecko Bootloader Lab WorksheetAdding Signing and Encryption

silabs.com | Building a more connected world. Rev. 0.1 | 12

9. Transfer an unsigned GBL file.

Send the file previously created GBL file simpleApp.gbl. The XMODEM bootloader should reject this file:

Note: XMODEM status and error codes are documented in AN1084.

10. Transfer a signed and encrypted image.

Select the file simpleApp_secure.gbl. The bootloader should accept the file. Once the transfer is done, press 2 or reset and verifythat the change you made to the application is observable.

Note: If you receive error 0x50, you may have skipped flashing your keys to the device, or may have accidentally erased them.Retry step 4 above.

Note: If you receive error 0x45, you may have a mismatch between Commander and the gecko bootloader version. The bootloaderin Gecko Suite 2.5.2 requires Commander version 1.7.2 or later. The bootloader in Gecko Suite 2.5.1 requires Commander version1.7.1 or earlier.

Commander version 1.7.1 can be found here: https://www.dropbox.com/sh/buqw1mx9hoel69u/AAA8UWKbyGSJITyrmVqJ3dwAa?dl=0

Commander version 1.7.2 can be found here: https://www.dropbox.com/sh/gack3se30hifllo/AAAaWsGrs82wTdgoE-vdeXgYa?dl=0

Gecko Bootloader Lab WorksheetAdding Signing and Encryption

silabs.com | Building a more connected world. Rev. 0.1 | 13

5. Appendix

1.application_properties.c

/***************************************************************************//** * @file application_properties.c * @brief Template for Application Properties * @author Silicon Labs * @version 5.7.0 ******************************************************************************* * @section License * <b>Copyright 2017 Silicon Laboratories, Inc. http://www.silabs.com</b> ******************************************************************************* * * This file is licensed under the Silabs License Agreement. See the file * "Silabs_License_Agreement.txt" for details. Before using this software for * any purpose, you must agree to the terms of that agreement. * ******************************************************************************/

#include <application_properties.h>

/// Version number for this application (uint32_t)#define APP_PROPERTIES_VERSION 1/// Unique ID (e.g. UUID or GUID) for the product this application is built for (uint8_t[16])#define APP_PROPERTIES_ID { 0 }

const ApplicationProperties_t applicationProperties = { /// @brief Magic value indicating that this is an ApplicationProperties_t struct. /// Must equal @ref APPLICATION_PROPERTIES_MAGIC .magic = APPLICATION_PROPERTIES_MAGIC, /// Version number of this struct .structVersion = APPLICATION_PROPERTIES_VERSION, /// Type of signature this application is signed with .signatureType = APPLICATION_SIGNATURE_NONE, /// Location of the signature. Typically a pointer to the end of the application .signatureLocation = 0, /// Information about the application .app = { /// Bitfield representing type of application, e.g. @ref APPLICATION_TYPE_BLUETOOTH_APP .type = APPLICATION_TYPE_MCU, /// Version number for this application .version = APP_PROPERTIES_VERSION, /// Capabilities of this application .capabilities = 0, /// Unique ID (e.g. UUID or GUID) for the product this application is built for .productId = APP_PROPERTIES_ID, },};

Gecko Bootloader Lab WorksheetAppendix

silabs.com | Building a more connected world. Rev. 0.1 | 14

2. simpleApp main.c:

This can be used to re-create the simpleApp project. To do so:a. Create a new project using [File] > [New] > [Project] > [Silicon Labs MCU Project], and select [Empty C Project].b. Add the application_properties.c file to your project. Make sure to add the location of application_properties.h to

your include path, located under the Simplicity Studio install directory under developer/sdks/gecko_sdk_suite/v2.x/platform/bootloader/api.

c. Under [Project] > [Properties] > [C/C++ Build] > [Settings] > [Memory Layout], select [Override default flash options] andchange [Origin] to 0x4000.

d. Add em_gpio.c and em_cmu.c to the project.

#include "em_device.h"#include "em_chip.h"#include "em_cmu.h"#include "em_gpio.h"#include "application_properties.h"

#define BSP_LED0_PIN (0U)#define BSP_LED0_PORT (gpioPortB)

#define BSP_LED1_PIN (1U)#define BSP_LED1_PORT (gpioPortB)

extern const ApplicationProperties_t applicationProperties;int main(void){ // Initialize the chip CHIP_Init();

// Initialize the LED0 on the board CMU_ClockEnable(cmuClock_GPIO, true);

// Trick the linker into keeping the applicationProperties struct if (applicationProperties.app.version == 1) { // Turn on one of the LEDs GPIO_PinModeSet(BSP_LED1_PORT, BSP_LED1_PIN, gpioModePushPull, 1); }

/* Infinite loop */ while (1) { }}

Gecko Bootloader Lab WorksheetAppendix

silabs.com | Building a more connected world. Rev. 0.1 | 15