GBL4 Commands#

Creates and parses Gecko Bootloader (GBL) version 4 files for devices that support GBL4. GBL4 files are used to upgrade the bootloader, application, and/or SE firmware of supported devices.

GBL4 File Creation With Config File#

There are two ways to create a GBL4 file.

Note: When the --config option is used in the create command, all other command line options defining the output file are ignored.

A template configuration file can be created using the gbl4 createconfig command.

GBL4 Config File Format#

The configuration file is structured into several sections - manifest, se_upgrade, and updates. All sections are optional, but at least either one update file or an SE upgrade must be provided.

Manifest#

The manifest section sets parameters which apply to the GBL file as a whole.

Product ID#

The product ID is a 16 byte long identifier. It is extracted from the application image, if available. If the product ID is present in both the application and the configuration file, the entry in the configuration file is used. If not provided, the default is zero.

Bundle Version#

The bundle version is the version of the upgrade bundle. Lower versions will be rejected by the bootloader. If not provided, the default is zero.

Minimum Version#

The minimum version is the minimum acceptable previous bundle version to which this update can be applied. This may be needed if DFU is only a partial update.

Certificate and Signature#

The GBL file can be signed with a private key, optionally using a delegate certificate authorizing this key pair. See Generate Certificate and Generating a Signing Key for details.

SE Upgrade#

The se_upgrade section is used to include a Secure Engine (SE) upgrade file in seuv2 format.

Updates#

The updates section provides a list of one or more updates to be included. For example, an update can be a bootloader or an application image.

Data#

Each update must specify an update file in one of the supported formats: s37, hex, or elf.

Type, Capabilities, Version#

The application type, capabilities, and version are by default extracted from the ApplicationProperties_t struct. These values can be overridden by the config file. If not provided at all, they are set to zero by default.

Compression#

Each update can optionally be compressed. Supported algorithms are lz4 and lzma.

Encryption#

Each update can be encrypted with a symmetric key using the aes-ctr-128 algorithm. Keys can be generated using the util keygen command.

Block Size#

A list of hashes of the update data can be added to the GBL file. This can be useful for streaming updates, to allow authenticating the update on the fly. To use this feature, a block size must be set. The block size sets the size of a block of data for which a hash will be generated.

Command Line Usage#

Command Line Syntax

$ commander gbl4 create <gblfile> --config <configfile> --device <device>

Command Line Input Example

$ commander gbl4 create example.gbl --config gbl_config.yaml

Command Line Output Example

Initializing GBLV4 file...
Reading SE upgrade file se_upgrade.seu
Parsing file example.s37...
Writing example.gbl...
Image SHA256: cd74050714df55752d8612474239c12941b19eaa67baa245342c80373abf144b
R = 7A3C8E2FF71DB6AE5351DB565967A16821BF5AC40483432E6630BCCCBC62E17C
S = 517ED3971A49A52E673446D11A187DD1B0A0331235CC52AE6E8393CAF711D313
DONE

GBL4 File Creation with Command Line Options#

GBL4 files can also be created using command line options. The command line options largely correspond to the options available in GBL4 Config File Format, with the following limitations/simplifications:

  • The --compress and --encrypt options apply to all updates.

  • Application type, capabilities, and version cannot be set manually.

  • Block hashes are not supported.

Command Line Syntax

$ commander gbl4 create <gblfile> [--data <filename>] [--seupgrade <filename>] [--compress <compression algorithm>] [--encrypt <keyfile>] [--bundleversion <version>] [--productid <product id>] [--minversion <version>] [--sign <keyfile>] [--certificate <certificate file>] [--device <device>]

Command Line Input Example

$ commander gbl4 create app.gbl --data example.s37 --compress lz4 --encrypt encryption_key.pem --sign signing_key.pem

Command Line Output Example

Initializing GBLV4 file...
Parsing file example.s37...
Writing GBL file app.gbl...
Image SHA256: 5ba67b656103a3539f0f3802a4398f0babb3ff182fe9890962e578052571d4ea
R = 6845219257E660918B7BAE26FFF3DC7BBE8150DA3281CE8881B7088E9E973CE6
S = B8C5B58987FA3C7E44444B7C43096A41F48D245ED148C4E0863F0F91013381E1
DONE

Create a GBL4 File for Bootloader Upgrade#

Creates a Gecko Bootloader (GBL) file from a bootloader image and writes the output to the specified bootloader image filename.

Command Line Syntax

$ commander gbl4 create <gblfile> --data <bootloader image file> [--compress <compression algorithm>] [--encrypt <keyfile>] [--bundleversion <version>] [--productid <product id>] [--minversion <version>] [--sign <keyfile>] [--certificate <certificate file>] [--device <device>]

Command Line Input Example

$ commander gbl4 create bootloader.gbl --data bootloader.s37 --productid 45879184758294571094581908385139 --compress lz4 --bundleversion 0x00000002 --minversion 0x0000001

Command Line Output Example

Initializing GBLV4 file...
Parsing file bootloader.s37...
Writing GBL file bootloader.gbl...
DONE

Creating a GBL File for Secure Engine Upgrade#

The Secure Engine can be upgraded using a Secure Engine upgrade binary provided by Silicon Labs. This command creates a GBL file containing a Secure Engine upgrade file and writes the output to the specified GBL filename.

Command Line Syntax

$ commander gbl4 create <gblfile> --seupgrade <SE upgrade file> [--bundleversion <version>] [--productid <product id>] [--minversion <version>] [--sign <keyfile>] [--certificate <certificate file>] [--device <device>]

Command Line Input Example

$ commander gbl4 create se-upgrade.gbl --seupgrade se_fw.seuv2

Command Line Output Example

Initializing GBLV4 file...
Reading SE upgrade file from se_fw.seuv2
Writing GBL file se-upgrade.gbl...
DONE

GBL4 Create Configuration File#

This command creates a default template configuration file for creating a GBL file. The configuration file is a YAML file that describes the GBL file to be created. See GBL4 Config File Format for details on the fields of the config file.

Command Line Syntax

$ commander gbl4 createconfig --outfile <configfile>

Command Line Input Example

$ commander gbl4 createconfig --outfile gbl_config.yaml

Command Line Output Example

Writing template configuration file gbl_config.yaml...
Please modify to your needs.
DONE

Below is an example of the default configuration file:

manifest:
  product_id: "[16 B ID] (default from app or 00000000000000000000000000000000)"
  bundle_version: "[version] (default 0x00000000)"
  min_version: "[version] (default 0x00000000)"
  certificate: "[path to file] (optional)"
  signing_key: "[path to file] (optional)"
se_upgrade:
  se_file: "[path to file] (optional)"
updates:
  - data: <path to file>
    app_type: "[uint32] (default from app or 0x00000000)"
    app_capabilities: "[uint32] (default from app or 0x00000000)"
    version: "[uint32] (default from app or 0x00000000)"
    compression_scheme: "[none | lz4 | lzma] (default none)"
    encryption_scheme: "[none | aes-ctr-128] (default none)"
    block_size: "[size in bytes] (default 0/disabled)"

GBL4 File Information#

Parse a Gecko Bootloader (GBL) file and shows information about the file.

Command Line Syntax

$ commander gbl4 info <gbl filename>

Command Line Input Example

$ commander gbl4 info example.gbl

Command Line Output Example

GBL manifest info:
  GBL version:          4.0.0
  Encryption:           Enabled
  Compression:          Disabled
  Certificate:          Not used
  Signature type:       ECDSA-P256
  Product version:      00000000000000000000000000000000
  Bundle version:       0x00000000
  Min previous version: 0x00000000

Update info:
  Target address:            0x01008000
  Version:                   0x00000001
  Binary size:               43916 B
  Compression scheme:        None
  Encryption scheme:         AES-CTR-128
  Secure boot scheme:        Appinfo
  Signature block size:      0
  Number of blocks:          0

DONE