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 |
data_length (uint16) –
Meaning depends on value of ‘command’-field:
For other commands this field is ignored.
address (uint32) – Address at which to perform command.
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.
device_id (uint16) – A device-specific identifier.
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.
| [ResponsePacket] | uint32 | uint32 | | [ResponsePacket] | 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.
| [ResponsePacket] | uint16 | | [ResponsePacket] | 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.