Set Up a Receiver

Contribute aircraft data to the tracking network. All you need is a USB radio dongle and something to plug it into.

One-Command Setup

Installs drivers, downloads the binary, configures systemd, starts the service:

curl -sL https://raw.githubusercontent.com/blueOctopusAI/adsb-decode/main/deploy/receiver-setup.sh | sudo bash

Or follow the manual steps below.

What You Need

RTL-SDR Blog V4

USB software-defined radio with 1090 MHz antenna. The standard ADS-B receiver.

~$35

Raspberry Pi 4/5

Dedicated, low-power, always-on. Plug in the dongle and forget about it. Pre-built binaries available.

~$35-80

Any Linux Box

x86_64 or ARM. An old laptop, mini PC, or NUC works great. Just needs a USB port and line-of-sight to the sky.

Whatever you have

Tip: Antenna placement matters more than hardware quality. A $35 dongle on the roof will outperform a $200 setup in a basement. Higher = farther range. Expect 100-200 nautical miles with decent antenna placement.

Manual Setup Steps

Register Your Receiver

Visit the registration page to create a receiver entry and get your API key. Each receiver gets a unique UUID for authentication and tracking.

Install RTL-SDR Drivers

The receiver needs the rtl_adsb command from the rtl-sdr package:

sudo apt install rtl-sdr

Then blacklist the DVB kernel module so it doesn't conflict:

echo 'blacklist dvb_usb_rtl28xxu' | sudo tee /etc/modprobe.d/blacklist-rtlsdr.conf
sudo modprobe -r dvb_usb_rtl28xxu

Download the Receiver Binary

Pre-built binaries for all major architectures:

# Raspberry Pi 4/5 (64-bit)
curl -sL https://github.com/blueOctopusAI/adsb-decode/releases/latest/download/adsb-receiver-aarch64-unknown-linux-gnu.tar.gz | tar xz

# Raspberry Pi 3 (32-bit)
curl -sL https://github.com/blueOctopusAI/adsb-decode/releases/latest/download/adsb-receiver-armv7-unknown-linux-gnueabihf.tar.gz | tar xz

# x86_64 Linux
curl -sL https://github.com/blueOctopusAI/adsb-decode/releases/latest/download/adsb-receiver-x86_64-unknown-linux-gnu.tar.gz | tar xz

sudo mkdir -p /opt/adsb-receiver
sudo mv adsb-receiver /opt/adsb-receiver/
sudo chmod +x /opt/adsb-receiver/adsb-receiver

Configure

Create an environment file with your settings:

sudo tee /etc/adsb-receiver.env <<EOF
ADSB_SERVER=https://adsb.blueoctopustechnology.com
ADSB_NAME=my-receiver
ADSB_API_KEY=your-api-key-from-step-1
ADSB_LAT=35.0
ADSB_LON=-83.0
EOF
sudo chmod 600 /etc/adsb-receiver.env

Start the Service

Install and enable the systemd service:

sudo tee /etc/systemd/system/adsb-receiver.service <<EOF
[Unit]
Description=adsb-decode receiver
After=network-online.target
Wants=network-online.target

[Service]
EnvironmentFile=/etc/adsb-receiver.env
ExecStart=/opt/adsb-receiver/adsb-receiver
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now adsb-receiver

Verify It Works

Check that frames are flowing:

sudo journalctl -u adsb-receiver -f

You should see lines like:

[sender] POST 200 — 12 frames (batch 47)
[capture] frame: 8D4840D6202CC371C32CE0576098
[sender] heartbeat OK — 342 captured, 298 sent, uptime 1h23m

Then check the receivers dashboard to see your station online. It shows frame count, uptime, active aircraft count, and last heartbeat time.

Quick test: You can also run the receiver directly without systemd:

/opt/adsb-receiver/adsb-receiver --server https://adsb.blueoctopustechnology.com --name test --api-key YOUR_KEY

Build from Source

If you prefer to build from source:

git clone https://github.com/blueOctopusAI/adsb-decode.git
cd adsb-decode/rust
cargo build --release -p adsb-receiver
# Binary at target/release/adsb-receiver

All Options

The receiver binary supports these flags (all also configurable via environment variables):

adsb-receiver --help

  --server <URL>      Server URL (env: ADSB_SERVER)
  --name <NAME>        Receiver name (env: ADSB_NAME)
  --api-key <KEY>      API key (env: ADSB_API_KEY)
  --lat <LAT>          Latitude (env: ADSB_LAT)
  --lon <LON>          Longitude (env: ADSB_LON)
  --interval <SECS>    Batch interval, default 2.0 (env: ADSB_INTERVAL)
  --device <N>         RTL-SDR device index, default 0 (env: ADSB_DEVICE)
  --gain <N>           RTL-SDR gain (env: ADSB_GAIN)
  --ppm <N>            PPM correction (env: ADSB_PPM)

← Back to About | Register a Receiver →