F. wixel app file format – Pololu Wixel User Manual
Page 61
Initially, you will commit your changes to your local repository, but when you are ready to publish them, you should
set up your own repository on GitHub to make them accessible to the community. To do this, sign up for a GitHub
account and fork our repository into a repository on your account. Please do this by clicking the “fork” button at the
top of
so that it will be connected within the GitHub system – this way
we will see your changes and can easily incorporate them into the SDK. After making your fork, you can push all of
the changes from your local repository to GitHub with
git remote add myrepo <GitHub URL>
git push myrepo
where
<GitHub URL>
is the SSH or HTTP URL shown on your GitHub page.
Finally, you will probably want to post a link to your GitHub repository on
10.e. USB Configurations Recognized by the Wixel Configuration Software
The Wixel Configuration Utility and the Wixel Command-Line Utility can currently only recognize certain Wixel
apps. If your app is not recognized, then users of your app will not easily be able to reconfigure it after they have
loaded it onto their Wixel (they will have to get their Wixel into bootloader mode manually).
To be recognized, your app must implement a particular USB interface. Specifically, it must implement a USB CDC
ACM virtual COM port with vendor ID 0x1FFB and product ID 0x2200. When the USB host sends a command
to your app that sets the baud rate to 333, your app should enter bootloader mode. Your app should work with the
wixel_serial.inf
driver which is installed along with the other Windows software (see
). The easiest
way to write an app that meets these requirements is to use the
usb_cdc_acm.lib
library in the Wixel SDK.
In the future we will add support for other types of USB interfaces if there is a need for it. Please
if you would like to use other types of interfaces in your apps.
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.
Pololu Wixel User's Guide
© 2001–2014 Pololu Corporation
10. Writing Your Own Wixel App
Page 61 of 64