GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing makecode.com — Source Embedding

About MakeCode Blog Online Learning Contact Us Tools

Technical Docs

JS Editor Features Programming Language Async Functions Partial Flashing Source Embedding Updating Blockly Version Accessibility Profiling Debugging Hardware

Creating Targets

pxtarget.json Defining Blocks Auto-generation of .d.ts Static File Drops Simulator Theming Editor Embedding resources

Creating Extensions

Getting started pxt.json Extension versioning Extension localization Extension approval Editor extensions GitHub Extension Authoring

Writing Docs

Macros Anchors Tutorials User Tutorials Skillmaps Routing Licensing Testing

Translations

Translation languages Localization files Parts to translate Translating markdown Translator roles In context translation

Blocks Embedding

Command Line Interface

install build bump deploy console gdb staticpkg update pyconv hidserial hiddmesg login

Labs UF2 File Format Accessibility Telemetry

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 editor
eVER (string): semver of the editor
name (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:

"" (or null 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.

Edit this page on GitHub
Edit template of this page on GitHub

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.