diff --git a/protocol.md b/protocol.md index f6de349..cbae140 100644 --- a/protocol.md +++ b/protocol.md @@ -6,7 +6,9 @@ Each command and response is framed as follows: ``` -<2 byte header> <1 byte command> <1 byte payload word length> <2 byte trailer> <2 byte crc> +<2 byte header> <1 byte command> <1 byte payload word length> <2 byte crc> <2 byte trailer> +| | | | | | +-<0x01><0x88>-- ----------------- CRC Checked Data -------------------- --<0x99><0x03>-- ``` - The header is <0x01><0x88> @@ -15,10 +17,10 @@ Each command and response is framed as follows: corresponds to a payload 4 bytes in length. - The payload is optional depending on the command. If present it must be a multiple of 4 bytes in length. -- Any arguments within the payload should be sent in big endian byte order. -- The CRC is performed on the entire frame (header through trailer) using +- The CRC is performed on the command byte, length byte, and payload using the standard CRC16-CCITT algorithm. -- The CRC and all integer arguments are sent in big endian byte order. +- The CRC and all integer arguments within the payload are sent in little-endian + byte order. ### Commands @@ -29,88 +31,97 @@ The bootloader accepts the following commands: Initiates communication with the bootloader. This command has no payload: ``` -<0x01><0x88><0x11><0x00><0x99><0x03> +<0x01><0x88><0x11><0x00><0x99><0x03> ``` -Responds with [acknowledged](#acknowledged-0xa0) containing a 4 byte payload +Responds with [acknowledged](#acknowledged-0xa0) containing a 16 byte payload in the following format: ``` -<0x11><0x00><2 byte block_size> +<4 byte orig_command><4 byte protocol_version><4 byte start_address><4 byte block_size> ``` -The `block_size` is a 16 bit unsigned integer in big endian byte order. It -represents the size of a block (in bytes) expected in the `send block` and -`request block` commands. Typically this should be 64 bytes. +- `orig_command` - must be `0x11` +- `protocol_version` - The current version of the protocol. This is an integer + value, where each of the 3 least significant bytes represent a part of the + version string. For example, a value of `0x00010002` represents `1.0.2`. +- `start_address` - The application start address in flash memory. All addresses + provided in the `send_block` and `request block` commands must start at this + address. +- `block_size` - the size of a block (in bytes) expected in the `send block` and + `request block` commands. Typically this should be 64 bytes. + #### Send Block: `0x12` -Sends a block of data to be written. This command takes a `block index` -argument followed by the block of data: +Sends a block of data to be written. ``` -<0x01><0x88><0x12><1 byte payload word length><4 byte block_index><0x99><0x03> +<0x01><0x88><0x12><1 byte payload word length><4 byte block_address><0x99><0x03> ``` +The `payload word length` will include one word for the `block_address` argument +plus `block_size / 4` for the data. -The `payload word length` will include one word for the block index argument -plus `block_size // 4` for the data. - -The `block_index` refers to a single block within the binary of `block_size` -bytes, starting at 0. It should be sent as 32-bit integer in big endian format. +The `block_address` refers to a address in flash memory where the block write +should begin. The first `block_address` must be the `start_address` received +in the [connect](#connect-0x11) command. The `block_data` is the data contained with in the block. If the final block is less than `block_size` in length it should be padded with `0xFF` to fill the remainder. -Responds with [acknowledged](#acknowledged-0xa0) containing a 4 byte payload +Responds with [acknowledged](#acknowledged-0xa0) containing an 8 byte payload in the following format: ``` -<0x12><0x00><2 byte block_index> +<4 byte orig_command><4 byte block_address> ``` -The returned `block_index` is a 16-bit unsigned integer in big endian byte -order. It must match the `block_index` sent in the request. +- `orig_command`: Must be `0x12` +- `block_address`: Must match the `block_address` sent in the command #### EOF: `0x13` Indicates that the end of file has been reached and the bootloader should -write any remaining in the buffer to flash. This command has no payload: +write any remaining data in the buffer to flash. This command has no payload: ``` -<0x01><0x88><0x13><0x00><0x99><0x03> +<0x01><0x88><0x13><0x00><0x99><0x03> ``` -Responds with [acknowledged](#acknowledged-0xa0) containing a 4 byte payload +Responds with [acknowledged](#acknowledged-0xa0) containing an 8 byte payload in the following format: ``` -<0x13><0x00><2 byte page_count> +<4 byte orig_command><4 byte page_count> ``` -The `page_count` is a 16-bit unsigned integer in big endian byte order. It -represents the total number of pages written to flash. +- `orig_command`: Must be `0x13` +- `page_count`: The total number of pages written to flash. #### Request Block: `0x14` -Requests of block of data in flash, used for verification. This command takes -a `block index` argument indicating the block to read: +Requests of block of data in flash, used for verification. ``` -<0x01><0x88><0x14><0x01><4 byte block_index><0x99><0x03> +<0x01><0x88><0x14><0x01><4 byte block_address><0x99><0x03> ``` -The `block_index` is a 32-bit unsigned integer in big endian byte order. +The `block_address` refers to a address in flash memory where the block read +should begin. The first `block_address` must be the `start_address` received +in the [connect](#connect-0x11) command. Responds with [acknowledged](#acknowledged-0xa0) containing a payload in the following format: ``` -<0x14><0x00><2 byte block_index> +<4 byte orig_command><4 byte block_address> ``` -The returned `block_index` is a 16-bit unsigned integer in big endian byte -order. It must match the `block_index` sent in the request. +- `orig_command`: Must be `0x14` +- `block_address`: Must match the `block_address` sent in the command +- `block_data`: The requested block of data + #### Complete: `0x15` @@ -118,112 +129,33 @@ Indicates that process is complete. The bootloader will reset and attempt to jump to the application after responding to this command: ``` -<0x01><0x88><0x15><0x00><0x99><0x03> +<0x01><0x88><0x15><0x00><0x99><0x03> ``` Responds with [acknowledged](#acknowledged-0xa0) containing a 4 byte payload in the following format: ``` -<0x15><0x00><0x00><0x00> +<4 byte orig_command> ``` ### Responses -All responses contain a payload of at least 4 bytes, where the first -byte contains the command being responded to. It is possible for -a response to include another argument within this first word. - #### Acknowledged: `0xa0` -This response indicate successful execution of a command: +This response indicates successful execution of a command: ``` -<0x01><0x88><0xa0><0x99><0x03> +<0x01><0x88><0xa0><0x99><0x03> ``` The payload depends on the command. -#### Invalid Command: `0xf0` +#### NACK: `0xf1` -Indicates the the bootloader received an invalid command: +Indicates that the bootloader encountered an error when processing +a command. ``` -<0x01><0x88><0xf0><0x01><4 byte payload><0x99><0x03> +<0x01><0x88><0xf1><0x00><0x68><0x95><0x99><0x03> ``` - -The payload is in the following format: - -``` -<1 byte orig_command><0x00><0x00><0x00> -``` - -The `orig_command` is the invalid command received. - -#### CRC Mismatch: `0xf1` - -Indicates that CRC verification failed on the requested command: - -``` -<0x01><0x88><0xf1><0x01><4 byte payload><0x99><0x03> -``` - -The payload is in the following format: - -``` -<1 byte orig_command><0x00><2 byte calculated_crc> -``` - -The `command` is the command received from the original request. -The `calculated_crc` is a 16-bit unsigned integer represented -the CRC calculated on the frame. - -#### Invalid Block: `0xf2` - -Indicates that the payload contained in a [send block](#send-block-0x12) -command is not of the expected lenght: - -``` -<0x01><0x88><0xf2><0x01><4 byte payload><0x99><0x03> -``` - -The payload is in the following format: - -``` -<1 byte orig_command><0x00><0x00><0x00> -``` - -The `orig_command` is the command received which generated - -#### Invalid Trailer: `0xf3` - -Indicates that the trailer of the frame is not `<0x88><0x03>`: - -``` -<0x01><0x88><0xf3><0x01><4 byte payload><0x99><0x03> -``` - -The payload is in the following format: - -``` -<1 byte orig_command><0x00><0x00><0x00> -``` - -The `orig_command` is the command received from the original request. - -#### Invalid Length: `0xf4` - -Indicates that the payload length of a request is too large -to fit within the buffer: - -``` -<0x01><0x88><0xf4><0x01><4 byte payload><0x99><0x03> -``` - -The payload is in the following format: - -``` -<1 byte orig_command><0x00><0x00><0x00> -``` - -The `orig_command` is the command received from the original request.