Raspberry Pi Zero W How-to Guide

A guide to running Flightkit software on the Raspberry Pi Zero W.

1. Introduction

The following guide walks you through the steps required to configure a Raspberry Pi Zero W such that it can run flight software developed using Flightkit.

It has been written specifically for the Raspberry Pi Zero W. Other models of Raspberry Pi may require different steps. For simplicity we will refer to the Raspberry Pi Zero W as the "Pi" throughout this document.

The guide begins by explaining how to install the Raspberry Pi OS and configure the various drivers that are supported in FlightkitFoundation. It then goes on to describe how to build flight software for the Pi, how to run it on the device, and how to interact with it using Lab.

2. Installing Raspberry Pi OS

In order to run any software on the Pi, you first need to flash an operating system (OS) on the device. There are many OSs which are compatible with this model of Pi. We will use Raspberry Pi OS.

Complete the following steps to install Raspberry Pi OS:

  1. Insert a microSD card into your PC using a relevant adapter. Ensure that the SD card is between 8GB and 32GB in size.

  2. Download, install and run Raspberry Pi Imager by following the steps shown here.

  3. Click 'Choose Device' and select 'Raspberry Pi Zero W'.

  4. Click 'Choose OS' and select 'Raspberry Pi OS (32-bit)'.

  5. Click 'Choose Storage' and select your microSD card from the list of options.

  6. Click 'Next'.

  7. When prompted whether you’d would like to apply OS customisation settings, click 'Edit Settings'.

  8. Complete all fields in the 'General' tab, and toggle 'Enable SSH' and select 'Use password authentication' on the 'Services' tab. If you choose to overwrite any of the existing default values on these tabs, be sure to keep a note of the new values as you will need them later, specifically the hostname, username and password.

  9. Click 'Save'.

  10. Click 'Yes' to apply the OS customisation settings.

  11. Click 'Yes' to confirm that you want to write to the selected microSD card.

  12. Once complete, click 'Continue'.

After completing all of the above steps, the OS will now be flashed to your microSD card. Finally eject your card from the PC, and insert it into your Pi’s microSD card slot.

3. Connecting to the Pi via SSH

Now that the OS has been configured for running on the Pi and the microSD card inserted into the device, you can power up the device and connect to it.

The simplest way to interact with the Pi from your Linux machine is to use SSH on the command line. Follow the steps below to connect and interact with the Pi via SSH.

  1. Apply power to the device via one of its micro USB ports. This can be provided via an external power supply, or via your PC’s USB port. Once properly connected, you should see a small green LED flash before finally turning off. This indicates that the board has booted successfully.

  2. Connect to the device via SSH by running the following command in the terminal. If you changed the username and/or hostname in the OS configuration steps above then use your values instead of pi and raspberrypi, respectively:

    ssh pi@raspberrypi

  3. When prompted, input the password. By default this should be raspberry. If you changed the password in the OS configuration steps above, use the password you set.

You should now be connected and be able to run commands on the Pi’s shell.

4. Configuring drivers on the Pi

We provide a variety of different deployment types that can be run on the Pi in the bundles shipped with Flightkit. One of these deployment types, generic.linux.DriversDemo, which can be found in the FlightkitFoundation bundle, is configured to make use of the various drivers on the Pi that we currently provide support for. These drivers include its I2C driver, its SPI driver and its Serial (UART) driver. In order for software to communicate with these drivers on the device, they first need to be enabled in the kernel.

4.1. Configuring the I2C driver

To enable the I2C driver:

  1. Open the Pi’s configuration tool by running the following command in the terminal when connected to the Pi via SSH:

    sudo raspi-config

  2. Select 'Interface Options'.

  3. Select 'I2C'.

  4. When asked whether you would like the ARM I2C interface to be enabled, select 'Yes'.

  5. To close the configuration tool, click 'Finish'.

  6. If prompted whether you would like to reboot the device, select 'Yes'. Wait until it has rebooted then reconnect to it via SSH.

  7. To confirm that the I2C driver is enabled, run the following command in the terminal:

    lsmod

If successfully enabled, i2c_bcm2835 should be included in the list reported by lsmod.

4.2. Configuring the SPI driver

To enable the SPI driver:

  1. Open the Pi’s configuration tool by running the following command in the terminal when connected to the Pi via SSH:

    sudo raspi-config

  2. Select 'Interface Options'.

  3. Select 'SPI'.

  4. When asked whether you would like the SPI interface to be enabled, select 'Yes'.

  5. To close the configuration tool, click 'Finish'.

  6. If prompted whether you would like to reboot the device, select 'Yes'. Wait until it has rebooted then reconnect to it via SSH.

  7. To confirm that the SPI driver is enabled, run the following command in the terminal:

    lsmod

If successfully enabled, spi_bcm2835 should be included in the list reported by lsmod.

4.3. Configuring the Serial driver

There are two different Serial (UART) drivers available on the Pi - UART0 which is the PL011 UART, and UART1 which is the mini UART. The mini UART is more limited than the PL011 UART as it relies on other parts of the SoC to operate. PL011 however is a standalone UART driver, so it offers all the functionality that one would expect from a UART driver.

If you wish to know more about the details of these two drivers refer to the BCM2835 datasheet.

By default, the PL011 UART is configured to work in conjunction with the on board bluetooth/wireless module as it offers better performance than the mini UART - an important factor when working with wireless protocols.

If you do not require use of the bluetooth/wireless functionality, and/or you require a reliable Serial connection via the GPIO header, we recommend you follow the steps shown in this guide to reconfigure the PL011 UART to be used as the GPIO header’s primary UART.

To configure the PL011 UART as the primary UART:

  1. Disable the bluetooth module by running the following command in the terminal. This sets PL011 as the primary UART:

    cat dtoverlay=disable-bt >> /boot/firmware/config.txt

  2. Disable the system service that initialises the modem by running the following command in the terminal:

    sudo systemctl disable hciuart

    Now that the bluetooth module has been disabled, configure the primary UART (now the PL011 UART) to be used for the GPIO header, and not the serial console.

  3. Open the Pi’s configuration tool by running the following command in the terminal:

    sudo raspi-config

  4. Select 'Interface Options'.

  5. Select 'Serial Port'.

  6. When asked whether you would like a login shell to be accessible over serial, select 'No'.

  7. When asked whether you would like the serial port hardware to be enabled, select 'Yes'.

  8. To close the configuration tool, click 'Finish'.

  9. If prompted whether you would like to reboot the device, select 'Yes'. Wait until it has rebooted then reconnect to it via SSH.

  10. To confirm that the PL011 UART has successfully been configured as the primary UART, run the following command in the terminal:

    ls -l /dev/serial*

If successfully configured, /dev/serial0 → ttyAMA0 should be displayed in the output of the ls command.

/dev/serial0 is the symlink that refers to the primary UART, and ttyAMA0 is the device name for the PL011 UART.

With these steps all complete, your Pi should now be properly configured to enable access to its onboard I2C, SPI and Serial drivers.

5. Installing the Toolchain

In order to build flight software binaries that can run on the Pi, you need to use the correct toolchain.

FlightkitFoundation includes the PiZero build configuration. This build configuration specifies that binaries should be built using the armv6-rpi-linux-gnueabihf toolchain.

Many different builds of this toolchain can be found here. We recommend you install the 1.0.0 build of the GCC 14-based toolchain which can be downloaded by clicking here.

Once downloaded:

  1. Extract the archive. The /opt directory is a common location used for storing external toolchains.

  2. Add the extracted …​/armv6-rpi-linux-gnueabihf/bin directory containing the toolchain executables to your PATH.

  3. Verify that the toolchain was successfully added to the path by restarting your shell and running the following command:

    armv6-rpi-linux-gnueabihf-gcc --version

More detailed installation instructions are available here and may be followed instead of the above, but be sure to replace aarch64-rpi3-linux-gnu with armv6-rpi-linux-gnueabihf in all commands and paths.

6. Building the Demo Mission

With the toolchain successfully downloaded and installed you can build flight software to run on the Pi.

The following steps will guide you through this process using the PiDemo mission from the FlightkitFoundation bundle:

  1. Create a new workspace for building the mission in.

  2. Require the FlightkitFoundation bundle so that the tooling can access its contents by running the following command:

    hfk workspace bundle require FlightkitFoundation

  3. Build the PiDemo mission in the FlightkitFoundation bundle by running the following command:

    hfk mission build PiDemo

This builds all the deployment instances in the mission using the new toolchain you installed in the previous section. It also generates a mission database for interacting with them via Lab. The resultant binaries for each deployment instance and the mission database can be found within output/bundles/FlightkitFoundation/X.Y.Z/missions/PiDemo/ where X.Y.Z is the version of FlightkitFoundation you are using.

Alternatively, you can build deployment instances within other missions you have created, to run on the Pi. To do so, set the <BuildConfig> elements of those deployment instances within the mission.xml file to name="PiZero". This ensures the binaries are built using the correct toolchain.

7. Running Flight Software on the Pi

In order to run the binaries on the Pi, they first need to be copied over to the device.

This section demonstrates this process using the Default deployment instance binary.

  1. To copy the binary over to the device run the following command from the root directory of your workspace, replacing X.Y.Z with the version of your FlightkitFoundation bundle. As above, if you changed the username and/or hostname when configuring the OS then use you values here instead of pi and raspberrypi.

    scp output/bundles/FlightkitFoundation/X.Y.Z/missions/PiDemo/DriversDemo/Default/Default pi@raspberrypi:

  2. SSH into your Pi as described previously:

    ssh pi@raspberrypi

  3. The scp command copied the Default binary to the pi user’s home directory. This is the same directory which the ssh shell starts in. In order to execute the binary you can just run the following command:

    ./Default

This should run the binary on the device resulting in the following output being printed to the console:

INF: Deployment.c:424 Running deployment:
INF: Deployment.c:425 - Deployment instance: Default
INF: Deployment.c:426 - Deployment type:     generic.linux.DriversDemo
INF: Deployment.c:427 - Target:              DriversDemo
INF: Deployment.c:428 - Mission:             PiDemo
INF: Deployment.c:598 Deployment initialisation successful

With the binary running, you can interact with it using Lab:

  1. Open Lab.

  2. Load the PiDemo mission database.

  3. Connect to the deployment instance using the Pi’s IP address and the port specified in the deployment instance’s TCPServer initialization data. If unchanged from default values, this should be 51423.

  4. Invoke the Version component instance’s dumpVersion action.

  5. Verify that the following output is printed to the Pi’s console with the date and time that your binary was built:

    INF: Version.c:126 Version: Version: 0.1 build 4D61646520696E20466C696768746B697400
INF: Version.c:132 Version: Build date: May 28 2024
INF: Version.c:134 Version: Build time: 11:55:26

You have now successfully built, run and interacted with a deployment instance on the Pi.