Appendix B: Software setup: Difference between revisions

From Bare Metal micro:bit
Jump to navigation Jump to search
No edit summary
No edit summary
(One intermediate revision by the same user not shown)
Line 27: Line 27:
==Updating==
==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.
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.
::<code>$ ''cd baremetal''</code>
::<code>$ ''cd baremetal-v1''</code>&emsp;(or <code>''cd baremetal-v2''</code>)
::<code>$ ''git pull''</code>
::<code>$ ''git pull''</code>
::<code>$ ''bash setup/genproj''</code>
::<code>$ ''bash setup/genproj''</code>
Line 55: Line 55:


[[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 vesions, 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.

Revision as of 15:19, 2 July 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. 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 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 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

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