Skip to content

Latest commit

 

History

History
229 lines (159 loc) · 7.93 KB

develop.md

File metadata and controls

229 lines (159 loc) · 7.93 KB
Raw
title image
Developer Docs
./docs/images/generated/sample_smiley_buttons.png

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

  • open https://github.com/microsoft/microcode
  • click on Code drop down and select Create Codespace on main
  • you can do your editing from VS Code online or click on Codespaces in lower left and select Open in VS Code to use the desktop version (must be installed on your machine)
  • press "Ctrl + `" to open a terminal and you're ready to go!

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

Local Install (skip in Codespaces)

  • install Node.js
  • install the MakeCode command line tools (mkc for short)
npm install -g -u makecode
  • clone this repo
git clone https://github.com/microsoft/microcode
  • setup MakeCode project structure (one time only)
cd microcode
mkc init

Build

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

  • start a compilation server that will automatically compile and reload a compile web version of the editor
sh serve.sh

To flash a micro:bit,

  • build a micro:bit Hex file and deploy
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:

  • create 16 x 16 sprite in assets.ts (contains all the artwork for MicroCode)
  • copy the code from the JavaScript view of https://arcade.makecode.com
  • paste code into assets.ts into VS Code
  • make sure it works locally
  • git commit and push

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

  • locales/tooltips.json contains the tooltips displayed on the micro:bit screen
  • _includes/dialogs.html contains the webusb dialogs

Adding tooltips in source code

  • add new tooltip to locales/tooltips.json
  • refresh tooltips.ts
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
  • you may use npm instead of yarn
  • you may skip PXT_NODOCKER if you don't have locally installed arm-none-eabi-gcc
  • in projects/microcode create pxt.json file with the following contents:
{
    "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"
    }
}
  • run pxt - it will compile an deploy
  • run code built/codal/libraries/codal-*
  • checkout main or master in all codal-* repos and in jacdac-c

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.