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.
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.
- class mcbootflash.connection.Bootloader(port: str, **kwargs: Any)
Communication interface to device running MCC 16-bit bootloader.
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
Flash application firmware.
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.
BootloaderError – If HEX-file cannot be flashed.
- erase_flash(erase_range: None | range = None, force: bool = False, verify: bool = True) None
Erase program memory area.
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
See also Protocol specification.
Definitions and representations for data sent to and from the bootloader.
- class mcbootflash.protocol.CommandCode(value)
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)
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)
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.
- data_length: int = 0
- unlock_sequence: int = 0
- address: int = 0
- FORMAT: ClassVar[str] = '=BH2I'
- classmethod from_bytes(data: bytes) _P
Create a Packet instance from a bytes-like object.
- classmethod from_serial(interface: Serial) _P
Create a Packet instance by reading from a serial interface.
- classmethod get_size() int
Get the size of Packet in bytes.
- class mcbootflash.protocol.Command(command: CommandCode, data_length: int = 0, unlock_sequence: int = 0, address: int = 0)
Base class for packets sent to the bootloader.
Layout is identical to Packet.
- class mcbootflash.protocol.ResponseBase(command: CommandCode, data_length: int = 0, unlock_sequence: int = 0, address: int = 0)
Base class for packets received from the bootloader.
Layout is identical to Packet.
- 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.
- 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)
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.
- 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)
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.
- 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)
Response to CALCULATE_CHECKSUM command.
| [Response] | uint16 | | [Response] | checksum |
checksum (uint16) – Checksum of data_length bytes starting from address.
- checksum: int = 0
- FORMAT: ClassVar[str] = '=BH2IBH'
See also Command-line interface.
Command line tool for flashing firmware.
- mcbootflash.flashing.get_parser() ArgumentParser
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.
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:
- mcbootflash.flashing.flash(parsed_args: None | Namespace = None) None
Command line script for firmware flashing.
Use this directly or indirectly as entry point for project.scripts.
parsed_args (argparse.Namespace, optional) – Pre-parsed arguments. If not specified, arguments will be parsed from the command line.
Exceptions raised by mcbootflash.
- exception mcbootflash.error.BootloaderError
Base class for mcbootflash exceptions.
Subclasses must map to a specific error response code.
- exception mcbootflash.error.UnsupportedCommand
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
Raised if Response.success is ResponseCode.BAD_ADDRESS.
This means an operation was attempted outside of the program memory range.
- exception mcbootflash.error.BadLength
Raised if Response.success is ResponseCode.BAD_LENGTH.
This means that the size of the command packet plus associated data was greater than permitted.