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 thegcc-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:
- The relevant ARM cross compiler versions of GCC and GDB. On Debian, the packages are called
gcc-arm-none-eabi
andgdb-multiarch
, or formerlygdb-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 calledgcc-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. - The relevant C libraries – a package that Debian calls
libnewlib-arm-none-eabi
. - A Python script called pyOCD that connects GDB with the debug interface of the micro:bit.
- The version control system
mercurial
. - The terminal emulator program
minicom
. - 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
, thensudo 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 ofbinutils
and alsonewlib
. - 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
orpyocd
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
andlibnewlib-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 orcu
in WSL. (minicom
andscreen
are not supported in WSL.)/dev/ttySx
in WSL isCOMx
in Windows, so you can runcu -l /dev/ttyS4 -s 9600
if the micro:bit isCOM4
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.