Appendix B: Software setup: Difference between revisions

From Bare Metal micro:bit
Jump to navigation Jump to search
No edit summary
No edit summary
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
The experiments in this book assume that you are preparing programs for the {{microbit}} 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 {{microbit}}, 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.
<!--Uploaded-->The experiments in this book assume that you are preparing programs for the {{microbit}} using a Raspberry Pi (version 3 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 programming the {{microbit}}, 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.
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.  Although 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.
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 environment 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 {{microbit}} directly to the serial port on the {{RPi}}, and for these to work, it's necessary to enable the serial port on the Pi.  Instructions for doing this appear below.
Some experiments rely on connecting the serial port on the {{microbit}} directly to the serial port on the {{RPi}}, and for these to work, it's necessary to enable the serial port on the Pi.  Instructions for doing this appear below.


==Instructions==
==Instructions==
* '''1: Begin with latest version of Raspbian,''' which you can get from the Raspberry Pi [https://www.raspberrypi.org/downloads downloads page].
* '''1: Begin with latest version of Raspberry Pi OS,''' which you can get from the Raspberry Pi [https://www.raspberrypi.org/downloads downloads page]. Follow the instructions on that page to write the operating system image to an SD card and boot it in your Raspberry Pi.
: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 [[Image: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.
Perform the following steps in a Terminal window (which you can open by clicking on the [[Image: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: Update the system''' with the latest versions of all installed packages:
* '''2: Update the system''' with the latest versions of all installed packages:
Line 23: Line 22:
::<code>$ ''sh setup/install''</code>
::<code>$ ''sh setup/install''</code>
:This will automatically carry out the steps listed later in this appendix, and takes about 10 minutes at most.
: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 {{Menu|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.
* '''5: Finally, reboot the machine''' by choosing {{Menu|Shutdown>Reboot}} in the main system menu.  Afterwards, you should see that Geany project files (such as the file @x01.geany@ in sub-directory @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==
==Updating==
Line 34: Line 33:
==Setup actions==
==Setup actions==
These are the actions performed by the setup script.
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 {{Menu|Build}} menu.
*Add a new software repository and signing key: the repository contains an enhanced build of the latest version of Geany, able to handle syntax highlighting for ARM assembly language, and with space for more entries in the {{Menu|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.
*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.
<pre>
<pre>
Line 52: Line 51:


==Enabling the serial port==
==Enabling the serial port==
For some experiements, we will want to use the serial port on the {{RPi}} to connect to the {{microbit}}.  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 {{Menu|Preferences>Raspberry Pi Configuration}}; in the dialog that appears, click on the {{Menu|Interfaces}} tab, choose {{Menu|Serial Port}} = enable and {{Menu|Serial Console}} = disable and click on {{Menu|OK}}.  A pop-up will appear asking if you would you like to reboot: click {{Menu|Yes}}.
For some experiments, we will want to use the serial port on the {{RPi}} to connect to the {{microbit}}.  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 {{Menu|Preferences>Raspberry Pi Configuration}}; in the dialog that appears, click on the {{Menu|Interfaces}} tab, choose {{Menu|Serial Port}} = enable and {{Menu|Serial Console}} = disable and click on {{Menu|OK}}.  A pop-up will appear asking if you would you like to reboot: click {{Menu|Yes}}.


[[Image:RPi-config.png|center|frame|Raspberry Pi configuration]]
[[Image:RPi-config.png|center|frame|Raspberry Pi configuration]]
==V1 and V2 boards==
All the experiments in this book will work with either Version 1 of the {{microbit}} board (released in 2016), based on the Nordic nRF51822 chip, or Version 2 (released in 2020), based on the nRF52833 chip.  There are separate software kits for each of them, installed by fetching the GitHub repositories @baremetal-v1@ or @baremetal-v2@ respectively.  Some difference between the two versions is inevitable because the board designs differ, and while the peripherals integrated into the two microcontrollers are similar, the memory layout, the clock setup and other details differ.  The software follows a number of principles to keep the differences between versions manageable.
* The layout of device registers in each chip is defined in a header file @hardware.h@ that, as far as possible, provides the same interface for both chips, but with definitions adjusted for each of them.  The header file exists in two versions, each adjusted to the hardware of one of the chips.  One version additionally defines the macro @UBIT_V1@ and the other defines @UBIT_V2@, and these macros are used to enable variants of the code in other source files that are adapted to the different boards.
* Any files that participants are expected to edit are free of @ifdefs@, to avoid the familiar problem of editing the wrong piece of conditionally-compiled code and then puzzling over why the changes have no effect.  Wherever possible, these participant-modified files are the same in both versions, but occasionally they exist in two versions, with the differences between them noted in the text, often in callout boxes labelled "{{microbit}} version 2".
* Other files, when the content is vastly different for the two boards, also exist in two versions that are identically named and provide the same interface, but contain different implementations for the two versions.  When the differences are more circumscribed (and especially in the source code of the {{microbian}} operating system in the third part of the book), there are sometimes parallel pieces of code that are activated by @ifdef@s based on the @UBIT_V1@ and @UBIT_V2@ macros.
Programs in the early part of the book are entirely independent of each other, and each contains in a single directory all the source code that is needed, with each program having its own copy of shared files like @hardware.h@ and the library @lib.c@ that provides @printf@ and other things.  For the third part of the book, there is a shared directory containing the source code for the {{microbian}} scheduler and various device drivers.
The simplicity of the setup does mean that it's hard to support both boards at the same time: but doing that more or less demands a setup with separate source directories for the common parts of the code and for the files specific to each board, separate build directories for the boards, and Makefiles that include search paths to find the relevant source -- all many times more complicated than the one-program-one-directory approach that is provided for this book.
==Alternatives==
The instructions in this book assume you are using a Raspberry Pi to prepare programs for the {{microbit}}, but they can also be followed with little change on other platforms.
* You could use a PC running Linux.  If you are running Debian, then the @install@ script from the software kit can likely be used without change to install the tools you need.  It doesn't matter at all that the host processor in the PC is an Intel chip and the binary code for our programs will be for the Cortex-M variant of the ARM: the translation will explicitly be done by a ''cross-compiler'' that runs on one kind of machine but generates binary code for another kind.
* You could use a PC running Windows or a Macintosh, and set up a virtual Linux environment within VirtualBox.  For this, I recommend as the 'guest' operating system a version of Debian with the Raspberry Pi desktop, because it look identical to the screenshots in the book and is lightweight enough to make good use of the limited amounts of RAM and machine time that are available in a virtual machine.  You can download it from the same Raspberry Pi [https://www.raspberrypi.org/downloads downloads page].

Latest revision as of 18:58, 14 August 2022

The experiments in this book assume that you are preparing programs for the micro:bit using a Raspberry Pi (version 3 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 programming 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. Although 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 environment 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 Raspberry Pi OS, which you can get from the Raspberry Pi downloads page. Follow the instructions on that page to write the operating system image to an SD card and boot it in your Raspberry 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: 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 sub-directory 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 highlighting 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 experiments, 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

V1 and V2 boards

All the experiments in this book will work with either Version 1 of the micro:bit board (released in 2016), based on the Nordic nRF51822 chip, or Version 2 (released in 2020), based on the nRF52833 chip. There are separate software kits for each of them, installed by fetching the GitHub repositories baremetal-v1 or baremetal-v2 respectively. Some difference between the two versions is inevitable because the board designs differ, and while the peripherals integrated into the two microcontrollers are similar, the memory layout, the clock setup and other details differ. The software follows a number of principles to keep the differences between versions manageable.

  • The layout of device registers in each chip is defined in a header file hardware.h that, as far as possible, provides the same interface for both chips, but with definitions adjusted for each of them. The header file exists in two versions, each adjusted to the hardware of one of the chips. One version additionally defines the macro UBIT_V1 and the other defines UBIT_V2, and these macros are used to enable variants of the code in other source files that are adapted to the different boards.
  • Any files that participants are expected to edit are free of ifdefs, to avoid the familiar problem of editing the wrong piece of conditionally-compiled code and then puzzling over why the changes have no effect. Wherever possible, these participant-modified files are the same in both versions, but occasionally they exist in two versions, with the differences between them noted in the text, often in callout boxes labelled "micro:bit version 2".
  • Other files, when the content is vastly different for the two boards, also exist in two versions that are identically named and provide the same interface, but contain different implementations for the two versions. When the differences are more circumscribed (and especially in the source code of the micro:bian operating system in the third part of the book), there are sometimes parallel pieces of code that are activated by ifdefs based on the UBIT_V1 and UBIT_V2 macros.

Programs in the early part of the book are entirely independent of each other, and each contains in a single directory all the source code that is needed, with each program having its own copy of shared files like hardware.h and the library lib.c that provides printf and other things. For the third part of the book, there is a shared directory containing the source code for the micro:bian scheduler and various device drivers.

The simplicity of the setup does mean that it's hard to support both boards at the same time: but doing that more or less demands a setup with separate source directories for the common parts of the code and for the files specific to each board, separate build directories for the boards, and Makefiles that include search paths to find the relevant source – all many times more complicated than the one-program-one-directory approach that is provided for this book.

Alternatives

The instructions in this book assume you are using a Raspberry Pi to prepare programs for the micro:bit, but they can also be followed with little change on other platforms.

  • You could use a PC running Linux. If you are running Debian, then the install script from the software kit can likely be used without change to install the tools you need. It doesn't matter at all that the host processor in the PC is an Intel chip and the binary code for our programs will be for the Cortex-M variant of the ARM: the translation will explicitly be done by a cross-compiler that runs on one kind of machine but generates binary code for another kind.
  • You could use a PC running Windows or a Macintosh, and set up a virtual Linux environment within VirtualBox. For this, I recommend as the 'guest' operating system a version of Debian with the Raspberry Pi desktop, because it look identical to the screenshots in the book and is lightweight enough to make good use of the limited amounts of RAM and machine time that are available in a virtual machine. You can download it from the same Raspberry Pi downloads page.