protocol.md

February 24, 2025 ยท View on GitHub

Katapult Protocol

Frame

Each command and response is framed as follows:

<2 byte header> <1 byte command> <1 byte payload word length> <payload> <2 byte crc> <2 byte trailer>
|             | |                                                     |              |              |
-<0x01><0x88>-- ----------------- CRC Checked Data --------------------              --<0x99><0x03>--
  • The header is <0x01><0x88>
  • The trailer is <0x99><0x03>
  • The payload length must be specified in 4 byte words. A value of 1 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.
  • The CRC is performed on the command byte, length byte, and payload using the standard CRC16-CCITT algorithm.
  • The CRC and all integer arguments within the payload are sent in little-endian byte order.

Commands

The bootloader accepts the following commands:

Connect: 0x11

Initiates communication with the bootloader. This command has no payload:

<0x01><0x88><0x11><0x00><CRC><0x99><0x03>

Responds with acknowledged containing a variable length payload in the following format:

<4 byte orig_command><4 byte protocol_version><4 byte start_address><4 byte block_size><n byte mcu_type_string><1 null byte><n byte software_version_string>
  • 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.
  • mcu_type_string - The type of micro-controller (eg, "stm32f103xe").
  • software_version_string - The software version as reported by git describe --tags --always --long --dirty.

Send Block: 0x12

Sends a block of data to be written.

<0x01><0x88><0x12><1 byte payload word length><4 byte block_address><block_data><CRC><0x99><0x03>

The payload word length will include one word for the block_address argument plus block_size / 4 for the data.

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 command.

The block_data is the data contained within 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 containing an 8 byte payload in the following format:

<4 byte orig_command><4 byte block_address>
  • 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 data in the buffer to flash. This command has no payload:

<0x01><0x88><0x13><0x00><CRC><0x99><0x03>

Responds with acknowledged containing an 8 byte payload in the following format:

<4 byte orig_command><4 byte page_count>
  • 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.

<0x01><0x88><0x14><0x01><4 byte block_address><CRC><0x99><0x03>

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 command.

Responds with acknowledged containing a payload in the following format:

<4 byte orig_command><4 byte block_address><block_data>
  • 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

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><CRC><0x99><0x03>

Responds with acknowledged containing a 4 byte payload in the following format:

<4 byte orig_command>

Get CANbus id: 0x16

Return the CANbus UUID (for verification of correct communication channel).

<0x01><0x88><0x16><0x00><CRC><0x99><0x03>

Responds with acknowledged containing a 12 byte payload in the following format:

<4 byte orig_command><6 byte UUID><0x00><0x00>

Responses

Acknowledged: 0xa0

This response indicates successful execution of a command:

<0x01><0x88><0xa0><payload word length><payload><CRC><0x99><0x03>

The payload depends on the command.

NACK: 0xf1

Indicates that the bootloader failed to receive a well formed command. The sender should retry.

<0x01><0x88><0xf1><0x00><0x68><0x95><0x99><0x03>

Command Error: 0xf2

Indicates that the bootloader encountered an error when processing a command.

<0x01><0x88><0xf2><0x00><0x00><0xbf><0x99><0x03>

Command Busy: 0xf3

Indicates that the bootloader is busy and cannot currently execute the last requested command.

<0x01><0x88><0xf3><0x00><0x00><0xbf><0x99><0x03>