GBL Commands#

GBL File Creation#

Creates a Gecko Bootloader (GBL) file from an application image and writes the output to the specified filename. Can optionally encrypt the GBL file using a keyfile generated by the gbl keygen command.

Command Line Syntax

$ commander gbl create <gblfile> --app <filename> [--encrypt <keyfile>]

Command Line Input Example

$ commander gbl create app.gbl.encrypted --app example.s37 --encrypt key.txt

Command Line Output Example

Parsing file example.s37...
Initializing GBL file...
Adding application to GBL...
Encrypting GBL...
Writing GBL file app.gbl.encrypted...
DONE

GBL File Creation with Compression#

Creates a compressed Gecko Bootloader (GBL) file from an application image and writes the output to the specified filename. Can optionally encrypt the GBL file using a keyfile generated by the gbl keygen command.

The currently supported compression algorithms are lz4 and lzma. The bootloader on the targeted devices must support decompressing the selected compression type.

Command Line Syntax

$ commander gbl create <gblfile> --app <filename> --compress <compression algorithm> [--encrypt <keyfile>]

Command Line Input Example

$ commander gbl create app.gbl --app example.s37 --compress lz4

Command Line Output Example

Parsing file example.s37...
Initializing GBL file...
Adding application to GBL...
Compressing using lz4...
Writing GBL file app.gbl...
DONE

Create a GBL File for Bootloader Upgrade#

Creates a Gecko Bootloader (GBL) file from a bootloader image and writes the output to the specified bootloader image filename. For more information, see UG266: Silicon Labs Gecko Bootloader User's Guide for GSDK 3.x and Lower or UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Command Line Syntax

$ commander gbl create <gblfile> --bootloader <bootloader image file> [--encrypt <keyfile>]

Command Line Input Example

$ commander gbl create bootloader.gbl --bootloader bootloader.s37

Command Line Output Example

Initializing GBL file...
Adding bootloader to GBL...
Writing GBL file bootloader.gbl...
DONE

Creating a GBL File for Secure Element Upgrade#

The Secure Element on EFR32xG21 devices can be upgraded using a Secure Element upgrade binary provided by Silicon Labs. This command creates a GBL file containing a Secure Element upgrade file and writes the output to the specified GBL filename. For more information, see UG266: Silicon Labs Gecko Bootloader User's Guide for GSDK 3.x and Lower or UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Command Line Syntax

$ commander gbl create <gblfile> --seupgrade <secure element upgrade file> --app <application image>

Command Line Input Example

$ commander gbl create se-upgrade.gbl --seupgrade secure-element-1.0.0.seu --app myapp.s37

Command Line Output Example

Parsing file myapp.s37...
Initializing GBL file...
Adding application to GBL...
Adding Secure Element upgrade image to GBL...
Writing GBL file se-upgrade.gbl...
DONE

Creating a Signed and Encrypted GBL Upgrade Image File from an Application#

Creates a GBL file, signs the GBL file, and encrypts the GBL file. For more information, see UG266: Silicon Labs Gecko Bootloader User's Guide for GSDK 3.x and Lower or UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Command Line Syntax

$ commander gbl create <gblfile> --app <app image file> --sign <signing key> [--encrypt <encryption key>]

Command Line Input Example

$ commander gbl create example.gbl --app example.s37 --sign ecdsakey --encrypt aeskey

Command Line Output Example

Parsing file example.s37...
Initializing GBL file...
Adding application to GBL...
Encrypting GBL...
Signing GBL...
Image SHA256: 74b126bdbad680470487e32d7d7b3ec7f12b15d9988e028b26c2dd54f81dcfb7
R = 055A23A44CDEDA34506EE72F4530FE174CFC85F48933C1379C1360F8BC1AA75B
S = 1C9EF6C3F5CAA0D5B92ECC2569E4A8251F8561DAF52DE54D3E59591A5001B9EA
Writing GBL file example.gbl...
DONE

Creating a Partial Signed and Encrypted GBL Upgrade File for Use with a Hardware Security Module#

It is often not desirable to keep the private key used for signing locally on the computer that creates the GBL images. A good way to increase security is to use a Hardware Security Module (HSM) to generate the actual signatures. Simplicity Commander supports using a three-step process:

  1. Create a partial GBL file for external signing using Simplicity Commander.

  2. Create an Elliptic Curve Digital Signature Algorithm (ECDSA) signature of the partial GBL file using an HSM.

  3. Use Simplicity Commander to sign the partial GBL file using the signature from the HSM, and create a complete GBL file.

Step 1 is described in this section. Step 2 is specific to the HSM you are using. Step 3 is described in Creating a Signed GBL File Using a Hardware Security Module. For more information, see UG266: Silicon Labs Gecko Bootloader User's Guide for GSDK 3.x and Lower or UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Command Line Syntax

$ commander gbl create <output partial GBL file for external signing> --app <app image file>
--extsign [--encrypt <encryption key>]

Command Line Input Example

$ commander gbl create example.gbl.extsign --app example.s37 --extsign --encrypt aeskey

Command Line Output Example

Parsing file example.s37...
Initializing GBL file...
Adding application to GBL...
Encrypting GBL...
Preparing GBL for external signing...
Writing GBL file example.gbl.extsign...
DONE

Creating a Signed GBL File Using a Hardware Security Module#

Creates a signed GBL file from a partial GBL file and an ECDSA signature file in Distinguished Encoding Rules (DER) format generated as described in Creating a Partial Signed and Encrypted GBL Upgrade File for Use with a Hardware Security Module. For more information, see UG266: Silicon Labs Gecko Bootloader User's Guide for GSDK 3.x and Lower or UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Silicon Labs recommends that you use the --verify option with the public key corresponding to the private key used by the HSM to ensure the integrity of the generated GBL file.

Command Line Syntax

$ commander gbl sign <partial GBL file for external signing> --signature <signature from HSM>
[--verify <public key file>] --outfile <signed GBL file>

Command Line Input Example

$ commander gbl sign example.gbl.extsign --signature example.gbl.extsign.sig --verify ecdsakey.pub
--outfile example-signed.gbl

Command Line Output Example

Reading GBL data from example.gbl.extsign...
Parsing signature file example.gbl.extsign.sig...
R = 2E73426A1052E12BFFFEFBA9BE2AA50CEA815B630C3CA878494EEF26088A5673
S = C218596DB9958AB30924B516953D2E5107644963B4CA128072AC965BE5C2992D
Writing signature to GBL...
Verifying GBL...
Image SHA256: 4d7325b09ade0ea272eb9895096c8137b18451f694a4eca9a5782f5c08dea03a
Q_X: 60BA97B850291456217C2149061AA344B32BBFB69A91A94BBF2F274744308D39
Q_Y: 41927DA5DB171E1C723C6B59C2BC88EDFF5A37014B0473775BA5B15921686ECA
R = 2E73426A1052E12BFFFEFBA9BE2AA50CEA815B630C3CA878494EEF26088A5673
S = C218596DB9958AB30924B516953D2E5107644963B4CA128072AC965BE5C2992D
Writing GBL file example-signed.gbl...
DONE

GBL File Parsing#

Parses a Gecko Bootloader (GBL) file and writes the application image to the specified filename. Optionally decrypts an encrypted GBL file. The keyfile must be the same as was used for encrypting the encrypted GBL file.

Command Line Syntax

$ commander gbl parse <gbl filename> --app < filename> [--decrypt <key filename>]

Command Line Input Example

$ commander gbl parse example.gbl.encrypted --app app.s37 --decrypt key.txt

Command Line Output Example

Reading GBL data...
Decrypting GBL...
Reading application...
Writing application to app.s37...
DONE

GBL Key Generation#

This command is deprecated. See Key Generation for more information about key generation.

Generating a Signing Key#

This command is deprecated. See Generating a Signing Key for more information about generating a signing key.

Generate a Signing Key Using a Hardware Security Module#

This command is deprecated. See Key to Token for more information about generating a signing key using a hardware security module.

Creating a Signed GBL File Using a Hardware Security Module#

Creates a signed GBL file from a partial GBL file and an ECDSA signature file in Distinguished Encoding Rules (DER) format generated as described in Creating a Partial Signed and Encrypted GBL Upgrade File for Use with a Hardware Security Module. For more information, see UG266: Silicon Labs Gecko Bootloader User's Guide for GSDK 3.x and Lower or UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Silicon Labs recommends that you use the --verify option with the public key corresponding to the private key used by the HSM to ensure the integrity of the generated GBL file.

Command Line Syntax

$ commander gbl sign <partial GBL file for external signing> --signature <signature from HSM>
[--verify <public key file>] --outfile <signed GBL file>

Command Line Input Example

$ commander gbl sign example.gbl.extsign --signature example.gbl.extsign.sig --verify ecdsakey.pub
--outfile example-signed.gbl

Command Line Output Example

Reading GBL data from example.gbl.extsign...
Parsing signature file example.gbl.extsign.sig...
R = 2E73426A1052E12BFFFEFBA9BE2AA50CEA815B630C3CA878494EEF26088A5673
S = C218596DB9958AB30924B516953D2E5107644963B4CA128072AC965BE5C2992D
Writing signature to GBL...
Verifying GBL...
Image SHA256: 4d7325b09ade0ea272eb9895096c8137b18451f694a4eca9a5782f5c08dea03a
Q_X: 60BA97B850291456217C2149061AA344B32BBFB69A91A94BBF2F274744308D39
Q_Y: 41927DA5DB171E1C723C6B59C2BC88EDFF5A37014B0473775BA5B15921686ECA
R = 2E73426A1052E12BFFFEFBA9BE2AA50CEA815B630C3CA878494EEF26088A5673
S = C218596DB9958AB30924B516953D2E5107644963B4CA128072AC965BE5C2992D
Writing GBL file example-signed.gbl...
DONE

Create a GBL File from an ELF File#

Creates a Gecko Bootloader (GBL) file from an Executable and Linkable Format (ELF) file and writes the output to the specified file. If neither the --include-section nor the --exclude-section option is used, Simplicity Commander will include all sections that appear to be part of the application.

Command Line Syntax

$ commander gbl create <gblfile> --app <application image file> [--include-section <section> --exclude-section <section>]

Command Line Input Example

$ commander gbl create app.gbl --app app.out --exclude-section text_apploader --exclude-section text_signature

Creates a GBL file containing an ELF application, excluding the text_apploader and text_signature sections from the application.

Command Line Output Example

Parsing file app.out...
Initializing GBL file...
Adding application to GBL...
Encrypting GBL...
Writing GBL file app.gbl.encrypted...
DONE

Create an Encrypted GBL File with an Unencrypted Secure Element Upgrade File#

Creates an encrypted Gecko Bootloader (GBL) file containing an unencrypted Secure Element upgrade file and then writes the output to the specified GBL file.

Command Line Syntax

$ commander gbl create <gblfile> --seupgrade <secure element upgrade file> --seunencrypted --app <application image> --encrypt <AES key file>

Command Line Input Example

$ commander gbl create se-upgrade.gbl --seupgrade secure-element.seu --seunencrypted --app myapp.s37 --encrypt aes-key.txt

Creates an encrypted GBL file with a Secure Element upgrade file outside the encrypted area of the file.

Command Line Output Example

Parsing file myapp.s37...
Initializing GBL file...
Adding application to GBL...
Adding Secure Element upgrade image to GBL...
Encrypting GBL...
Writing GBL file se-upgrade.gbl...
DONE

Create a GBL File with Version Dependencies#

Any version dependencies between application, bootloader, and secure element upgrade files in a Gecko Bootloader (GBL) file may be resolved using the --dep-app, --dep-boot, and --dep-se options.

Command Line Syntax

$ commander gbl create <gblfile> --seupgrade <secure element upgrade file> --app <application image> --dep-app <statement:version> --dep-se <staetment:version> --dep-boot <statement:version>

Dependency Statement

The dependency statement may be one of the following:

Simplicity Commander Input

Statement

g

Greater than

geq

Greater than or equal

eq

Equal

leq

Less than or equal

l

Less than

The --dep-app option takes an uint32 as version input, while the --dep-se and --dep-boot options take the version input in the format major.minor.patch.

Command Line Input Example

$ commander gbl create se-upgrade.gbl --app myapp.s37 --seupgrade secure-element.seu --bootloader my-bootloader.s37 --dep-app geq:0x01020002 --dep-boot l:0.5.7 --dep-se g:1.2.3

Creates a GBL where the application version must be greater than or equal to version 0x01020002, bootloader version must be less than version 0.5.7, and secure element upgrade version must be greater than version 1.2.3.

Command Line Output Example

Parsing file myapp.s37
Initializing GBL file...
Setting version dependency of Application to >= 0x00120002
Setting version dependency of Bootloader to < 0x00050007
Setting version dependency of SE upgrade image to > 0x00010203
Adding version dependencies to GBL...
Adding application to GBL...
Adding bootloader to GBL...
Adding Secure Element upgrade image to GBL...
Writing GBL file se-upgrade.gbl
DONE

Create a Delta GBL File#

Creates a Gecko Bootloader (GBL) file which contains the difference between two specific application versions for minimal upgrade file size. For more information on delta updates, see UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Command Line Syntax

$ commander gbl create <gblfile> --app <new application image file>  --delta-app <old application image file> [--compress lzma|lz4]

Symbol Information

The calculation of the delta between two application versions is significantly improved by having access to symbol information. When given files without symbol information (typically srec or hex files), Simplicity Commander will try to find ELF files with the same name in the same directory, and extract the symbol information from the ELF file. For example, if Commander is given --app release/1.3.0/app.s37 --delta-app release/1.2.0/app.s37, it will try to find app.axf, app.out, or app.elf in both of the release/1.3.0/ and release/1.2.0/ folders. Symbol information for both versions is required.

Secure Boot

If using secure boot, please ensure that both the old and the new application file is signed. The signature is then restored as part of applying the delta patch.

Additionally, delta GBL files may be signed and/or encrypted just like regular GBL files. See Creating a Signed and Encrypted GBL Upgrade Image File from an Application for details.

Version Dependency

Simplicity Commander will automatically extract the version of the old application and add a version dependency tag to the GBL. See Create a GBL File with Version Dependencies for details on version dependencies. If a specific version is provided with the --dep-app option, this is used instead of the version found in the application image.

Compression

Delta GBL files can be compressed using LZMA or LZ4 compression. See GBL File Creation with Compression for details.

Command Line Input Example

$ commander gbl create delta-upgrade.gbl --app app_1.3.0.s37 --delta-app app_1.2.3.s37

Command Line Output Example

Parsing file app_1.3.0.s37...
Initializing GBL file...
Parsing file app_1.2.3.s37...
Filling with 0xFF from 0x0800631c to 0x08006320
Automatically adding dependency to the detected version of "--delta-app"...
Setting version dependency of Application to = 0x00010203
Writing GBL file delta-upgrade.gbl...
DONE