Commands description | ModusToolbox™ ecosystem documentation

Shift

Shift segment to a specific address.

Inputs


Name	Type	Optional/Required	Description
file	string	required	Input hex file containing the segment to shift.
address	string	optional	Address of the segment that has to be shifted.
description	string	optional	Description for this field.

Outputs


Name	Type	Optional/Required	Description
file	string	required	Path to the output file.
address	string	optional	The new address of the segment.
description	string	optional	Description for this field.

Example

{    
    "schema-version": 1.0,
    "content": [
        {
            "name": "Shift command example",
            "description": "Shifts a hex segment to a secondary address",
            "enabled": true,
            "commands": [
                {
                    "command": "shift",
                    "inputs": [
                        {
                            "description": "CM33 Secure + CM33 Non-Secure application",
                            "file": "rram_3.hex",
                            "address" : "0x32030000"
                        }
                    ],
                    "outputs": [
                        {
                            "description": "CM33 Secure + CM33 Non-Secure application shifted to secure region",
                            "address": "0x3202A000",
                            "file": "shifted_rram_3.hex"
                        }
                    ]
                }
            ]
        }
    ]
}

Hex relocate

Relocates regions in the hex file to new address spaces. Relocates regions in the hex file to new address spaces. All segments within the specified region (from start to start + size) will be relocated to the new address (dest).

Inputs:


Name	Type	Optional/Required	Description
file	string	required	Input hex file containing the segment(s) to relocate.
regions	array	required	Regions to relocate. An array of objects, each containing `start`, `size`, and `dest` fields.
description	string	optional	Description for this field.

Outputs:


Name	Type	Optional/Required	Description
file	string	required	Path to the output hex file.
description	string	optional	Description for this field.

Example:

{
    "schema-version": 1.0,
    "content": [
        {
            "name": "hex-relocate command example",
            "description": "Relocates regions in hex file to new address spaces",
            "enabled": true,
            "commands": [
                {
                    "command": "hex-relocate",
                    "inputs": [
                        {
                            "file": "input.hex",
                            "regions": [
                                {
                                    "start": "0x08000000",
                                    "size": "0x04000000",
                                    "dest": "0x60000000"
                                }
                            ]
                        }
                    ],
                    "outputs": [
                        {
                            "file": "output.hex"
                        }
                    ]
                }
            ]
        }
    ]
}

Hex segment

Extracts a segment from the hex file.

Inputs


Name	Type	Optional/Required	Description
file	string	required	Path to the input hex file.
address	string	required	Address of the segment.
description	string	optional	Description for this field.

Outputs


Name	Type	Optional/Required	Description
file	string	required	Path to the file where to save the extracted segment.
description	string	optional	Description for this field.

Example

{
    "schema-version": 1.0,
    "content": [
        {
            "name": "Shift command example",
            "description": "Shifts a hex segment to a secondary address",
            "enabled": true,
            "commands": [
                {
                    "command": "shift",
                    "inputs": [
                        {
                            "description": "CM33 Secure + CM33 Non-Secure application",
                            "file": "rram_3.hex",
                            "address" : "0x32030000"
                        }
                    ],
                    "outputs": [
                        {
                            "description": "CM33 Secure + CM33 Non-Secure application shifted to secure region",
                            "address": "0x3202A000",
                            "file": "shifted_rram_3.hex"
                        }
                    ]
                }
            ]
        }
    ]
}

Merge

Inputs

This command requires two or more inputs of the same format.


Name	Type	Optional/Required	Description
file	string	required	Path to the file to merge.
description	string	optional	Description for this field.

Outputs


Name	Type	Optional/Required	Description
file	string	required	Path to the merged file.
format	string	optional	Format of the output file. Available values: ihex or bin.
address	string	optional	Start address of the output hex file.
description	string	optional	Description for this field.

Example

{    
    "schema-version": 1.0,
    "content": [
        {
            "name": "Merge command example",
            "description": "Merges two or more hex/bin files into a single file",
            "enabled": true,
            "commands": [
                {
                    "command": "merge",
                    "inputs": [
                        {
                            "description": "CM33 Secure  application",
                            "file": "./rram_1.hex"
                        },
                        {
                            "description": "CM33 Non-Secure application",
                            "file": "./rram_2.hex"
                        },
                        {
                            "description": "CM33 Secure + CM33 Non-Secure application",
                            "file": "./rram_3.hex"
                        }
                    ],
                    "outputs": [
                        {
                            "description": "CM33 Secure + CM33 Non-Secure application merged to one file",
                            "format": "ihex",
                            "file": "./cmd_merge_3_files.hex"
                        }
                    ]
                }
            ]
        }
    ]
}

Sign image

Signs the user application and converts it into MCUboot format. If the signing key is not provided, the result is the MCUboot formatted unsigned image. All the numeric values can be provided in a decimal (for example, fill-value: 255) or hexadecimal format (for example, fill-value: "0xFF").

Inputs


Name	Type	Optional/Required	Description
file	string	required	Path to the file to be signed or converted into MCUboot format.
description	string	optional	Description for this field.
signing-key	string	optional	ECDSA or RSA private key used to sign the image.
header-size	string, integer	required	MCUboot header size.
slot-size	string, integer	required	Maximum slot size.
fill-value	string, integer	optional	Value read back from erased flash. Default: `0`. Available values: `0`, `0xFF`.
min-erase-size	string, integer	optional	Minimum erase size. Default: `0x8000`.
image-version	string	optional	Image version in the image header. Default: `0.0.0`.
security-counter	string, integer	optional	Value of security counter. Use the `auto` keyword to automatically generate it from the image version. Default: `auto`.
align	string, integer	optional	Flash alignment. Default: `8`. Available values: `1`, `2`, `4`, `8`.
pubkey-format	string	optional	Public key format in the image TLV: full key or hash of the key. Available values: `hash` or `full`. Default: `hash`.
pubkey-encoding	string	optional	Public key encoding in the image TLV. Applicable values: `der`, or `raw`. Default: `der`.
signature-encoding	string	optional	Image signature encoding. Applicable values: `asn1`, or `raw`. Default: `asn1`.
pad	boolean	optional	Adds padding to the image trailer. Pads the image from the end of the TLV area up to the slot size. boot_magic is always at the very end after the padding.
confirm	boolean	optional	Adds image OK status to the trailer. Pads the image from the end of the TLV area up to the slot size and sets the image OK byte to 0x01 (the eighth byte from the end). The padding is required for this feature and is always applied. boot_magic is always at the very end after the padding.
overwrite-only	boolean	optional	Use overwrite mode instead of swap.
boot-record	string	optional	Create CBOR encoded boot record TLV. Represents the role of the software component (for example, CoFM for coprocessor firmware). Maximum 12 characters.
hex-address	string, integer	optional	Adjust the address in the hex output file.
load-address	string, integer	optional	Load address for image when it should run from RAM.
rom-fixed	string, integer	optional	Set flash address the image is built for.
max-sectors	string, integer	optional	When padding allow for this amount of sectors. Default: `128`.
save-enctlv	boolean	optional	When upgrading, save encrypted key TLVs instead of plain keys. Enable when BOOT_SWAP_SAVE_ENCTLV config option was set.
dependencies	string	optional	Add dependency on another image. Format: `(<image_ID>,<image_version>), ...` .
encryption-public-key	string	optional	ECDSA public key used to generate the symmetric key for image encryption (ECIES schema). It must be the receiver's public key.
encryption-secret-key	string	optional	An encryption key.
encryption-key-role	string	optional	An encryption key role. Specifies what the key is used for: Image Encryption: Encrypts images for decryption in the XIP mode Key Wrapping: Acts as a Key Encryption Key (KEK) for AES Key Wrapping (AES-KW), ensuring secure key management. Available values: `XIP`, `AES-KW`. Default: `XIP`.
encryption-address	string	optional	Starting address for data encryption.
protected-tlv	list	optional	The custom TLV to be placed into a protected area (the signed part). Add the `0x` prefix for the value to be interpreted as an `integer`, otherwise it will be interpreted as a `string`.
tlv	list	optional	The custom TLV to be placed into a non-protected area. Add the `0x` prefix for the value to be interpreted as an `integer`, otherwise it will be interpreted as a `string`.
kdf	string	optional	Key derivation function name. Default: `HKDF`. Available values: `HKDF`, `KBKDFCMAC`.
remove-tlv	list	optional	Removes TLV with the specified ID.

Outputs


Name	Type	Optional/Required	Description
description	string	optional	Description for this field.
file	string	required	Path to the signed and/or converted to the MCUboot format image.
format	string	required	Format of the output file. Available values: `ihex` or `bin`.
unencrypted	string	optional	The path where to save unencrypted image payload (bin). Specify this option if the image is encrypted and provide the unencrypted image to HSM because the signature is calculated on the unencrypted data.
nonce-output	string	optional	The path to a file where to save the nonce.

Example

{    
    "schema-version": 1.0,
    "content": [
        {
            "name" : "sign command example",
            "description": "Signs the input file and converts it to the MCUboot format",
            "enabled": true,
            "commands": [
                {
                    "command": "sign",
                    "inputs": [
                        {
                            "description": "Secure application",
                            "file": "./rram_1.hex",
                            "signing-key": "./some-key-ec-p256.pem",
                            "overwrite-only": true,
                            "header-size": "0x400",
                            "slot-size": "0x1000",
                            "fill-value": "0x00",
                            "min-erase-size": "0x200",
                            "pad": true,
                            "hex-address": "0x32005000",
                            "protected-tlv": [
                                {
                                    "tag": "0x22",
                                    "value": "0x12345678"
                                }
                            ]
                        }
                    ],
                    "outputs" : [
                        {
                            "description": "Signed secured application",
                            "format" : "ihex",
                            "file": "./rram_1_signed.hex"
                        }
                    ]
                }
            ]
        }
    ]
}

Extract payload

The MCUboot formatted image consists of a header, a payload, a protected TLV area, and a non-protected TLV area. A header, a payload, and a protected TLV are the data that must be signed. A non-protected TLV area must not be included in a signature. This command extracts a part of an image to be signed.

Inputs


Name	Type	Optional/Required	Description
file	string	required	Image with MCUboot metadata.
description	string	optional	Description for this field.

Outputs


Name	Type	Optional/Required	Description
file	string	required	Path where to save the image to be signed (bin).
description	string	optional	Description for this field.

Example

{    
    "schema-version": 1.0,
    "content": [
        {
            "name": "Extract-payload command example",
            "description": "Adds a signature to the MCUboot formatted image",
            "enabled": true,
            "commands": [
                {
                    "command": "extract-payload",
                    "inputs": [
                        {
                            "description": "Path to the input hex file",
                            "file": "./hexs/rram_1_meta.hex"
                        }
                    ],
                    "outputs": [
                        {
                            "description": "Name of output file",
                            "file": "./hexs/extracted.bin"
                        }
                    ]
                }
            ]
        }
    ]
}

Add signature

Adds signature to the existing MCUboot format image.

Command name

add-signature

Inputs

This command requires two input files, where one is the MCUboot formatted image and the second is the signature.


Name	Type	Optional/Required	Description
file	string	required	Path to the image with MCUboot metadata
description	string	optional	Description for this field.


Name	Type	Optional/Required	Description
file	string	required	Binary file containing signature.
algorithm	string	required	Signature algorithm. Available values: ECDSA-P256, RSA2048, RSA4096.
description	string	optional	Description for this field.

Outputs


Name	Type	Optional/Required	Description
file	string	required	Path to the output file.
format	string	required	Format of the output file. Available values: ihex, bin.
description	string	optional	Description for this field.

Example

{    
    "schema-version": 1.0,
    "content": [
        {
            "name": "Add-signature command example",
            "description": "Adds a signature to the MCUboot formatted image",
            "enabled": true,
            "commands": [
                {
                    "command": "add-signature",
                    "inputs": [
                        {
                            "description": "Unsigned bootloader in MCUboot format",
                            "file": "./hexs/bootloader_meta.hex"
                        },
                        {
                            "description": "Signature returned by HSM",
                            "file": "./hexs/signature.bin",
                            "algorithm": "ECDSA-P256"
                        }
                    ],
                    "outputs": [
                        {
                            "description": "Final image signed with HSM",
                            "format": "ihex",
                            "file": "./hexs/bootloader_signed.hex"
                        }
                    ]
                }
            ]
        }
    ]
}

Custom script

Executes system commands or other programs.

Command name

custom-script

Inputs


Name	Type	Optional/Required	Description
command-line	string	required	The command line to be executed.
shell	boolean	optional	Specifies whether the command will be executed through the shell. On POSIX with shell=True, the shell defaults to /bin/sh. Invoking via the shell does allow you to expand environment variables and file globs according to the shell's usual mechanism. On Windows with shell=True, the COMSPEC environment variable specifies the default shell. The only time you need to specify shell=True on Windows is when the command you wish to execute is built into the shell (for example, dir or copy). You do not need shell=True to run a batch file or console-based executable.
description	string	optional	The command description.

Outputs

None

Example

{    
    "schema-version": 1.0,
    "content": [
        {
            "name": "Custom-script command example",
            "description": "Test template for the custom-script command",
            "enabled": true,
            "commands": [
                {
                    "command": "custom-script",
                    "inputs": [
                        {
                            "description": "List detailed information about files and directories in the current directory",
                            "command-line": "ls -la",
                            "shell": false
                        }
                    ]
                }
            ]
        }
    ]
}

Bin dump

Creates binary file from the hex string or random bytes.

Command name: bin-dump

Inputs:


Name	Type	Optional/Required	Description
data	string	optional	The hex string. Either `data` or `random` property must be specified.
random	string, integer	optional	Generate random binary of the specified length.
description	string	optional	Description for this field.

Outputs:


Name	Type	Optional/Required	Description
file	string	required	Path to the output bin file.
description	string	optional	Description for this field.

Example:

{
    "schema-version": 1.0,
    "content": [
        {
            "name": "bin-dump command example",
            "description": "Creates binary file",
            "enabled": true,
            "commands": [
                {
                    "command": "bin-dump",
                    "inputs": [
                        {
                            "description": "Hex string or random value",
                            "data": "0011223344556677889900AABBCCDDEEFF",
                            "random": null
                        }
                    ],
                    "outputs": [
                        {
                            "description": "Output file",
                            "file": "output.bin"
                        }
                    ]
                }
            ]
        }
    ]
}

Hex dump

Extracts data from the hex file and saves it to a binary file.

Command name: hex-dump

Inputs:


Name	Type	Optional/Required	Description
file	string	required	The path to the hex file.
address	string, integer	required	Address of the data in the hex file.
size	string, integer	required	Size of the data.
description	string	optional	Description for this field.

Outputs:


Name	Type	Optional/Required	Description
file	string	required	Path to the output bin file.
fill-value	string, integer	optional	Value to fill the spaces between the segments. Available values: `0x00`-`0xFF`. Default: `0`.
description	string	optional	Description for this field.

Example:

{
    "schema-version": 1.0,
    "content": [
        {
            "name": "hex-dump command example",
            "description": "Extracts data from the hex file",
            "enabled": true,
            "commands": [
                {
                    "command": "hex-dump",
                    "inputs": [
                        {
                            "description": "Input hex file",
                            "file": "input.hex",
                            "address": "0x00",
                            "size": "0xFF"
                        }
                    ],
                    "outputs": [
                        {
                            "description": "Output bin file",
                            "file": "output.bin",
                            "fill-value": 0
                        }
                    ]
                }
            ]
        }
    ]
}

Bin to hex

Converts binary file to hex.

Command name: bin2hex

Inputs:


Name	Type	Optional/Required	Description
file	string	required	The path to the bin file.
offset	string, integer	optional	Starting address offset for loading bin.
description	string	optional	Description for this field.

Outputs:


Name	Type	Optional/Required	Description
file	string	required	Path to the output hex file.
description	string	optional	Description for this field.

Example:

{    
    "schema-version": 1.0,
    "content": [
        {
            "name": "bin2hex command example",
            "description": "Converts binary image to hex",
            "enabled": true,
            "commands": [
                {
                    "command": "bin2hex",
                    "inputs": [
                        {
                            "description": "Input bin file",
                            "file": "input.bin",
                            "offset": 0
                        }
                    ],
                    "outputs": [
                        {
                            "description": "Output hex file",
                            "file": "output.hex"
                        }
                    ]
                }
            ]
        }
    ]
}

Hex to bin

Converts hex file to binary.

Command name: hex2bin

Inputs:


Name	Type	Optional/Required	Description
file	string	required	The path to the input hex file.
start	string, integer	optional	Start of address range.
end	string, integer	optional	End of address range.
description	string	optional	Description for this field.

Outputs:


Name	Type	Optional/Required	Description
file	string	required	The path to the output bin file.
size	string, integer	optional	Size of the resulting file in bytes.
fill-value	string, integer	optional	Value to fill the spaces between the segments. Available values: `0x00`-`0xFF`. Default: `0xFF`.
description	string	optional	Description for this field.

Example:

{
    "schema-version": 1.0,
    "content": [
        {
            "name": "hex2bin command example",
            "description": "Converts hex file to binary",
            "enabled": true,
            "commands": [
                {
                    "command": "hex2bin",
                    "inputs": [
                        {
                            "description": "Input hex file",
                            "file": "input.hex",
                            "start": "0x32000000",
                            "end": "0x32000200"
                        }
                    ],
                    "outputs": [
                        {
                            "description": "Output bin file",
                            "file": "output.bin",
                            "size": "0x400",
                            "fill-value": 0
                        }
                    ]
                }
            ]
        }
    ]
}

Hash

Calculates hash of a file.

Command name: hash

Inputs:


Name	Type	Optional/Required	Description
file	string	required	The path to the input file.
algorithm	string	required	Hash algorithm.
description	string	optional	Description for this field.

Outputs:


Name	Type	Optional/Required	Description
file	string	required	Output binary or text file.
format	string	required	Format of the output file. Available values: `bin`, `txt`. Default: `bin`.
description	string	optional	Description for this field.

Example:

{
    "schema-version": 1.0,
    "content": [
        {
            "name": "hash command example",
            "description": "Calculates hash of a file",
            "enabled": true,
            "commands": [
                {
                    "command": "hash",
                    "inputs": [
                        {
                            "description": "Calculate hash of binary file",
                            "file": "output.bin",
                            "algorithm": "SHA256"
                        }
                    ],
                    "outputs": [
                        {
                            "description": "Output binary or text file",
                            "file": "hash.txt",
                            "format": "txt"
                        }
                    ]
                }
            ]
        }
    ]
}