11.a. Bootloader Protocol

This section documents the protocol used by Wixel USB Bootloader. This information is for advanced users who want to write their own software for loading apps onto the Wixel. Most users can just use the Wixel Configuration Utility and WixelCmd, which implement this protocol. If you have trouble using this information, please post on the Wixel section of our forum.

The Wixel USB Bootloader can be identified by its USB vendor ID and product ID. The bootloader uses the vendor ID of Pololu Corporation, which is 0x1FFB, and its product ID is 0x0100.

The bootloader supports the following USB requests, which are implemented as control transfers on endpoint 0.

Request: Read Flash

bmRequestType	0xC0
bRequest	REQUEST_READ_FLASH
wValue	The address of the region of flash to read.
wIndex	0
wLength	The number of bytes to read. Must be greater than 0.

The data transferred from the bootloader will consist of the bytes from the specified region of flash memory.

Request: Erase Flash Page

bmRequestType	0xC0
bRequest	REQUEST_ERASE_FLASH
wValue	The address of the page of flash to erase. Must be a multiple of 1024.
wIndex	0
wLength	1

The data transferred from the bootloader will be a one-byte error code. A value of zero indicates success, and the other error codes are listed below.

Request: Write Flash Block

bmRequestType	0x40
bRequest	REQUEST_WRITE_FLASH_BLOCK
wValue	The address of the block to write. Must be even.
wIndex	0
wLength	Must be even, greater than 0, and at most 3072.

The data transferred to the bootloader will be written to the specified address in flash and verified. If an error occurs, then the bootloader will respond with a STALL packet in the Status stage and the specific error code can be retrieved using the Get Last Error request.

Request: Get Last Error

bmRequestType	0xC0
bRequest	REQUEST_GET_LAST_ERROR
wValue	0
wIndex	0
wLength	1

The data transferred from the bootloader will be a one-byte error code for the last Write Flash Block request. It will be zero if the last Write Flash Block was successful, and the other error codes are listed below.

Request: Check Application

bmRequestType	0xC0
bRequest	REQUEST_CHECK_APPLICATION
wValue	0
wIndex	0
wLength	1

The data transferred from the bootloader will be a single byte with a value of 0 if the app is invalid and 1 if the application is valid. The app is considered to be valid if the first byte of the application flash region is not 0xFF.

Request: Restart

bmRequestType	0x40
bRequest	REQUEST_RESTART
wValue	The number of milliseconds to delay while disconnected from USB (500 is recommended).
wIndex	0
wLength	0

This request causes the bootloader to disable the USB pull-up resistor on D+, signaling a disconnect from the bus. The bootloader then delays for the specified time, and then does a system reset. The behavior of the Wixel after a reset is documented in Section 11. This request is generally used to start running the app.

Request codes

Request code	Value
REQUEST_WRITE_FLASH_BLOCK	0x82
REQUEST_GET_LAST_ERROR	0x83
REQUEST_CHECK_APPLICATION	0x84
REQUEST_ERASE_FLASH	0x85
REQUEST_READ_FLASH_BLOCK	0x86
REQUEST_RESTART	0xFE

Error codes

Error code	Value	Description
ERROR_LENGTH	2	The wLength parameter was not valid.
ERROR_VERIFICATION	5	Verification of the data written to flash failed.
ERROR_ADDRESS_RANGE	6	The given address was not in the application section.
ERROR_ADDRESS_ALIGNMENT	8	The given address was not properly aligned.

Tips

We recommend first erasing the Wixel’s flash in ascending order and then writing it in descending order. The last Write Flash Block request should only write the first two bytes of flash and nothing else. Doing this makes it very unlikely that an interrupted firmware upgrade could leave the Wixel in an invalid state. If the firmware upgrade is interrupted, the first byte of flash will almost certainly be 0xFF, so the bootloader will not attempt to run the app.

The requests listed above can only operate on the application section of flash memory (0x400–0x77FF).