.HEX file format

Hex files

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:

:020000040000FA

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.

A Universal Hex JavaScript Library has been written to implement the format and associated detailed specification of the Universal Hex format.

Universal Hex Creator

We have created a Universal Hex Creator tool, to easily create a .hex file that will support all micro:bit variants.

This tool is based on the Universal Hex JavaScript Library.

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.

Download standalone error hex

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.

Micropython

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.

Reading out a hex file

If you want to read out the .hex file currently on your micro:bit, you can do so using uBitTool.