You've put everything together using the build instructions and now you're ready to install the software.

The easiest way to get all the FlightTracker software installed is with a freshly prepared Raspberry Pi. The installer script assumes it's running on a fresh install of Raspberry Pi OS Trixie.

These instructions are a walk-through of how to use the Raspberry Pi Imager for those unfamiliar with these tools.

First, download and install Raspberry Pi Imager on your computer.

Stick a microSD card into your computer and open the Imager. The steps are:

1. Choose your device - pick the Raspberry Pi model you're using (3B, 4B, Zero 2, Zero W, etc.).

Select your device

2. Choose your OS - select Raspberry Pi OS (Other) and then Raspberry Pi OS Lite. The Lite version has no desktop environment, which is exactly what we want - FlightTracker runs headless and a desktop would just waste resources. The Imager will show you the correct version for your device. If it offers you a choice between 32-bit and 64-bit, go with 64-bit unless you're on a Pi Zero, in which case choose 32-bit.

Choose your OS

3. Choose your storage - select your microSD card. Double-check you've picked the right one, because everything on it is about to be wiped.
4. Edit the settings - before you write, the Imager will offer to apply OS customisation settings. This is where you set up:
   • A hostname for your Pi (something like flighttracker makes it easy to find on your network).
   • A username and password - you'll need these to SSH in later. The quick-installer assumes the username pi.
   Set your username and password

   
   • SSH - under the Services tab, tick Enable SSH and choose Use password authentication. Unless you know what you're doing with SSH keys, password-based login is the simplest way to get going.
   • Your Wi-Fi details, if you're not using a wired connection.
   Configure Wi-Fi

   
   Enable SSH

   
5. Write - hit the button and wait. The Imager writes the image, verifies it, and applies your settings in one go.

Once that's done, eject the card, slot it into your Pi, and power it on. Give it a minute or two to boot and join your network, then SSH in from your computer:

If the .local hostname doesn't resolve on your network, you can find the Pi's IP address from your router's admin page and use that instead.

Now you need to connect to your Pi over SSH and run the installer script. If you've never used SSH before, it's a way to run commands on another computer over the network. The Raspberry Pi SSH guide covers installing an SSH client on Windows, macOS, and Linux.

Open a terminal (or Command Prompt / PowerShell on Windows) and connect to your Pi using the username and hostname you set in the Imager:

Accept the security prompt (type yes if it asks about a host key), then enter the password you set in the Imager. You won't see the characters as you type - that's normal for SSH.

Once you're in, you'll be sitting at a prompt on the Pi. Now run the installer:

The script walks through the whole install: the RGB matrix driver appropriate for your hardware, the FlightTracker code, the Python environment, and a systemd service so it starts automatically on boot. This can take anywhere from a few minutes on newer systems to half an hour or so on older Pi models.

When it's done, the Pi will reboot and FlightTracker will start up. The first boot can take a few minutes before everything is running. If you're concerned something isn't right, SSH in and run sudo systemctl status FlightTracker.service to see what's going on.

On boot, FlightTracker shows a QR code on the matrix - scan it with your phone to open the web configuration UI. You can also access the settings directly in a browser at http://flighttracker.local:8584 (using the hostname you set in the Imager) or http://<your-pi-ip>:8584.

First boot - scan to configure

If anything goes wrong, the manual install steps are in the platform-specific folders on GitHub: platforms/pi and platforms/pi5. You can also raise an issue if you get stuck.

Upgrading from FlightTracker v1 to v2

I'd recommend a clean install by wiping your SD card and starting from scratch. If that's not an option, you should be able to stop the current code from running and swap out the source code for the latest version.

If you've customised the code, you're probably going to have a bad time trying to update in place, as a huge amount has been rewritten between v1 and v2.

If you've got a clear path to upgrade then the code will port across your config.py to a config.json automatically on the first boot.

Before proceeding make sure you stop the FlightTracker from running:

sudo systemctl stop FlightTracker.service

You installed the original from a zip file

If you originally downloaded FlightTracker as a zip file from GitHub and extracted it into /home/pi/FlightTracker, the folder won't be a git repository so you can't pull updates. The cleanest approach is to remove the old source code and clone the latest version in its place.

Since the folder isn't a git repository you can't pull updates, but you can swap out the source code by hand while keeping your existing virtual environment and settings. Back up your config.py, clear out everything except the env directory, drop in the latest source from GitHub, refresh the dependencies, restore your config and restart the service:

cp /home/pi/FlightTracker/config.py /tmp/config.py.backup

cd /home/pi/FlightTracker
find . -maxdepth 1 -not -name 'env' -not -name '.' -exec rm -rf {} +
curl -sSL https://github.com/ColinWaddell/FlightTracker/archive/refs/heads/main.zip -o /tmp/FlightTracker.zip
unzip -q /tmp/FlightTracker.zip -d /tmp/FlightTracker-src
cp -r /tmp/FlightTracker-src/FlightTracker-release-v2/. /home/pi/FlightTracker/
source env/bin/activate
pip install -r requirements.txt
cp /tmp/config.py.backup /home/pi/FlightTracker/config.py
sudo systemctl restart FlightTracker.service

On first boot the new code will port your config.py across to a config.json automatically.

You installed the original using git clone

If you originally cloned the repository with git clone, upgrading is straightforward. Move into your existing checkout and pull down the latest changes:

cd /home/pi/FlightTracker
git fetch --all
git checkout main
git pull

If you have local modifications, the git pull may complain about conflicts. Stash your changes first, pull, then decide whether you still need them - remember a huge amount has been rewritten between v1 and v2:

cd /home/pi/FlightTracker
git stash
git checkout main
git pull

Your existing config.py sits at the top level of the checkout and won't be touched by the pull. Once the new code is in place, refresh the Python dependencies and reinstall the systemd service. On first boot your config.py will be migrated to config.json automatically.

cd /home/pi/FlightTracker
source env/bin/activate
pip install -r requirements.txt

sudo systemctl restart FlightTracker.service

If you don't have a Raspberry Pi or LED panel handy, FlightTracker can run entirely on your desktop or laptop. When the hardware display drivers (piomatter for Pi 5, rgbmatrix for Pi 3/4) aren't available, the app automatically falls back to a pygame-based simulator that renders the LED matrix in a window on your screen.

This is useful for development, testing configuration changes, or just seeing what the software looks like before you commit to building the full hardware.

Setup

You'll need Python 3.10 or newer. Clone the repo, create a virtual environment, and install the simulator dependencies:

git clone https://github.com/ColinWaddell/FlightTracker
cd FlightTracker
python3 -m venv env
source env/bin/activate
pip install -r platforms/simulator/requirements.txt

git clone https://github.com/ColinWaddell/FlightTracker
cd FlightTracker
python -m venv env
env\Scripts\activate
pip install -r platforms/simulator/requirements.txt

Running

Launch it the same way you would on a Pi:

env/bin/python3 flight-tracker.py

env\Scripts\python.exe flight-tracker.py

A pygame window opens showing the simulated LED matrix. The app runs exactly as it would on a Pi, including the web configuration interface at http://localhost:8584.

Capture keys

The simulator supports saving screenshots and video frame sequences — handy for creating the kind of capture clips you see on the home page:

• P — Save a photo to captures/
• R — Toggle video recording on/off (saves a PNG frame sequence to captures/)

Full setup details are in the simulator install guide on GitHub.