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
v2.0.*
, branchstable2.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
Please add an issue if you discover an (unreported) bug.
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.
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.
- Install Node.js 8.9.4 or higher.
- Clone this repository.
git clone https://github.com/microsoft/pxt-microbit
cd pxt-microbit
- Install the PXT command line (add
sudo
for Mac/Linux shells).
npm install -g pxt
- Install the pxt-microbit dependencies.
npm install
Go to the Running section.
This is the typical setup used by the MakeCode team to work on the microbit.
- Install Node.js 8.9.4 or higher.
- Install Docker if you plan to build
.cpp
files. - Clone the pxt repository.
git clone https://github.com/microsoft/pxt
cd pxt
- Install the dependencies of pxt and build it
npm install
npm run build
cd ..
- Clone the pxt-common-packages repository
git clone https://github.com/microsoft/pxt-common-packages
cd pxt-common-packages
npm install
cd ..
- Clone this repository.
git clone https://github.com/microsoft/pxt-microbit
cd pxt-microbit
- Install the PXT command line (add
sudo
for Mac/Linux shells).
npm install -g pxt
- Install the pxt-microbit dependencies.
npm install
- 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.
pxt link ../pxt
pxt link ../pxt-common-packages
Note the above command assumes the folder structure of
makecode
|
----------------------------------
| | |
pxt pxt-common-packages pxt-microbit
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
Sometimes, your built folder might be in a bad state, clean it and try again.
pxt clean
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.
- 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 addPXT_NODOCKER=1
;pxt help
has help on these - find project folder under
pxt-microbit/projects
, typicallypxt-microbit/projects/Untitled-42
- if you're going to modify
.cpp
files in PXT, replace"core": "*"
inpxt.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 thatDownload
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 underbuilt/
(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 inpxt-microbit/built/hexcache
to force local build - the built hex can be found in
pxt-microbit/projects/<your project name>/built
namedbinary.hex
- similarly, you can run
pxt deploy
(or justpxt
which is the same) - it will build and copy toMICROBIT
drive - assuming the build folder is under
built/codal
, go tobuilt/codal/libraries
and runcode *
- in git tab, checkout appropriate branches (they are all in detached head state to the way we tag releases)
- modify files, run
pxt
, see effects - you can also run
pxt gdb
to debug; this requiresopenocd
- other commands using
openocd
arepxt dmesg
which dumpsDMESG(...)
buffer andpxt heap
which can be used to visualize PXT heap (and CODAL's one to some extent)
cd libs/blocksprj
rm -rf built
PXT_FORCE_LOCAL=1 PXT_COMPILE_SWITCHES=csv---mbcodal pxt build
PXT_FORCE_LOCAL=1 PXT_COMPILE_SWITCHES=csv---mbcodal pxt builddaldts
mv dal.d.ts ../core
Make sure to pull changes from all repos regularly. More instructions are at https://github.com/Microsoft/pxt#running-a-target-from-localhost
Get a Google API key and store it in the GOOGLE_API_KEY
environment variables (turn on data from the app).
pxt downloadplaylists
The pxt-microbit target depends on several other repos. The main ones are:
- https://github.com/Microsoft/pxt, the PXT framework
- https://github.com/Microsoft/pxt-common-packages, common APIs accross various MakeCode editors
- https://github.com/lancaster-university/microbit, basic wrapper around the DAL
- https://github.com/lancaster-university/microbit-dal
See the MakeCode blog.
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.
MICROSOFT, the Microsoft Logo, and MAKECODE are registered trademarks of Microsoft Corporation. They can only be used for the purposes described in and in accordance with Microsoft’s Trademark and Brand guidelines published at https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general.aspx. If the use is not covered in Microsoft’s published guidelines or you are not sure, please consult your legal counsel or MakeCode team (makecode@microsoft.com).