Part of the Project Logs series.

On a family vacation I recently had a chance to set up a quick ad-hoc ADS-B monitoring system. I’ve written down the steps I followed, for future reference.

For this entire guide to work, you’ll need Homebrew installed on macOS, plus Python 3 and virtualenvwrapper.

Equipment

• MacBook running OS X 10.12
• FlightAware Pro Stick Plus ADS-B USB Receiver with Built-in Filter
• A cheap 1090MHz antenna
• USB-C to USB-A adapter, since I have a Touch Bar MacBook
• A baking/cookie sheet, to use as a ground plane for the antenna

Find location and altitude

Find your location on Google Maps, right-click, and select “What’s Here?” to copy your exact latitude and longitude.

Then, to find the exact elevation above sea level of my antenna, use this app.

Install and run dump1090

dump1090 is the core software in this setup; it receives radio data from the SDR and decodes ADS-B messages.

1. Run brew update and then brew install librtlsdr pkg-config
2. Choose a working directory where software will be placed. Run git clone git@github.com:mutability/dump1090.git
3. Change into the dump1090 directory and run make. You should soon have a dump1090 executable in the current directory.
4. Connect the SDR USB device to the Mac.
5. Run mkdir -p /usr/local/var/dump1090-mut-data
6. Run ./dump1090 --interactive --net --lat <YOUR LATITUDE> --lon <YOUR LONGITUDE> --modeac --mlat --write-json /usr/local/var/dump1090-mut-data
7. Confirm that planes are showing up on the terminal, and that data files have appeared in /usr/local/var/dump1090-mut-data

Configure nginx and run the dump1090 web interface

dump1090 used to have a web server built in, but it now requires an external server. I chose nginx, since I’m already familiar with it.

Run brew install nginx, then write the following config to /usr/local/etc/nginx/servers/dump1090:

# Allows access to the static files that provide the dump1090 map view,
# and also to the dynamically-generated json parts that contain aircraft
# data and are periodically written by the dump1090 daemon.

server {
    listen 8081;
    root /Users/YOUR-USERNAME/PATH-TO/dump1090/public_html;
    index gmap.html;

    location /data/ {
        alias /usr/local/var/dump1090-mut-data/;
    }
}

Run nginx to start nginx. This won’t automatically restart when the laptop reboots; this is exactly what I want for a one-off monitoring setup.

Verify that you see the dump1090 web UI when visiting http://localhost:8081 from the host MacBook.

Multilateration with ADS-B Exchange

My final step is connecting to ADS-B exchange to use multilateration to position more aircraft on the map.

1. In your working directory, git clone https://github.com/mutability/mlat-client.git
2. Change into mlat-client and create a virtualenv via mkvirtualenv mlat-client. Activate it if it isn’t automatically activated.
3. Apply my patch from mlat-client PR #17 to mlat-client (necessary if you’ve installed python3 via Homebrew)
4. Run ./setup.py install to install the client. (This seemed to touch /usr/local/bin even though I was working in a virtualenv; I’m not sure why.)

Running everything

• Run nginx with nginx
• Run dump1090 with ./dump1090 --interactive --net --lat <YOUR LATITUDE> --lon <YOUR LONGITUDE> --modeac --mlat --write-json /usr/local/var/dump1090-mut-data
• Run mlat-client with mlat-client --input-type dump1090 --input-connect localhost:30005 --lat <YOUR LATITUDE> --lon <YOUR LONGITUDE> --alt <ALT>ft --user <CHOOSE USERNAME> --server feed.adsbexchange.com:31090 --no-udp --results beast,connect,localhost:30104

To keep your MacBook from sleeping, run dump1090 via caffeinate -i as described in Quick Tip: Caffeinate your Terminal.