microsoft/pxt-microbit

microsoft/pxt-microbit

Description: A Blocks / JavaScript code editor for the micro:bit built on Microsoft MakeCode

Language: TypeScript

License: NOASSERTION

Stars: 805

Forks: 714

Open issues: 417

Created: 2016-03-10T19:27:31Z

Pushed: 2026-06-24T04:28:02Z

Default branch: master

Fork: no

Archived: no

README:

micro:bit target for PXT

 !pxt-testghpkgs

pxt-microbit is a Microsoft Programming Experience Toolkit (PXT) target that allows you to program a BBC micro:bit.

• pxt-microbit beta, `v3.0.*` requires
• pxt-microbit#stable3.0
• pxt#stable6.0.
• pxt-common-packages#stable6.0.
• pxt-microbit `v2.0.*, branch stable2.0`, requires pxt v5.15.\*. It is the servicing branch for live editor.
• pxt-microbit `v1.*` requires pxt v4.4, which is currently in the stable4.4 branch of pxt.
• pxt-microbit `v0.*` is in the v0 branch of this repository

• Try it live

Issue tracking

Please add an issue if you discover an (unreported) bug.

Developing new extensions

Authoring and testing of new extensions can be done directly from the web editor. See our documentation on how to get started. If you want to run the editor locally, keep reading.

Local server setup

The local server lets you to run the editor and serve the documentation from your own computer. It is meant for a single developer used and not designed to serve the editor to a large amount of users.

1. Install Node.js 8.9.4 or higher. 2. Clone this repository.

git clone https://github.com/microsoft/pxt-microbit
cd pxt-microbit

3. Install the PXT command line (add sudo for Mac/Linux shells).

npm install -g pxt

4. Install the pxt-microbit dependencies.

npm install

Go to the Running section.

Developer Setup

This is the typical setup used by the MakeCode team to work on the microbit.

1. Install Node.js 8.9.4 or higher. 2. Install Docker if you plan to build `.cpp` files. 3. Clone the pxt repository.

git clone https://github.com/microsoft/pxt
cd pxt

4. Install the dependencies of pxt and build it

npm install
npm run build
cd ..

5. Clone the pxt-common-packages repository

git clone https://github.com/microsoft/pxt-common-packages
cd pxt-common-packages
npm install

6. Link pxt-common-packages to pxt

npm link ../pxt
cd ..

7. Clone this repository.

git clone https://github.com/microsoft/pxt-microbit
cd pxt-microbit

8. Install the PXT command line (add sudo for Mac/Linux shells).

npm install -g pxt

9. Install the pxt-microbit dependencies.

npm install

10. Link pxt-microbit back to base pxt repo (add sudo for Mac/Linux shells). This step is only required if you intend to make changes to pxt and/or pxt-common-packages repos. If all you want is serve a local Makecode, you can skip this step.

npm link ../pxt ../pxt-common-packages

Note the above command assumes the folder structure of

makecode
|
----------------------------------
| | |
pxt pxt-common-packages pxt-microbit

Running

Run this command from inside pxt-microbit to open a local web server

pxt serve

If the local server opens in the wrong browser, make sure to copy the URL containing the local token. Otherwise, the editor will not be able to load the projects.

If you need to modify the .cpp files (and have installed yotta), enable yotta compilation using the --localbuild flag:

pxt serve --local

If you want to speed up the build, you can use the `rebundle` option, which skips building and simply refreshes the target information

pxt serve --rebundle

Cleaning

Sometimes, your built folder might be in a bad state, clean it and try again.

pxt clean

Building with CODAL locally

The following commands force a local build using CODAL.

pxt buildtarget --local

To disable docker, run

export PXT_NODOCKER=1

If you are also modifiying CODAL, consider running `pxt clean` to ensure the proper branch is picked up.

Modifying DAL/CODAL locally

• follow instructions above until pxt serve
• open editor on localhost and create a project
• do export PXT_FORCE_LOCAL=1 PXT_RUNTIME_DEV=1 PXT_ASMDEBUG=1; you can add PXT_NODOCKER=1; pxt help has help on these
• find project folder under pxt-microbit/projects, typically pxt-microbit/projects/Untitled-42
• if you're going to modify .cpp files in PXT, replace "core": "*" in pxt.json with "core": "file:../../libs/core";

similarly "radio": "file:../../libs/radio" and "microphone": "file:../../libs/microphone"

• you can edit main.ts to change the PXT side of the program; you can also edit it from the localhost editor;

note that Download in the localhost editor will produce different binary than command line, as it builds in the cloud and uses tagged version of CODAL

• in that folder run pxt build - this will clone codal somewhere under built/ (depends on build engine and docker)
• there can be an issue with exporting the variables i.e. PXT_FORCE, so including them in the build command can help solve issues sudo PXT_NODOCKER=1 PXT_ASMDEBUG=1 PXT_RUNTIME_DEV=1 PXT_DEBUG=1 PXT_FORCE_LOCAL=1 PXT_COMPILE_SWITCHES=csv---mbcodal pxt build
• if the target is not building, delete files in hexcache found in pxt-microbit/built/hexcache to force local build
• the built hex can be found in pxt-microbit/projects//built named binary.hex
• similarly, you can run pxt deploy (or just pxt which is the same) - it will build and copy to MICROBIT drive
• assuming the build folder is under built/codal, go to built/codal/libraries and run code *
• in git tab, checkout appropriate branches (they are all in detached head state to the way we tag releases)

*...