RPS Commands#

SiWx917 devices require that application binaries are converted to RPS images before flashing. Simplicity Commander can be used to convert M4 application binaries to RPS images, apply security features, and to combine multiple RPS images into a single RPS file.

Simplicity Commander's RPS image creation supports bin, hex, SRec and ELF image formats. Commander will prepend an RPS style header to the provided application image, containing information used by the device's bootloader. An application version number may be provided using the --app-version option, and additional firmware/device information can be provided using the --fw-info option. If you intend on combining one or multiple RPS application images, the --combinedimage flag can be provided to prepare the image for combining with other eligible RPS images.

Simplicity Commander also supports creating RPS key images for upgrading on-device M4 keys.

Create an RPS File From a Binary Image#

To create an RPS file from a binary image, you must provide an application start address using the --address flag.

Command Line Syntax

$ commander rps create <output filename> --app <filename> --address <start address> [--app-version <version no.> --fw-info <firmware info> --combinedimage]

Command Line Input Example

$ commander rps create output.rps --app app.bin --address 0x08212000

This command line creates an RPS file from a binary image with flash address '0x08212000' and saves it to the file named 'output.rps'.

Command Line Output Example

Parsing file app.bin...
RPS file successfully created at 'output.rps'
DONE

Create an RPS File From an ELF Image#

When generating an RPS file from an Execution and Linkable Format (ELF) image, you can use the --include-section and --exclude-section options to either include or exclude certain ELF sections from the application image of the output RPS file. If neither of these options is provided, Simplicity Commander will include all sections that appear to be part of the application.

You can include or exclude multiple sections by providing the respective options repeatedly.

Command Line Syntax

$ commander rps create <output filename> --app <filename> [--include-section <section> --exclude-section <section> --app-version <version no.> --fw-info <firmware info> --combinedimage]

Command Line Input Example

$ commander rps create output.rps --app app.axf --include-section .text --include-section .data

This command line creates an RPS file from the sections '.text' and '.data' of an ELF application file and saves it to the file named 'output.rps'.

Command Line Output Example

Including ELF section(s):
  .text
  .data
Parsing file app.axf...
RPS file successfully created at 'output.rps'
DONE

Create an RPS File from a Hex/s37 Image#

You can create an RPS file from an Intel Hex (hex) image or from a Motorola S-record (s37) image.

Command Line Syntax

$ commander rps create <output filename> --app <filename> [--app-version <version no.> --fw-info <firmware info> --combinedimage]

Command Line Input Example

$ commander rps create output.rps --app app.hex

This command line creates an RPS file from a hex image and saves it to the file named 'output.rps'.

Command Line Output Example

Parsing file app.hex...
RPS file successfully created at 'output.rps'
DONE

Create an RPS File For Upgrading On-Device Key#

Creating an RPS key file requires a new key to store on the device, the previous (current) key stored on the device, as well as a private ECDSA key (.pem) for signing the RPS file. Only the device's M4 public key and the M4 OTA key can be upgraded, being denoted by the key types public and OTA, respectively.

Options --new-key and --prev-key support keys as plain hex-strings (e.g. '0123456789ABCDEF'), or as .h-files containing comma-separated hexadecimal values (each prefixed with '0x'). If the provided key type is public, the new and previous keys can also be provided as .pem-files. Alternatively, an eligible key configuration JSON file can be provided to let Commander collect the required keys automatically.

Command Line Syntax

$ commander rps create <output filename> --key-type <'public'|'ota'> --new-key <key> --prev-key <key> --sign <filename>

Command Line Input Example

$ commander rps create key.rps --key-type 'public' --new-key new-key.h --prev-key old-key.h --sign private-key.pem

This command line creates an RPS key file for updating the on-device M4 public key, and saves it to the file named 'key.rps'.

Command Line Output Example

Parsing new key 'new-key.h'...
Parsing previous key 'old-key.h'...
Parsing signing key 'private-key.pem'...
Signing image...
Image SHA256: 1c01440a60849ff35f56ed09fb468bbf2f92f3c8d6e50cb5b9c12b4cb38c9df3
R = E03FC4A415E6FEA584F48CC08E1F8EE45090A2CE5E8C176C44720D8314DAEA1C
S = B7CED83970B74B2E75F3E42B229DBA022265BB6E319A777AA9F530380052494B
RPS file successfully created at 'key.rps'.
DONE

Create a Secure RPS Application Image#

RPS application images support multiple security-related features: AES-ECB-based encryption, AES-CBC MIC integrity check, and ECDSA signatures (SHA-256, SHA-384, and SHA-512). By default, these features are disabled, and a CRC-based integrity check is used on the RPS file contents.

The keys for encryption and MIC are symmetric keys (32 bytes in length), and can be provided as hex strings, .bin files or as .h-files containing comma-separated hexadecimal values (each prefixed with '0x'). Alternatively, an eligible key configuration JSON file can be provided to let Commander collect the required keys automatically. If MIC integrity check is used, a custom initialization vector (IV) for the MIC algorithm may be provided as a binary file containing a 16 byte IV, using the --iv option.

Command Line Syntax

$ commander rps create <output filename> --app <application filename> --encrypt <key> --mic <key> [--iv <iv>] --sign <key> [--sha <sha type>] [--app-version <version no.> --fw-info <firmware info> --combinedimage]

Command Line Input Example

$ commander rps create secure-app.rps --app app.hex --encrypt keyconfig.json --mic mkey.bin --sign private-key.pem --sha SHA-512

This command line creates a secure RPS file 'secure-app.rps' from the binary image 'app.hex', encrypted using the symmetric key in 'keyconfig.json', MIC protected using the key 'mkey.bin', and signed (SHA-512) using the private key 'private-key.pem'.

Command Line Output Example

Parsing file app.hex...
Parsing MIC key 'mkey.bin'...
Calculating MIC of image...
Parsing encryption key 'keyconfig.json'...
Encrypting image...
Parsing signing key 'private-key.pem'...
Signing image...
Image SHA512: cd7c5ca70167e91ae22e519e25e8f1f1967879bbfda852e75d77c1c3a54c07cd7
90a2ddfd54f0a55d065dd964cb1de49afb92f96d86acf52d591e213f1c41700
R = CE26333E667842859469622C4E35B72B1C1FCA7D148F58FD67F66C70449A4092
S = 91EA3A02A4B7374401A46161869819AA14065FE760C2781466BAD0643AD8FF60
RPS file successfully created at 'secure-app.rps'.
DONE

Convert an Existing RPS Application Image#

Simplicity Commander can be used to convert already existing non-secure (no encryption, MIC, or signature) RPS images (both NWP and M4 images) into secure images by applying AES-ECB encryption, AES-CBC MIC integrity check, and ECDSA signatures. Non-secure images can also be modified to support combining with other RPS images by providing the --combinedimage flag, which sets the COMBINED_IMAGE bit in the RPS header.

M4 RPS images are provided using the --app option, whereas TA RPS images are provided using the --nwpapp option.

Command Line Syntax

$ commander rps convert <output filename> --app <application filename> | --nwpapp <application filename> [--encrypt <key> --mic <key> --sign <key> --app-version <version no.> --fw-info <firmware info> --combinedimage]

Command Line Input Example

$ commander rps convert secure-app.rps --app app.rps --encrypt ekey.h --mic mkey.h --sign private-key.pem --app-version 0x00010209 --combinedimage

This command line takes the non-secure M4 RPS 'app.rps' and creates a secure RPS application image with encryption, MIC integrity check, and SHA-512 based signature, and saves it to the file named 'secure-app.rps' The command also sets a new application version number in the RPS header, and it prepares the image for combining.

Command Line Output Example

Setting COMBINED_IMAGE flag...
Parsing file app.hex...
Parsing MIC key 'mkey.h'...
Calculating MIC of image...
Parsing encryption key 'ekey.h'...
Encrypting image...
Parsing signing key 'private-key.pem'...
Signing image...
Image SHA256: e53775814dc61c2ecbe14f1b1d9310c8d79ad96681a9f6258cd427cbc9cd6576
R = CE26333E667842859469622C4E35B72B1C1FCA7D148F58FD67F66C70449A4092
S = 91EA3A02A4B7374401A46161869819AA14065FE760C2781466BAD0643AD8FF60
RPS file successfully created at 'secure-app.rps'.
DONE

Combine Multiple RPS Images Into a Single RPS File#

Using Simplicity Commander, you can combine an M4 RPS application image with an NWP RPS application image into a single RPS file. For an RPS image to be eligible for combining, the COMBINED_IMAGE bit must be set in the header of the image, either during the image's creation, or by converting an already existing non-secure RPS image.

The M4 image is provided via the --app option, and is always placed first within the combined image. The TA image is provided using the --nwpapp option.

The combined image can be signed with a private ECDSA key, provided in .pem format.

Command Line Syntax

$ commander rps convert <output filename> --app <M4 application filename> --nwpapp <TA application filename> [--sign <key filename>]

Command Line Input Example

$ commander rps convert combined-image.rps --app image1.rps --nwpapp image2.rps --sign private-key.pem

This command line takes the M4 RPS image 'image1.rps' and combines it with the TA RPS image 'image2.rps' into a single RPS image with signature.

Command Line Output Example

Combining images...
  Adding image1.rps...
  Adding image2.rps...
Parsing signing key 'private-key.pem'...
Signing combined image...
Image SHA256: e53775814dc61c2ecbe14f1b1d9310c8d79ad96681a9f6258cd427cbc9cd6576
R = CE26333E667842859469622C4E35B72B1C1FCA7D148F58FD67F66C70449A4092
S = 91EA3A02A4B7374401A46161869819AA14065FE760C2781466BAD0643AD8FF60
RPS file successfully created at 'combined-image.rps'.
DONE

Create an RPS File for External Signing#

Create an RPS file to be signed externally, for instance by a hardware security module (HSM), using the the rps create command with the --extsign option. The signature can be added using the sign command in the following section.

Command Line Syntax

$ commander rps create <output filename> --app <application filename> --extsign [--sha <sha type>]

Command Line Input Example

$ commander rps create app.extsign --app app.hex --extsign

This command line creates an intermediate RPS image 'app.extsign' from the application image 'app.hex', ready for being signed by an external signer.

Command Line Output Example

WARNING: No SHA type was provided, defaulting to SHA-256.
Parsing file app.hex...
RPS image to be signed externally; skipping signature calculation.
Calculating CRC of image...
RPS file successfully created at 'app.extsign'.
DONE

Externally Sign an RPS File#

Append an externally generated signature file (binary, DER-formatted) to an RPS file created using the rps sign command.

Note: The externally generated signature must be at most 72 bytes long. Shorter signatures will be padded with zeroes.

Command Line Syntax

$ commander rps sign <filename> --signature <filename> --outfile <filename>

Command Line Input Example

$ commander rps sign app.extsign --signature signature.bin --outfile app.rps

This command line appends the signature in 'signature.bin' to the intermediate RPS file 'app.extsign', writing the completed signed RPS file to 'app.rps'.

Command Line Output Example

Signed RPS file written to 'app.rps'.
DONE

Load RPS Image Onto Device#

Simplicity Commander can load RPS images onto SiWx91x devices using the rps load command. Both M4 and NWP (TA) application images can be loaded using this command. If the --eraseapp option is used, the M4 application will be erased after the NWP firmware has been loaded.

Command Line Syntax

$ commander rps load <filename> [--eraseapp]

Command Line Input Example

$ commander rps load app.rps

This command line takes the RPS image 'app.rps' and loads it onto the device.

Command Line Output Example

Uploading flashloader...
Waiting for flashloader to become ready
Writing data...
Waiting for bootloader to perform upgrade...
Resetting
DONE