Difference between revisions of "Software setup"

From Bare Metal micro:bit
Jump to navigation Jump to search
Line 11: Line 11:
::<code>$ ''git clone <nowiki>https://github.com/Spivoxity/baremetal-v1</nowiki>''</code>
::<code>$ ''git clone <nowiki>https://github.com/Spivoxity/baremetal-v1</nowiki>''</code>
::<code>$ ''cd baremetal-v1''</code>
::<code>$ ''cd baremetal-v1''</code>
:Having separate software kits for V1 and V2 reduces complexity by allowing each kit to be adjusted to work with one board.
* '''3: Run the setup script:'''
* '''3: Run the setup script:'''
::<code>$ ''sh setup/install''</code>
::<code>$ ''sh setup/install''</code>

Revision as of 21:09, 26 May 2021

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. 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.


  • 1: Begin with latest 32-bit version of Raspberry Pi OS, which you can get from the Raspberry Pi downloads page. (The 64-bit version of the OS is not supported.)
It works well if you 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 Terminal.png 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: Download the software kit. For now, that means cloning the Git repository as follows. There are separate repositories baremetal-v1 and baremetal-v2 containing code adapted to the V1 and V2 micro:bit boards, respectively. Substitute baremetal-v2 for baremetal-v1 in the following if you have a V2 board.
$ git clone https://github.com/Spivoxity/baremetal-v1
$ cd baremetal-v1
Having separate software kits for V1 and V2 reduces complexity by allowing each kit to be adjusted to work with one board.
  • 3: Run the setup script:
$ sh setup/install
This will automatically carry out the steps listed later in this appendix, and takes about 10 minutes at most.
  • 4: 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 x1000.geany in subdirectory x1000-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.


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:

$ cd baremetal
$ git pull

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 software repository that contains an up-to-date version of Geany.
  • 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.
geany geany-plugin-projectorganizer
gcc-arm-none-eabi gdb-arm-none-eabi
pulseview sigrok-firmware-fx2lafw minicom
python3-pip bsdmainutils sed
  • Install an updated version of Geany with better syntax highlighting; this version is fully compatible with the standard version, but adds an option to change the character used to start comments in assembly language. The updated packages can be obtained from https://github.com/Spivoxity/geany-mods/releases.
  • 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 Debian or Ubuntu Linux; for other non-Debian-based Linux distributions, you will need to carry out similar actions by hand.