Home
Install & set up

From a blank SD card
to a working scanner.

Everything in order: flash Raspberry Pi OS onto the card, install Airwave Scan with one command, then pair your iPhone by scanning a QR code. Plan on about half an hour, most of it waiting.

00

What you need

  • Raspberry Pi 5 — 4 GB or 8 GB. A Pi 4 works too.
  • Official 27 W USB-C power supply — the Pi 5 only gives USB devices full power on a 5 A supply, and dongles drop out on weak power.
  • microSD card, 32 GB or larger — A2-rated or high-endurance; the decoders write to it around the clock.
  • A computer with an SD card reader — Mac, Windows or Linux, to flash the card and log in to the Pi.
  • An RTL-SDR dongle and antenna — an RTL-SDR Blog V4 or any RTL2832U dongle. See Hardware for more.
  • A powered USB hub — if you'll run three or more dongles.
  • Your Wi-Fi name and password — or an Ethernet cable to your router.
  • An iPhone on iOS 16 or later — on the same network as the Pi while you pair.
01

Flash the SD card

Download Raspberry Pi Imager from raspberrypi.com/software, put the SD card in your computer and open Imager. It walks you through a tab at a time; choose Next after each:

Device
Raspberry Pi 5
OS
Lite isn't at the top of the list: open Raspberry Pi OS (other), then choose Raspberry Pi OS Lite (64-bit) — "a port of Debian Trixie with no desktop environment"
Storage
Your SD card (leave Exclude system drives on)

Next comes the Customisation tab. Fill it in rather than skipping it, so the Pi joins your network and accepts logins on first boot:

Hostname
airwave — you'll reach the Pi as airwave.local
Localisation
Your capital city; it sets the time zone, keyboard and Wi-Fi country
User
A lowercase username and a password; you'll log in with them in step 2
Wi-Fi
Your network name and password (skip if you're using Ethernet)
Remote Access
Turn on Enable SSH, with password authentication (or your public key)
Raspberry Pi Connect
Not needed — leave it off

Then write the card. Imager erases it, writes the OS and checks it, which takes a few minutes. (Older versions of Imager keep the same settings behind Edit settings, offered just before writing.)

Why Lite? It has no desktop, so the Pi spends everything on radio work, and you'll do the rest from your computer over the network. If you'd rather not dig for it, Raspberry Pi OS (64-bit) at the top of the list works too; it just adds a desktop the scanner doesn't use.
02

Boot and log in

Put the card in the Pi, plug in your dongle (or the powered hub with your dongles), connect the antenna, then plug in the power. Give the first boot two or three minutes: it expands the file system and joins your Wi-Fi.

On your computer, open a terminal (Terminal on a Mac, PowerShell on Windows) and log in. Replace you with the username you chose:

ssh you@airwave.local

Type yes to trust the Pi the first time, then your password. Your prompt changes to you@airwave once you're in.

Can't find airwave.local? Look up the Pi's IP address in your router's list of connected devices and use that instead, for example ssh you@192.168.1.50.
03

Update the OS

Bring the fresh image up to date, then restart:

sudo apt update && sudo apt full-upgrade -y
sudo reboot

Wait about a minute, then log in again with the same ssh command.

04

Install Airwave Scan

One command downloads Airwave Scan and installs it with everything it depends on:

curl -fsSL https://cdn.airwavescan.com/edge/bootstrap.sh | sudo bash

It takes a few minutes. Along the way it:

  • Installs the radio tools and libraries — rtl-sdr, SoapySDR and rtl_433 — and Python.
  • Stops Linux's TV-tuner driver from grabbing your RTL-SDR, so the scanner can use it.
  • Creates a dedicated rfscanner account with USB access to the dongles.
  • Installs the Airwave Scan engine in /opt/rfscanner, with its settings in /etc/rfscanner/edge.env.
  • Starts the rfscanner-edge service now and at every boot, and caps its logs so they can't fill the card.
  • Adds the rfscanner-pair command you'll use to pair your phone.

Check that it's running:

systemctl status rfscanner-edge

Look for active (running) in green, then press q.

05

Add the decoders

Recommended

The core install listens, scans and pairs. The decoders that turn signals into aircraft on the map, ship positions, packets and weak-signal spots are built from source by a second script. Download the full package and run it:

curl -fsSL https://cdn.airwavescan.com/edge/rfscanner-edge.tar.gz | tar -xz
sudo bash edge/install/setup-pi.sh

The default set is ADS-B (aircraft on the map), ACARS and VDL2 (aircraft messages), AIS (ships), APRS, SAME weather alerts, FT8 and WSPR (HF propagation), and utility meters. The builds take a while, so let it run. It finishes by checking every piece it installed.

# everything, including DMR digital voice and JS8:
sudo bash edge/install/setup-pi.sh --all
# or just the ones you want:
sudo bash edge/install/setup-pi.sh --with adsb,ft8
# re-run the checks any time:
sudo bash edge/install/setup-pi.sh verify
06

Check the radio

Optional

A quick self-test proves the dongle, the antenna and the audio path work, with no phone needed. It tunes NOAA Weather Radio for a few seconds and prints PASS or FAIL with the signal level:

sudo systemctl stop rfscanner-edge
sudo -u rfscanner /opt/rfscanner/venv/bin/python -m rfscanner_edge.server --selftest --wav /tmp/wx.wav
sudo systemctl start rfscanner-edge

Outside the US, test with a station you can hear instead: add --freq 98100000 --mode wfm (an FM broadcast station, in Hz) to the middle command. A FAIL says what to check.

07

Get the app

Airwave Scan for iPhone is in private beta on TestFlight. Request access, then install TestFlight from the App Store and open your invite on the iPhone to install Airwave Scan.

Request beta access

08

Pair your iPhone

Pairing gives your phone the Pi's key and the Pi your phone's, so only your phone can connect. The phone and the Pi need to be on the same network.

  1. On the Pi, start pairing. It pauses the scanner and prints a QR code and passcode right in your terminal. Make the window big enough to show the whole code.
    sudo rfscanner-pair
  2. On the iPhone, open Airwave Scan, go to the Scanners tab, tap Pair a Scanner and point the camera at the QR code on your computer screen.
  3. Check that the device ID the app shows matches the one in your terminal, then tap Pair.
  4. Back on the Pi, press Ctrl-C. The scanner restarts and the app connects.
The passcode is good for about five minutes. If it runs out, run sudo rfscanner-pair again for a fresh one.
09

Set up your station

The rest happens in the app:

  • Scanners → Radios. Tap each dongle and say which antenna it's on and which bands that antenna covers, so every job lands on the right radio.
  • Scanners → Decoders. Switch on what you want and pick the radio for each. A decoder that runs all the time needs a dongle of its own.
  • Settings → Station location. If the Pi lives somewhere other than where you carry your phone, set its location so satellite passes and nearby channels are right.
  • Channels. What's on the air near the station. Tap a channel to listen.
+

In the car, SDRplay, updates

In the car. With no home Wi-Fi, the Pi can make its own Wi-Fi network for your phone to join. Run these from your home directory, where step 5 put the edge folder, over Ethernet or a keyboard and screen, because turning Wi-Fi into a hotspot drops an SSH session that's using Wi-Fi:

sudo bash edge/install/car-ap.sh install       # asks for a Wi-Fi password
sudo bash edge/install/car-ap.sh up            # try it now
sudo bash edge/install/car-ap.sh enable-boot   # keep it on after restarts

Join the Wi-Fi network named RFScanner from your iPhone and pair once more. Back home, sudo bash edge/install/car-ap.sh disable-boot returns the Pi to your home Wi-Fi.

SDRplay radios. An RSP needs SDRplay's own driver. This script installs it, along with the bridge Airwave Scan uses, and asks you to accept SDRplay's license:

sudo bash edge/install/setup-sdrplay.sh

Updating. Run the install command from step 4 again. Your settings and paired phones are kept.

Uninstalling. This keeps the Pi's identity and paired phones; add --purge to remove everything:

sudo bash edge/install/uninstall.sh
?

Troubleshooting

"Could not resolve hostname airwave.local"
Give a first boot a few minutes. If it still fails, check the Wi-Fi name and password you gave Imager, or plug in Ethernet. Your router's device list shows the Pi's IP address, which you can use instead of airwave.local.
The service isn't running
The last log lines say why: journalctl -u rfscanner-edge -n 50. After fixing the cause, start it with sudo systemctl start rfscanner-edge.
The app can't connect to the Pi
Your phone needs to be on the same network the Pi was on when you paired, and guest networks often stop devices from seeing each other. Check systemctl status rfscanner-edge on the Pi, and if in doubt pair again with sudo rfscanner-pair.
No signal, or the dongle isn't found
lsusb should list a Realtek RTL2838 device. If it doesn't, unplug the dongle and plug it back in. Use the official power supply: low voltage makes dongles drop off the USB bus.
The QR code in the terminal won't scan
Make the terminal window wider and taller, or shrink its font, so the whole code fits without wrapping. Then point the camera at it again.

These steps are for Raspberry Pi OS (64-bit), Bookworm or newer, and were tested on the current Debian 13 (Trixie) release.