Convert and Modify File Commands#
The convert command performs image file conversion and manipulation. It supports the following actions:
Converting between file formats.
Merging several image files.
Extracting subsets of images.
Patching bytes.
Setting token data.
The convert command can either write its output to a file or print it to standard out in human-readable format similar to the readmem command. When writing to a file, the file format is auto-detected based on the file extension used.
The convert command works off-line without any J-Link/debug connection. The command is device-agnostic, except when working with tokens or Ember Bootloader (EBL) files. In this case, you must use the --device option.
Command Line Syntax
$ commander convert [infile1] [infile2 …] [options]Combine Two Files#
Converts two files with different file formats into one specified output file.
Command Line Syntax
$ commander convert <filename> <filename> [--address <address>] --outfile <filename>Command Line Input Example
$ commander convert blink.bin userpage.hex --address 0x0 --outfile blinkapp.s37Combines blink.bin and userpage.hex to blinkapp.s37. The address option is used to set the start address of the .bin file, since bin files doesn’t contain any addressing information. The address value is interpreted as a hexadecimal number. If more than one .bin file is supplied, the same start address is used for all. If this is not desirable, consider converting the bin files to s37 or hex in a separate preparation step.
Command Line Output Example
Parsing file blink.bin...
Parsing file userpage.hex...
Writing to blinkapp.s37...
DONEDefine Specific Bytes#
Like the flash command, the convert command supports the --patch option for setting arbitrary unsigned integers at any address.
Command Line Syntax
$ commander convert [filename] --patch <address>:<data>[:length] [--outfile <filename>]Command Line Input Example
$ commander convert blink.s37 --patch 0x0FE00000:0x12345:4 --outfile blink.hexConverts blink.s37 to hex format, while simultaneously defining the first four bytes of the user page to 0x00012345. This works just like flash blink.s37 --patch 0x0FE00000:0x``12345:4, but works against a file instead of writing to a device flash.
Command Line Output Example
Parsing file blink.s37...
Patching 0x0FE00000 = 0x00012345...
Writing to blink.hex...
DONEDefine Tokens#
Like the flash command, the convert command supports the --tokengroup, --token, and --tokenfile options for setting token data while executing file conversion.
Command Line Syntax
$ commander convert [filename] --tokengroup <token group> [--tokenfile <filename>]
[--token <token name>:<token data>] [--device <device>] [--outfile <filename>]
Command Line Input Example
$ commander convert blink.s37 --tokengroup znet --tokenfile tokens.txt --device EFR32MG1P --outfile blink.hexConverts blink.s37 to hex format, while simultaneously defining the tokens defined in tokens.txt and on the command line. Works just like the corresponding options with flash, but writes to a file instead of flash.
Command Line Output Example
Parsing file blink.s37...
Writing to blink.hex...
DONEDump File Contents#
Like the readmem command, the convert command will print its output in human-readable format to standard out if no output file is given. The value of the address option is interpreted as a hexadecimal number.
Command Line Syntax
$ commander convert <filename> [--address <bin file start address>]Command Line Input Example
$ commander convert blink.bin --address 0x0 userpage.hexIf the --outfile option is not used, the data is printed to stdout instead of writing to file.
Command Line Output Example
Parsing file blink.bin...
Parsing file userpage.hex...
{address: 0 1 2 3 4 5 6 7 8 9 A B C D E F}
00000000: 10 04 00 20 B5 0A 00 00 57 08 00 00 8B 0A 00 00
00000010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00000020: 00 00 00 00 00 00 00 00 00 00 00 00 97 0A 00 00
00000030: 00 00 00 00 00 00 00 00 D1 0A 00 00 13 06 00 00
00000040: D3 0A 00 00 D5 0A 00 00 D7 0A 00 00 D9 0A 00 00
00000050: DB 0A 00 00 DD 0A 00 00 DF 0A 00 00 E1 0A 00 00
00000060: E3 0A 00 00 E5 0A 00 00 E7 0A 00 00 E9 0A 00 00
00000070: EB 0A 00 00 ED 0A 00 00 EF 0A 00 00 F1 0A 00 00
<shortened data for documentation>
00000ac0: C5 0A 00 00 C0 46 C0 46 C0 46 C0 46 FF F7 CA FF
00000ad0: FE E7 FE E7 FE E7 FE E7 FE E7 FE E7 FE E7 FE E7
00000ae0: FE E7 FE E7 FE E7 FE E7 FE E7 FE E7 FE E7 FE E7
00000af0: FE E7 FE E7 00 36 6E 01 00 80 00 00
{address: 0 1 2 3 4 5 6 7 8 9 A B C D E F}
0fe00000: 45 23 01 00 FF FF FF FF FF FF FF FF FF FF FF FF
0fe00010: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
0fe00020: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
<shortened data for documentation>
0fe007e0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
0fe007f0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
DONESigning an Application for Secure Boot#
Signs an application for use with a Secure Boot bootloader. 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 convert <image file> --secureboot --keyfile <signing key> --outfile <signed image file>Command Line Input Example
$ commander convert example.s37 --secureboot --keyfile mykey --outfile example-signed.s37This example signs the image file named example.s37.
Command Line Output Example
Parsing file example.s37...
Image SHA256: 4591da45b6c40a424b81753001708061d5319197adec5188f4acc512cfb88e65
R = 8E417EB4CBC584218A8605FCF3E778F2A7810F2CAE190CB2EF4D0DF842829CC1
S = 5B095025FFD571699725107C4666C0B8B867370E990B73E74A0502CB9788DCA8
Writing to example-signed.s37...
DONESigning an Application for Secure Boot using a Hardware Security Module#
Prepares an application for signing for use with a Secure Boot enabled bootloader using a Hardware Security Module (HSM). 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 convert <image file> --secureboot --extsign --outfile <image file for external signing>Command Line Input Example
$ commander convert example.s37 --secureboot --extsign --outfile example.s37.extsignThis example creates an output in the form that an HSM can create a signature over of the entire file. This signature can again be written to the file using the command described in the section below.
Command Line Output Example
Parsing file example.s37...
Writing to example.s37.extsign...
DONESigning an Application for Secure Boot Signing using a Signature Created by a Hardware Security Module#
Signs an application for use with a Secure Boot bootloader using a signature created by a Hardware Security Module (HSM). 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 convert <image file> --secureboot --signature <signature from external signing> --outfile <signed image file>Command Line Input Example
$ commander convert example.s37 --secureboot --signature example.s37.extsign.sig --outfile example-signed.s37This example signs the image file example.s37 using a signature obtained from an HSM using the .extsign file generated in the section above. The input file (example.s37) used with this function must be the same file as was used when generating the .extsign file in the section above.
Command Line Output Example
Parsing file example.s37...
Parsing signature file example.s37.extsign.sig...
R = 8E417EB4CBC584218A8605FCF3E778F2A7810F2CAE190CB2EF4D0DF842829CC1
S = 5B095025FFD571699725107C4666C0B8B867370E990B73E74A0502CB9788DCA8
Writing to example-signed.s37...
Overwriting file: example-signed.s37...
DONEAdding a CRC32 for Gecko Bootloader#
This option adds a CRC32 (32-bit cyclic redundancy check) of the image that the Gecko Bootloader can use to ensure image integrity when Secure Boot is not used. This feature requires that an ApplicationProperties_t struct is present in the image. For more details on the ApplicationProperties_t struct, 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 convert <image file> --crc --outfile <image file with CRC>Command Line Input Example
$ commander convert example.s37 --crc --outfile example-crc.s37This example adds a checksum to the image file named example.s37.
Command Line Output Example
Parsing file example.s37...
Appending CRC32 checksum...
Writing to example-crc.s37...
DONESigning an Application for Secure Boot using an Intermediary Certificate#
Signs an application for use with a Secure Boot bootloader using an intermediary certificate. When using an intermediary certificate, the ApplicationProperties_t struct must be present in the image. For more information on the ApplicationProperties_t struct, 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.
Secure Boot verification via an intermediary certificate is only supported on Series 2 EFR32 devices. Secure Boot must be enabled before signing a bootloader with an intermediary certificate. For more information about enabling Secure Boot, see Write User Configuration.
There are two ways of signing the application:
Providing the private keyfile corresponding to the public key embedded in the certificate directly.
Preparing an application for signing with a Hardware Security Module (HSM) by generating an output in the form that an HSM can create a signature over the entire file. The signature can then be written to the file by passing it to Simplicity Commander as described below.
Note: Simplicity Commander does currently not support the generation of certificates for Secure Boot signing. This will be available in a future version of Simplicity Commander.
Command Line Syntax
$ commander convert <image file> --secureboot --certificate <certificate file> --keyfile <keyfile> --outfile <signed image file>$ commander convert <image file> --secureboot --certificate <certificate file> --extsign --outfile <image file for external signing>$ commander convert <image file> --secureboot --certificate <certificate file> --signature <signature> --outfile <signed image file>Command Line Input Example
$ commander convert example.s37 --secureboot --certificate example_certificate.bin --keyfile public_certificate_key.pem --outfile example-signed.s37This example signs the image file example.s37 using an intermediary certificate. The keyfile used to sign the application corresponds to the public key embedded in the certificate. Simplicity Commander always validates the key before signing the application.
Command Line Output Example
Parsing file example.s37...
Private key matches public key in certificate.
R = 137EA7A19F6100E1EFA5C185CA952B67137D0597F4A89C7543BC5A49A7A6681E
S = C537A833018C3A23CF1EBDBAB04559482B0B5333A7C21556E6B42EDA1D1A5102
Writing to example-signed.s37...
DONEAdd a Trust Zone Decryption Key#
Adds an Advanced Encryption Standard (AES) encryption/decryption key to a bootloader image for TrustZone secure key storage. Requires Application Properties struct version 1.2 or higher.
Command Line Syntax
$ commander convert <image file> --aeskey <keyfile> --outfile <bootloader with decryption key>Command Line Input Example
$ commander convert my_bootloader.s37 --aeskey my_key.txt --outfile my_bootloader_with_key.s37Adds the decryption key my_key.txt to the bootloader image named my_bootloader_with_key.s37.
Command Line Output Example
Parsing file my_bootloader.s37...
Writing to my_bootloader_with_key.s37...
DONEExtract Sections from ELF Files#
Extract sections from an Executable and Linkable Format (ELF) file and convert into the specified output file. If neither the --include-section nor the --exclude-section option is used, Simplicity Commander will extract all .text sections, as well as sections of type progbits with address not equal to 0x0.
Command Line Syntax
$ commander convert <filename> [--include-section <section> --exclude-section <section>] --outfile <filename>Command Line Input Example
$ commander convert application.out --include-section text_apploader --outfile apploader.s37Creates an S-record file from the text_apploader section of an ELF file.
Command Line Output Example
Parsing file application.out...
Writing to apploader.s37...
DONE