MicroCode is open source at https://github.com/microbit-apps/microcode-classic and welcomes contributions. The easiest way to get started is to open this repository in a GitHub Codespace and everything will be ready for you.

We recommend using Visual Studio Code as it provides excellent support for MakeCode editing, Git, and Codespaces.

Codespaces setup

In the future, click again on Code to find previously created Codespaces.

Local Install (skip in Codespaces)

npm install -g -u makecode

git clone https://github.com/microbit-apps/microcode-classic

cd microcode
mkc init

Build

Note that you can open terminals directly from VS Code by pressing “Ctrl + `”.

sh serve.sh

To flash a micro:bit,

mkc build --hw n3 -d

If you are running in Codespaces, the -d option won’t work. Instead, right click on built/binary.hex in the explorer and select Download... to download the hex file to your micro:bit.

With Jacdac devtools

To load the local editor in a Jacdac devtools page, click on the sim link at the bottom of the local server on http://127.0.0.1:7001/. Or,

https://microsoft.github.io/jacdac-docs/clients/javascript/devtools?jacscript=1&simulators=microbitmicrocode#http://127.0.0.1:7001/index.html?usb=0

Creating artwork

To preview all artwork, click on the art icon at the bottom right of the local editor (and wait…). Use save to download all artwork on the images/generated folder.

If you want to create/edit new sprites, you should import this web site into https://arcade.makecode.com, using the following directions:

You might also be able to commit and push directly from the web site, but we find that this isn’t very reliable.

Some art images are precomputed, you will need to load scripts/renderart.ts in MakeCode Arcade and copy the console output back into the project.

Updating sample

Updating GitHub pages

To bump and refresh the github pages javascript and pre-built .hex file, run this script

sh ./bump.sh

A GitHub Action will trigger and update the web site within a few minutes.

Running Jekyll locally

It is easiest to launch a codespace to get the right setup to run Jekyll (Ruby). Run the Jekyll setup script

sh scripts/setup-jekyll.sh

then launch jekyll

bundle exec jekyll serve --incremental

and nav to http://localhost:4000

Re-building library

There is library of LED animations etc in scripts/lib/lib.js. To rebuild, make sure you have jacscript checked out parallel to microcode and run:

cd scripts
./genlib.sh

Localization

Adding tooltips in source code

node scripts/lochex.mjs en

Updating crowdin

Refreshing translations

Dependencies

This app is built with MakeCode Arcade, specifically targeting the NRF52833 MCU of the micro:bit V2 (for now). There are a number of repos containing the C++ of the underlying CODAL runtime:

Build setup for C++ runtime dev

npm install -g pxt-core
cd pxt-arcade
yarn install
mkdir projects
cd projects
mkdir microcode
cd microcode
export PXT_ASMDEBUG=1
export PXT_COMPILE_SWITCHES=size
export PXT_FORCE_LOCAL=yes
export PXT_NODOCKER=yes
export PXT_RUNTIME_DEV=yes

{
    "additionalFilePath": "../../../microcode",
    "dependencies": {
        "game---light": "file:../../libs/game---light",
        "hw---n3": "file:../../libs/hw---n3",
        "device": "file:../../libs/device",
        "codal-jacdac-pxt": "file:../../../microcode/codal-jacdac-pxt"
    }
}

Make sure not to delete projects/microcode/built since it contains your sources. If possible, you can move built/codal/libraries folder somewhere else, and symlink it inside built/codal to avoid accidentally deleting it.