Installing the micro:bit toolchain (Digital Systems)

These instructions will guide you through installing the relevant version of the GNU C compiler, binary file utilities, and other needed programs on a Linux machine, specifically one running Debian, or a Debian derivative such as Ubuntu. The tools have been installed on the Fedora-based machines in the Software Lab, and should be easily installed on other flavours of Linux.

The notes below mostly refer to the basic toolchain – Make, the GNU C compiler and related utilities – and mostly omit installing the Geany programming environment that I've recommended for the course. It's possible to install Geany on Windows and the Mac, but the Geany project files I've provided for the lab exercises may need adjustments, particularly for Windows, and I haven't investigated that. You won't absolutely need to install the toolchain on your own machine to complete the course, but since you have a micro:bit to take away with you, it would be a shame not to do so.

• If you have a Linux machine, then all should go smoothly. The instructions below are biased towards Debian, but should work without change on Debian derivatives such as Ubuntu.

• If you have a Windows machine, then the best way forward (apart from nuking Windows and installing Linux in its place) is probably to install VirtualBox, make a small Debian installation inside it, and install the toolchain in Debian. There may be small problems if Windows and Debian decide to fight over the ownership of various USB devices.

• If you have an Intel-based Mac, then the VirtualBox method is also available. Alternatively, it should be possible to install the needed tools via Homebrew or MacPorts, noting that the ARM version of GCC that is needed is called gcc-arm-none-eabi, and is different from the gcc-arm-linux-gnueabihf that is needed for the compilers course.

• If you have a Raspberry Pi running the latest version of Raspbian ('Stretch'), then things should go smoothly, since Raspbian is a variant of Debian, and the required packages all exist.

Installing the toolchain on Linux

These are the packages you'll need:

1. The relevant ARM cross compiler versions of GCC and GDB. On Debian, the packages are called gcc-arm-none-eabi and gdb-multiarch, or formerly gdb-arm-none-eabi – with the "none" indicating that there is no operating system on the board. Note that the compiler is different from the one called gcc-arm-linux-gnueabihf that is needed to (cross)-compile for the Raspberry Pi. We will also need the GNU assembler and binutils, but these should be dragged in with GCC.
2. The relevant C libraries – a package that Debian calls libnewlib-arm-none-eabi.
3. A Python script called pyOCD that connects GDB with the debug interface of the micro:bit.
4. The version control system mercurial.
5. The terminal emulator program minicom.
6. Optionally, the programming environment geany.

On Debian-based systems, all these can be installed by running the command

$ sudo apt-get install gcc-arm-none-eabi gdb-multiarch mercurial minicom python3-pip

plus, if you want geany,

$ sudo apt-get install geany geany-plugin-projectorganizer

followed in either case by

$ sudo pip3 install pyocd

Installing the C libraries is implied by installing GCC, but in case of trouble you can install the package libnewlib-arm-none-eabi explicitly. There is a Debian package python3-pyocd that provides the pyocd command, but the version is far too old to be usable with the micro:bit.

Note: some people prefer to install Python packages for each user, rather than once for the entire system, believing that this reduces the risk that buggy or malicious packages will break the system. That's certainly a good idea for untrusted or experimental packages, but less important in my opinion for relatively stable components like pyOCD. If that's what you prefer, then substitute

$ pip3 install pyocd --user

for the sudo-based command shown above, and make sure the directory $HOME/.local/bin is in your path.

When the micro:bit is plugged into a USB port, you will need permission to access it as a Mass Storage Device to download programs, as a Serial device to interact with the serial port on the board, and as a generic HID device for the debugger interface. Access to the device can be enabled by adding an appropriate udev rule; here's the rule that I added on my Debian machine in /etc/udev/rules.d/50-mbed.rules (it must appear all on one line).

ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="0d28", ATTRS{idProduct}=="0204", 
    MODE="660", GROUP="plugdev"

After adding the rule, you must add yourself to the group plugdev, then log in afresh. For convenience, a copy of this file is included as setup/50-mbed.rules in the lab materials; you can copy it to the right place with the command

$ sudo cp setup/50-mbed.rules /etc/udev/rules.d

There may be some difficulty in accessing the micro:bit using Minicom, which may sometimes report "/dev/ttyACM0: device or resource busy". There's some evidence that the Linux modem manager is to blame: whenever it sees a new serial device, it considers whether to grab the device and treat it as a modem supporting a potential network connection. It's possible to configure the modem manager to ignore unknown USB devices, but quicker (if, like me, you have no modems at all) to remove it with the command,

$ sudo apt-get purge modemmanager

That command will do no harm if you do not have the modem manager installed after all.

By the way, if you appear to be able to write hex files to the micro:bit but nothing more happens, then it isn't a good sign when the files seem to appear in the root directory of the virtual storage device. What ought to happen is that, as soon as the host computer has finished writing a hex file, the micro:bit disconnects, then immediately reconnects again, but with the hex file gone – it has been written into Flash and exists no longer. If the hex file continues to appear, it means that the writing process has not properly finished for some reason.

VirtualBox notes

I've put together a 'virtual appliance' that can be installed within VirtualBox on a Windows or Linux machine or an Intel-based Mac, and contains all the software needed for the course. Another page has instructions for installing it.

Raspberry Pi notes

On a headless RPi running Raspbian Stretch lite:

• Install packages as listed above.
• Needed sudo addgroup mike dialout to access /dev/ttyACM0.
• Set up minicom with 9660 8N1 and no flow control.
• Find the block device with lsblk, then sudo mount -o uid=mike /dev/sdb /mnt
• Use cp echo.hex /mnt; sync
• The micro:bit seems to need a manual reset before it is accessible from minicom.

More up-to-date information is available on the site for my book Bare Metal micro:bit, which describes programming the micro:bit using a Raspberry Pi as the host.

Mac notes

Quentin Miller writes as follows.

I thought I'd be a guinea pig for the MacPorts installation. Gave up after a few miserable hours – I've never got on terribly well with MacPorts. But Homebrew worked without any hitches:

brew tap PX4/homebrew-px4
brew update
brew install gcc-arm-none-eabi

(arm-none-eabi-gdb seems to be installed as part of the above)

brew install srecord
brew install python (to upgrade to python3)
python -m pip install --pre -U pyocd
brew install mercurial

This was enough to allow proj0 and proj1 to work. Homebrew can install minicom, but the native "screen" command seems sufficient:

ls /dev/tty.*
screen /dev/tty.<usbmodemname> 9600
exit with CTRL-A k

Works with the debugging stuff as well. But if minicom is needed,

brew install minicom

and there's no special setup; invoke

minicom -D /dev/tty.<usbmodemname> -b 9600
exit with META-Z x

(Exiting with META-Z q seems to [leave] the port locked; you then need to unmount and remount the microbit before subsequent connections are allowed.)

Having a Mac with MacPorts installed for other purposes, Mike tried going that route.

Use port install arm-none-eabi-gcc. This brings with it the appropriate version of binutils and also newlib.

My Mac already had the MacPorts version of Mercurial installed, but presumably port install mercurial will do the business.

After compiling a micro:bit program, use cp add.hex /Volumes/MICROBIT to upload it. When the micro:bit unmounts and remounts itself, Mac OS moans as usual about not ejecting the device properly, but that's nothing to worry about.

I also used port install minicom, and then

minicom -b 9600 -D /dev/tty.usbmodem1422

or something similar.

I haven't tried installing gdb or pyocd yet.

Windows notes

If you want to try installing on Windows, the relevant software seems to be here:

https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads

Other tools such as make that we take for granted under Linux might need installing from elsewhere.

Another possibility is to use the Windows Subsystem for Linux to install the Linux tools.

Yet another is to install VirtualBox and make a small installation of Linux.

Zeyang Zhao reports:

• He installed gcc-arm-none-eabi, gdb-arm-none-eabi and libnewlib-arm-none-eabi from the ARM developer site. He needed to specify GCCLIB in the Makefile for Lab 1.
• pyocd can be installed from pip on Windows. (WSL does not have support for the debugging device.) You also need to follow https://github.com/mbedmicro/pyOCD#libusb-installation.
• In place of minicom, use PuTTY or cu in WSL. (minicom and screen are not supported in WSL.) /dev/ttySx in WSL is COMx in Windows, so you can run cu -l /dev/ttyS4 -s 9600 if the micro:bit is COM4 in Windows.
• For make, use Make for Windows (It's a old version. Install from Choco if you want a newer version.)
• For srecord and Mercurial, use WSL.