Source Embedding
The sources of a program can be embedded in HEX file, or any other format. They are flashed with the program on the device, so if the device supports read-back they can be recovered from there.
This specification is in terms of the contents of the flash of the device, not the particular file format, HEX or otherwise.
Binary Header
The header is aligned to 16 bytes, and sits somewhere in the flash. All numbers are unsigned little endian integers.
Offset | Size | Value |
---|---|---|
0 | 8 | Magic, "\x41\x14\x0E\x2F\xB8\x2F\xA2\xBB" |
8 | 2 | JSON header length |
10 | 4 | Text length |
14 | 2 | Reserved; write as zero |
Note that text length is not naturally aligned. This is due to historical reasons (it used to be 16 bit long).
What follows is the JSON header and the text (possibly compressed), both with the specified length.
JSON header
The JSON header is UTF8 encoded JSON with the following fields:
eURL
(string): the URL of the editoreVER
(string): semver of the editorname
(string): name of the script (can be displayed by flashing tools)compression
(string): specifies compression method; optional
Compression field specifies the encoding of the text section. It can have one of the following values:
""
(ornull
or missing field) - no compression"LZMA"
- LZMA raw compression
Editors should always check if the project was meant for them (ie., eURL
and
eVER
have sensible values). If not, the editor should present the user with a
dialog with an option to redirect to eURL
(where the file needs to be loaded
again), or if it seems possible, with option to try to load the file in the current
editor.
There may be other fields, which are editor-specific.
This header should be kept small, since it is not compressed.
Text
The interpretation of this section is editor-specific.
In case of PXT, the text is always LZMA compressed. If headerSize
field of JSON header
is present and non-zero, then the first headerSize
characters (not bytes) of the decompressed text
contain a JSON object that logically extends fields of the JSON header (but is compressed).
The remainder of the uncompressed text (or the entire text, if there is no header) is JSON files -
a map from file name to file content for all files in the project.
In case of a scripting language, the text can be raw, uncompressed, and used straight by the interpreter.
Caveats
Older versions of PXT and Touch Develop (as implemented in the legacy micro:bit programming
environment) didn’t use eURL
/eVER
.
If the source is too large for the flash size it is not embedded.