Build a Raspberry Pi Plane Tracker: ADS-B Readsb Setup & Debugging

Project Overview & Difficulty Rating

Tracking commercial aircraft from your workbench relies on ADS-B (Automatic Dependent Surveillance-Broadcast), a system where planes transmit their GPS position, altitude, and callsign at 1090 MHz. By pairing a software-defined radio (SDR) with a Raspberry Pi, you can decode these signals in real-time. This guide builds a standalone raspberry pi plane tracker that decodes local air traffic and displays the nearest aircraft on a local I2C OLED screen, while simultaneously hosting a full web-based radar map on your network.

Hardware BOM & Pin Mapping

The core of this build is the RTL-SDR Blog V4. Unlike cheaper generic clones, the V4 includes a 0.5 PPM TCXO (temperature-compensated crystal oscillator), which is critical for holding the narrow 1090 MHz frequency drift within acceptable limits during thermal changes.

GPIO Pin Mapping (Pi 40-Pin Header to OLED)

The SSD1306 operates over the I2C bus. We will use the default hardware I2C1 bus on the Raspberry Pi. Ensure your Pi's I2C interface is enabled via sudo raspi-config before wiring.

Step-by-Step Assembly & Software Setup

We are using readsb, the modern, actively maintained fork of the legacy dump1090 project. It is highly optimized for the ARM architecture and handles the 1090 MHz demodulation efficiently.

1. Flash the OS: Install Raspberry Pi OS (64-bit, Bookworm) using the Raspberry Pi Imager. Enable SSH and configure your WiFi credentials in the imager settings.
2. Update and Install Dependencies:

   sudo apt update && sudo apt upgrade -y
   sudo apt install -y git cmake build-essential libusb-1.0-0-dev libncurses5-dev pkg-config python3-pip python3-venv i2c-tools

3. Blacklist the DVB-T Kernel Driver: By default, Linux loads a TV-tuner driver that blocks the SDR. Prevent this:

   echo "blacklist dvb_usb_rtl28xxu" | sudo tee /etc/modprobe.d/blacklist-rtl.conf
   sudo update-initramfs -u

4. Install RTL-SDR Drivers & Readsb:

   sudo apt install -y rtl-sdr
   git clone https://github.com/wiedehopf/readsb.git
   cd readsb
   make RTLSDR=yes
   sudo make install

5. Set Up Python Virtual Environment: To comply with PEP 668 in Bookworm, use a venv for the OLED display script:

   python3 -m venv ~/tracker-env
   source ~/tracker-env/bin/activate
   pip3 install luma.oled requests

6. Start the Decoder: Run readsb in the background, pointing to the RTL-SDR and enabling the JSON web output:

   readsb --device-type rtlsdr --device 0 --gain -10 --net --net-bo-port 30005 --net-connector localhost,30005,beast_out --json-trace-every 1 &

The Tracking Code (Python + Error Handling)

This script polls the local readsb HTTP server (which serves aircraft.json on port 8080 by default if integrated with lighttpd, but for a raw readsb instance, we will read the local file or use a lightweight socket. For simplicity and reliability in this build, we will configure readsb to write to a JSON file, or use the requests library against a local port. Let's use the standard readsb JSON output file path for zero-config networking).

Ensure you append --write-json /run/readsb to your readsb startup command if it isn't default in your build.

import time
import json
import os
import sys
from luma.core.interface.serial import i2c
from luma.core.error import DeviceNotFoundError
from luma.oled.device import ssd1306
from PIL import ImageFont, ImageDraw, Image

# --- Configuration & Pin Definitions ---
# I2C Bus 1 uses GPIO 2 (SDA) and GPIO 3 (SCL) by default on Pi 4/5
I2C_PORT = 1
I2C_ADDRESS = 0x3C  # Standard for Adafruit SSD1306
JSON_PATH = "/run/readsb/aircraft.json"
POLL_INTERVAL = 2  # Seconds between screen updates

def initialize_display():
    """Initialize the I2C OLED display with error handling."""
    try:
        serial = i2c(port=I2C_PORT, address=I2C_ADDRESS)
        device = ssd1306(serial)
        return device
    except DeviceNotFoundError:
        print(f"FATAL: OLED not found at I2C bus {I2C_PORT}, address 0x{I2C_ADDRESS:02X}.")
        print("Check wiring and run 'sudo i2cdetect -y 1' to verify.")
        sys.exit(1)

def get_aircraft_data():
    """Read and parse the readsb JSON output."""
    if not os.path.exists(JSON_PATH):
        return None
    try:
        with open(JSON_PATH, 'r') as f:
            data = json.load(f)
            return data.get('aircraft', [])
    except (json.JSONDecodeError, IOError) as e:
        print(f"Warning: JSON read error - {e}")
        return []

def main():
    device = initialize_display()
    
    # Use default font, fallback to basic if custom fails
    try:
        font_large = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf", 14)
        font_small = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", 11)
    except IOError:
        font_large = ImageFont.load_default()
        font_small = ImageFont.load_default()

    print("Raspberry Pi Plane Tracker running. Press Ctrl+C to exit.")
    
    try:
        while True:
            aircraft_list = get_aircraft_data()
            
            # Create a blank image for drawing
            image = Image.new('1', (device.width, device.height))
            draw = ImageDraw.Draw(image)
            
            if not aircraft_list:
                draw.text((0, 0), "Scanning...", font=font_large, fill=255)
                draw.text((0, 20), "No aircraft in", font=font_small, fill=255)
                draw.text((0, 35), "range or SDR", font=font_small, fill=255)
                draw.text((0, 50), "disconnected.", font=font_small, fill=255)
            else:
                # Sort by signal strength (RSSI) or distance, showing the strongest/closest
                # readsb JSON uses 'rssi' (signal strength, higher/closer to 0 is better)
                sorted_aircraft = sorted(
                    [a for a in aircraft_list if 'rssi' in a and 'flight' in a],
                    key=lambda x: x.get('rssi', -99), 
                    reverse=True
                )
                
                draw.text((0, 0), f"Traffic: {len(aircraft_list)}", font=font_large, fill=255)
                draw.line([(0, 16), (127, 16)], fill=255)
                
                y_offset = 20
                for plane in sorted_aircraft[:3]:  # Show top 3 strongest signals
                    callsign = plane.get('flight', 'N/A').strip()
                    alt = plane.get('alt_baro', 'UNK')
                    rssi = plane.get('rssi', 0)
                    
                    draw.text((0, y_offset), f"{callsign[:8]}", font=font_small, fill=255)
                    draw.text((70, y_offset), f"{alt}ft", font=font_small, fill=255)
                    y_offset += 15
            
            device.display(image)
            time.sleep(POLL_INTERVAL)
            
    except KeyboardInterrupt:
        print("\nShutting down display...")
        device.cleanup()

if __name__ == "__main__":
    main()

Debugging Common RTL-SDR & I2C Failures

When working with RF hardware and Linux USB stacks, you will inevitably hit driver conflicts or bus errors. Here is how to diagnose the most common roadblocks.

Error: rtlsdr: No supported devices found or usb_claim_interface error -6

This exact error string means the RTL-SDR hardware is physically detected by the USB bus, but the readsb application cannot claim exclusive control of it.

The First Three Things to Check When It Fails:

1. Check for Kernel Driver Hijacking: Run dmesg | grep rtl. If you see Registered as device /dev/dvb, the Linux TV tuner driver grabbed the dongle. You missed the blacklist step in the setup. Re-run the blacklist dvb_usb_rtl28xxu command and reboot.
2. Verify USB Enumeration & Power: Run lsusb. You must see 0bda:2838 Realtek Semiconductor Corp. RTL2838 DVB-T. If it's missing, or if it appears and disappears in dmesg, your Pi's power supply is browning out under the SDR's current draw. Use an official 27W USB-C Pi power supply.
3. Check udev Permissions: If running readsb as a standard user (not root), you need udev rules. Run sudo cp rtl-sdr.rules /etc/udev/rules.d/ (from the rtl-sdr source directory) and sudo udevadm control --reload-rules.

Error: OSError: [Errno 121] Remote I/O error (Python OLED)

This occurs when the Python script attempts to write to the I2C bus, but the SSD1306 does not acknowledge (NACK) the transaction. Fix: Run sudo i2cdetect -y 1. If the grid is empty, check your SDA/SCL wiring. If you see 3c in the grid but the script still fails, your I2C baud rate is too high for the wire length. Add dtparam=i2c_baudrate=50000 to your /boot/firmware/config.txt and reboot.

Extending and Simplifying the Build

Depending on your end goal, you can strip this project down to its bare essentials or scale it into a full-fledged community radar node.

How to Simplify the Build

If you don't need a physical desk display and only want the web map, drop the OLED and the Python script entirely. Install readsb alongside lighttpd and the tar1090 web interface. This reduces CPU overhead by ~15% and eliminates all I2C dependencies. You simply access http://[pi-ip-address]:8080 from your phone or laptop to view the radar.

How to Extend the Build

• Add an LNA (Low Noise Amplifier): Insert an ADS-B specific LNA (like the RTL-SDR Blog ADS-B LNA) between the antenna and the dongle. This drops the noise figure and can increase your tracking radius from 50 miles to over 150 miles, depending on terrain.
• Feed Flight Tracking Networks: Extend the build by installing fr24feed (Flightradar24) or pfclient (PlaneFinder). By sharing your decoded Beast-format data with them on port 30005, you earn free premium enterprise accounts worth hundreds of dollars a year.
• Add MLAT (Multilateration): If you install piaware (FlightAware), your Pi will sync with other local receivers to triangulate the position of older aircraft that lack ADS-B GPS, using readsb's raw timing data.

Raspberry Pi Plane Tracker FAQs

Can I use a Raspberry Pi Zero 2 W for a plane tracker?

Yes, but with caveats. The Pi Zero 2 W has 512MB of RAM. Running readsb takes about 40MB, but the web interface (tar1090 or skyaware) compiling historical traces will quickly exhaust the remaining RAM, causing the Linux OOM (Out of Memory) killer to crash the decoder. If using a Zero 2 W, disable the web UI history features, skip the OLED Python script, and use it strictly as a headless data feeder to external networks.

How high of an antenna do I need for a raspberry pi plane tracker?

ADS-B at 1090 MHz is strictly line-of-sight. Antenna height matters vastly more than antenna gain. A basic 5.5dBi antenna mounted at 30 feet (roof peak) will outperform a high-gain 10dBi antenna mounted in an attic. For every 10 feet you raise the antenna, you gain roughly 1-2 miles of horizon visibility. Aim for at least 20 feet above ground level, clear of metal roofing and dense tree canopies.

Why does my raspberry pi plane tracker drop USB connection randomly?

Random USB drops (visible in dmesg as USB disconnect) are almost always caused by voltage ripple on the Pi's 5V rail. The RTL-SDR V4 draws spikes of current during RF sampling. If your power supply or USB cable has high resistance, the voltage dips below 4.6V, and the Pi's USB controller resets. Use a high-quality, thick-gauge USB-C cable and an official power supply. If the issue persists, plug the SDR into a powered USB 3.0 hub.

Do I need a 1090 MHz specific antenna or will a standard TV dipole work?

You must use a 1090 MHz tuned antenna. While a standard VHF/UHF TV antenna might pick up aircraft flying directly overhead (due to massive signal overpower), it will be completely deaf to planes 30+ miles away. ADS-B antennas are precisely cut to a quarter-wavelength (approx 6.9 cm per element) for 1090 MHz. Using a mismatched antenna introduces a high Standing Wave Ratio (SWR), which attenuates the micro-watt signals from distant aircraft before they even reach the SDR's front-end amplifier.