Library API

When mcbootflash is used as a library, the main object of intereset is the BootloaderConnection. It provides methods for flashing new firmware, erasing existing firmware, reading metadata from the connected device, and resetting the device.

The flashing module also offers a command-line interface which other applications can hook into to set their own defaults, add or remove parameters, set help messages, etc. See Command-line interface.

connection

class mcbootflash.connection.Bootloader(port: str, **kwargs: Any)[source]

Bases: object

Communication interface to device running MCC 16-bit bootloader.

Parameters:

  • port (str) – Serial port name. Typically /dev/ttyUSBx or /dev/ttyACMx on Posix, or COMx on Windows.

  • **kwargs – Any additional arguments for the serial.Serial constructor.

  • optional – Any additional arguments for the serial.Serial constructor.

flash(hexfile: str, progress_callback: None | Callable[[int, int], None] = None) → None[source]

Flash application firmware.

Parameters:

  • hexfile (str) – Path to a HEX-file containing application firmware.

  • progress_callback (Callable[[int, int], None] (optional)) – A callable which takes the number of bytes written so far as its first argument, and the total number of bytes to write as its second argument. The callable returns None. If no callback is provided, progress is not reported.

Raises:

BootloaderError – If HEX-file cannot be flashed.

erase_flash(erase_range: None | range = None, force: bool = False, verify: bool = True) → None[source]

Erase program memory area.

Parameters:

  • erase_range (range, optional) – Address range to erase. By default the entire program memory is erased.

  • force (bool, optional) – By default, flash erase will be skipped if no program is detected in the program memory area. Setting force to True skips program detection and erases regardless of whether a program is present or not.

  • verify (bool, optional) – The ERASE_FLASH command may fail silently if the unlock_sequence field of the command packet is incorrect. By default, this method verifies that the erase was successful by checking that no application is detected after the erase. Set verify to False to skip this check.

reset() → None[source]

Reset device.

protocol

See also Protocol specification.

Definitions and representations for data sent to and from the bootloader.

class mcbootflash.protocol.CommandCode(value)[source]

Bases: IntEnum

The MCC 16-bit bootloader supports these commands.

READ_VERSION = 0
READ_FLASH = 1
WRITE_FLASH = 2
ERASE_FLASH = 3
CALC_CHECKSUM = 8
RESET_DEVICE = 9
SELF_VERIFY = 10
GET_MEMORY_ADDRESS_RANGE = 11
class mcbootflash.protocol.ResponseCode(value)[source]

Bases: IntEnum

Sent by the bootloader in response to a command.

SUCCESS = 1
UNSUPPORTED_COMMAND = 255
BAD_ADDRESS = 254
BAD_LENGTH = 253
VERIFY_FAIL = 252
class mcbootflash.protocol.Packet(command: CommandCode, data_length: int = 0, unlock_sequence: int = 0, address: int = 0)[source]

Bases: object

Base class for communication packets to and from the bootloader.

Layout:

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

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

Note

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.

command: CommandCode
data_length: int = 0
unlock_sequence: int = 0
address: int = 0
FORMAT: ClassVar[str] = '=BH2I'
classmethod from_bytes(data: bytes) → _P[source]

Create a Packet instance from a bytes-like object.

classmethod from_serial(interface: Serial) → _P[source]

Create a Packet instance by reading from a serial interface.

classmethod get_size() → int[source]

Get the size of Packet in bytes.

class mcbootflash.protocol.Command(command: CommandCode, data_length: int = 0, unlock_sequence: int = 0, address: int = 0)[source]

Bases: Packet

Base class for packets sent to the bootloader.

Layout is identical to Packet.

command: CommandCode
class mcbootflash.protocol.ResponseBase(command: CommandCode, data_length: int = 0, unlock_sequence: int = 0, address: int = 0)[source]

Bases: Packet

Base class for packets received from the bootloader.

Layout is identical to Packet.

command: CommandCode
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)[source]

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:

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

version: int = 0
max_packet_length: int = 0
device_id: int = 0
erase_size: int = 0
write_size: int = 0
FORMAT: ClassVar[str] = '=BH2I2H2xH2x2H12x'
class mcbootflash.protocol.Response(command: CommandCode, data_length: int = 0, unlock_sequence: int = 0, address: int = 0, success: ResponseCode = ResponseCode.UNSUPPORTED_COMMAND)[source]

Bases: ResponseBase

Response to any command except READ_VERSION.

Layout:

| [Packet] | uint8   |
| [Packet] | success |
Parameters:

success (ResponseCode) – Success or failure status of the command this packet is sent in response to.

success: ResponseCode = 255
FORMAT: ClassVar[str] = '=BH2IB'
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)[source]

Bases: Response

Response to GET_MEMORY_RANGE command.

Layout:

| [Response] | uint32        | uint32      |
| [Response] | program_start | program_end |
Parameters:

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

program_start: int = 0
program_end: int = 0
FORMAT: ClassVar[str] = '=BH2IB2I'
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)[source]

Bases: Response

Response to CALCULATE_CHECKSUM command.

Layout:

| [Response] | uint16   |
| [Response] | checksum |
Parameters:

checksum (uint16) – Checksum of data_length bytes starting from address.

checksum: int = 0
FORMAT: ClassVar[str] = '=BH2IBH'

flashing

See also Command-line interface.

Command line tool for flashing firmware.

mcbootflash.flashing.get_parser() → ArgumentParser[source]

Return a populated ArgumentParser instance.

This function is meant to be used by applications which want to create their own CLI while using mcbootflash in the background.

Returns:

The returned ArgumentParser has the following arguments already added:

file           (str,   required)
-p, --port     (str,   required)
-b, --baudrate (int,   required)
-t, --timeout  (float, default=5)
-v, --verbose  (bool,  default=False)
-q, --quiet    (bool,  default=False)

These arguments can be overridden by adding a new argument with the same option string. For example, an application which only needs to communicate with a specific device with a known serial baudrate could override the ‘baudrate’ option to make it optional:

import mcbootflash
parser = mcbootflash.get_parser()
parser.add_argument("-b", "--baudrate", default=460800)
mcbootflash.flash(parser.parse_args())

Return type:

argparse.ArgumentParser

mcbootflash.flashing.flash(parsed_args: None | Namespace = None) → None[source]

Command line script for firmware flashing.

Use this directly or indirectly as entry point for project.scripts.

Parameters:

parsed_args (argparse.Namespace, optional) – Pre-parsed arguments. If not specified, arguments will be parsed from the command line.

error

Exceptions raised by mcbootflash.

exception mcbootflash.error.BootloaderError[source]

Bases: Exception

Base class for mcbootflash exceptions.

Subclasses must map to a specific error response code.

exception mcbootflash.error.UnsupportedCommand[source]

Bases: BootloaderError

Raised if Response.success is ResponseCode.UNSUPPORTED_COMMAND.

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

exception mcbootflash.error.BadAddress[source]

Bases: BootloaderError

Raised if Response.success is ResponseCode.BAD_ADDRESS.

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

exception mcbootflash.error.BadLength[source]

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.

exception mcbootflash.error.VerifyFail[source]

Bases: BootloaderError

Raised if Response.success is ResponseCode.VERIFY_FAIL.

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