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. A Simplicity Studio IDE project 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. As of the current release, the only project examples that include an .slpb file are bootloader projects for Series 1 and Series 2 bootloaders. The bootloader .slpb files are simple examples. More full-featured examples will be include in subsequent releases. 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.

NOTE: The PBE output of this task has syntax errors that must be manually edited by clicking the SHOW YAML button after filling out the UI fields. The manual edits are described below the description.

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>.

Manual Edits: After filling in the desired fields and clicking SAVE, click SHOW YAML and then make the following changes

  • If a compression algorithm is specified, change it to lower case. For example, change LZMA to 'lzma' or LZ4 to 'lz4'.

  • For any lines with app, bootloader or seupgrade, the file path must start on the same line as that label and the leading '-' must be deleted.

An example of the correct syntax is provided.

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 PBE output of this task has syntax errors that must be manually edited by clicking the SHOW YAML button after filing out the UI fields. Also the "Input name" field should be ignored; it will be removed in the next release. The "Input name" is a duplicate of the "Upgrade Image". Using both will add two copies of the file to the output. The manual edits are described below the description.

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: NOTE: This required field is currently missing from the PBE UI. See the manual edits below for the syntax.

  • 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

Manual Edits: After filling in the desired fields and clicking SAVE, click SHOW YAML and then make the following changes:

  • Add a firmware-version: line

  • Edit the upgrade-image; line. The file path must start on the same line as that label and the leading '-' deleted.

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 SAVE. The OTA task should look like this:

    post build editor EFR32MG24 OTA Taskpost build editor EFR32MG24 OTA Task

Edit the YAML File#

  1. Click SHOW YAML.

  2. Change the compression algorithm from 'LZMA' to 'lzma'.

  3. Edit the app, bootloader, seupgrade and upgrade_image file paths, removing the newline and "-".

  4. Add a line at the end for 'firmware-version:' with the version of this OTA image: firmware-version: "0x10001".

  5. Save the file. The file contents should look like this:

  ---
parameters:
- name: "build_dir"
constants:
- name: "project_name"
  value: "bootloader-storage-internal-single-lzma"
steps:
- task: "copy"
  output: "artifact/{{project_name}}.s37"
  export: "bootloader_main_stage"
  input: "{{build_dir}}/{{project_name}}.s37"
- task: "convert"
  output: "artifact/{{project_name}}-crc.s37"
  export: "bootloader_binary"
  input: "artifact/{{project_name}}.s37"
  crc: true
- task: "create_gbl"
  output: "artifact/CompressedZigbeeMinimal.gbl"
  app: "C:/SiliconLabs/workspaces/v5_workspace/ZigbeeMinimal/GNU ARM v10.3.1 - Default/ZigbeeMinimal.s37"
  compress: "lzma"
  bootloader: "GNU ARM v10.3.1 - Default/bootloader-storage-internal-single-lzma.s37"
  seupgrade: "C:/Users/USERNAME/SimplicityStudio/SDKs/gecko_sdk4_2_0/util/se_release/public/s2c4_se_fw_upgrade_2v2p1.seu"
- task: "create_ota"
  output: "artifact/CompressedZigbeeMinimal.ota"
  string: "\"Example\""
  upgrade-image: "artifact/CompressedZigbeeMinimal.gbl"
  image-type: "0x5678"
  manufacturer-id: "0x1002"
  firmware-version: "0x10001"

  1. 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