Tokens Command#

The tokens command is the new unified interface for managing manufacturing tokens and static tokens on Silicon Labs devices. It replaces the legacy token handling in flash, tokendump and tokenheader commands, providing a consistent experience across device families.

This command supports both the old manufacturing tokens format and the new static tokens format.

  • Manufacturing tokens are used on Series 1 and 2 devices. These tokens are defined with fixed length and fixed locations in memory.

  • Static tokens are used on Series 3 devices. These tokens use a Key-Length-Value (KLV) format. There are two types of static tokens

    • Static Secure Tokens are stored in a dedicated flash region. The secure range must be provided when reading/writing these tokens. Static secure tokens are encrypted by default.

    • Static device tokens have limited storage capacity and are mass-erase protected. The number of writes/erases for static device tokens is limited to 100 due to hardware OTP bit constraints.

Important:

  • The KLV chain will be automatically initialized by the tokens write command if it is not already present.

  • The tokens erase command also leaves the KLV chain initialized after erasing.

  • All token commands require information about the target device. This requires that either the --device option is given, or that the device part number can be inferred from a known Silicon Labs board.

  • If neither the --tokengroup nor --tokendefs option is specified, Simplicity Commander defaults to using all known token groups. For static tokens this means common and zigbee, and for manufacturing tokens this means znet.

Write Tokens#

The tokens write command writes tokens to the device. It replaces the legacy flash --token and flash --tokenfile commands and supports both manufacturing tokens and static tokens. The available options and behavior differ depending on the device type.

Command Line Syntax#

Static Tokens#

$ commander tokens write  --device <target device> [--token <TOKEN_NAME:VALUE> --tokenfile <file> --securerange <address1:address2> --tokengroup <group> --tokendefs <file>]

Manufacturing Tokens#

$ commander tokens write --device <target device> [ --token <TOKEN_NAME:VALUE> --tokenfile <file> --tokengroup <group> --tokendefs  <file>]

Note:

  • At least one of --token or --tokenfile must be provided.

  • For static tokens --securerange is required for secure tokens.

Command Line Input Example (Static Tokens)#

$ commander tokens write --securerange 0x0138A000:+0x2000  --token "Install Code":12345123451234512341234512345123 --device SiMG301M104LILB0

Writes the Install Code token to the device in the secure range.

Command Line Output Example#

Parsing token input...
Uploading RAM code...
Waiting for RAM code to become ready
Configure tokens...
Writing secure token...
DONE

Command Line Input Example (Manufacturing Tokens)#

$ commander tokens write --token MFG_XO_TUNE:0x1234 --token MFG_CTUNE:0x002d --token MFG_LFXO_TUNE:0x90 --device EFR32MG21A010F1024

Writes the MFG_XO_TUNE, MFG_CTUNE, and MFG_LFXO_TUNE tokens to the device.

Command Line Output Example#

Parsing token input...
Writing tokens...
DONE

Command Line Input Example (Using Token File)#

$ commander tokens write --tokenfile my_tokens.txt --device EFR32MG21A010F1024

Writes all tokens specified in my_tokens.txt to the device. A template token file can be generated using the tokens read command.

Command Line Output Example#

Parsing token input...
Writing tokens...
DONE

Read Tokens#

The tokens read command reads tokens from a device or one or more files (manufacturing tokens only). The output of read can either be printed to standard output or written to a file using the --outfile option. The output file can be modified and re-used as input to the tokens write, verify, or convert commands using the --tokenfile option.

For static tokens, tokens are read directly from the device. All tokens will be included if the --includeall option is set; otherwise, only tokens found on the device are shown. Use --showoverrides to display any potential NVM3 overrides on the device.

Command Line Syntax#

Static Tokens#

$ commander tokens read --device <target device> [--tokengroup <group> --token <TOKEN_NAME> --outfile <filename> --securerange <start:end> --type <secure|device> --includeall --showoverrides]

Manufacturing Tokens#

$ commander tokens read --device <target device> [--token <TOKEN_NAME> --tokengroup <group> --tokendefs <file>  --outfile <filename>]

Command Line Input Example (Static Tokens)#

$ commander tokens read --securerange 0x0138A000:+0x2000 --outfile tokens.txt --device SiMG301M104LILB0

Reads all static tokens from the device in the specified secure range and writes them to tokens.txt.

Command Line Output Example#

Uploading RAM code...
Waiting for RAM code to become ready
Configure tokens...
Reading secure tokens...
Reading device tokens...
Writing tokens to tokens.txt...
DONE

Command Line Input Example (Static Tokens, with NVM3 overrides)#

$ commander tokens read --securerange 0x0138A000:+0x2000 --showoverrides

Reads all static tokens from the device, including any NVM3 overrides, and prints them to the console.

Command Line Output Example#

Found NVM3 range: 0x01381000 - 0x01385000. Security mode: aead
Uploading RAM code...
Waiting for RAM code to become ready
Configuring secure tokens...
Reading secure tokens...
Reading device tokens...
Opening NVM3...
Getting NVM3 objects...
Closing NVM3...
Resetting device
#
# 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.
# String data is a quoted set of ASCII characters.
#
#
# Lines beginning with '# // ' are static tokens that are overridden in NVM3.
# The NVM3 override token is presented on the following line.
#
MFG_CUSTOM_EUI_64 : ABCDEF0123456789
MFG_CUSTOM_VERSION: 0x1337
MFG_PHY_CONFIG    : 0x1234
MFG_LFXO_TUNE     : 0x69
MFG_CTUNE         : 0x002d
# // MFG_MANUF_ID      : 0xCAFE [overridden]
MFG_MANUF_ID      : 0x3412
MFG_CCA_THRESHOLD : 0x5A5A
MFG_BOARD_NAME    : "My Board"

#'MFG_CBKE_283K1_DATA (Smart Energy 1.2 CBKE)' token group
Device Implicit Cert (283k1) : 1234512345123451234123451234512345123412345123451234512341234512123451234512345123412345123451231234512345123451234123451234512345123412345123451234
CA Public Key (283k1)        : 12345123451234512341234512345123451234123451234512345123412345121234512345
Device Private Key (283k1)   : 123451234512345123412345123451234512341234512345123451234123451212345123
# CBKE FLAGS (283k1)           : 0x00

#'MFG_CBKE_DATA (Smart Energy CBKE)' token group
Device Implicit Cert : 123451234512345123412345123451234512341234512345123451234123451212345123451234512341234512345123
CA Public Key        : 12345123451234512341234512345123451234123451
Device Private Key   : 123451234512345123412345123451234512341234
# CBKE Flags           : 0x00

#'MFG_INSTALLATION_CODE (Smart Energy Install Code)' token group
# Install Code Flags : 0x0006
Install Code       : 12345123451234512341234512345123
# CRC                : 0xD6F2
DONE

Command Line Input Example (Manufacturing Tokens)#

$ commander tokens read app.s37 --device EFR32MG21A010F1024 --outfile tokens.txt

Reads all tokens from app.s37 and writes them to tokens.txt.

Command Line Output Example#

Writing tokens to tokens.txt...
DONE

Erase Tokens#

The tokens erase command erases tokens from a device. Specific tokens can be erased using the --token option. For static tokens, you can use this command to erase all tokens, only secure tokens, only device tokens, or specific tokens. If only a subset of the tokens are erased, the remaining tokens are rewritten to maintain a valid KLV chain. If all tokens of a given type are deleted, Commander will leave the KLV chain initialized. Every erase operation involving device tokens consume one OTP bit, so it is recommended to minimize erase/write operations for these tokens. Use the --type option to specify whether to erase secure or device tokens. For manufacturing tokens, erasing sets the token memory to 0xFF.

Command Line Syntax#

Static Tokens#

$ commander tokens erase --device <target device> [--securerange <start:end> --token <TOKEN_NAME> --type <secure|device> --tokengroup <group> ]

Manufacturing Tokens#

$ commander tokens erase --device <target device>  [--token <TOKEN_NAME> --tokengroup znet --tokendefs <file>]

Command Line Input Example (Erase all secure tokens, Static Tokens)#

$ commander tokens erase --type secure --securerange 0x0138A000:+0x2000 --device SiMG301M104LILB0

Erases all secure static tokens from the device in the specified secure range.

Command Line Output Example#

Uploading RAM code...
Waiting for RAM code to become ready
Configure tokens...
Erasing secure tokens...
DONE

Command Line Input Example (Erase specific token, Static Tokens)#

$ commander tokens erase --token "Install Code" --securerange 0x0138A000:+0x2000 --device SiMG301M104LILB0

Erases the Install Code static token from the device. Rewrites two remaining secure tokens to the KLV chain.

Command Line Output Example#

Uploading RAM code...
Waiting for RAM code to become ready
WARNING: Token is part of group. Erasing the whole group.
Configuring secure tokens...
Reading secure tokens...
Erasing secure tokens...
Writing secure token...
Writing secure token...
DONE

Command Line Input Example (Erase all tokens, Manufacturing Tokens)#

$ commander tokens erase --device EFR32MG21A010F1024

Erases all manufacturing tokens from the device in the znet token group (sets memory to 0xFF).

Command Line Output Example#

Writing 8192 bytes starting at address 0x081de000
Writing 1024 bytes starting at address 0x0fe00000
Comparing range 0x081DE000 - 0x081DFFFF (8 KB)
Erasing range 0x0FE00000 - 0x0FE003FF (1 sector, 1024 Bytes)
Programming range 0x0FE00000 - 0x0FE003FF (1024 Bytes)
Verifying range 0x0FE00000 - 0x0FE003FF (1024 Bytes)
DONE

Generate C Header Files from Token Groups#

The createheader command generates a simple header file based on a custom token group. The generated header file contains pre-processor defines that specify the location and size of each token.

Command Line Syntax

$ commander tokens createheader --tokendefs <group name> --device <target device> <filename>

Command Line Input Example

$ commander tokens createheader --tokendefs myapp --device EFR32MG21A010F1024 my_tokens.h

Command Line Output Example

Writing token header file: my_tokens.h
DONE

Custom Tokens#

Custom tokens allow the user to define their own token groups and tokens for use with Simplicity Commander. This is useful for applications that require specific token management beyond the predefined groups.

For more information on how to create custom tokens, see the Custom Tokens documentation.

Command Line Input Example (Static Tokens)#

$ commander tokens read --securerange 0x0138A000:+0x2000 --tokendefs my_app.json --outfile tokens.txt --device SiMG301M104LILB0

Reads all static tokens defined in my_app.json from the device in the specified secure range and writes them to tokens.txt.

Command Line Output Example#

Uploading RAM code...
Waiting for RAM code to become ready
Configure tokens...
Reading secure tokens...
Writing tokens to tokens.txt...
DONE

Command Line Input Example (Manufacturing Tokens)#

$ commander tokens --tokendefs my_app.json --device EFR32MG21A010F1024 --outfile tokens.txt

Reads all tokens defined in my_app.json from the device and writes them to tokens.txt.

Command Line Output Example#

Writing tokens to tokens.txt...
DONE