Examples#

Prerequisites#

At the time of publication, this document was written using Simplicity Commander version 1.19.2 and SE Firmware version 3.3.1. It is a requirement to upgrade to at least these versions before proceeding, but it is recommended to upgrade to the latest version of both products, if a newer version is available. Install the latest version of Simplicity Commander delivered via silabs.com, to ensure you have the latest features and bugfixes. Additionally, it is recommended to upgrade devices to the latest SE Firmware version, delivered as part of the Simplicity SDK, as support for new Commander instructions, bug fixes, features, and vulnerability patches may be included in these updated versions.

Note: Before continuing with the steps listed in this section, refer to Considerations for Development Devices for important informa- tion on using AXiP and EXiP on development devices.

Using AXiP Out of the Box#

When using an in-package flash device with default configuration, all that needs to be done is to flash a valid image to the device. This section shows how to read the default region configuration on the device and program a firmware image with automatic closing of code regions.

On devices with external flash, AXiP is not enabled out of the box. Once the external flash is initialized and SE firmware is program- med, AXiP is configured to the default two-region setup (bootloader and application), matching the behavior of in-package flash devi- ces.

Reading Default Code Region Configuration#

To read the region configuration details from a device, issue the following command. This command is not required to be run for use AXiP out of the box, it is only intended to display the current configuration status.

commander security readregionconfig -d sixg301
Index        : 0
Size         : 32 kB
Protection   : Encrypted and authenticated 
Closed       : False

Index       : 1
Size        : 1408 kB
Protection  : Encrypted and authenticated
Closed      : False

DONE

Flashing a Device with AXiP Enabled#

To use AXiP on this device, simply flash the firmware image to the device using the following command. This command will auto- matically close the code regions after flashing is completed successfully.

commander flash example.hex -d sixg301
Parsing file example.hex...
Writing 168756 bytes starting at address 0x01000000 
Erasing range 0x01000000 - 0x01007FFF (1 sector, 32 KB) 
Erasing range 0x01008000 - 0x010B7FFF (1 sector, 704 KB) 
Programming range 0x01000000 - 0x01001FFF (8 KB)
...
Programming range 0x010B6000 - 0x010B7FFF (8 KB) 
Closing region 1
Closing region 0
Flashing completed successfully! DONE

Custom Code Region Configuration#

Modifying the region configuration can be done on devices with open code regions. If code regions are closed, they cannot be modified or reconfigured until they are erased, which will reopen the closed code region.

Note: The following steps begin with a device which is in the default configuration, where all configured code regions are open. If a user is reconfiguring a device with closed code regions, issue a commander device masserase or a commander device recover command to the device before proceeding.

  1. To begin modifying a device's code region configuration, a configuration YAML file must be generated. The recommended way to do this is to read out the current configuration into a YAML file using the following command.

    commander security readregionconfig --outfile region_config.yaml -d sixg301
    Writing parsed configuration to file region_config.yaml... 
DONE

    Below is a copy of the contents of the region_config.yaml file. This was read out from a device in the default code region config- uration state.

    regions:
 - size_kb: 32
     protection: encrypted_authenticated
 - size_kb: 1408
     protection: encrypted_authenticated

  2. Modify the code region_config.yaml file and save the modified file. More details on the allowed fields for this file can be found in the Code Region Configuration File section of this document. An example of a modified region_config.yaml file is shown below.

    regions:
    - size_kb: 32
      protection: encrypted_authenticated
    - size_kb: 256 
      protection: encrypted
    - size_kb: 64 
      protection: none

  3. Write the new configuration file to the device using the following command.

    commander security writeregionconfig region_config.yaml -d sixg301
    Reading configuration from file region_config.yaml... 
Writing region configuration to device...
DONE

  4. Read out the configuration of the device to verify settings were applied successfully.

    commander security readregionconfig -d sixg301
    Index       : 0
Size        : 32 kB
Protection  : Encrypted and authenticated
Closed      : False

Index       : 1
Size        : 256 kB 
Protection  : Encrypted 
Closed      : False

 Index      : 2  
 Size       : 64 kB
 Protection : Plaintext 
 Closed     : False

 DONE

  5. Once the code regions are configured, firmware can be programmed to the regions using the commander flash command. In this example, the --noclose flag is used to later illustrate how to close a code region independently from flashing.

    commander flash bootloader.hex --noclose -d sixg301
    Parsing file bootloader.hex...
Writing 18788 bytes starting at address 0x01000000 
Erasing range 0x01000000 - 0x01007FFF (1 sector, 32 KB) 
Programming range 0x01000000 - 0x01000FFF (4 KB) 
Programming range 0x01001000 - 0x01001FFF (4 KB) 
Programming range 0x01002000 - 0x01002FFF (4 KB) 
Programming range 0x01003000 - 0x01003FFF (4 KB) 
Programming range 0x01004000 - 0x01004FFF (4 KB) 
Programming range 0x01005000 - 0x01005FFF (4 KB) 
Programming range 0x01006000 - 0x01006FFF (4 KB) 
Programming range 0x01007000 - 0x01007FFF (4 KB) 
Flashing completed successfully!
DONE

Closing a Code Region#

  1. The following command can be used to close a code region. The command takes in a region index, starting from 0, and an optional code region version number. This command was run following the previous step where a bootloader was flashed to a device. Closing a code region is required after regions are configured and firmware is programmed.

    Note: The code region version can only be set when a code region is closed. This functionality is supported exclusively through the DCI using this command.

    commander security closeregion 0 --codeversion 2 -d sixg301
    Succesfully closed code region 0 (version 0x00000002)
DONE

  2. To verify the code region was closed, read out the current code region configuration.

    commander security readregionconfig -d sixg301
    Index         : 0
Size          : 32 kB
Protection    : Encrypted and authenticated 
Closed        : True

Index         : 1
Size          : 256 kB 
Protection    : Encrypted
Closed        : False

Index         : 2
Size          : 64 kB
Protection    : Plaintext
Closed         : False

DONE