BBC micro:bit Development Environment for C/C++, MakeCode, and MicroPython
This repository contains a Vagrant box configured to facilitate the development of MicroPython, MakeCode, and C/C++ programs for the BBC micro:bit.
Vagrant is a tool to easily build and manage virtual machine environments.
This virtual machine is very easy to use and contains everything you need to:
- Build micro:bit MicroPython from source
- Easily load Python scripts using your own built MicroPython
- Easily access the MicroPython REPL
- Run a local version of MakeCode/PXT
- Develop your own MakeCode packages
- Build C/C++ applications for the micro:bit
With a single command this project takes care of creating a virtual machine, installing all the development tools and dependencies required, download all the source code into a shared folder, compile everything, and get it ready for use.
It offers a replicable development environment that is independent of your operating system, working the same way under Windows, macOS, or Linux.
Table of contents:
- Access the virtual machine
You will need the following applications first:
Vagrant Project Bring-up
Clone, or download this repository:
git clone https://github.com/carlosperate/microbit-dev-env.git cd microbit-dev-env
Getting the virtual machine up and running with Vagrant is extremely easy, on the Command Line Interface just run:
This will download an Ubuntu 16.04 64 bit virtual box image, so it might take a while depending on your internet connection. It will also install the tool-chain, download and build all the source code for all the projects, ensuring everything is ready to develop your application in any of these platforms.
Access the Virtual Machine
First, start-up the virtual machine:
You can now SSH into the virtual machine with Vagrant itself:
Or with your preferred SSH client:
Host: 127.0.0.1 Port: 2222 Username: vagrant Password: vagrant
This will give you command line access to the virtual machine, allowing you to compile the source code contained in the
vagrant_shared folder. By default you will find the
pxt-workspace and a couple of extra folders there, which can be accessed from the virtual machine to build the projects. So within the SSH connection you can:
cd vagrant_shared/micropython make all
To stop the virtual machine from running, you can use the following command on the host:
More information can be found in the Vagrant documentation.
The general workflow concept is to have one folder that is accessible by both the host operating system (your computer), and the virtual machine.
This allows you to create and edit your code like you would normally do, using any IDE or editor you prefer, and then use the virtual machine to build it or compile it.
In essence the steps are:
- Edit the code inside the
vagrant_sharedfolder in your OS as you would normally do
- SSH into the virtual machine
- Compile/build the project from the SSH session (accessible via
- The built output can be accessed from the
vagrant_sharedfolder within your OS
vagrant_shared folder is where the source code and projects have to be located, as Vagrant configures it as a shared folder that can be accessed indiscriminately by both your OS and the virtual machine.
Remember! If you delete something within the virtual machine
~/vagrant_shared/ directory it will also be removed from the folder you see in your Operating System.
vagrant_shared directory has been gitignored, so feel free to add or clone your own repositories there without interference from this one.
The microbit samples project contains a collection of example programs using the micro:bit runtime (DAL). The project directory can be found at:
This C/C++ project has already been built, but if you wish to recompile the examples you can access the virtual machine via SSH, and run:
cd ~/vagrant_shared/cpp-samples/ yt clean yt build
cpp-samples/source/examples folder contains a selection of samples demonstrating the capabilities and usage of the runtime APIs. To select a sample, simply copy the .cpp files from the relevant folder into the
cpp-samples/source/ folder. More info can be found in the microbit samples repository.
Built output location
To load the application into the micro:bit you will need to copy the
microbit-xxx-combined.hex file into the micro:bit USB drive.
The MicroPython source code can be found in:
MicroPython has already been built, but if you wish to build it again, you can open an SSH session and run:
cd ~/vagrant_shared/micropython/ yt clean make all
Built output location
The MicroPython hex file is saved into the following path:
Flashing to the micro:bit
You can simply copy the MicroPython hex into your micro:bit USB drive.
To simplify the process and be able to load MicroPython with or without an additional Python program, uflash (by Nicholas Tollervey) has been included with a wrapper script. So, from the host operating system you can run the following if you have Python (2 or 3) installed.
To load only the new MicroPython simply run this script:
python upy.py flash
To load the new MicroPython together with your Python code:
python upy.py flash <path to your python file>
For a quick test you could load any of the included MicroPython examples for the microbit:
python upy.py flash vagrant_shared/micropython/examples/conway.py
All command line arguments sent to the
upy_load.py wrapper script are sent over to uFlash (more info about available options in the uFlash's README). So, for example, if you'd like to save the combined
micropython.hex file (MicroPython + user Python code) into the current directory (indicated using
.), you can do so with the following command:
python upy.py flash vagrant_shared/micropython/examples/conway.py .
Access the MicroPython REPL
Once MicroPython is flashed, you will have access to the REPL on the USB CDC serial port, with baud rate 115200 (eg
picocom /dev/ttyACM0 -b 115200 on Linux,
screen /dev/tty.usbmodem* 115200 on OS X, or a tool like putty/TeraTerm on Windows).
The microrepl tool (by Nicholas Tollervey)is also bundled and easily accessible via a provided helper script. If you'd like to access the micro:bit REPL using your host computer terminal/console you can simply run the following Python (2 or 3) script:
python upy.py repl
If you are running Windows you might need to install the microbit driver, which can be found at: https://developer.mbed.org/handbook/Windows-serial-configuration
Access the MicroPython file system
MicroPython implements a simple file system inside the micro:bit flash, allowing you to read and write small files. The microfs Python command line utility (by Nicholas Tollervey), is bundled with a wrapper script to enable easy access from the host computer.
You can use the following commands:
- List the files on the micro:bit:
python upy.py fs ls
- Copy a file onto the micro:bit:
python upy.py fs put path/to/local.txt
- Get a file from the micro:bit:
python upy.py fs get remote.txt
- Delete a file on the micro:bit:
python upy.py fs rm remote.txt
- More info in the built-in help:
python upy.py fs --help
The PXT workspace is installed in the following directory:
Launch MakeCode server
To run MakeCode, open an SSH session and run:
cd ~/vagrant_shared/pxtworkspace pxt serve --no-browser --no-serial --hostname 0.0.0.0 --port 3232 --wsport 3233
Then, to connect from your host operating system, open a browser at the address displayed in the SSH terminal with one change: Replace
The terminal session should have showed you a message similar to the one below, but with a different token in the URL (which you need to keep):
... --------------------------------------------- To launch the editor, open this URL: http://0.0.0.0:3232/#local_token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&wsport=3233 ---------------------------------------------
So in the example above, point your browser to
This projects is not endorsed, sponsored or associated with the BBC. "BBC” and “micro:bit” are trade marks of the BBC. https://microbit.org