Skip to content

Home

Whitebox logo

Description

Whitebox is a flight recording and sharing system for small airplanes, enhancing the flight experience by allowing pilots and passengers to record, review, and share flight data, communications, and media. It can also be used to review training flights during debrief, taking care of synchronizing and uploading the flight data to the cloud.

It's an open source counterpart to the black boxes airplanes have to record all information about a flight.

Documentation is available in docs.whitebox.aero.

Certification

It is an uncertified system which is not directly connected to the airplane systems, much like a tablet running Foreflight or SkyDemon. It can thus be brought in with you in any general aviation airplane. Being also open source, it can be freely accessed and modified.

Technical description

Whitebox is a small computer which you bring with you in the cockpit during flight, and connect to various additional recording devices, such as a 360 camera or the passengers phones.

It can be accessed by the pilot and the passengers, from tablets or phones over wifi (or your desktop computer after the flight), using the devices' browser.

Roadmap

Features being considered (TBD):

  • Video recording and playback:
    • 360 camera external view
    • Cockpit interior cameras views
    • Control the 360 camera orientation during the flight
    • Passenger phone recordings synchronization (photos/videos), tagged to specific flight times/locations
    • Automatically generate a video to share, showing the highlights of the flight (tagged during the flight)
  • Automatic recording and transcription of radio and in-cockpit communications
  • GPS position tracking and 3D route visualization (like/via FlySto)
  • Note-taking for in-flight observations (instructions, comments, remarks by passengers)
  • Automated synchronization of data to the cloud - bring the Whitebox within reach of a wifi connection and it will happen automatically
  • Community contribution platform (public/forum/wiki) for sharing flight experiences:
    • A page dedicated to each flight, with access permission management
    • Link and embed flight recordings in external platforms (e.g., YouTube), including deep-linking to a specific section of the flight
  • Pre-flight briefing and post-flight debriefing
    • Review critical phases of flights
    • Integration with external data sources (OpenFlightMaps, Flypedia) for airport and flight procedure information sharing: use data to share and discover information about airports, flight procedures and practices, radio recordings...

System Overview

Whitebox is built on Django Channels, providing real-time communication capabilities. The system features:

  • A web interface for flight tracking and recording
  • Plugin system for extensibility
  • Standard API for plugins to interact with the system
  • Event-driven architecture
  • Real-time communication between clients, server, and plugins
  • Database for persistent storage
  • Docker support for easy deployment

Frontend is built mobile-first, so you can conveniently use it on your phone or tablet, even in the cockpit. It's built in React, with Tailwind CSS.

Prerequisites

  • git (for cloning the repository)
  • Git LFS (for downloading asset files when cloning the repository)
  • Docker (for running with Docker)

Prerequisites Installation

Docker

The easiest way to run or develop Whitebox is by using Docker. It sets up the whole environment for you, including the database, backend, and frontend.

Check whether Docker is installed by running:

docker --version

If not, you can install it using official convenience script like so:

curl -L https://get.docker.com/ -o docker-install.sh
chmod +x docker-install.sh
sudo ./docker-install.sh
sudo usermod -aG docker whitebox

replacing whitebox with the user you will be running docker commands from.

Git LFS

This repository uses Git LFS to store the asset files. If you do not have it installed, the repository will clone successfully, but the asset files will not be downloaded and the frontend will look broken.

To check whether Git LFS is installed, run:

git lfs --version

If it isn't, installation instructions are available for various distributions and operating systems.

On Ubuntu, it's as simple as running:

sudo apt install git-lfs

For other distributions and operating systems, you can check out the installation instructions.

Installation and Usage

Ensure that you have the all the prerequisites installed before proceeding.

All official Whitebox plugins are included in the repository. Hence, no extra steps are required to install them.

Optional Instructions - Full Hardware Setup

If you are just setting up the project on your laptop to test it, you can skip this section.

Following is the recommended hardware list for the full Whitebox setup. Direct links to the products are provided for convenience, we do not endorse any specific sellers.

  • 1x Single Board Computer (SBC)
    • Raspberry Pi 3
    • Raspberry Pi 4
    • Raspberry Pi 5
  • 1x microSD card
  • 1x Ethernet cable (to connect to a router with internet access)
  • 2x Software-Defined Radio (SDR) devices
  • 1x GPS device
  • 1x Antenna (if the GPS device does not come with one)

  • Make a fresh install of Raspberry OS using Raspberry Pi Imager with a blank/erasable microSD card

  • During the installation, when the wizard asks you if you would like to "apply OS customization settings", click "Edit Settings". Check and set:

  • General tab:

    • Set hostname: whitebox.local
    • Set username and password: whitebox/whitebox
    • Configure wireless LAN: no
  • Services:
    • Enable SSH & Use password authentication

  • Then click "Save" -> "Yes"

  • After the installer has written the image on the microSD card, put the card in your Raspberry Pi, reboot it, and plug it to your internet router using the ethernet cable. Internet connection is required to setup the Whitebox, and we need to leave the Raspberry wifi available to setup a hotspot for direct connection.

  • Either connect a screen and keyboard to your Raspberry Pi, or find its IP to access it from another computer using the following command, which will list all the IPs open for connection on the SSH server port, which should include your Raspberry Pi:

sudo nmap -p 22 --open 192.168.1.0/24

replacing 192.168.1.0/24 with your local network IP range. You can SSH into your Raspberry Pi using:

ssh whitebox@192.168.1.120

replacing 192.168.1.120 with the IP identified via nmap. The password should be the one you have set during the microSD card imaging (whitebox).

  • Clone the repository:
git clone https://gitlab.com/whitebox-aero/whitebox.git

Run access point setup script to create a wifi network for the Whitebox:

cd whitebox
sudo make setup-wifi

This will create a wifi hotspot named whitebox, and reboot the Raspberry automatically to apply the changes.

Raspberry Pi 3+ might require the following additional steps for access point to work properly:

COUNTRY=$(curl -s ipinfo.io/json | jq -r .country)
sudo raspi-config nonint do_wifi_country ${COUNTRY}

  • Connect to the whitebox wifi network, using the default password 12345678

  • Reconnect to the Raspberry Pi using SSH - this time using the IP address of the Raspberry Pi from its wifi hotspot network, which will be:

ssh whitebox@10.42.0.1
cd whitebox

Now, run udev rules setup script to allow Whitebox to access USB devices:

sudo make setup-udev

Connect the two SDR devices and the GPS device to the Whitebox. Now, all that is left is to run the docker-compose file.

Starting Whitebox

Now, all that is left is to run the docker-compose file. Run the following command to start the Whitebox:

docker compose up -d

Once the containers are built and started, you should be able to connect to the whitebox wifi network.

Now, you can access the Whitebox frontend on http://localhost:80 or with the full hardware setup on Raspberry Pi, at http://10.42.0.1/.

Additionally, backend is available on http://localhost:8000 for the local setup, or http://10.42.0.1:8000 with the full hardware setup on Raspberry Pi.

Plugins

Official Whitebox plugins are available on PyPI.

To develop your own plugins for Whitebox, you can refer to the Plugin Guide.

Support

If you find an issue with the software, please open a bug report ticket, or write to support@whitebox.aero.

You can also come:

Contributing

To contribute, feel free to open a merge request, or reach out to contact@whitebox.aero.

License

The project is released under the AGPLv3.

Acknowledgements

This project is tested with BrowserStack.