Note: I've just migrated to a different physical server to run Spivey's Corner,
with a new architecture, a new operating system, a new version of PHP, and an updated version of MediaWiki.
Please let me know if anything needs adjustment! – Mike

Installing the micro:bit toolchain: Difference between revisions

Copyright © 2017–2023 J. M. Spivey
Jump to navigation Jump to search
No edit summary
Line 42: Line 42:
==VirtualBox notes==
==VirtualBox notes==
A [[The micro:bit toolchain on VirtualBox|separate page]] has notes on 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''.
A [[The micro:bit toolchain on VirtualBox|separate page]] has notes on 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''.
That page is in the process of being superseded by [[corner:Setting up a programming environment|another]], with general instructions for setting up a comfortable environment for programming.


==Raspberry Pi notes==
==Raspberry Pi notes==

Revision as of 21:25, 18 July 2022

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 a 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-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 script called pyOCD that connects GDB with the debug interface of the micro:bit. This can be installed on top of Python 2.7 with pip install --pre -U pyocd.
  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 as root the command

$ sudo apt-get install gcc-arm-none-eabi gdb-arm-none-eabi mercurial minicom geany geany-plugin-projectorganizer

followed by

$ sudo pip install --pre -U 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.)

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.

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

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

A separate page has notes on 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.

That page is in the process of being superseded by another, with general instructions for setting up a comfortable environment for programming.

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.