Tokens

Overview

---

The elcap tokens subcommands provide functionality for reading, writing, and erasing flash tokens on Trident MCUs. Each of these commands have command line –options for executing the commands. These options are situationally required so they are not all needed for every command use case. This document will go over when each of the options for each command is required and how to use them. This information can also be gotten from running elcap with the --help option.

TIP: elcap will make assumptions when commands are being run inside of a Trident IoT project directory that reduce the number of required options for commands. For example, running command

elcap tokens list

outside of a project directory will throw an error because it does not know which chip target to list the MFG tokens for. If you run the same command inside of a project directory, it will get the chip target being used within that project and list the corresponding MFG tokens for it.

Token Types

---

There are 2 types of tokens that can be interacted with, MFG and APP tokens. For a more detailed description of token use cases, please see the Trident IoT SDK Documentation page.

MFG Tokens

MFG tokens are manufacturing tokens that are supported by Trident IoT devices. These are used for setting things such as XTAL calibration information or for storing information that is used by an application in a place that does not require it to be built into the application itself.

APP Tokens

APP tokens are custom tokens that can be created by the application developer for doing things like storing device specific calibration data or storing data in persistent memory. Defining APP tokens is done using the Trident framework from within a project. Review the Trident IoT SDK Documentation for more details.

Tokens List

---

elcap tokens list

Lists the available tokens for the passed in type. Defaults to MFG.

Options

--option	description	default
--type	Specifies the type of token to use - 'APP' or 'MFG'	MFG
--target	Chip target - 'T32CM11C' or 'T32CZ20B'	None or chip from project directory
--def	JSON token definition file (only required for APP type)	None
--help	Print help for this sub-command	None

NOTE: The json token definition for APP tokens is generated as part of the project build if the project supports APP tokens. This file will be in the build directory and look something like: T32CM11C_app_token_def.json

List MFG Tokens

Outside of a project directory:

elcap tokens list --target <chip_pn>

Inside of a project directory:

elcap tokens list

List APP Tokens

Outside of a project directory:

elcap tokens list --target <chip_pn> --type APP --def path/to/app_token_def.json

Inside of a project directory:

elcap tokens list --type APP --def path/to/app_token_def.json

Example Output for MFG Tokens:

TR_MFG_TOKEN_VERSION                 | Size: 0x2  | Address: 0x1fc000
TR_MFG_TOKEN_CUSTOM_EUI              | Size: 0x8  | Address: 0x1fc002
TR_MFG_TOKEN_MFG_NAME                | Size: 0x20 | Address: 0x1fc00a
TR_MFG_TOKEN_MODEL_NAME              | Size: 0x20 | Address: 0x1fc02a
TR_MFG_TOKEN_HW_VERSION              | Size: 0x1  | Address: 0x1fc04a
TR_MFG_TOKEN_MANUF_ID                | Size: 0x2  | Address: 0x1fc04b
TR_MFG_TOKEN_SERIAL_NUM              | Size: 0x8  | Address: 0x1fc04d
TR_MFG_TOKEN_XTAL_TRIM               | Size: 0x2  | Address: 0x1fc055
TR_MFG_TOKEN_PHY_CONFIG              | Size: 0x2  | Address: 0x1fc057
TR_MFG_TOKEN_CCA_THRESHOLD           | Size: 0x2  | Address: 0x1fc059
TR_MFG_TOKEN_CBKE_DATA               | Size: 0x5c | Address: 0x1fc05b
TR_MFG_TOKEN_INSTALLATION_CODE       | Size: 0x14 | Address: 0x1fc0b7
TR_MFG_TOKEN_DISTRIBUTED_KEY         | Size: 0x10 | Address: 0x1fc0cb
TR_MFG_TOKEN_SECURITY_CONFIG         | Size: 0x2  | Address: 0x1fc0db
TR_MFG_TOKEN_CBKE_283K1_DATA         | Size: 0x94 | Address: 0x1fc0dd
TR_MFG_TOKEN_NVM_CRYPTO_KEY          | Size: 0x10 | Address: 0x1fc171
TR_MFG_TOKEN_BOOTLOAD_AES_KEY        | Size: 0x10 | Address: 0x1fc181
TR_MFG_TOKEN_SECURE_BOOTLOADER_KEY   | Size: 0x10 | Address: 0x1fc191
TR_MFG_TOKEN_SIGNED_BOOTLOADER_KEY_X | Size: 0x20 | Address: 0x1fc1a1
TR_MFG_TOKEN_SIGNED_BOOTLOADER_KEY_Y | Size: 0x20 | Address: 0x1fc1c1
TR_MFG_TOKEN_SERIAL_BOOT_DELAY_SEC   | Size: 0x1  | Address: 0x1fc1e1
TR_MFG_TOKEN_THREAD_JOIN_KEY         | Size: 0x22 | Address: 0x1fc1e2
TR_MFG_TOKEN_ZWAVE_COUNTRY_FREQ      | Size: 0x1  | Address: 0x1fc204
TR_MFG_TOKEN_ZWAVE_INITIALIZED       | Size: 0x1  | Address: 0x1fc205
TR_MFG_TOKEN_ZWAVE_QR_CODE           | Size: 0x6a | Address: 0x1fc206
TR_MFG_TOKEN_ZWAVE_PUK               | Size: 0x20 | Address: 0x1fc270
TR_MFG_TOKEN_ZWAVE_PRK               | Size: 0x20 | Address: 0x1fc290

Tokens Read

---

elcap tokens read

Read contents of flash tokens on a device.

Options

--option	description	default
--type	Specifies the type of token to use - 'APP' or 'MFG'	MFG
--target	Chip target - 'T32CM11C' or 'T32CZ20B'	None or chip from project directory
--def	JSON token definition file (only required for APP type)	None
--name	Name of the single token to read, leave off to read all	None
--usb	USB serial no. of connected programmer/dev kit	None
--ip	IP address of connected programmer/dev kit	None
--alias	Alias for the JLink device	None
--interface	Programming interface (SWD or JTAG)	SWD
--speed	Programming speed in kHz	4000
--help	Print help for this sub-command	None

Read All MFG Tokens

Outside of a project directory:

elcap tokens read --target <chip_pn>

Inside of a project directory:

elcap tokens read

Read All APP Tokens

Outside of a project directory:

elcap tokens read --target <chip_pn> --type APP --def path/to/app_token_def.json

Inside of a project directory:

elcap tokens read --type APP --def path/to/app_token_def.json

Read Single MFG Token

Outside of a project directory:

elcap tokens read --target <chip_pn> --name TR_MFG_TOKEN_MODEL_NAME

Inside of a project directory:

elcap tokens read --name TR_MFG_TOKEN_MODEL_NAME

Read Single APP Token

Outside of a project directory:

elcap tokens read --target <chip_pn> --type APP --def path/to/app_token_def.json --name MY_APP_TOKEN

Inside of a project directory:

elcap tokens read --type APP --def path/to/app_token_def.json --name MY_APP_TOKEN

Tokens Write

---

elcap tokens write

Write contents of flash tokens on a device.

Options

--option	description	default
--type	Specifies the type of token to use - 'APP' or 'MFG'	MFG
--target	Chip target - 'T32CM11C' or 'T32CZ20B'	None or chip from project directory
--def	JSON token definition file (only required for APP type)	None
--name	Name of the single token to write	None
--value	Value to write when using --name option	None
--value-type	Value data type when using --name option (hex, int, ascii)	None
--file	Token data JSON file to use when writing multiple tokens	None
--usb	USB serial no. of connected programmer/dev kit	None
--ip	IP address of connected programmer/dev kit	None
--alias	Alias for the JLink device	None
--interface	Programming interface (SWD or JTAG)	SWD
--speed	Programming speed in kHz	4000
--help	Print help for this sub-command	None

NOTE:

When writing tokens with a value-type of hex, the padding must explicity be written. For example, for token TR_MFG_TOKEN_CUSTOM_EUI: FFFFFFFFFFFFFFFF if you write --value 0x1234 --value-type hex it will write as TR_MFG_TOKEN_CUSTOM_EUI: 1234FFFFFFFFFFFF. If you wanted to write TR_MFG_TOKEN_CUSTOM_EUI: 0000000000001234 you would need to write --value 0x0000000000001234 --value-type hex.

Write Single MFG Token

Outside of a project directory:

elcap tokens write --target <chip_pn> --name TR_MFG_TOKEN_CUSTOM_EUI --value 0x1122334455667788 --value-type hex

Inside of a project directory:

elcap tokens write --name TR_MFG_TOKEN_MFG_NAME --value "Trident IoT" --value-type ascii

Write Single APP Token

Outside of a project directory:

elcap tokens write --target <chip_pn> --type APP --def path/to/app_token_def.json --name MY_APP_TOKEN --value "Token Value" --value-type ascii

Inside of a project directory:

elcap tokens write --type APP --def path/to/app_token_def.json --name MY_APP_TOKEN --value "Token Value" --value-type ascii

Write Multiple MFG Tokens

Outside of a project directory:

elcap tokens write --target <chip_pn> --file path/to/mfg_token_data.json

Inside of a project directory:

elcap tokens write --file path/to/mfg_token_data.json

Example contents of mfg_token_data.json:

{
    "TR_MFG_TOKEN_VERSION": {
        "value": "4",
        "value_type": "int"
    },
    "TR_MFG_TOKEN_CUSTOM_EUI": {
        "value": "0x0011223344556677",
        "value_type": "hex"
    },
    "TR_MFG_TOKEN_MFG_NAME": {
        "value": "Trident MFG Name",
        "value_type": "ascii"
    },
    "TR_MFG_TOKEN_MODEL_NAME": {
        "value": "ALL CLUSTERS TEST",
        "value_type": "ascii"
    },
}

Write Multiple APP Tokens

Outside of a project directory:

elcap tokens write --target <chip_pn> --type APP --def path/to/app_token_def.json --file path/to/app_token_data.json

Inside of a project directory:

elcap tokens write --type APP --def path/to/app_token_def.json --file path/to/app_token_data.json

Example contents of app_token_data.json:

{
    "MY_APP_TOKEN_U32": "0x11223344",
    "MY_APP_TOKEN_STRING": "This is a string"
}

NOTE: APP tokens must be defined in a Trident project before interacting with them via elcap.

Tokens Erase

---

elcap tokens erase

Options

--option	description	default
--type	Specifies the type of token to use - 'APP' or 'MFG'	MFG
--target	Chip target - 'T32CM11C' or 'T32CZ20B'	None or chip from project directory
--def	JSON token definition file (only required for APP type)	None
--name	Name of the single token to erase, leave off to read all	None
--usb	USB serial no. of connected programmer/dev kit	None
--ip	IP address of connected programmer/dev kit	None
--alias	Alias for the JLink device	None
--interface	Programming interface (SWD or JTAG)	SWD
--speed	Programming speed in kHz	4000
--confirm	Auto-confirm erasing all tokens, only for mass erase	No auto-confirm
--help	Print help for this sub-command	None

Erase All MFG Tokens

Outside of a project directory:

elcap tokens erase --target <chip_pn>

Inside of a project directory:

elcap tokens erase

NOTE: use –confirm option to erase all tokens without additional user input.

Erase All APP Tokens

Outside of a project directory:

elcap tokens erase --target <chip_pn> --type APP --def path/to/app_token_def.json

Inside of a project directory:

elcap tokens erase --type APP --def path/to/app_token_def.json

NOTE: use –confirm option to erase all tokens without additional user input.

Erase Single MFG Token

Outside of a project directory:

elcap tokens erase --target <chip_pn> --name TR_MFG_TOKEN_MODEL_NAME

Inside of a project directory:

elcap tokens erase --name TR_MFG_TOKEN_MODEL_NAME

Erase Single APP Token

Outside of a project directory:

elcap tokens erase --target <chip_pn> --type APP --def path/to/app_token_def.json --name MY_APP_TOKEN

Inside of a project directory:

elcap tokens erase --type APP --def path/to/app_token_def.json --name MY_APP_TOKEN

Tokens Patch

---

elcap tokens patch <input_hex_file> [output_hex_file]

Arguments

argument	description	required
input_hex_file	Path to the input hex file to patch	Yes
output_hex_file	Path to the output hex file (defaults to modifying input in place)	No

Options

--option	description	default
--type	Specifies the type of token to use - 'APP' or 'MFG'	MFG
--target	Chip target - 'T32CM11C' or 'T32CZ20B'	None or chip from project directory
--def	JSON token definition file (only required for APP type)	None
--name	Name of the single token to patch	None
--value	Value to patch when using --name option	None
--value-type	Value data type when using --name option (hex, int, ascii)	None
--file	Token data JSON file to use when patching multiple tokens	None
--help	Print help for this sub-command	None

Patch Single MFG Token

Outside of a project directory:

elcap tokens patch firmware.hex --target <chip_pn> --name TR_MFG_TOKEN_CUSTOM_EUI --value 0x1122334455667788 --value-type hex

Inside of a project directory:

elcap tokens patch firmware.hex --name TR_MFG_TOKEN_MFG_NAME --value "Trident IoT" --value-type ascii

Patch Single APP Token

Outside of a project directory:

elcap tokens patch firmware.hex --target <chip_pn> --type APP --def path/to/app_token_def.json --name MY_APP_TOKEN --value "Token Value" --value-type ascii

Inside of a project directory:

elcap tokens patch firmware.hex --type APP --def path/to/app_token_def.json --name MY_APP_TOKEN --value "Token Value" --value-type ascii

Patch Multiple MFG Tokens

Outside of a project directory:

elcap tokens patch firmware.hex patched_firmware.hex --target <chip_pn> --file path/to/mfg_token_data.json

Inside of a project directory:

elcap tokens patch firmware.hex patched_firmware.hex --file path/to/mfg_token_data.json

Example contents of mfg_token_data.json:

{
    "TR_MFG_TOKEN_VERSION": {
        "value": "4",
        "value_type": "int"
    },
    "TR_MFG_TOKEN_CUSTOM_EUI": {
        "value": "0x0011223344556677",
        "value_type": "hex"
    },
    "TR_MFG_TOKEN_MFG_NAME": {
        "value": "Trident MFG Name",
        "value_type": "ascii"
    },
    "TR_MFG_TOKEN_MODEL_NAME": {
        "value": "ALL CLUSTERS TEST",
        "value_type": "ascii"
    }
}

Patch Multiple APP Tokens

Outside of a project directory:

elcap tokens patch firmware.hex patched_firmware.hex --target <chip_pn> --type APP --def path/to/app_token_def.json --file path/to/app_token_data.json

Inside of a project directory:

elcap tokens patch firmware.hex patched_firmware.hex --type APP --def path/to/app_token_def.json --file path/to/app_token_data.json

In-Place Patching

If you don't specify an output file, the input file will be modified in place:

elcap tokens patch firmware.hex --name TR_MFG_TOKEN_CUSTOM_EUI --value 0x1122334455667788 --value-type hex