ADS-B Docker Setup

This repository contains a Docker Compose setup for running an ADS-B feeder based on the SDR Enthusiasts ADS-B documentation.

Blacklist Kernel Modules (Required)

IMPORTANT: Before plugging in your RTL-SDR dongle, you must blacklist kernel modules on the host system. Otherwise, the host kernel will claim the device and prevent Docker containers from accessing it.

This step is required and only needs to be done once on the host system.

On the Host System:

1. Create the blacklist file:

   sudo tee /etc/modprobe.d/exclusions-rtl2832.conf <<EOF
   # Blacklist host from loading modules for RTL-SDRs to ensure they
   # are left available for the Docker guest.
   blacklist dvb_core
   blacklist dvb_usb_rtl2832u
   blacklist dvb_usb_rtl28xxu
   blacklist dvb_usb_v2
   blacklist r820t
   blacklist rtl2830
   blacklist rtl2832
   blacklist rtl2832_sdr
   blacklist rtl2838
   # Prevent modules from being loaded as dependencies
   install dvb_core /bin/false
   install dvb_usb_rtl2832u /bin/false
   install dvb_usb_rtl28xxu /bin/false
   install dvb_usb_v2 /bin/false
   install r820t /bin/false
   install rtl2830 /bin/false
   install rtl2832 /bin/false
   install rtl2832_sdr /bin/false
   install rtl2838 /bin/false
   EOF
   

2. Unload any currently loaded modules:

   sudo modprobe -r dvb_core dvb_usb_rtl2832u dvb_usb_rtl28xxu dvb_usb_v2 r820t rtl2830 rtl2832 rtl2832_sdr rtl2838 2>/dev/null || true
   

3. Rebuild module dependency database:

   sudo depmod -a
   

4. Update boot image (if supported):

   sudo update-initramfs -u 2>/dev/null || true
   

5. Reboot your system to ensure modules are blacklisted:

   sudo reboot
   

Note: If you're already running the companion ogn_docker stack or have used the SDR-Enthusiasts docker-install script, you may have already done this step. You can skip it if /etc/modprobe.d/exclusions-rtl2832.conf already exists.

SDR Serialization

Before setting up the containers, you need to re-serialize your RTL-SDR dongles to distinguish them. This is especially important if you're running multiple SDRs (e.g., one for ADS-B and one for OGN).

The documentation recommends using serial numbers that match the frequencies. However, to distinguish between multiple SDRs (e.g., ADS-B and FLARM/OGN), we use frequency-encoded serial numbers:

• 1090MHz (ADS-B Mode-S): Serial number 01090000 (encoding 1090.0 MHz)
• 868MHz (FLARM/OGN): Serial number 00868000 (encoding 868.0 MHz)
• 978MHz (ADS-B UAT, if used): Serial number 00978000 (encoding 978.0 MHz)

Re-serializing SDRs

1. For 1090MHz ADS-B reception:

   • Unplug all SDRs, leaving only the SDR to be used for 1090MHz reception plugged in
   • Run:

     docker run --rm -it --device /dev/bus/usb --entrypoint rtl_eeprom ghcr.io/sdr-enthusiasts/docker-adsb-ultrafeeder -s 01090000
     

   • Review the configuration and press y to confirm
   • This uses 01090000 to encode the frequency (1090.0 MHz), matching the pattern used for FLARM/OGN (00868000 for 868.0 MHz)

2. For 978MHz UAT reception (if used):

   • Unplug all SDRs, leaving only the SDR to be used for 978MHz reception plugged in
   • Run:

     docker run --rm -it --device /dev/bus/usb --entrypoint rtl_eeprom ghcr.io/sdr-enthusiasts/docker-adsb-ultrafeeder -s 00978000
     

   • Review the configuration and press y to confirm
   • This uses 00978000 to encode the frequency (978.0 MHz)

3. Unplug and replug all SDRs to make the system aware of the new serial numbers (a reboot will not accomplish this)

Note: The serial numbers used here (01090000 for ADS-B, 00868000 for FLARM/OGN) follow a frequency-encoding pattern that helps distinguish between multiple SDRs while maintaining clarity about which frequency each SDR is configured for.

Related / companion stack: OGN Docker Receiver

This ADS-B stack is designed to run alongside a companion FLARM/OGN stack:

• OGN / FLARM receiver: ogn_docker
  • Repository: LSV-Linkenheim/ogn_docker
  • Frequency / protocol: ~868 MHz, FLARM / OGN
• This repository: ADS-B ultrafeeder stack
  • Frequency / protocol: 1090 MHz (and optionally 978 MHz), ADS-B

Both stacks perform very similar roles (receiving and forwarding flight information) but for different radio bands and networks:

• ogn_docker focuses on gliders and light aircraft via the OGN/FLARM network at 868 MHz.
• This adsb_docker stack focuses on Mode-S / ADS-B aircraft at 1090 MHz (plus optional UAT at 978 MHz).

They can safely share the same host as long as each SDR has a unique, frequency-encoded serial number (for example 00868000 for OGN/FLARM and 01090000 for ADS-B), as described above.

Setup

1. Copy example.env to .env and fill in your values:

   cp example.env .env
   

2. Edit .env with your location details, UUID, and other configuration

3. Obtain OpenSky Network Serial Number (if feeding to OpenSky):

   • Register for an account at OpenSky Network
   • Add your OPENSKY_USERNAME to .env
   • Run the following command to obtain a serial number (replace values with your actual data):

     source ./.env
     timeout 60s docker run \
         --rm \
         -it \
         -e LAT=${FEEDER_LAT} \
         -e LONG=${FEEDER_LONG} \
         -e ALT=${FEEDER_ALT_M} \
         -e BEASTHOST=ultrafeeder \
         -e OPENSKY_USERNAME=${OPENSKY_USERNAME} \
         ghcr.io/sdr-enthusiasts/docker-opensky-network:latest
     

   • Note the serial number from the output and add it to .env as OPENSKY_SERIAL

4. Start the containers:

   docker compose up -d
   

Services

• ultrafeeder: Main ADS-B decoder and web interface (tar1090 map, graphs1090 statistics)
  • Feeds to: Airplanes.live
• opensky: Feeds data to OpenSky Network

Web Interfaces

• Map: http://your-host-ip:8080/
• Statistics: http://your-host-ip:8080/graphs1090/

Troubleshooting

Container won't start

• Check that .env file exists and is properly configured
• Verify SDR device is connected: lsusb | grep RTL
• Check logs: docker compose logs

"Cannot open device" errors

• Verify kernel modules are blacklisted (see Blacklist Kernel Modules section above)
• Check if host kernel claimed the device: lsmod | grep rtl2832
• Verify SDR serial number matches ADSB_SDR_SERIAL in .env
• Ensure only one SDR is connected (or use serial numbers to distinguish)
• Check USB device permissions
• Unload modules if loaded: sudo modprobe -r rtl2832 dvb_usb_rtl2832u

SDR not detected

• Verify the SDR serial number is correctly set (see SDR Serialization section)
• Check that you've unplugged and replugged the SDR after programming the serial number
• Ensure the serial number in .env matches the programmed serial number

Documentation

Based on:

• SDR Enthusiasts ADS-B Documentation
• Blacklist Kernel Modules
• Re-serialise SDRs
• Prepare the Application Environment
• Deploy ultrafeeder
• Feeding OpenSky Network