Support » Pololu Wixel User’s Guide » 11. The Wixel USB Bootloader »
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).