Post-Build Editor (PBE)#

The Post-Build Editor (PBE) is provided to make it easy for the user to specify actions required on the project output binary to create various types of image files. The tool provides the following capabilities:

  • Adding signatures or checksums to application or bootloader binaries

  • Merging applications and other data into production images

  • Packaging applications and other data into upgrade files, including GBL and Zigbee OTA.

Workflow#

The PBE-defined post-build steps are stored in a post-build YAML file with an '.slpb' extension that can be used either from within Simplicity Studio 5 (SSv5) or by running Simplicity Commander on the command line. Simplicity Studio IDE projects and SLC exported projects will execute the post-build steps automatically using the post-build command step to call the command line version of Simplicity Commander. Also, the various project configurator generators (GCC Makefile, Visual Studio Code Compatible (beta), and IAR Embedded Workbench) will include the necessary Simplicity Commander call to automatically perform the post build steps when the project is built in those environments.

Several example .slpb files are included in the Gecko SDK Suite (GSDK) starting with version 4.2.0.0. For examples of projects that use the .slpb feature, see the TrustZone examples. Refer to UG162: Simplicity Commander User's Guide for details on the signing and secure boot information in the following tasks.

Tasks#

The PBE supports four different tasks: copy, convert, create_gbl, and create_ota.

Copy#

The copy task is used to copy a file from one folder to another and it is also the starting point for specifying the post-build sequence.

post build editor copypost build editor copy

  • Required Arguments:

    • Input name: The project relative path and filename to copy.

    • Output name: The destination project relative path and filename. Folders will be created as needed.

  • Optional Arguments:

    • Export output as: The parameter name to assign to the output file.

Convert#

The convert task performs various actions on the binary to convert it to another form, such as adding a CRC or a signature. See the Simplicity Commander User’s Guide 'Convert and Modify File Commands' section for details.

post build editor convertpost build editor convert

  • Required Arguments:

    • Input name: The project relative path and filename to convert.

    • Output name: The destination project relative path and filename. Folders will be created as needed.

  • Optional Arguments:

    • Export output as: The parameter name to assign to the output file.

    • Add CRC checkbox: To calculate and store the CRC32 on the bootloader image. The Gecko Bootloader can use the CRC to ensure image integrity when Secure Boot is not used.

    • Secure boot: Private Key and Intermediary Certificate to use to sign the secure boot image.

    • Signature file to sign the image

    • Include-section: <ELF section to include in image>

    • Exclude-section: <ELF section to exclude from image>

    • Verify: Key file

The Include-section and Exclude-section optional arguments can be used if the input file is an Executable and Linkable Format (ELF) file. If neither the Include-section nor the Exclude-section arguments are used, all .text sections will be extracted, as well as sections of type progbits with address not equal to 0x0.

Create_gbl#

The create_gbl task creates a Gecko Bootloader file (GBL) from an application and/or bootloader image that optionally includes a Secure Element (SE) upgrade image. See the Simplicity Commander User’s Guide "GBL Commands" section for details.

post build editor create_gblpost build editor create_gbl

  • Required Arguments:

    • Output name: The destination project relative path and filename. Folders will be created as needed.

  • Optional Arguments:

    • Export output as: The parameter name to assign to the output file.

    • Application Image: Application image file.

    • Bootloader: Bootloader image file.

    • SE upgrade: Secure Element upgrade image file.

    • Metadata: Metadata bin file to include in the image.

    • Compression: Compression method for output (none, lzma, lz4).

    • Sign using HWM checkbox: Check if the signature will be created using Hardware Security Module.

    • Signing key

    • Signing certificate

    • Encrypt: Encryption key used to encrypt image.

    • Include-section: <ELF section to include in image>.

    • Exclude-section: <ELF section to exclude from image>.

Create_ota#

The create_ota task creates a Zigbee Over-the-air (OTA) bootloader file from one or more GBL files. See the Simplicity Commander User’s Guide "OTA Commands" section for details.

NOTE: The "Input name" field should be ignored; it will be removed in a future release. The "Input name" is a duplicate of the "Upgrade Image". Using both will add two copies of the file to the output.

post build editor create_otapost build editor create_ota

  • Required Arguments:

    • Upgrade Image: The project relative path of the gbl file.

    • Output name: The destination project relative path and filename. Folders will be created as needed.

    • Manufacturer ID

    • Image type

    • Header string

    • Firmware Version

  • Optional Arguments:

    • Export output as: The parameter name to assign to the output file

    • Manufacturer tag: Tag ID.

    • Stack version

    • Credentials

    • Target device EUI64

    • Minimum HW version

    • Maximum HW version

Example#

Series 1 Combined Bootloader#

An example of the PBE can be seen by creating a Series 1 bootloader for an EFR32MG12 target part. The PBE file copies the output .s37 of the main bootloader and adds a CRC to it. Then it copies the pre-built first stage bootloader image into a combined bootloader file that can be programmed to the device. To create this example:

  1. Add BRD4161A to the Launcher Perspective [My Products] window and select it.

  2. Make sure GSDK 4.2.0 or later is the Preferred SDK.

  3. Click the Example Projects and Demos tab and click the Bootloaders filter checkbox

  4. Click [Create] for “Bootloader – SoC Internal Storage (single image on 1MB device)

  5. Build the project. In the build console output will be a call to commander.exe with the postbuild argument and the .slpb file:

"C:\SiliconLabs\SimplicityStudio\v5\developer\adapter_packs\commander\commander.exe" postbuild "C:\Users\USERNAME\SimplicityStudio\v5_workspace\bootloader-storage-internal-single/bootloader-storage-internal-single.slpb" --parameter build_dir:"C:\Users\USERNAME\SimplicityStudio\v5_workspace\bootloader-storage-internal-single\GNU ARM v10.3.1 - Default"
Parsing file C:\Users\japitt\SimplicityStudio\v5.rel.Staging_1865\bootloader-storage-internal-single/bootloader-storage-internal-single.slpb...
Running task copy...
Running task convert...
Running task convert...
DONE

The 'artifact' folder is created with three files in it:

post build editor artifact folderpost build editor artifact folder

Opening the .slpb file shows three operations with the last one being a convert that takes the ‘autogen/first_stage.s37’ file and adds it to the main bootloader image in a new file called ‘bootloader-storage-internal-single-combined.s37.

post build editor Series 1 Combined Bootloaderpost build editor Series 1 Combined Bootloader

Series 2 OTA Image Creation#

The following example was created using an EFR32MG24B210F1536IM48 target on a BRD4186C radio board. It includes all four tasks and can be created with the following steps:

  1. Create and build a "Bootloader - SoC Internal Storage single image with LZMA compression, 1MB Flash" (bootloader-storage-internal-single-lzma) project.

  2. Create and build a "Zigbee SoC ZigbeeMinimal" (ZigbeeMinimal) project.

  3. Open the bootloader .slpb file in the PBE. It will have copy and convert tasks already defined:

    post build editor EFR32MG24 Bootloaderpost build editor EFR32MG24 Bootloader

Add a Create_gbl Task#

  1. Select the Convert task and then click the "+" icon and select "create_gbl".

  2. Next to 'Application Image', click BROWSE and select the ZigbeeMinimal.s37 file. Multiple application images could be entered in this field if needed.

  3. Next to 'Bootloader', click BROWSE and select the bootloader .s37 file.

  4. Next to 'SE Upgrade', click BROWSE and browse to the Secure Element upgrade image file "s2c4_se_fw_upgrade_2v2p1.seu".

  5. Click the 'Compression' dropdown and select "lzma".

  6. Click the 'Output name' field and enter "artifact/CompressedZigbeeMinimal.gbl".

  7. Click SAVE. The GBL task should look like this:

    post build editor EFR32MG24 GBL Taskpost build editor EFR32MG24 GBL Task

Add a Create_ota Task#

  1. Click the "+" icon and select "create_ota".

  2. Click the 'Output name' field and enter "artifact/CompressedZigbeeMinimal.ota".

  3. Click the 'Manufacturer ID' field and enter your manufacturer ID. A dummy value of 0x1002 is used in this example.

  4. Click the 'Image type' field and enter a hex number for the image type. A dummy value of 0x5678 is used in this example.

  5. Click the 'Header string' field and enter "Example".

  6. Click the 'Upgrade Image' field and enter the path and .gbl filename from the create_gbl task - artifact/CompressedZigbeeMinimal.gbl. Note multiple .gbl files could be entered in this field if needed.

  7. Click the 'Firmware Version' field and enter an unsigned integer value for the version. A dummy value of 0x1002 is used in this example.

  8. Click SAVE. The OTA task should look like this:

    post build editor EFR32MG24 OTA Taskpost build editor EFR32MG24 OTA Task

Test the Post-Build File#

Build the project and at the end of the build commander will be called with the .slpb file and each of the tasks will be run:

"C:\SiliconLabs\SimplicityStudio\v5\developer\adapter_packs\commander\commander.exe" postbuild "C:\SiliconLabs\workspaces\v5_workspace\bootloader-storage-internal-single-lzma/bootloader-storage-internal-single-lzma.slpb" --parameter build_dir:"C:\SiliconLabs\workspaces\v5_workspace\bootloader-storage-internal-single-lzma\GNU ARM v10.3.1 - Default"
Parsing file C:\SiliconLabs\workspaces\v5_workspace\bootloader-storage-internal-single-lzma/bootloader-storage-internal-single-lzma.slpb...
Running task copy...
Running task convert...
Running task GBL create...
Running task OTA create...
DONE