Appendix B: Software setup

The experiments in this book assume that you are preparing programs for the micro:bit using a Raspberry Pi (version 2 or later), and the instructions given here are aimed at setting up the Pi with the software needed for that. The steps involve installing various software packages needed for ptogramming the micro:bit, such as versions of the GNU C compiler and attendant programs that are capable of generating code for the ARM Cortex-M0 processor on the board. They also install a modified version of the Geany programming environment that is able to make sense of the syntax of ARM assembly language.

Using a Raspberry Pi is convenient as a way of getting a standardised Linux-based setup with minimal fuss. However, it is almost as easy to set up any other Linux machine in a similar way, and I did much of the development work for the book on an ordinary Intel-based laptop. For machines running Debian or a derivative, the same setup script described below will work just as well as on a Raspberry Pi. For other Linux distributions, similar steps will work if performed manually. It doesn't matter if the host machine is based on an Intel processor rather than an ARM processor, because it's not necessary for the host processor actually to run any of the code that is being compiled; even on the Raspberry Pi, the compiler we use is a cross-compiler, running on one machine and generating code for another. Althogh in that case, both machines are designed by ARM, the host runs native ARM code while the target machine runs Thumb code.

Similarly, the instructions in this book are written on the assumption that you will be using Geany as a programming environment for editing and compiling the programs, but it is quite easy to use a different enviornment instead. The procedure for compiling and linking each program is described by a Makefile, so any programming environment that can invoke make to build a program can easily be used in place of Geany. If you prefer, you can use an ordinary text editor for programming and invoke make from the command line.

Some experiments rely on connecting the serial port on the micro:bit directly to the serial port on the Raspberry Pi, and for these to work, it's necessary to enable the serial port on the Pi. Instructions for doing this appear below.

Instructions

• 1: Begin with latest version of Raspbian, which you can get from the Raspberry Pi downloads page.

It works well if we continue to use the automatically generated 'pi' account: if you prefer to create an account with your own name, be sure to add yourself to all the same groups as user 'pi'.

Perform the following steps in a Terminal window (which you can open by clicking on the icon near the top left corner of the screen. In what follows, $ represents the shell prompt, and the rest of the line (shown in italics) is what you must type.

• 2: Update the system with the latest versions of all installed packages:

$ sudo apt-get update

$ sudo apt-get upgrade

This will avoid problems when the setup script installs new repositories and packages later.

• 3: Download the software kit. (For now, that means installing Git and cloning the Git repository as follows.)

$ sudo apt-get install git

$ git clone https://spivey.oriel.ox.ac.uk/git/baremetal-v1.git

If you have the V2 micro:bit, replace baremetal-v1.git with baremetal-v2.git; for simplicity, the software kit supports one version or the other, but not both at once.

• 4: Run the setup script:

$ cd baremetal-v1 (or cd baremetal-v2)

$ sh setup/install

This will automatically carry out the steps listed later in this appendix, and takes about 10 minutes at most.

• 5: Finally, reboot the machine by choosing Shutdown>Reboot in the main system menu. Afterwards, you should see that Geany project files (such as the file x01.geany in subdirectory x01-echo of the software kit) have the Geany icon, and double-clicking them opens the project in Geany. That is our preferred method of starting Geany with the correct options for building the project.

Updating

As more experiments are released, you will want to add the code to your copy of the software kit. You can do this using the git pull command, then running a script to create new Geany project files.

$ cd baremetal-v1 (or cd baremetal-v2)

$ git pull

$ bash setup/genproj

Any additions will be merged into your working copy of the files.

Setup actions

These are the actions performed by the setup script.

• Add a new software repository and signing key: the repository contains an enhanced build of the latest version of Geany, able to handle syntax hightlighting for ARM assembly language, and with space for more entries in the Build menu.
• Install the following Raspbian packages, together with the other packages on which they depend. Some may already be installed, but installing them again does no harm.

gcc-arm-none-eabi gdb-arm-none-eabi
pulseview sigrok-firmware-fx2lafw
minicom python3
geany geany-plugin-projectorganizer

• Associate Geany with project files (extension .geany), by adding a new MIME type application-geany-project.xml and a new desktop file geany.desktop.
• Install various personalised configuration files and settings for Geany. Specifically:
  • Create a file filetype_extensions.conf that associates files with extension .s with the language code GnuARM.
  • Disable the 'Load files from last session' option (it is confusing when used with projects).
  • Enable the project organiser plugin, and pre-select the Project tab in the Geany sidebar.
• Adjust the personalised file manager settings so that it no longer opens a dialog box every time a USB drive is inserted. (It's annoying if this happens every time the micro:bit reconnects.)
• Set the defaults for minicom to 9600 baud and device /dev/ttyACM0.

The script will also work on a PC running 32 bit or 64 bit Debian.

Enabling the serial port

For some experiements, we will want to use the serial port on the Raspberry Pi to connect to the micro:bit. Luckily, the 3.3V signals on both boards are compatible. For these experiments, the serial port on the Pi should be enabled, but should not show a login prompt. To set this up, from the main menu choose Preferences>Raspberry Pi Configuration; in the dialog that appears, click on the Interfaces tab, choose Serial Port = enable and Serial Console = disable and click on OK. A pop-up will appear asking if you would you like to reboot: click Yes.

Raspberry Pi configuration