Communication between mcbootflash and a connected bootloader is split up into
packets. The layout of a basic
packet is as follows:
- class mcbootflash.protocol.Packet(command: CommandCode, data_length: int = 0, unlock_sequence: int = 0, address: int = 0)
Base class for communication packets to and from the bootloader.
| uint8 | uint16 | uint32 | uint32 | | command | data_length | unlock_sequence | address |
command (CommandCode) – Command code which specifies which command should be executed by the bootloader.
data_length (uint16) –
Meaning depends on value of ‘command’-field:
WRITE_FLASH: Number of bytes following the command packet. ERASE_FLASH: Number of flash pages to be erased. CALC_CHECKSUM: Number of bytes to checksum.
For other commands this field is ignored.
unlock_sequence (uint32) – Key to unlock flash memory for writing. Write operations (WRITE_FLASH, ERASE_FLASH) will fail SILENTLY if this key is incorrect.
address (uint32) – Address at which to perform command.
FORMAT (ClassVar[str]) – Format string for struct which specifies types and layout of the data fields.
No error is raised if the key is incorrect. A failed WRITE_FLASH operation can be detected by comparing checksums of the written bytes and the flash area they were written to. A failed ERASE_FLASH operation can be detected by issuing a SELF_VERIFY command. If the erase succeeded, SELF_VERIFY should return VERIFY_FAIL.
Every packet sent to or from the bootloader has at least these four fields.
The bootloader never sends anything without first receiving a packet from the host application. After receiving a command packet, the bootloader must respond with exactly one packet in return. The response packet’s command field must be the same as that of the received command packet.
Packets sent from the host application to the bootloader are called command packets. They have the same data layout as the basic packet specified above, plus an optional data field following the address field. The following commands are supported:
Replies from the bootloader come in two variations; responses to READ_VERSION and responses to other commands. Responses to READ_VERSION have the following format:
- class mcbootflash.protocol.Version(command: CommandCode, data_length: int = 0, unlock_sequence: int = 0, address: int = 0, version: int = 0, max_packet_length: int = 0, device_id: int = 0, erase_size: int = 0, write_size: int = 0)
Response to a READ_VERSION command.
| [Packet] | uint16 | uint16 | uint16 | uint16 | ... | [Packet] | version | max_packet_length | (ignored) | device_id | ... ... | uint16 | uint16 | uint16 | uint32 | uint32 | uint32 | ... | (ignored) | erase_size | write_size | (ignored) | (ignored) | (ignored) |
version (uint16) – Bootloader version number.
max_packet_length (int16) – Maximum number of bytes which can be sent to the bootloader per packet. Includes the size of the packet itself plus associated data.
device_id (uint16) – A device-specific identifier.
erase_size (uint16) – Size of a flash erase page in bytes. When erasing flash, the size of the memory area which should be erased is given in number of erase pages.
write_size (uint16) – Size of a write block in bytes. When writing to flash, the data must align with a write block.
Responses to all other commands have the following basic layout:
- class mcbootflash.protocol.Response(command: CommandCode, data_length: int = 0, unlock_sequence: int = 0, address: int = 0, success: ResponseCode = ResponseCode.UNSUPPORTED_COMMAND)
Response to any command except READ_VERSION.
| [Packet] | uint8 | | [Packet] | success |
success (ResponseCode) – Success or failure status of the command this packet is sent in response to.
The success field has one of the following values:
- class mcbootflash.protocol.ResponseCode(value)
Sent by the bootloader in response to a command.
- SUCCESS = 1
- UNSUPPORTED_COMMAND = 255
- BAD_ADDRESS = 254
- BAD_LENGTH = 253
- VERIFY_FAIL = 252
Some commands (GET_MEMORY_ADDRESS_RANGE and CALCULATE_CHECKSUM) send additional data following the success field:
- class mcbootflash.protocol.MemoryRange(command: CommandCode, data_length: int = 0, unlock_sequence: int = 0, address: int = 0, success: ResponseCode = ResponseCode.UNSUPPORTED_COMMAND, program_start: int = 0, program_end: int = 0)
Response to GET_MEMORY_RANGE command.
| [Response] | uint32 | uint32 | | [Response] | program_start | program_end |
program_start (uint32) – Low end of address space to which application firmware can be flashed.
program_end (uint32) – High end of address space to which application firmware can be flashed.
- class mcbootflash.protocol.Checksum(command: CommandCode, data_length: int = 0, unlock_sequence: int = 0, address: int = 0, success: ResponseCode = ResponseCode.UNSUPPORTED_COMMAND, checksum: int = 0)
Response to CALCULATE_CHECKSUM command.
| [Response] | uint16 | | [Response] | checksum |
checksum (uint16) – Checksum of data_length bytes starting from address.
Blue arrows/bubbles indicate normal program flow, red arrows/bubbles indicate errors.
* If SELF_VERIFY returns SUCCESS immediately after an ERASE_FLASH command, the erase failed. Normal execution flow therefore requires a response of VERIFY_FAIL.