MicroCode is open source at https://github.com/microsoft/microcode 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/microsoft/microcode

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.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies.