.HEX file format
What is the format of the .hex file created by the micro:bit editors?
The .hex file is in intel-hex format. Intel hex consists of records of data, with the address in memory to store the data at the start. All data is hex-ascii encoded. All lines start with a : character. All lines end with a checksum byte that can be used to verify the integrity of the data.
A micro:bit .hex file usually starts writing data to the same fixed location in memory, so depending on the toolchain, we might expect the first line of the file to start like this:
Universal Hex files
The latest board revision introduces a superset of the Intel-Hex format that enables compatibility across processor variants. A Universal Hex is a file that contains the binary data for both micro:bit V1 and micro:bit V2, in a format that DAPLink can process to only write to memory the data relevant to its micro:bit board.
A Universal Hex hex file will work on a V1 or V2 board. A clear indication that you are working with this format is that a compiled .hex file will be ~1.8Mb as opposed to ~700Kb in size.
Universal Hex Creator
We have created a Universal Hex Creator tool, to easily create a .hex file that will support all micro:bit variants.
Cross device compatibility
The Universal Hex format has been developed to ensure the best experience for users when moving between board variants. If a V1 only .hex is detected on a V2 board it will throw an error, but a V2 only hex will fail silently on a V1. This is very confusing to users and should be avoided.
There may be cases where it is not possible to support both boards, for example an accessory that is designed only to target the V2 board variant. In these cases, to ensure the best user experience when flashing a hex file to any board variant, the file should always include an error message to signify board incompatibility to the user.
We have created a standalone error hex that can be combined with a V2 only hex to produce a Hex that will work on a V2 board, but error if used on a V1.
This example shows the worst, best and acceptable (when support for V1 is impossible) cases for users. The best case is to provide a Universal Hex that supports all board variants.
These examples show the process of creating a Universal Hex. A V1 and V2 hex can be combined to produce a Universal Hex. If you can only support a V2 board, the standalone error can be combined with a V2 hex to produce a hex that will fail with an error on a V1 board, rather than failing silently.
|Universal Hex format||V2 only Hex format|
If you are building .hex files for both board variants, you will need to use the respective toolchains for the DALV1 and CODALV2. See more information on the micro:bit runtime.
See the Micropython Hex file reference for up to date information.
MicroPython builds take a firmware.hex image (the MicroPython pre-compiled image) and appends your script to the end of it, in a fixed 8K region at a known address. When MicroPythons starts to run on the micro:bit, it looks for a signature at this fixed location, and uses that to determine whether to run the script, or drop directly to the REPL prompt.
Microsoft MakeCode Editor
Hex files generated by the MakeCode Editor have embedded meta-data inside the .hex file. This is a JSON encoded blob with various data about the script, and also the source code program. This may be compressed, and it is stored inside the flash memory of the micro:bit (but only if space is available in the flash memory). But it is always inside the .hex file. This embedded source code program ensures that when you drag and drop the .hex file onto the originating editor, it can recover the source program again.