EFR32 Custom Tokens#

Introduction#

Simplicity Commander supports defining custom token groups for reading and writing. Custom tokens work just like manufacturing tokens, but the definition and location of the tokens is configurable to suit different requirements.

There are two different ways for Simplicity Commander to find and use custom token definition files. For Simplicity Commander to treat the custom token file in the same way as a regular token group, the file must be placed in a specific location as described in Custom Token Groups below.

The other option is to use the --tokendefs command line option instead of the --tokengroup option. With this method, Simplicity Commander uses a token definition file in an arbitrary location, for example, under revision control. For more information, see Using Custom Token Files in Any Location.

Custom Token Groups#

For Simplicity Commander to treat custom token files like regular token groups, the file must be placed in a specific tokens folder and the filename must follow a special syntax.

The location and initialization of the tokens folder depends on the operating system used.

On Windows and Linux, the tokens folder is included in the zip file and is placed alongside the executable in the installation directory.

On Mac OS X, the folder named ~/Library/SimplicityCommander/tokens/ is generated automatically in the user's home directory when running commander on the command line for the first time. Running commander --help, for example, is enough to ensure that the folder with files is created. Inside this tokens folder, there is a file named tokens-example-efr32.json. This file provides an example of the token types and locations currently supported by Simplicity Commander.

The syntax of the filename is tokens-<group name>-<architecture>.json. <group name> is the name of the custom token group and can be any string. <architecture> is a string describing which devices the token definitions apply to. The following table lists the supported architecture strings.

For example, to define the token group myapp for EFR32 Series 1 devices, the filename would be tokens-myapp-efr32.json.

Creating Custom Token Groups#

To define a custom token group, copy tokens-example-efr32.json to a new file in the same directory using the following naming convention: tokens-<groupname>-``efr32.json.

For example: tokens-myapp-efr32.json

To verify that Simplicity Commander sees the new file, run:

$ commander tokendump --help

The name of your token group (for example, "myapp") should be listed as a supported token group like this:

--tokengroup <tokengroup> which set of tokens to use. Supported: myapp, znet

Defining Tokens#

Each token in the JSON file has the following properties.

Memory Regions#

The following values are valid data in the "page" option:

USERDATA

The user data page is a separate flash page intended for persistent data and configuration. The user data page is not erased when disabling debug lock. It can, however, be erased by a specific page erase.

The user data page is located at address 0x0FE00000. It is 2 kB on Series 1 EFR32 devices and 1 kB on Series 2 EFR32 devices.

LOCKBITSDATA

On Series 1 EFR32 devices, the lock bits page is used by the chip itself to configure flash write locks, debug lock, AAP lock, and so on. However, the last 1.5 kB of this page is unused by the device itself and has the important property that it is erased when disabling debug lock. A regular mass erase by the MSC—typically by executing the commander device masserase or commander flash --masserase command—does not erase the lock bits page.

The lock bits page is located at address 0x0FE04000 with size 2 kB on Series 1 EFR32 devices. Tokens in this page must use an offset of at least 0x200 on these devices; otherwise, collisions with chip functionality can occur.

On Series 2 EFR32 devices, there is no physical lock bits page. Instead, the LOCKBITSPAGE region is defined to be the first 2 kB of the last flash page in the main flash block. This maintains backwards compatibility, while still ensuring that any data in this region is erased when the device is erased during debug unlock.

Token File Format Description#

A token file declares what values are programmed for manufacturing tokens on the chip. Lines are composed of one of the following forms:

<token-name> : <data>
<token-name> : !ERASE!

Follow these guidelines when using a token file:

• Omitted tokens are left untouched and not programmed on the chip.

• Token names are case insensitive.

• All integer values are interpreted as hexadecimal numbers in BIG-endian format and must be prefixed with '0x'.

• Blank lines and lines beginning with # (hashtag) are ignored.

• Byte arrays are given in hexadecimal format without a leading '0x'.

• Specifying !ERASE! for the data sets that token to all 0xFF.

• The token data can be in one of three main forms: byte-array, integer, or string.

• Byte arrays are a series of hexadecimal numbers of the required length.

• Integers are BIG-endian hexadecimal numbers that must be prefixed with '0x'.

• String data is a quoted set of ASCII characters.

Using Custom Token Files#

Refer to Introduction for a definition of custom token files and where they should be located for Simplicity Commander to find them automatically. To use a custom token file located in the tokens folder, run Simplicity Commander with a --tokengroup option corresponding to the name of the JSON file. For example, if the file was named tokens-myapp-efr32.json, use this option:

--tokengroup myapp

To create a text file useful as input to the flash or convert commands, the easiest way is to start by dumping the current data from a device.

For example:

$ commander tokendump -s 440050148 --tokengroup myapp --outfile mytokens.txt

mytokens.txt can then modified to have the desired content, and then used when flashing devices or creating images in this way:

$ commander flash -s 440050148 --tokengroup myapp --tokenfile mytokens.txt

To be able to read the custom token data from an application, Simplicity Commander provides the tokenheader command, which generates a C header file that can be included in an application. See Generate C Header Files from Token Groups for details.

Using Custom Token Files in Any Location#

In some cases, it is more convenient to have the custom token defintions file somewhere in the file system (for example, if it is placed under revision control). Simplicity Commander supports this functionality with the --tokendefs option which refers to a JSON file anywhere in the file system. Use it instead of the --tokengroup option.

For example:

$ commander tokendump --tokendefs my_tokens.json --outfile mytokens.txt
$ commander flash --tokendefs my_tokens.json --tokenfile mytokens.txt