RTL-SDR Setup Guide

RTL-SDR Setup Guide for satellite.stsgym.com

Created: March 13, 2026 Status: Pending Hardware Installation


Current Status

✅ Running Services

Service Status Port
stsgym-satellite-web Running 5006
satellite-db (PostgreSQL) Running 5432
satellite-redis Running 6379

❌ Not Installed

Component Status
RTL-SDR drivers Not installed
dump1090/readsb Not installed
wxtoimg/noaa-apt Not installed
RTL-SDR hardware Not connected

Hardware Requirements

Two RTL-SDR Dongles

  1. Dongle 1 (NOAA Weather Satellites) - 137 MHz
  2. Dongle 2 (ADS-B) - 1090 MHz

Installation Instructions

Step 1: Install RTL-SDR Drivers

# Run the setup script (requires sudo)
cd ~/stsgym-satellite/scripts
sudo ./setup_sdr.sh

# Or manually:
sudo apt update
sudo apt install rtl-sdr librtlsdr-dev sox

# Blacklist DVB-T drivers (conflict with RTL-SDR)
sudo bash -c 'cat > /etc/modprobe.d/rtl-sdr.conf << EOF
blacklist dvb_usb_rtl28xxu
blacklist rtl2832
blacklist rtl2830
EOF'

# Unload existing drivers
sudo modprobe -r dvb_usb_rtl28xxu 2>/dev/null || true
sudo modprobe -r rtl2832 2>/dev/null || true
sudo modprobe -r rtl2830 2>/dev/null || true

# Create udev rules
sudo bash -c 'cat > /etc/udev/rules.d/99-rtl-sdr.rules << EOF
# RTL-SDR dongles
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0bda", ATTRS{idProduct}=="2832", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0bda", ATTRS{idProduct}=="2838", MODE:="0666"
EOF'

sudo udevadm control --reload-rules
sudo udevadm trigger

Step 2: Install dump1090 for ADS-B

# Option A: dump1090-mutability (stable)
sudo apt install dump1090-mutability

# Option B: readsb (recommended, more modern)
# Build from source:
cd /tmp
git clone https://github.com/wiedehopf/readsb.git
cd readsb
make
sudo make install

# Create systemd service for readsb
sudo bash -c 'cat > /etc/systemd/system/readsb.service << EOF
[Unit]
Description=readsb ADS-B receiver
After=network.target

[Service]
ExecStart=/usr/local/bin/readsb --net --gain 40 --quiet
Type=simple
Restart=always
RestartSec=30

[Install]
WantedBy=multi-user.target
EOF'

sudo systemctl daemon-reload
sudo systemctl enable readsb
sudo systemctl start readsb

Step 3: Install NOAA Decoders

# wxtoimg (NOAA APT decoder)
sudo apt install wxtoimg

# Or build noaa-apt from source (open source alternative)
cd /tmp
git clone https://github.com/martinber/noaa-apt.git
cd noaa-apt
cargo build --release
sudo cp target/release/noaa-apt /usr/local/bin/

Step 4: Configure for Two Dongles

Since we need two dongles, we must assign them different serial numbers and create separate services:

# First, set unique serial numbers for each dongle
# Plug in dongle 1:
rtl_eeprom -s 'NOAA_001' -d 0

# Plug in dongle 2:
rtl_eeprom -s 'ADSB_001' -d 1

# Verify serial numbers:
rtl_eeprom -d 0 -q
rtl_eeprom -d 1 -q

Step 5: Create NOAA Recording Service

# Create systemd service for NOAA recording
sudo bash -c 'cat > /etc/systemd/system/noaa-recorder.service << EOF
[Unit]
Description=NOAA Satellite Recorder
After=network.target

[Service]
Type=simple
User=wez
WorkingDirectory=/home/wez/stsgym-satellite
ExecStart=/home/wez/stsgym-satellite/venv/bin/python -m services.noaa_recorder
Restart=always
RestartSec=60

[Install]
WantedBy=multi-user.target
EOF'

# Create ADS-B collector service
sudo bash -c 'cat > /etc/systemd/system/adsb-collector.service << EOF
[Unit]
Description=ADS-B Data Collector
After=network.target readsb.service

[Service]
Type=simple
User=wez
WorkingDirectory=/home/wez/stsgym-satellite
ExecStart=/home/wez/stsgym-satellite/venv/bin/python -m services.adsb_collector
Restart=always
RestartSec=30

[Install]
WantedBy=multi-user.target
EOF'

sudo systemctl daemon-reload

Testing Procedures

Test 1: Verify RTL-SDR Detection

# Test device detection
rtl_test -t

# Expected output:
# Found 1 device(s):
#   0:  Realtek, RTL2838UHIDIR, SN: NOAA_001 (or ADSB_001)
#
# Supported gain values (29): 0.0 0.9 1.4 2.7 ...
# [R82XX] PLL not locked!
# Sampling at 2048000 S/s.
# NO EES, NO OVERRUN

Test 2: Test NOAA Reception (Dongle 1)

# Check next NOAA pass
# First, update TLE data:
cd ~/stsgym-satellite
./scripts/download_tle.sh

# Find next NOAA pass (manual test):
# NOAA-15: 137.620 MHz
# NOAA-18: 137.9125 MHz
# NOAA-19: 137.100 MHz

# Quick test recording (60 seconds):
rtl_fm -d 0 -f 137100000 -s 55000 -g 40 -r 11025 -t 60 test_noaa.wav

# Decode test:
wxtoimg -n -e HVC test_noaa.wav test_noaa.png

# View image:
# Look for horizontal lines indicating APT signal
# If image is mostly noise, check antenna and gain

Test 3: Test ADS-B Reception (Dongle 2)

# Start readsb/dump1090 on dongle 1 (index 1 = second dongle)
readsb --device-type rtlsdr --device-index 1 --net --gain 40 --quiet

# Check JSON output:
curl http://localhost:8080/data/aircraft.json | jq .

# Expected output:
# {
#   "now": 1710352800.123,
#   "messages": 12345,
#   "aircraft": [
#     {
#       "hex": "a12345",
#       "flight": "UAL123",
#       "lat": 40.7128,
#       "lon": -74.0060,
#       "alt_baro": 35000,
#       "gs": 450.5,
#       ...
#     }
#   ]
# }

# If no aircraft, check:
# 1. Antenna connected to dongle 2
# 2. Antenna has clear sky view
# 3. Gain setting (try 40-50)

Test 4: Verify Web Interface

# Check satellite.stsgym.com API
curl http://localhost:5006/api/satellites/ | jq .

# Check ADS-B API
curl http://localhost:5006/api/aircraft/live | jq .

# Access web interface:
# https://satellite.stsgym.com

Test 5: Full Integration Test

# 1. Start all services:
sudo systemctl start readsb
sudo systemctl start adsb-collector
sudo systemctl start noaa-recorder

# 2. Check status:
sudo systemctl status readsb
sudo systemctl status adsb-collector
sudo systemctl status noaa-recorder

# 3. Monitor logs:
tail -f /var/log/syslog | grep -E 'readsb|adsb|noaa'

# 4. Check database:
cd ~/stsgym-satellite
docker exec -it satellite-db psql -U satellite -d satellite -c "SELECT COUNT(*) FROM aircraft_positions;"

# 5. View live data:
curl http://localhost:5006/api/aircraft/live | jq '.aircraft | length'

Troubleshooting

“No RTL-SDR devices found”

# Check USB connection
lsusb | grep Realtek

# Check kernel messages
dmesg | tail -20

# Re-plug device and reload drivers
sudo modprobe -r dvb_usb_rtl28xxu rtl2832
sudo modprobe rtl2832

“Device busy”

# Find process using device
lsof | grep rtl
fuser -v /dev/bus/usb/*/*

# Kill if needed
kill -9 <pid>

“PLL not locked”

# This is normal for RTL-SDR dongles
# Can usually be ignored

Poor Signal Quality

  1. Check antenna connections
  2. Move antenna away from electronics
  3. Try different gain settings:
  4. Add LNA (Low Noise Amplifier) for weak signals

No ADS-B Aircraft

  1. Verify dump1090/readsb is running:

    pgrep -a readsb
  2. Check antenna position (outdoor is best)

  3. Verify correct dongle (use -d 1 for second dongle)

  4. Check gain setting (too low = no signals, too high = noise)


Services Overview

Service Purpose Port Status
readsb ADS-B receiver 8080 ❌ Not installed
adsb-collector Store ADS-B data - ❌ Not configured
noaa-recorder Record satellite passes - ❌ Not configured
stsgym-satellite Web interface 5006 ✅ Running

File Locations

Path Purpose
/var/satellite/recordings/ NOAA audio recordings
/var/satellite/images/ Decoded satellite images
~/stsgym-satellite/scripts/ Setup and utility scripts
~/stsgym-satellite/services/ Python services
/etc/systemd/system/ Service definitions

Next Steps

  1. Connect RTL-SDR hardware to the server via USB
  2. Run setup script: sudo ./scripts/setup_sdr.sh
  3. Set serial numbers: Configure each dongle with unique ID
  4. Install dump1090/readsb: For ADS-B reception
  5. Install wxtoimg/noaa-apt: For NOAA image decoding
  6. Create systemd services: For automatic startup
  7. Test reception: Follow testing procedures above
  8. Monitor: Check web interface and database for data

References


Last updated: March 13, 2026