HowTo:Display Aircraft and Ships

Displaying Real-Time Aircraft or Ship Locations

An RTL SDR USB dongle can be had for about $25 U.S.. They can receive signals from roughly 24 MHz to 1.77 GHz depending on the model. Much preferred: Models with TCXO (temperature compensated oscillators). TCXO versions require less calibration to arrive at the correct frequency. With one or more of these devices plugged into your computer and connected to suitable antennas you can receive all sorts of analog or digital transmissions, however each signal must fit within a 2.4 or 2.5 MHz bandwidth (most signals do).

An aside: If you acquire a non-TCXO version of the RTL-SDR you should calibrate it against a cell-phone tower, which you can do using a variety of software. I calibrated my TCXO versions as well, then affixed a label with the PPM offset to them so I know what to enter as a parameter to adjust the final frequency when I use them with various pieces of software. Do a search for "rtl sdr calibrate" to find methods and software for calibrating them.

Back to airplanes and ships:

Information on additional software to download/compile plus how to use each script is listed in the comments at the top of each script listed below:

"xastir/scripts/ads-b.pl" is used to receive real-time aircraft positions.

"xastir/scripts/ais.pl" is used to receive real-time ship positions.

To receive ALL aircraft and ship protocols and frequencies you'll need two dongles for ADS-B and two for AIS. I haven't heard much on the 978 MHz ADS-B frequency so one dongle seems adequate for planes. If you're near a coast or a large lake and have good external antennas (plus perhaps amplifiers/filters) it _may_ be useful to have two dongles for AIS (ships): This lets you receive all four AIS frequencies including the long-distance ones. Each dongle set to AIS will receive/decode two frequencies at once.

For practical use one dongle each for ADS-B and AIS should get most of the aircraft and ship traffic displayed on your screen.

Simplest explanation:

• "dump1090", "dump978", or "rtl_ais" programs control the dongles, receiving and decoding the transmissions.
• "ads-b.pl" and "ais.pl" scripts connect to the above programs, convert the data to APRS packets, and inject them into Xastir as UDP packets.
• Xastir receives APRS packets via its UDP server port and displays them in real-time.

Initial Setup

• You may need to blacklist a kernel module before you can use the RTL dongles on Linux. They may default to the setup for receiving digital TV without doing this. You only need to do this once as your Linux box will continue to blacklist the dbv_usb_rtl28xxu driver after running this command only once. Reboot the machine after doing this command to assure it takes effect:

 blacklist dvb_usb_rtl28xxu

If the blacklist command doesn't work you can add the line above to a file like "/etc/modprobe.d/50-blacklist.conf" or similar. That filename works on SUSE linux anyway. Do a search for your particular flavor of Linux for blacklisting drivers on your system.

• Enable "Interface"->"Enable Server Ports" in Xastir. This enables Xastir server port 2023 for TCP/IP and UDP protocols.

• Tweak your firewall to allow traffic on localhost port 2023 using UDP protocol. This is where the scripts will inject aircraft and ship packets into Xastir.

• Download/Compile/Install the "rtl-sdr" package (open-source). Install the "rtl-sdr.rules" file in "/etc/udev/rules.d/" and run "udevadm control --reload-rules" (or reboot the machine) before trying to use the RTL-SDR. If not rebooting make sure to unplug/re-plug the dongle -after- you install the "rtl-sdr.rules" file.

 mkdir ~/src
 cd ~/src
 git clone git://git.osmocom.org/rtl-sdr.git
 cd rtl-sdr
 mkdir build
 cd build
 sudo apt-get install cmake             # Needed for Rpi
 sudo apt-get install libusb-1.0-0-dev  # Needed for Rpi
 cmake ../
 make
 sudo make install
 sudo ldconfig
 cd ..
 sudo cp rtl-sdr.rules /etc/udev/rules.d/.

Steps To Receive Aircraft Positions (ADS-B)

• Download & compile the dump1090 version listed in the comments inside the ads-b.pl script. Install any additional packages required as listed in the script or as determined by attempting compiling.

 cd ~src
 git clone https://github.com/flightaware/dump1090
 cd dump1090
 sudo apt-get install libbladerf-dev    # Needed for Rpi
 make

• Plug in your RTL SDR dongle(s), attached to suitable antennas.

• Start up dump1090 with appropriate parameters. Example using dongle #0:

 ./dump1090 --interactive --ppm -1.4 --gain -10  --net --net-sbs-port 30003 --phase-enhance --oversample --fix --device-index 0

• Start up ads-b.pl with appropriate parameters:

 xastir/scripts/ads-b.pl planes <passcode>

Will connect to "dump1090" and "xastir" to display planes. Determine the passcode for the callsign "planes" in the usual manner.

Screenshots: ADS-B (Aircraft)

Click in twice to get the original detail, back-arrow twice in the browser to get back.

ADS-B (Aircraft) doing a survey

ADS-B (Aircraft) doing some picture-taking

Steps To Receive Ship Positions (AIS)

• Download & compile the aisdecoder version listed inside the ais.pl script. Install any additional packages required as listed in the script or as determined by attempting compiling.

• Plug in your RTL SDR dongle(s), attached to suitable antennas.

• Start up rtl_ais with appropriate parameters. Example using dongle #1 for the standard set of two AIS frequencies:

 ./rtl_ais -h 127.0.0.1 -P 10110 -d 1 -l 161.975M -r 162.025M -n -p -2

-or- for the long-range set of two AIS frequencies:

 ./rtl_ais -h 127.0.0.1 -P 10110 -d 1 -l 156.775M -r 156.825M -n -p -2

• Start up ais.pl with appropriate parameters.

 xastir/scripts/ais.pl boats <passcode>

Will connect to "rtl_ais" and "xastir" to display ships. Determine the passcode for the callsign "boats" in the usual manner.

Screenshots: AIS (Ships)

N7IPB's configuration

Ken runs multiple dongles to receive aircraft on the primary ADS-B frequency, plus ships on the short-range -and- long-range frequencies for AIS.

Dongle #0, set up to receive aircraft on the primary ADS-B frequency & protocol:

 ./dump1090 --interactive --ppm -1.4 --gain -10  --net --net-sbs-port 30003 --phase-enhance --oversample --fix --device-index 0  # Planes

Dongles #1 and #2, set up to receive ships on all FOUR AIS frequencies:

 ./rtl_ais -h 127.0.0.1 -P 10110 -d 1 -l 161.975M -r 162.025M -n -p -1.5   # Short-range ships
 ./rtl_ais -h 127.0.0.1 -P 10110 -d 2 -l 156.775M -r 156.825M -n -p -1.5   # Long-range ships

N7IPB's multiple-dongle setup for ADS-B and AIS

Alternate ADS-B Frequency / Protocol

There's an alternate frequency & protocol for planes using the dump978 program. It requires another dongle and for dump1090 to be running before you start dump978. Fetch the dump978 code like this:

 git clone https://github.com/mutability/dump978

Run it like this:

 ./rtl_sdr -f 978000000 -s 2083334 -g 0 -d 1 - | ./dump978 | ./uat2esnt | nc -q1 localhost 30001

Scripting

Put each command into a script to automate the startup once you get your particular configuration working and debugged. Modify the below to fit your paths, dongle numbers, and passcodes. Install the "netcat" package if you intend to use the dump978 program. This script can start from 1 to four RTL-SDR dongles and start Xastir too if you wish:

 #!/usr/bin/perl -W
 
 # Enable various functions below.
 $enable_planes          = 1;  # Requires 1 SDR dongle
 $enable_plane_logging   = 0;  # Can fill up hard drive!
 $enable_plane_alternate = 0;  # Must also set $enable_planes. Requires a 2nd SDR dongle
 $enable_ships           = 0;  # Requires 1 SDR dongle
 $enable_ship_long_range = 0;  # Requires 1 SDR dongle
 $start_xastir           = 0;
 
 # Set RTL-SDR device numbers below (Starts at device 0).
 # You'll need a separate RTL-SDR dongle for each one you wish to use.
 $plane1090_SDR       = 0;  # Used with "enable_planes" above
 $plane978_SDR        = 1;  # Used with "enable_plane_alternate" above
 $ship_SDR            = 2;  # Used with "enable_ships" above
 $ship_long_range_SDR = 3;  # Used with "enable_ship_long_range" above
 
 $passcode_for_planes = 0; #  Enter passcode here for "planes"
 $passcode_for_boats  = 0; #  Enter passcode here for "boats"
 
 # Paths to executables. Set these properly for your system.
 $XTERM    = "/usr/bin/xterm";
 $DUMP1090 = "~/src/dump1090/mutability/dump1090";
 $ADSBPL   = "/usr/local/share/xastir/scripts/ads-b.pl";
 $RTLSDR   = "/usr/local/bin/rtl_sdr";
 $DUMP978  = "~/src/dump978/dump978";
 $UAT2ESNT = "~/src/dump978/uat2esnt";
 $NC       = "/usr/bin/nc";
 $XASTIR   = "/usr/local/bin/xastir";
 $RTLAIS   = "~/src/rtl-ais/rtl-ais/rtl_ais";
 $AISPL    = "/usr/local/share/xastir/scripts/ais.pl";
 
 if ($enable_planes == 1) {
   # SDR on main ADS-B frequency/protocol of 1.09 GHz:
   system("$XTERM -T ADS-B -e $DUMP1090 --interactive --net --interactive-ttl 86400 --net-sbs-port 30003 --phase-enhance --oversample --fix --ppm -1.2 --gain -10 --device-index $plane1090_SDR &");
   
   if ($enable_plane_alternate == 1) {
     sleep(1); # Give time to start dump1090 before dump978 connects to it
     
     # SDR on alternate ADS-B frequency of 978 MHz (and alternate ADS-B protocol):
     system("$XTERM -T ADS-B-Alternate -e $RTLSDR -f 978000000 -s 2083334 -g 0 -d $plane978_SDR - | $DUMP978 | $UAT2ESNT | $NC -q1 localhost 30001 &");
   }
   
   sleep(1); # Give time to start programs before Perl script connects
   
   if ($enable_plane_logging) {
     system("$XTERM -T ads-b.pl -e $ADSBPL planes $passcode_for_planes --logging &");
   }
   else {
     system("$XTERM -T ads-b.pl -e $ADSBPL planes $passcode_for_planes &");
   }
 }
 
 if ( ($enable_ships == 1) || ($enable_ship_long_range == 1) ) {
   
   if ($enable_ships == 1) {
     # SDR receiving the two normal AIS frequencies:
     system("$XTERM -T AIS -e $RTLAIS -h 127.0.0.1 -P 10110 -d $ship_SDR -l 161.975M -r 162.025M -n -p -2 &");
   }
   
   if ($enable_ship_long_range == 1) {
     # SDR receiving the two long-range AIS frequencies:
     system("$XTERM -T AISLongRange -e $RTLAIS -h 127.0.0.1 -P 10110 -d $ship_long_range_SDR -l 156.775M -r 156.825M -n -p -2 &");
   }
   
   sleep(1); # Give time to start rtl_ais before Perl script connects
   
   system("$XTERM -T ais.pl -e $AISPL boats $passcode_for_boats &");
 }
 
 if ($start_xastir == 1) {
   system("$XASTIR &");
 }

Screenshot: ADS-B (Aircraft) and AIS (Ships) combined

Other Uses for the RTL-SDR Dongles

• Use SDR programs like "GQRX" (and others) to use RTL-SDR's as general-purpose receivers. There are additional gadgets you can buy to be able to use them for receiving HF frequencies (lower frequencies than the RTL-SDR's were designed to use).

• One SDR can receive eight AM or eight FM analog voice channels at once and push eight MPEG audio streams up to an Icecast server using "RTLSDR-Airband". There's a patch available for "rtl_fm" to send samples of 0 when the radio is squelched if you need to keep an audio stream alive to send to Icecast or similar ("RTLSDR-Airband" has that feature included). Curt and Ken have implemented this successfully to make audio streams of VHF radio frequencies accessible on mobile devices.

• Use an SDR as a scanner via "rtl_fm" from the "rtl-sdr" package.

• Setting Deviation using RTL-SDR. A procedure Curt and Ken came up with which allows setting deviation on packet rigs using the RTL-SDR as the test equipment, a computer, and a TNC in calibrate mode to generate the tones.

Have fun!