10.f. Wixel App File Format

For the purpose of loading a compiled program onto a Wixel, the Wixel Configuration Utility and the Wixel Command-Line Utility (WixelCmd) accept two file formats: Intel HEX (.hex) and Wixel App (.wxl). The Intel HEX (.hex) file format is an industry standard, and can be produced by most toolchains. The Wixel App (.wxl) file format is a simple format created by Pololu that includes an Intel HEX file inside it along with important metadata, such as the names and addresses of user-configurable parameters. The Wixel App file format is designed to be extensible and easy to generate.

The Wixel App file is plain text: every byte is an ASCII-encoded character. The allowed ASCII codes are 0x20 through 0x7F and also 0x09 (tab), 0xA (new line, “\n”), and 0xD (carriage return, “\r”). The bytes in a Wixel App file are divided into lines. Line endings can be encoded with any of the following byte sequences: “\r\n” (0xD, 0xA), “\r” (0xD), or “\n” (0xA).

The first line must be “Pololu Wixel Application - www.pololu.com”. This line explains the purpose of the Wixel App file. The second line must be “1.0”. This specifies the version number of the file format used in the file.

The third line and all the lines below it are divided into sections. Each section has a one-line header at the top of it that specifies the name of the section. The header line consists of 6 equals signs (======) followed by a space, followed by the name of the section. The order of the sections does not matter. The only sections required by the Wixel software are the cdb and hex sections.

The hex section

The hex section contains an Intel Hex file that specifies the bytes to write to the flash of the Wixel. See the Intel HEX page on Wikipedia for more information. The flash memory region on the CC2511F32 that is available for Wixel applications consists of addresses 0x400 through 0x77FF (inclusive). Any line of the HEX file that writes to bytes outside of this region will be ignored.

The license section

The license section is a human-readable section that should specify the terms under which others may distribute copies or modifications of the app. The Wixel SDK automatically inserts the MIT license into all Wixel App files because that is required by the Wixel SDK’s license.

The description section

The description section is a human-readable section that should describe what the app does or link to a web site about the app.

The cdb section

The cdb section contains the names and addresses of the user-configurable parameters. For each parameter, there must be two lines in this section (not necessarily consecutive) as specified below.

One line contains the address of the parameter, and must be of the form: L:G$param_NAME$0$0:ADDRESS where NAME is the name of the parameter and ADDRESS specifies the address of the parameter in the Wixel’s flash memory as a 4-digit hexadecimal number (e.g. “11C3”).

Another line contains the type of the parameter, and must be of the form: S:G$param_NAME$0$0(TYPE),D,0,0 where NAME is the name of the parameter and TYPE is the type of the parameter. Currently, the only allowed type is a 32-bit signed integer, which is encoded as “{4}SL:S”.

The Wixel SDK generates the cdb of section by running grep on the CDB file produced by SDCC during the linking step, selecting all lines containing the string “param”. This means you can define a parameter simply by writing the following code in your Wixel App, outside of any function:

int32 CODE param_NAME = DEFAULT_VALUE;

where NAME is the name of your parameter and DEFAULT_VALUE is the default value it will have if the user does not change its value. This default value is stored in the hex section, not the cdb section.

You could put your entire CDB file in the WXL file if you wanted to; the software ignores unrecognized lines. However the CDB file can be hundreds of kilobytes long so this is not encouraged.

Wixel App files usually have non-Windows line endings in the cdb section so they can not be viewed properly in Notepad or other text editors that only recognize Windows line endings.