The micro:bit toolchain on VirtualBox
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 light version of Debian within VirtualBox and setting it up for the labs. 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 Debian with the LXDE desktop environment, 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.
- The hard way is to begin with an empty virtual machine and install Debian 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.
When it is ready, I will move over to using the "Raspberry Pi desktop for PC and Mac" for this installation: it is a version of LXDE with improvements the look and feel. Currently, this software is based on Debian Buster, and we need the later version of Geany that comes with Debian Bullseye.
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 between the host and the guest operating system.
- The virtual appliance, downloaded from https://github.com/Spivoxity/digisys-vbox/releases/download/v1.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-6.1.32 on your Desktop or the USB drive, 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.
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.
- Install Debian on it, using installation media downloaded from
- We need Bullseye because the version of Geany provided in Buster is too old for our purposes.
- 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.
- For quick results, uncheck GNOME and check LXDE when asked. Lots of unneeded software will be installed, but you'll get a working installation with minimal fuss.
- For a compact image without games and office software, you can not choose a desktop environment initially (at the
taskselstage, uncheck both Desktop Environmet and GNOME, leaving just Standard Utilities selected). Then log in to the command line and do
$ sudo apt-get install lxde-core
- Rebooting will get you the LXDE login screen, and you can then install further software as needed.
The USB sticks provided for install parties contain not the 'netinst' CD image linked above, but a larger DVD image that allows most of the software to be installed without having to download it separately, reducing the bandwidth consumption.
- 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 buuld 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.