The micro:bit toolchain on VirtualBox
[This page is in the process of being superseded by another, with general instructions for setting up a comfortable environment for programming, based on Debian Linux with the Raspberry Pi desktop.]
VirtualBox is a virtual machine monitor: it uses the resources provided on a PC or Mac by a host operating system (for example, Windows) to simulate an empty computer, on which another guest operating system (for example, Linux) can be installed. We will use VirtualBox on a Windows machine or Mac to provide a Linux environment that can compile and download programs for the micro:bit. VirtualBox keeps the contents of the guest machine's hard disk in a single file in the host operating system, so virtual machine setups can be shared by copying this file.
These instructions will guide you through installing a version of Debian Linux within VirtualBox and setting it up for the labs. The version of Linux we will use is the "Raspberry Pi Desktop for PC and Mac", a lightweight Linux environment based on Debian and LXDE. The instructions are prepared for a Windows machine, but the same setup should work on a Mac, mutatis mutandis. There are two options.
- The easy way is to use a virtual machine image that has been prepared in advance. This image contains the desktop environment with the Geany editor and all the tools needed to compile the lab programs. It does not contain the lab software itself, so your first step after installing the image will be to clone the Mercurial repository containing the software, then run the setup script.
- The hard way is to begin with an empty virtual machine and install Linux and the needed software yourself. This can be a bit tedious, but gives you the freedom to make choices different from the ones I made.
The easy way is described first, and the hard way is described in a separate section at the end. If you have the disk space and want to experiment, you can do both and make two or more virtual machines with different variations on the suggested setup: that is one of the blessings of using virtual machines.
The easy way
The easy way of installing the software is to use a pre-made image.
You will need the following resources, which for convenience you could download onto your desktop.
- VirtualBox. Download the appropriate installer for your system from https://www.virtualbox.org/wiki/Downloads. I used version 6.1.32.
- Also download the VirtualBox Extension Pack from the same place. This lets us share USB devices (like the micro:bit) between the host and the guest operating system.
- The virtual appliance, downloaded from https://github.com/Spivoxity/digisys-vbox/releases/download/v2.0/digisys.ova. This "Open Virtualisation Archive" contains an image of the guest machine's hard disk.
For install parties, we will provide USB sticks containing all of these; you won't need to copy the files off the USB stick before installing them, but just use them from the USB stick.
Installing VirtualBox and importing the appliance
1. Double-click on the VirtualBox installer and accept all defaults.
2. Start "Oracle VM VirtualBox" from the start menu. Pin it to the taskbar if you like. You will see the VirtualBox manager window, with (so far) no virtual machines listed.
3. Install the extension pack by clicking on Preferences, then choosing the Extensions tab.
- Click on the blue square with the green plus sign at the far right, then find the file
Oracle_VM_VirtualBox_Extension_Pack-<version>on your Desktop or the USB drive (where
<version>stands for a version number such as
6.1.32), select it, and click Open.
- In the next dialog box, click Install. You will be shown a licence agreement; scroll down to the bottom then click I Agree.
- Now the screen will go black and you will be asked to give permission for changes; click Yes.
- Next you should see a message that the installation was successful; click OK, and click OK again in the Preferences window.
You should now be back at the VirtualBox manager window.
4. Import the virtual appliance by clicking on Import, leaving the setting at Local File System, then clicking on the button at the right and finding a file named
digisys on the desktop or USB key.
Click on Next to see a summary of the VM you are importing.
Leave everything as it is and click import. After the inevitable glacial progress meter, you will be back at the VirtualBox manager, this time with a virtual machine installed.
5. Select Digisys and press the green Start arrow to start the virtual machine.
Virtual machine features
The virtual machine runs a 32-bit version of Linux, chosen for its small memory footprint so that it can run in 1GB of RAM. It is configured with a UK keyboard layout. If you don't have a PC with a UK keyboard, then you can change the layout [how?].
The virtual machine is set to automatically log in the user 'guest' on startup. The password for 'guest' is also 'guest'; since the virtual machine is not accessible from the internet, this is fairly safe, but feel free to change the password if you like. The 'guest' user can use
sudo to run commands as root (on the virtual machine, not on the host).
Now you can start work on the labs by opening a terminal window and typing,
$ hg clone https://spivey.oriel.ox.ac.uk/hg/digisys-v1 digisys
Then continue with the instructions for Lab zero, beginning with running the setup script.
If you plug in a micro:bit to a USB port, you should see that it appears as a drive within the virtual machine.
The hard way
The hard way of installing the software is to make your own virtual machine from scratch. You may install Linux in a VirtualBox machine any way you want, but recorded below are the choices I made in preparing the image used in 'the easy way'.
- Install the appropriate version of VirtualBox for your host, accepting all defaults.
- Install the extension pack.
- Create a virtual machine for 32-bit Debian with 1GB of RAM and a 20GB hard disk image in VDI format, dynamically allocated. Even if you have 64-bit hardware, you can install a 32-bit guest operating system within VirtualBox; it's best to stick to a 32-bit guest because it will run more happily in a small amount of allocated RAM.
- Install the Raspberry Pi desktop on it, using installation media downloaded from
- It's OK to accept most of the defaults proposed by the Debian installer
- For the prebuilt image, I chose not to allocate a swap partition. This makes the image more compact, and with no web browser installed, 1GB ought to be enough memory to avoid swapping.
- I chose to specify no root password, name the principal user as 'guest', and give them sudo rights instead.
The procedure above results in an environment where all the usual packages are installed, including LibreOffice and a lot of other stuff. Alternatively,
- install Debian without a desktop environment
- add the Apt entry for the Rpi desktop and the RPi signing key for packages.
to get something leaner and meaner. That's what I did for the virtual appliance.
- Now install VirtualBox guest additions to get smoother interaction between host and guest operating systems.
- You will need to install
linux-headers-686first in order build the VBox kernel modules.
- Next, choose "Devices/Insert Guest Additions CD Image". Find the CD-ROM in the File Manager – this causes it to be mounted.
- Then start a terminal window, change directory to
/media/cdrom, and run
- You will need to install
$ sudo sh VBoxLinuxAdditions.run
- Finally, reboot the guest machine so as to load the newly installed kernel drivers.
- Install the necessary software for the course.
$ sudo apt-get install mercurial geany geany-plugin-projectorganizer \
gcc-arm-none-eabi gdb-multiarch minicom python3-pip
- Disable the DVD image by editing
- Install pyOCD.
$ sudo pip3 install pyocd
update-alternatives --set x-terminal-emulator /usr/bin/lxterminaland uninstall lxterm.
- Enable autologin: see
- Disable screensaver.
- Disable PCManFM popup on device insertion: under Preferences/Volume Management.
- Allocate CMSIS-DAP USB device to VirtualBox – may need repeating after importing.
- Add udev rule for access to debug device.
Videosetc. directories under
- Customise the toolbar to omit the web browser but show Geany.
Some final hints:
- Use the
VboxSVGAgraphics adapter to avoid some messages at startup.
- I've left the desktop background and other choices unchanged (e.g. the colours for lxterminal).
- Clone the root fs (with
cp -a) and don't allocate a swap partition – that makes the OVA file 0.5GB smaller. We shouldn't need swap with no browser installed.
For next time:
lxappearanceand use it to choose the Gnome icon theme. The default theme has a funny object for the file manager – not helpful – whereas the Gnome theme has the conventional filing cabinet.