Setting Manufacturing Tokens#
EFR32 chips are delivered to customers with all memory erased. Exceptions to this rule are chips that come with kits. Before the EFR32 chips can be used to run applications for a networking stack, the customer or a contract manufacturer/test house must prepare them. Preparation includes programming the proper application and bootloader, if necessary, into the Main flash block, as well as programming customer manufacturing tokens in the User Data block and Lock Bits block.
Manufacturing tokens are values programmed into special, non-volatile storage area of flash. The User Data page and Lock Bits page contain data that manufacturers of EFR32-based devices can program. The Device Information Page also contains manufacturing tokens, but these tokens are fixed values that cannot be modified.
Note: Applications and the stack can read any manufacturing tokens at any time.
Simplicity Commander is a single, all-purpose tool to be used in a production environment. It is invoked using a simple Command-Line Interface (CLI) that is also scriptable. Simplicity Commander enables customers to complete these essential tasks:
Flash their own applications.
Configure their own applications.
Create binaries for production.
For more information, refer to UG162: Simplicity Commander Reference Guide.
The following two tables identify the User Data manufacturing tokens that OEMs and CMs may want to program at manufacturing time. Refer to platform\base\hal\micro\cortexm3\efm32\token-manufacturing.h for the token definition, because it may differ from these tables depending on the stack release version.
Note: Using tokens to set up manufacturing data in the Silicon Labs Flex SDK only works if you use the Silicon Labs Connect stack. If you’re interfacing the RAIL library directly, you can set up similar values using the board-specific header files.
Silicon Labs recommends that User Data and Lock Bits page tokens be written using Simplicity Commander at the same time as programming the main flash. Simplicity Commander also allows for patching and reprogramming the manufacturing blocks as many times as necessary. (See Simplicity Commander Reference Guide for details.) The following two tables describe the location of each manufacturing token as an offset to the starting address of the relevant block. For the most accurate and specific information about where the flash regions begin in the address map of your chip, please consult your IC’s Reference Manual or Data Sheet.
Some situations may require that a manufacturing token be programmed at runtime from code running on the chip itself. For wireless mesh network SDKs, the manufacturing token module of the HAL provides a token API to write the manufacturing tokens. However, this API only writes manufacturing tokens that are in a completely erased state. If a manufacturing token must be reprogrammed, you must use an external utility.
The API on SoC platforms is
halCommonSetMfgToken(token, data). The parameters for this API are the same as the APIhalCommonSetToken(token, data ).For EmberZNet PRO EZSP NCP platforms, the host API is
ezspSetMfgToken(tokenId, tokenDataLength,tokenData). (See UG100: EZSP Reference Guide for details.)
In the next table, the Connect stack only uses the following tokens (rows in bold):
TOKEN_MFG_CUSTOM_EUI_64
TOKEN_MFG_CTUNE
Table: User Data Manufacturing Tokens for the EFR32
Offset from User Data starting address | ||||
|---|---|---|---|---|
Series 1 | Series 2 | Size (Bytes) | Name | Description |
0x0000 | 0x000C | 2 | TOKEN_MFG_CUSTOM_VERSION | Version number to signify which revision of User Data manufacturing tokens you are using. This value should match CURRENT_MFG_CUSTOM_VERSION which is currently set to |
0x0002 | 0x0002 | 8 | TOKEN_MFG_CUSTOM_EUI_64 | IEEE 64-bit address, unique for each radio. Entered and stored in little-endian. Setting a value here overrides the EUI64 stored in the Device Information Page. This is for customers who have purchased their own address block from IEEE. WARNING: If this value is set "live," it may not propagate to all levels of the stack and some outgoing messages may continue to use the default value. Silicon Labs recommends forcing a reset after setting EUI64 and before starting the networking stack. Usage: Optionally set by device manufacturer if using custom EUI64 address block. |
0x0080 | 0x008C | 16 | TOKEN_MFG_SERIAL_NUMBER | Serial Number value of the entire product in binary representation. Usage: Optionally set by device manufacturer. |
0x001A | 0x0010 | 16 | TOKEN_MFG_STRING | Optional device-specific string, for example, the serial number. Usage: Optionally set by device manufacturer to identify device. |
0x002A | 0x0020 | 16 | TOKEN_MFG_BOARD_NAME | Optional string identifying the board name or hardware model. Usage: Optionally set by device manufacturer to identify device. |
0x003A | 0x0030 | 2 | TOKEN_MFG_MANUF_ID | 16-bit ID denoting the manufacturer of this device. When you are programming with EmberZNet PRO, Silicon Labs recommends setting this value to match your Zigbee-assigned manufacturer code, such as in the stack’s emberSetManufacturerCode()``API call. Usage: Recommended for EmberZNet PRO devices utilizing the stand-alone bootloader. |
0x003C | 0x0034 | 2 | TOKEN_MFG_PHY_CONFIG | Reserved for future use; should be left un-programmed (0xFFFF). |
0x0104 | 0x009C | 1 | TOKEN_MFG_LFXO_TUNE | Manufacturing token space for Low Frequency XTAL tune value. |
0x0108 | 0x0104 | 4 | TOKEN_MFG_KIT_SIGNATURE | Manufacturing token space for Kit Signature. Usage: Optionally set by device manufacturer for kit identification. |
0x003E | 0x0038 | 40 | TOKEN_MFG_ASH_CONFIG | ASH configuration information. Usage: Optional for EmberZNet PRO devices acting as network coprocessors (NCPs) for EZSP-UART. Not used by any SoC use cases. |
0x00F0 | 0x0060 | 2 | TOKEN_MFG_SYNTH_FREQ_OFFSET | Reserved for future use; should be left un-programmed (0xFFFF). Radio synthesizer frequency adjustments should be made using the |
0x00F6 | 0x0064 | 2 | TOKEN_MFG_CCA_THRESHOLD | Threshold(s) used for energy detection Clear Channel Assessment (CCA). You may want to override the default CCA threshold(s) by setting this token if your design uses a Low-Noise Amplifier (LNA). An LNA changes the gain on the radio input which results in the radio "seeing" a different energy level than if no LNA was used. Bits 0-7: Set to the two’s complement representation of the 2.4GHz band CCA threshold in dBm below which a 2.4GHz channel will be considered clear. Valid values are -128 through +126, inclusive. +127 is not valid and must not be used. Bit 8: Set to 0 if the threshold in Bits 0-7 is valid and should be used. Set to 1 (the erased state) if those bits are invalid or have not been set; in this case, the default 2.4GHz band threshold of -75 dBm will be used. Bits 9-15: Applies only to SubGHz-capable PHYs. These bits can be used to override the default CCA threshold that is applied to channels in the SubGHz band (for example, in GB868, the default SubGHz CCA threshold is -87 dBm). The interpretation of the SubGHz CCA threshold value in bits 9..15 is as a 7-bit unsigned value in the range 1..126 which is negated to be the CCA threshold to apply (that is, token values 1..126 in bits 15..9 map to SubGHz CCA thresholds of -1..-126 dBm respectively). The values 0 and 127 (the 7 bits all 0s or all 1s) are interpreted as no override—the default SubGHz CCA threshold will be used. |
0x00F6 (Cont.) | 0x0064 (Cont.) | TOKEN_MFG_CCA_THRESHOLD (Cont.) | Example 1: A 2.4GHz design uses an LNA that provides a gain of +12 dB. Add that gain to the 2.4GHz default threshold of -75 dBm to get the dBm value for the token: -75 + 12 = -63 dBm. The two’s complement signed representation of -63 is 0xC1 so the complete token value to be programmed is 0xFEC1. Example 2: A GB868 SubGHz design uses an LNA that provides a gain of +12 dB. Add that gain to the GB868 SubGHz default threshold of -87 dBm to get the negated dBm value for the token: -87 + 12 = -75 dBm. Negating, the value 75 or 0x4B goes into bits 9..15 of the token so the complete token value to be programmed is 0x97FF. Example 3: A dual-PHY design has an LNA like Example 1 for 2.4GHz and an LNA as in Example 2 for GB868 SubGHz. The token values in those examples combine to be 0x96C1 for this design. | |
0x00F8 | 0x0068 | 8 | TOKEN_MFG_EZSP_STORAGE | An 8-byte, general-purpose token that can be set at manufacturing time and read by the host microcontroller via EZSP’s getMfgToken command frame. Usage: Not required. Device manufacturer may populate or leave empty as desired. |
0x0100 | 0x0100 | 2 | TOKEN_MFG_CTUNE | This token is for tuning the EFR32 system XTAL and consequently also tunes the radio synthesizer frequency. Usage: Optional. Only necessary if additional crystal tuning is desired to reach optimal timing and frequency output. |
0x0102 | 0x0070 | 2 | TOKEN_MFG_XO_TUNE | This token is for tuning an attached Si446x transceiver's system crystal and consequently also tunes its radio synthesizer frequency. A value in the least-significant byte in the range 0x00 to 0x7F will be applied to the Si446x's GLOBAL_XO_TUNE property. All other values are currently ignored and reserved for future use. |
In the next table, the Connect stack only uses the following tokens for the Gecko Bootloader (rows in bold):
TOKEN_MFG_SECURE_BOOTLOADER KEY
TOKEN_MFG_SIGNED_BOOTLOADER KEY_X
TOKEN_MFG_SECURE_BOOTLOADER KEY_Y
Table: Lock Bits Manufacturing Tokens for the EFR32
Offset from Lock Bits starting address | ||||
|---|---|---|---|---|
(Series 1) | (Series 2) | Size (Bytes) | Name | Description |
0x0204 | 0x032C | 16 | TOKEN_MFG_BOOTLOAD_AES_KEY | Reserved for future use; should be left un-programmed (all 0xFF bytes). |
0x0214 | 0x0204 | 92 | TOKEN_MFG_CBKE_DATA | Defines the security data necessary for Smart Energy devices. It is used for Certificate Based Key Exchange to authenticate a device on a Smart Energy network. The first 48 bytes are the device’s implicit certificate, the next 22 bytes are the Root Certificate Authority’s Public Key, the next 21 bytes are the device’s private key (the other half of the public/private key pair stored in the certificate), and the last byte is a flags field. The flags field should be set to 0x00 to indicate that the security data is initialized. For more information on the Smart Energy tokens, see document AN708: Setting Smart Energy Certificates for Zigbee Device**s. Usage: Required by Smart Energy Profile certified devices. |
0x0270 | 0x0270 | 20 | TOKEN_MFG_INSTALLATION_CODE | Defines the installation code for Zigbee devices. The installation code is used to create a pre-configured link key for initially joining a Zigbee 3.0 or Zigbee Smart Energy (ZSE) network. The first 2 bytes are a flags field, the next 16 bytes are the installation code, and the last 2 bytes are a CRC. Valid installation code sizes for ZSE devices are 6, 8, 12, or 16 bytes in length, but Zigbee 3.0 devices are required to use 16-byte installation codes. All unused bytes should be 0xFF. The flags field should be set as follows depending on the size of the install code: 6 bytes = 0x0000 8 bytes = 0x0002 12 bytes = 0x0004 16 bytes = 0x0006 For more information on working with Zigbee installation codes, see document Using Installation Codes with Zigbee Devices. For more information on the Smart Energy tokens, see document AN708: Setting Smart Energy Certificates for Zigbee Devices. Usage: Required by Zigbee 3.0 and Zigbee Smart Energy compliant devices. |
0x0284 | 0x0260 | 2 | TOKEN_MFG_SECURITY_CONFIG | (EmberZNet PRO only) Defines the security policy for application calls into the stack to retrieve key values. The API calls emberGetKey() and emberGetKeyTableEntry() are affected by this setting. This prevents a running application from reading the actual encryption key values from the stack. This token may also be set at runtime with emberSetMfgSecurityConfig() (see that API for more information). The stack utilizes the emberGetMfgSecurityConfig() to determine the current security policy for encryption keys. The token values are mapped to the EmberKeySettings stack data type (defined in ember-types.h). See the following table for the mapping of token values to the stack values. Usage: Optional for EmberZNet NCP devices wishing to limit access to security data over the serial interface. |
0x0286 | 0x0286 | 16 | TOKEN_MFG_SECURE_BOOTLOADER_KEY | This token holds the 128 bit key used by the secure bootloader to decrypt encrypted Ember Bootloader (EBL) and Gecko Bootloader (GBL) files. A value of all F’s is considered an invalid key and will not be used by the secure bootloader. Usage: Required only if using one of the Ember bootloaders with the "secure" prefix, or the Gecko Bootloader with support for encrypted GBL files enabled. See UG266: Gecko Bootloader User Guide for GSDK 3.2 and Lower or Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher, for more information on the Gecko Bootloader. |
0x0296 | 0x0298 | 148 | TOKEN_MFG_CBKE_283K1_DATA | Defines the security data necessary for Smart Energy 1.2 devices using the ECC 283k1 curve. It is used for Certificate Based Key Exchange to authenticate a device on a Smart Energy network. The first 74 bytes are the device’s implicit certificate, the next 37 bytes are the Root Certificate Authority’s Public Key, the next 36 bytes are the device’s private key (the other half of the public/private key pair stored in the certificate), and the last byte is a flags field. The flags field should be set to 0x00 to indicate that the security data is initialized. For more information on the Smart Energy tokens, see document AN708: Setting Smart Energy Certificates for Zigbee Devices. Usage: Required for Zigbee Smart Energy 1.2 devices. |
0x34A | 0x034C | 32 | TOKEN_MFG_SIGNED_BOOTLOADER_KEY_X | These tokens hold the 256-bit X and Y components of the ECDSA P-256 public key used by the Gecko bootloader to perform cryptographic signature verification of signed GBL files ("secure bootload") and signed application images ("secure boot"). A value of all F’s is considered an invalid key. See UG266: Gecko Bootloader User Guide for GSDK 3.2 and Lower or Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher, for more information on the Gecko Bootloader. Usage: Required only if using the Gecko bootloader with secure boot or support for signed GBL files is enabled. |
0x36A | 0x036C | 32 | TOKEN_MFG_SIGNED_BOOTLOADER_KEY_Y | |
0x038A | 0x038C | 34 | TOKEN_MFG_THREAD_JOIN_KEY | This token is for saving the Join Key. The Join Key has a max length of 32 Bytes. Usage: Optional. Use with the Silicon Labs Thread Stack only. |
0x0448 | 0x03B0 | 16 | TOKEN_MFG_NVM3_CRYPTO_KEY | Manufacturer Token space for Storing NVM3 Crypto Key. |
Table: Mapping of EmberKeySettings to TOKEN_MFG_SECURITY_CONFIG
EmberKeySettings Value | TOKEN_MFG_SECURITY_CONFIG Value |
|---|---|
| 0x0000 |
| 0x00FF |
| 0xFF00 |