Advisory Circular

Advisory Circular is a twitter bot that posts when it detects aircraft flying in circles.

The bot uses data from the ADS-B Exchange, which is a network of amateurs who track aircraft, to monitor all the aircraft flying in a particular geographic region. When it detects a helicopter, fixed wing aircraft, blimp, or autogyro flying in circles, it will tweet a short description of the aircraft and an image of the aircraft's track on a map.


The text of the tweet includes the aircraft's registration (if known, otherwise just its ICAO code), type, speed, altitude, and transponder squawk code. It will also include the city over which the aircraft is circling, and a nearby landmark—a park, school, restaurant, or some other notable place.

The bot takes a screenshot of the aircraft as it currently appears on the ADS-B Exchange's "Global Radar View" web page.

This code currently powers 13 bots, including the following bots:

• @SkyCirclesLA, which covers the Los Angeles metro area.
• @SkyCirclesSF, the San Francisco Bay area.
• @SkyCirclesDC, for the Washington D.C. area.
• @SkyCirclesR2508, for the R-2508 airspace complex over Edwards Air Force Base.
• @SkyCirclesNTTR, for the Nevada Test and Training Range (including Groom Lake/ Area 51).

Technologies used

This bot is written in Clojurescript, targeting Node.

The bot uses the ADS-B Exchange API to get aircraft data in real time.

It uses the Pelias front-end to OpenStreetMap and WhosOnFirst data to come up with some color description of the aircraft's location.

It uses an embedded Chromium browser to take a screenshot of the aircraft on the ADS-B Exchange "global Radar View".

Criteria for tweeting

The bot will consider an aircraft to be "circling" if:

1. In the past 25 minutes, the sum of the aircraft's bearing changes (while in the air; not on the ground) is more than 1440 degrees. Port turns cancel out starboard turns and vice versa--there needs to be a net change of at least 1440 degrees in one direction.

2. The centroid of the last 3 minutes worth of positions must be more than 2.5 km away from all known airports.

3. The aircraft must, at the moment of decision, be at an altitude of 300 feet or more.

4. Once an aircraft is considered to be circling, it will be tweeted about. It won't be eligible to be considered circling/tweeted about again until it stops circling and 30 minutes pass.

Many of the specific numbers in the above criteria can be customized on a per-bot basis.

There are a lot of weird flight paths that can meet criterion #1, and I kind of like it that way. For example, see https://twitter.com/lemonodor/status/1203033917483175936 (consider whether we also want to detect something like https://twitter.com/lemonodor/status/1204550831103590400).

Prerequisites to running the bot

Set up a Pelias instance containing information for the geographical area you're interested in. Pelias is the geographic database that the bot uses to know which city aircraft are circling over and find nearby landmarks. It's also used to filter out aircraft that are circling over airports. See https://github.com/pelias/docker and if you're lucky the projects folder will have a predefined project that covers the area you want. I run one using the north-america project.

Get an API key for adsbexchange.com. See https://www.adsbexchange.com/data/. If you have a receiver and feed them data, they'll give you a key for free. Alternately, find another data source of realtime (or not) aircraft data and massage it into a form that the bot can work with.

Create a twitter account and get app access keys for it. Follow the instructions at botwiki.

Get a basestation.sqb file. basestation.sqb is a crowdsourced sqlite database file that contains registration and type information on aircraft. There is no canonical or official version of this file, unfortunately. Honestly, it's a real mess that somehow many people in the planetracking hobby are convinced is a good thing, or at least not a problem. In any case, you can try downloading a version from http://www.kinetic.co.uk/resourcesdownloads.php#4.

Running the bot

Put your ADS-B Exchange API key and twitter keys in secrets.yaml.

Create a config.yaml that looks like this:

adsbx:
  url: https://adsbexchange.com/api/aircraft/json
pelias:
  url: http://<my pelias host>:4000/v1
lat: 34.1335
lon: -118.1924
radius-km: 10
basestation-sqb: clean-basestation.sqb

Make sure you have at least Node version 10.0.0 installed, and then install the node dependencies:

npm install

Compile the clojurescript:

npx shadow-cljs compile script

Run the bot:

while :; do python intervalexec.py 10 node out/advisorycircular.js; sleep 5; done

intervalexec.py is a script that will try to run the bot script no more than once every 10 seconds.

• Do not run the script with a large radius, or adsbexchange.com will ban your IP.

• Do not run the script more often than once every 15 seconds, or adsbexchange.com will ban your IP.

• Do note that this brings up a test instance that is missing database configuration necessary for tweeting.

Development

To run a test watcher:

npx shadow-cljs watch script test

Installation

Once you're confident that you have everything set up correctly, decide what name your instance will have (e.g. "la" for Los Angeles) and run the following:

sudo ./install.sh la

This configure the proper directory tree, load up an aircraft database, install a skeletal systemd script, then configure a specific advisorycircular@la.service instance from your config.yaml and secrets.yaml.