Skip to content

Hardware Setup

Bill of Materials

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.

1. Compute & Storage

  • Single Board Computer (SBC)
    • Orange Pi 5 Plus
  • MicroSD Card – 64GB or larger (V30, A2 rated or better)

2. Connectivity & Networking

  • M.2 Wi-Fi Card
  • Ethernet Cable – for connecting to router with internet access when setting up
  • USB Wi-Fi Adapter
    • Dual-band (2.4GHz + 5GHz)
    • Plug-and-play Linux compatibility
    • Preferably Intel chipset
    • A few examples:

3. Radio & GPS Modules

4. Power & Cabling

  • Portable Power Bank – compact, sufficient to power Orange Pi with minimum 20W output.
  • USB Power Cable – USB-A → USB-C or USB-C → USB-C (for powering Orange Pi from a power bank).
  • USB Extension Cables (x4) – 15 cm each, for SDR modules and accessories

5. Camera

  • Insta360 Camera
    • X3 and X4 models are currently supported

Minimal hardware setup

Whitebox is best with full hardware setup, but you can quickly start with just an Orange Pi, a supported Wi-Fi dongle, an Insta360 camera, and a powerbank that can run the Orange Pi for the duration of your flight. You will not have any location or traffic data, but you'll be able to view and record camera feeds, annotate the flight, or record key moments for more convenient playback.

Setting up the Orange Pi 5 Plus

  • Install the M.2 Wi-Fi card into the Orange Pi.

  • Download the OS to flash to your MicroSD card

    • Go to Orange Pi's support website
    • Navigate down and click at Downloads in the Ubuntu Image section
    • Download the Orangepi5plus_1.2.0_ubuntu_jammy_server_linux6.1.43.7z file

  • Flash the file to your MicroSD card

    • Download a tool for flashing SD cards, like Balena Etcher
    • Extract the .img file from the .7z file you downloaded from Orange Pi's website
      • If you are using an older operating system that does not support .7z files, you can download 7-Zip to extract it
    • Connect your MicroSD card to the PC
    • Run Balena Etcher and flash the previously extracted .img file to the SD card

      • If you are using Balena Etcher on Mac, you might get a message like this when the flashing finishes:

        The disk you inserted was not readable by this computer.
        This message is safe to ignore, just click Eject.

  • After the installer has written the image on the MicroSD card, put the card in your Orange Pi, connect it to USB-C power cable, and plug it to your internet router using the ethernet cable. Internet connection will be required to set up the Whitebox for the first time.

  • Either connect a screen and keyboard to your Orange 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 Orange 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 Orange Pi using:

    ssh root@192.168.1.120

    replacing 192.168.1.120 with the IP identified via nmap. The password should be orangepi by default.

Installation

This method sets up the full Whitebox system automatically on an Orange Pi 5 Plus. No additional steps are required!

curl -fsSL https://install.whitebox.aero | bash

If you wish to install a specific branch, use the branch parameter:

curl -fsSL https://install.whitebox.aero/?branch=feature/whitebox-409 | bash

After installation completes, before restarting, make sure to connect the USB Wi-Fi adapter, two SDR devices and the GPS device to the Whitebox.

After the restart, you should be able to log in as the whitebox user and connect to the whitebox Wi-Fi network.

Manual Installation (Alternative)

If you prefer not to use the automated installation script, you can set up Whitebox manually by following these steps:

Step 1: Install Prerequisites

# Update package lists
sudo apt update -y

# Install required packages
sudo apt install -y git git-lfs jq docker.io docker-compose

# Add current user to docker group (or create whitebox user - see Step 2)
sudo usermod -aG docker $USER

# Create whitebox user
sudo useradd -m -s /bin/bash -G sudo whitebox

# Set password for whitebox user
sudo passwd whitebox

# Add user to docker group
sudo usermod -aG docker whitebox

Step 3: Clone Whitebox Repository

# Clone to /whitebox directory (recommended for production)
sudo git clone https://gitlab.com/whitebox-aero/whitebox /whitebox
sudo chown -R whitebox:whitebox /whitebox

# Or clone to your home directory (for testing)
cd ~
git clone https://gitlab.com/whitebox-aero/whitebox
cd whitebox

Step 4: Configure Network Interface Naming (Orange Pi only)

This step disables predictable network interface naming, which is required for the Wi-Fi access point setup.

cd /whitebox  # or wherever you cloned the repository
sudo make setup-network

This command will:

  • Check if you're running on an Orange Pi
  • Configure network interface naming to use traditional names (eth0, wlan0)
  • Automatically handle the configuration file updates
  • Warn you that a reboot is required for changes to take effect

Step 5: Set Up udev Rules for SDR Devices

cd /whitebox  # or wherever you cloned the repository
sudo make setup-udev

This command will:

  • Download the required udev rules for Stratux/SDR devices
  • Install them to the correct location
  • Reload the udev rules automatically

Step 6: Set Up Wi-Fi Access Point (Orange Pi only)

# Install linux-wifi-hotspot
cd /tmp
git clone https://github.com/lakinduakash/linux-wifi-hotspot.git
cd linux-wifi-hotspot/src/scripts
sudo make install

# Configure access point settings
sudo sed -i \
  -e "s/^GATEWAY=.*/GATEWAY=10.42.0.1/" \
  -e "s/^WIFI_IFACE=.*/WIFI_IFACE=wlan0/" \
  -e "s/^SSID=.*/SSID=whitebox/" \
  -e "s/^PASSPHRASE=.*/PASSPHRASE=whitebox/" \
  /etc/create_ap.conf

# Enable and start the access point service
sudo systemctl enable create_ap
sudo systemctl start create_ap

# Clean up
cd ~ && rm -rf /tmp/linux-wifi-hotspot

Step 7: Create .env file

cd /whitebox  # or wherever you cloned the repository

# Create .env file and populate required variables
# Refer to .env.example for examples
cp .env.example .env

# Edit .env to set env vars as needed and save the file
nano .env

Step 8: Build & Deploy Whitebox Services

# Deploy all services
docker compose up -d

If you'd like to force all containers to be re-created even if there are no changes to apply to them, you can use --force-recreate:

docker compose up -d --force-recreate

Step 9: Post-Installation

  1. Connect Hardware: Attach the USB Wi-Fi adapter, two SDR devices, and GPS module to your device
  2. Reboot (especially if you configured network interface naming): sudo reboot
  3. Connect to Wi-Fi: Join the whitebox network (password: whitebox)
  4. Access Whitebox: Open your browser and go to http://10.42.0.1

Starting Whitebox

If you have followed the steps above, Whitebox should be running in a few moments!

You can access Whitebox at http://10.42.0.1/.