Overview

A token is a chunk of data that is stored in a special region of flash outside of the application space that can be used for storing information so that it persists across reboots and power loss. This special area in flash can also be interacted with using elcap which allows for things like calibration data or serial numbers to be provisioned without needing to modify the application.

There are 2 types of tokens: MFG and APP tokens. MFG tokens are pre-defined and built into all Trident IoT applications while APP tokens are defined by the end user and are optional to support. Currently APP tokens are only supported in Zigbee applications.

MFG Tokens

MFG tokens are manufacturing tokens that are supported by all 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.

MFG tokens can be written at runtime only if the token was previously erased. Once it has been written, then that token cannot be written again from the application itself. MFG tokens can be read at runtime as many times as you wish. See MFG Tokens for the APIs used to interact with MFG tokens at runtime.

Interacting with tokens off the device is done via elcap.

Token ID	Size	Description
TR_MFG_TOKEN_VERSION	2	2 byte version ID
TR_MFG_TOKEN_CUSTOM_EUI	8	Used to override default EUI64 that comes provisioned in a chip
TR_MFG_TOKEN_MFG_NAME	32	ASCII manufacturer name
TR_MFG_TOKEN_MODEL_NAME	32	ASCII model name
TR_MFG_TOKEN_HW_VERSION	1	Single byte hardware version ID
TR_MFG_TOKEN_MANUF_ID	2	Set MFG ID used by Zigbee applications
TR_MFG_TOKEN_SERIAL_NUM	8	Used to provision serial number into device
TR_MFG_TOKEN_XTAL_TRIM	2	XTAL frequency calibration value (Valid values: 0-63)
TR_MFG_TOKEN_PHY_CONFIG	2	Future support
TR_MFG_TOKEN_CCA_THRESHOLD	2	Sets 802.15.4 CCA threshold magnitude (ex. 80 = -80dBm)
TR_MFG_TOKEN_CBKE_DATA	92	Future support
TR_MFG_TOKEN_INSTALLATION_CODE	20	Zigbee Install Code
TR_MFG_TOKEN_DISTRIBUTED_KEY	16	Zigbee Distributed Network Key
TR_MFG_TOKEN_SECURITY_CONFIG	2	Future support
TR_MFG_TOKEN_CBKE_283K1_DATA	148	Future support
TR_MFG_TOKEN_NVM_CRYPTO_KEY	16	Future support
TR_MFG_TOKEN_BOOTLOAD_AES_KEY	16	Future support
TR_MFG_TOKEN_SECURE_BOOTLOADER_KEY	16	128-bit key for secure bootloader to decrypt OTA images - Future Support
TR_MFG_TOKEN_SIGNED_BOOTLOADER_KEY_X	32	X component of ECDSA P-256 public key
TR_MFG_TOKEN_SIGNED_BOOTLOADER_KEY_Y	32	Y component of ECDSA P-256 public key
TR_MFG_TOKEN_SERIAL_BOOT_DELAY_SEC	1	Seconds to delay serial bootloader from starting application
TR_MFG_TOKEN_THREAD_JOIN_KEY	34	Future support
TR_MFG_TOKEN_ZWAVE_COUNTRY_FREQ	1	Z-Wave Frequency Region ID
TR_MFG_TOKEN_ZWAVE_INITIALIZED	1	Indicates if Z-Wave fields are initialized
TR_MFG_TOKEN_ZWAVE_QR_CODE	106	ASCII QR code string for Z-Wave DSK (Note: Size is max size)
TR_MFG_TOKEN_ZWAVE_PUK	32	Z-Wave Public key
TR_MFG_TOKEN_ZWAVE_PRK	32	Z-Wave Private key

XTAL Trim

The XTAL trim token is used to calibrate the external crystal during manufacturing time. The range of valid values that can be set in this token are described for each supported chip below:

Chip PN	XTAL Trim Range
T32CM11	0 to 1023
T32CZ20	0 to 63

Zigbee Install Codes

What is an Install Code?: A Zigbee Install Code is a random secret value shared out-of-band between a device and the Trust Center during commissioning. It enhances network security by deriving a unique link key for secure joining.

Token Structure: TR_MFG_TOKEN_INSTALLATION_CODE = [2-byte flags] [16 byte IC] [2-byte CRC]

1. Flags (2 bytes)

The first 4 bits specify the Install Code length (The current Zigbee Specification requires 16-byte install codes):

0xFF0F = 16-byte Install Code

2. IC - Install Code (16 bytes)

Random hex value shared with the Trust Center.

3. CRC (2 bytes)

Cyclic Redundancy Check computed using CRC-16/CCITT-FALSE (polynomial 0x1021, initial value 0xFFFF, RefIn/RefOut = true, XorOut = 0xFFFF). Calculate over the Install Code bytes only. Use online tools like https://crccalc.com/ (select "CRC-16/IBM-SDLC"). Append result MSB first.

Example to create 16-byte IC token (20 bytes total)

For a 16-byte IC, the flags will be: 0xFF0F
Generate a random 16-byte hex IC: 0x83FED3407A939723A5C639B26916D505
Go to https://crccalc.com/, enter your random IC, and find the CRC-16/IBM-SDLC result: 0xB5C3

Now construct the complete 20-byte token:

TR_MFG_TOKEN_INSTALLATION_CODE = 0xFF0F83FED3407A939723A5C639B26916D505B5C3

Derived Link Key: Your device automatically hashes the Install Code using the Matyas-Meyer-Oseas (MMO) hash function (AES-128, 128-bit digest per Zigbee spec Annex B.6) to create a derived link key. This derived key is the actual secret used to securely transport the network key from the coordinator to your joining device. The coordinator must be pre-configured with the Install Code (and sometimes the CRC) and the device's EUI64 to match the correct Install Code to the joining device. The coordinator with this new information should then use the same hash function above to derive the same link key for joining.

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 miscellaneous data in persistent memory. Defining APP tokens is done using the Trident framework from within a project. See APP Tokens for APIs used to do this. See any of the Zigbee Sample Applications for a sample implementation.

APP tokens differ from MFG tokens in 2 key ways. APP tokens are defined by the user in their specific application and are not pre-defined by Trident IoT. They can also be written during run time multiple times instead of the single write that MFG tokens support.

Interacting with tokens off the device is done via elcap.