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.
If you prefer to use 🐳 Docker this other project might interest you: Docker micro:bit Toolchain
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 using the DAL (micro:bit runtime)
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.
You will need the following applications first:
- VirtualBox
- Vagrant
- (Optional) Python (2.7 or >=3.4)
Clone, or download this repository:
git clone https://github.com/carlosperate/microbit-dev-env.git
cd microbit-dev-envGetting the virtual machine up and running with Vagrant is extremely easy, on the Command Line Interface just run:
vagrant up --provisionThis will first ask you what project would you like to build. Selecting only the project you are interested will significantly reduce the bring up time.
$ vagrant up --provision
Build MakeCode? (y/n): y ✅
Build C++ samples (DAL)? (y/n): y ✅
Build CODAL? (y/n): y ✅
Build MicroPython V1? (y/n): y ✅
Build MicroPython V2? (y/n): y ✅
After the questions have been answered, it 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 build tool-chain, download and build all the source code for the selected projects, ensuring everything is ready to develop your application in any of these platforms.
First, start-up the virtual machine:
vagrant upIf this is the first time you've run this command it will ask you which projects you would like to build. Enter y to select any of the prompted projects.
You can now SSH into the virtual machine with Vagrant itself:
vagrant sshOr 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 cpp-samples, micropython, 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 allTo stop the virtual machine from running, you can use the following command on the host:
vagrant halt
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
~/vagrant_shared/) - The built output can be accessed from the
vagrant_sharedfolder within your OS
The 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.
The 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:
vagrant_shared/cpp-samples/
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 buildThe 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.
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.
vagrant_shared/cpp-samples/build/bbc-microbit-classic-gcc/source/microbit-samples-combined.hex
The microbit samples project contains a collection of example programs using the micro:bit runtime for V2 (CODAL). The project directory can be found at:
vagrant_shared/microbit-v2-samples/
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/microbit-v2-samples/
python3 build.pyThe microbit-v2-samples/source/samples/ 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 micro:bit V2 samples repository.
To load the application into the micro:bit you will need to copy the MICROBIT.hex file into the micro:bit USB drive.
vagrant_shared/microbit-v2-samples/MICROBIT.hex
The MicroPython source code can be found in:
vagrant_shared/micropython/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 allThe MicroPython hex file is saved into the following path:
vagrant_shared/micropython/build/firmware.hexYou 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 flashTo 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.pyAll 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 .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 replIf 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
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 MicroPython source code can be found in:
vagrant_shared/micropython-microbit-v2/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-microbit-v2/src
makeThe MicroPython hex file is saved into the following path:
vagrant_shared/micropython-microbit-v2/src/MICROBIT.hexWIP
The PXT workspace is installed in the following directory:
vagrant_shared/pxtworkspace/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 3233VERY IMPORTANT: From your host OS open a browser and go to the address displayed in the SSH terminal with one CHANGE: Replace 0.0.0.0 with localhost.
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 http://localhost:3232/#local_token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&wsport=3233 instead.
This projects is not endorsed, sponsored or associated with the BBC or the Micro:bit Educational Foundation. "BBC” and “micro:bit” are trade marks of the BBC. https://microbit.org