How do I create my own XDV files for loading predetermined manufacturing tokens?

On the subject of tokens (non-volatile settings used in the EmberZNet platform), although many customers use the EM2xx_Patch or EM2USBPatch utility to alter the manufacturing token data on each device at manufacturing time, it is possible, as explained in the EmberZNet Utilities Guide (document 120-4020-0000), to manually create an XDV file that can contain manufacturing token data. This XDV file can then be used with EM2xx_Load or EM2USBLoad to load this data into your devices in addition to any normal flash data (such as bootloader and/or application firmware).

To help understand this process, you should first gain familiarity with the format of the XDV file, which is used to store data records (addresses and values) for the XAP2b architecture (used by the EM250 and EM260 chips). You can find an example of the XDV file format by inspecting one of the XDV files produced by your normal build (in the build output directory). Essentially, the file is a listing of byte addresses and the contents programmed at each, with some special instructions contained in the comments towards the top of the file.

In the case of programming manufacturing (“mfg”) data, the addresses refer to offsets into the manufacturing token space. (Note that this space, also known as the FIA or Flash Information Area, is a separate area of flash not considered as part of the 128KB programmable memory of the chip. It is NOT writeable by running code, only by SIF utilities such as the EM2xx and EM2USB executables. SIF utilities and applications can read the values, however. Values are intended to be written only once, although values may be “overridden” in cases where mfg data needs to be altered after its initial setting.) Since the first MFG token address is at 0×5000, the offset (which is also used in the address syntax for em2xx_read/patch commands) for a given mfg token is obtained by looking at the address declaration in hal/micro/xap2b/token-manufacturing.h and then subtracting 0×5000 from this value. Customers are encouraged read the “Setting Manufacturing Tokens” section of Application Note 5031 (for EM250) or 5041 (for EM260), in order to understand what mfg tokens exist and how they should be set (if at all). In cases where the token-manufacturing.h file is not available (such as in EM260 releases, which don’t include a HAL for the NCP), these application notes can also be consulted to obtain the mfg word (16-bit) offsets for each token.

For example, the Board Name token (used for providing a model number for the hardware) is declared in hal/micro/xap2b/token-manufacturing.h (circa EmberZNet 3.1.1 release) as follows:

#define MFG_BOARD_NAME_LOCATION 0×509A // 16 bytes

This means that the byte offset of this mfg token (needed for the XDV file) is 0×9A, and the word address (needed for the em2xx_read command) would therefore be half of this: 0×4D. This offset is confirmed by Aplication Note 5041, which lists MFG_BOARD_NAME with Word Offset 0×004D in the table of user-programmable EmberZNet manufacturing tokens.

To set the value (ASCII string of “DIBB” as an example) of this mfg token via an XDV file, you would specify bytes beginning at offset 0×9A (from the effective “zero” address of the Mfg area), so your XDV file would look something like this:

// ROM START ADDRESS 0000
// WORDSIZE 8
// BASE HEX : HEX
@009A   44
@009B   49
@009C   42
@009D   42
@009E   00
@009F   00
@00A0   00
@00A1   00

The above sets the Board Name token value to “DIBB “ when programmed. Other mfg token addresses are left unchanged.

Note that the 3 comment lines at the top are significant, since they tell the em2xx /em2USB tools how to parse the data:

• Addresses should be considered offsets from 0×0000. (Note that when the XDV file is programmed with the “-Mfg” command line option, this starting address is considered as the beginning of the mfg section, rather than the beginning of the normal Flash memory area.)
• Data sizes are 8 bits (byte addresses and values) rather than 16 bits.
• Number base for values is hexadecimal.

You should always include these comments at the top of your XDV file for best results.

Attached to this article is an example of the XDV file illustrated above, as well as two text files showing how this file is used in the manufacturing process:

• mfgload.txt – Command line and results of loading this mfg data to a node called 133bxi. (An EBL, XPV or HEX filename could also be appended to the command line in order to load firmware data/code to the Flash memory of the chip in the same operation as programming the XDV file’s mfg data.)
• mfgread.txt – Command line and results of reading this mfg data back from the 133bxi node, confirming expected results. (The “-outfile XXX” argument could also provided to this command to save the extracted data to some file, XXX.)

It is important to note (in the example command lines) that the “-Mfg” argument must be included so that the em2xx/em2USB tools understand that the addresses are relative to the manufacturing token area, as opposed to the standard 128KB of memory used for application/bootloader/token firmware.

Keep in mind that only manufacturing token data is appropriate to pre-construct in an XDV file in this manner. The stack’s tokens (such as saved network and security settings) are completely separate from the mfg tokens discussed abovem as they are stored in the normal 128KB of flash memory in a region used by the EM2xx HAL’s Simulated EEPROM (SimEE) driver. Therefore, you should not attempt to pre-program these manually, as the token storage in this region is not linear but rather it follows a complex algorithm of data writing via the SimEE driver. Also, the data format (based on the driver version and the stack token map) may change subtlely between stack releases, so you should not depend on a certain construction of these data. If you need to erase stack/application token data residing in the SimEE region, you should use the “-erase” option with em2xx_load/em2USBLoad. Once the area is clean, the stack will initialize the area with appropriate defaults during emberInit() at next boot time.

If you absolutely must use preloaded token defaults for non-mfg tokens, please obtain this data from an existing (working) device that is not currently part of a PAN (never joined a network or has most recently executed a LeaveNetwork action) so that any PAN-specific tokens are cleared. This can be done by performing em2xx_read on address range 0xF000-0xFFFF and saving the output to a HEX file for later programming. However, this process is generally discouraged (for the same reasons as for avoiding preprogramming this SimEE data as above), versus the option of booting the device with a clean SimEEPROM (via “-erase” option or loading of a HEX file that contains all FFFF words in this 0xF000-0xFFFF range.)

For more information about the SimEE driver, please consult Application Note 5037: Using Simulated EEPROM.