BMaX was originally an abbreviation for Bootloader for AtMega and Xmega, but it actually is a generic bootloader protocol. Its device protocol ID is 0x04.
The main assumption of the BMaX protocol is that the bootloader is always executed before the actual device firmware is started. The device listens on the bus for the duration of the activation time. If it receives a broadcast to activate the bootloader during this time, it remains active. Otherwise, the execution of the device firmware is started after the time has elapsed. The activation time is implementation-specific, yet 100 ms is a recommended sane default.
- Because each device has a potentially different startup time, the host should wait suffiently longer than the activation time of the devices. 500 ms may be a sane default value.
- Since writing to the flash can take a few milliseconds, the bus master has to wait longer for the answer than normally, otherwise the bus timeout could be reached even though no real error has actually occurred. Thus the host is advised to increase its bus timeout before interacting with bootloader devices.
The first byte of a packet (address) and the last (checksum) are left out in all packet descriptions/representations on this page.
|
Request
|
Response
|
Description
|
<0x01>
|
<mcu id, uint16>
|
Returns the MCU ID.
|
<0x02><mcu id, uint16>
<0x42><0x66>
|
<uint8>
|
Unlocks the bootloader. Returns an error code (see below). This command must be executed before the flash memory can be accessed.
|
<0x03>
|
<mcu id string, [n]>
|
Returns the MCU ID string (excluding \0). This command is only available if the MCU ID is reported to be 0xFFFF.
|
<0x04>
|
<mcu id string length>
|
Returns the length of the MCU ID string (excluding \0). This command is only available if the MCU ID is reported to be 0xFFFF.
|
<0x11>
|
<page size, uint16>
|
Returns the flash page size.
|
<0x13><0|1>
|
<flashsize, uint32>
|
If the second byte in the request is 0, the whole flash size is returned. If it is 1, the size of the flash which can be written by the bootloader is returned.
|
<0xAA><address, uint32>
<data [n]>
|
<error code>
|
Write data to the flash. The specific constraints of this command depend on the implementation, but normally the address needs to be a page boundary und the data size should be equal or less than a that of a flash page. Returns an error code (see below).
|
<0xAB><address, uint32>
<length, uint16>
|
<error code><data [n]>
|
Reads data from the flash. Returns an error code (see below) and the requested amount of data. On error the data portion is undefined (but it has to be transmitted anyway, as the device has cannot send less than requested).
|
Broadcasts (The broadcast address 0x04is omitted)
|
<0xA1>
|
-
|
Requests all devices not to jump to the application when the activiation time has expired.
|
<0xAF>
|
-
|
Requests all devices to leave the bootloader and start the application.
|
|
Value
|
Description
|
0x00
|
Success: Operation was successful.
|
0xFA
|
Failure size: the requested size for reading or writing data was invalid.
|
0xFB
|
Failure address: the requested address for reading or writing was invalid.
|
0xFC
|
Failure unsupported: the requested operation was invalid or not supported.
|
0xFD
|
Failure content: the supplied data did not match the actual data.
|
0xFE
|
Failure unlock: unlocking the bootloader was rejected.
|
|
Device type ID
|
Description
|
0x01
|
Generic
|
0x02
|
AVR Atmega bootloader
|
0x03
|
AVR Xmega bootloader
|
0x04
|
STM32 bootloader
|
0x05
|
STM32v2 bootloader
|
STM32 devices normally don't have dedicated bootloader flash sections. As it is desirable to have a bootloader which cannot be bricked by a malfunctioning user application the following approach is utilized:
- The bootloader is placed at the end of the flash, including its vector table. A second copy of the vector table is placed at the normal position at the beginning of the flash, so that the bootloader can start in absence of a user app. The linker script of the bootloader has to be adjusted accordingly.
- Within the startup code of the bootloader the vector table which is situated at the end of the flash is copied to SRAM. The SRAM is mapped to address 0x00.
- User application images do not need any knowledge of the bootloader.
- When the host writes a new app image to the flash, the bootloader intercepts the first page and replaces the first two entries of the vector table with its own to make sure it gets started first.
- The host extracts the first two vector table entries of the user app image and transmits it separetely to the bootloader.
- The bootloader stores these two addresses at an implementation-defined position.
- When the host asks to start the user app, the bootloader remaps the flash to 0x00 and jumps to the saved reset address of the user app.
|
Request
|
Response
|
Description
|
<0x15>
|
<address mode>
|
Returns the app address mode used by the bootloader implementation. See below for possible values.
|
<0x16><stack pointer, uint32>
<reset address, uint32>
|
<error code>
|
Transmits the first two vector table entries of the user application to the bootloader. This command must be called before transmitting any of the user application code if the address mode 0x01. Returns an error code.
|
<0x17><stack pointer, uint32>
<reset address, uint32>
|
<error code>
|
Commits the first two vector table entries of the user application to the flash. This function schould be called after the whole user application has been transmitted. Depending on the used address mode this function either
- writes the user application reset vector to the dedicated flash page
- checks whether the supplied reset vector can be found at the expected position in the vector table.
Returns an error code.
|
<0x18>
|
<vector address, uint32>
|
Informational command which returns the location in the flash where the bootloader will store the vector table entries of the user app.
|
Address modes:
|
Mode
|
Description
|
0x00
|
Dedicated page mode: In this mode the stack address and the address of the reset handler are stored at a specific address in the flash in addition to the program on a separate flash page. This approach is always possible to implement but requires an additional erasable flash segment which may be wasteful on some F4 devices whose flash sectors are very large at the end of the flash.
|
0x01
|
Hidden in vector table: This method makes use of reserved positions within the vector table itself. This is the preferred option for any device which has suitable unused space within its vector table.
|