Skip to content

API Reference

Flash Operations

These functions are used to communicate with the bootloader.

get_boot_attrs(connection)

Read bootloader attributes.

Parameters:

Name Type Description Default
connection Connection

Connection to device in bootloader mode.

 required

Returns:

Type Description
BootAttrs

erase_flash(connection, erase_range, erase_size)

Erase program memory area.

Note

Erasing a large memory area can take several seconds. Set the connection timeout accordingly.

Parameters:

Name Type Description Default
connection Connection

Connection to device in bootloader mode.

 required
erase_range tuple[int, int]

Tuple of addresses forming a range to erase. The range is half-open, [start, end), i.e. the second address in the tuple is not erased.

 required
erase_size int

Size of a flash page, i.e. the smallest number of bytes which can be atomically erased.

 required

Raises:

Type Description
ValueError

If erase_range[1] - erase_range[0] is not a multiple of erase_size.

write_flash(connection, chunk)

Write data to bootloader.

Parameters:

Name Type Description Default
connection Connection

Connection to device in bootloader mode.

 required
chunk Chunk

Firmware chunk to write to bootloader.

 required

self_verify(connection)

Run bootloader self-verification.

Parameters:

Name Type Description Default
connection Connection

Connection to device in bootloader mode.

 required

Raises:

Type Description
VerifyFail

If the bootloader cannot detect a bootable application in program memory.

checksum(connection, chunk)

Compare checksums calculated locally and onboard device.

Parameters:

Name Type Description Default
connection Connection

Connection to device in bootloader mode.

 required
chunk Chunk

Firmware chunk to checksum.

 required

Raises:

Type Description
BootloaderError

If checksums do not match.

reset(connection)

Reset device.

Parameters:

Name Type Description Default
connection Connection

Connection to device in bootloader mode.

 required

read_flash(connection, address, size)

Read bytes from flash.

Parameters:

Name Type Description Default
connection Connection

Connection to device in bootloader mode.

 required
address int

Start address to read from.

 required
size int

Number of bytes to read.

 required

Returns:

Type Description
bytes

Utility Functions

Utility functions.

chunked(hexfile, boot_attrs)

Split a HEX file into chunks.

Parameters:

Name Type Description Default
hexfile str

Path of a HEX file containing application firmware.

 required
boot_attrs BootAttrs

The bootloader's attributes, as read by get_boot_attrs.

 required

Returns:

Name Type Description
total_bytes int

The total number of bytes in all chunks.
chunks Iterator[Chunk]

Appropriatelly sized chunks of data, suitable for writing in a loop with write_flash.

Raises:

Type Description
Error

If HEX file contains no data in program memory range.

readback(connection, outfile)

Readback programmed application from flash memory.

Parameters:

Name Type Description Default
connection Connection

Connection to device in bootloader mode.

 required
outfile StringIO

File-like object to write HEX data to.

 required

Custom Types

Custom types used by mcbootflash.

CommandCode

Bases: IntEnum

The MCC 16-bit bootloader supports these commands.

ResponseCode

Bases: IntEnum

Sent by the bootloader in response to a command.

Packet dataclass

Bases: DataStructClass

Base class for communication packets to and from the bootloader.

Layout:

| uint8   | uint16      | uint32          | uint32   |
| command | data_length | unlock_sequence | address  |

Parameters:

Name Type Description Default
command CommandCode

Command code which specifies which command should be executed by the bootloader.

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

 0
unlock_sequence uint32

Key to unlock flash memory for writing. Write operations (WRITE_FLASH, ERASE_FLASH) will fail SILENTLY if this key is incorrect.

 0
address uint32

Address at which to perform command.

 0
Note

No error is raised if unlock_sequence 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.

Command dataclass

Bases: Packet

Base class for packets sent to the bootloader.

Layout is identical to Packet.

ResponseBase dataclass

Bases: Packet

Base class for packets received from the bootloader.

Layout is identical to Packet.

Version dataclass

Bases: ResponseBase

Response to a READ_VERSION command.

Layout::

| [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) |

Parameters:

Name Type Description Default
version uint16

Bootloader version number.

 0
max_packet_length uint16

Maximum number of bytes which can be sent to the bootloader per packet. Includes the size of the packet itself plus associated data.

 0
device_id uint16

A device-specific identifier.

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

 0
write_size uint16

Size of a write block in bytes. When writing to flash, the data must align with a write block.

 0

Response dataclass

Bases: ResponseBase

Response to any command except READ_VERSION.

Layout::

| [Packet] | uint8   |
| [Packet] | success |

Parameters:

Name Type Description Default
success ResponseCode

Success or failure status of the command this packet is sent in response to.

 UNSUPPORTED_COMMAND

MemoryRange dataclass

Bases: Response

Response to GET_MEMORY_RANGE command.

Layout::

| [Response] | uint32        | uint32      |
| [Response] | program_start | program_end |

Parameters:

Name Type Description Default
program_start uint32

Low end of address space to which application firmware can be flashed.

 0
program_end uint32

High end of address space to which application firmware can be flashed.

 0

Checksum dataclass

Bases: Response

Response to CALCULATE_CHECKSUM command.

Layout::

| [Response] | uint16   |
| [Response] | checksum |

Parameters:

Name Type Description Default
checksum uint16

Checksum of data_length bytes starting from address.

 0

BootAttrs dataclass

Bootloader attributes.

Parameters:

Name Type Description Default
version int

Bootloader version number.

 required
max_packet_length int

Maximum number of bytes which can be sent to the bootloader per packet. Includes the size of the packet itself plus associated data.

 required
device_id int

A device-specific identifier.

 required
erase_size int

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.

 required
write_size int

Size of a write block in bytes. When writing to flash, the data must align with a write block.

 required
memory_range tuple[int, int]

Tuple of addresses specifying the program memory range. The range is half-open, i.e. the upper address is not part of the program memory range.

 required

Chunk

Bases: Protocol

A piece of a firmware image.

mcbootflash.chunked can be used to generate correctly aligned and sized chunks from a HEX file.

Attributes:

Name Type Description
address int

The address associated with the start of the data. Must be aligned with (i.e. be a multiple of) the bootloader's write_size attribute.
data bytes

Data to be written to the bootloader. The data length must be a multiple of the bootloader's write_size attribute, and must be no longer than the bootloader's max_packet_length attribute minus the size of the command packet header (which can be gotten with Command.get_size).

Connection

Bases: Protocol

Anything that can read and write bytes from/to the bootloader.

Typically, this is an open serial.Serial instance.

read(size=1)

Read bytes from the bootloader.

Parameters:

Name Type Description Default
size int

Number of bytes to read.

 1

Returns:

Name Type Description
data bytes

Bytes read from the bootloader.

write(data)

Write bytes to the bootloader.

Parameters:

Name Type Description Default
data bytes

Bytes to write to the bootloader.

 required

Returns:

Name Type Description
size int

Number of bytes written to the bootloader.

Custom Exceptions

Exceptions raised by mcbootflash.

BootloaderError

Bases: Exception

Base class for mcbootflash exceptions.

Subclasses must map to a specific error response code.

UnsupportedCommand

Bases: BootloaderError

Raised if Response.success is ResponseCode.UNSUPPORTED_COMMAND.

This means that the bootloader did not recognize the most recently sent command.

BadAddress

Bases: BootloaderError

Raised if Response.success is ResponseCode.BAD_ADDRESS.

This means an operation was attempted outside of the program memory range.

BadLength

Bases: BootloaderError

Raised if Response.success is ResponseCode.BAD_LENGTH.

This means that the size of the command packet plus associated data was greater than permitted.

VerifyFail

Bases: BootloaderError

Raised if Response.success is ResponseCode.VERIFY_FAIL.

This means that no bootable program was detected in the program memory range.