2019-12-14 05:37:19 +00:00
# Advisory Circular
2020-10-29 18:12:59 +00:00
Advisory Circular is a twitter bot that posts when it detects
2020-02-04 00:38:27 +00:00
aircraft flying in circles.
2020-02-04 00:37:29 +00:00
The bot uses data from the [ADS-B
Exchange](https://adsbexchange.com/), 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 ](https://twitter.com/SkyCirclesLA/status/1224376709048193024 ),
[fixed wing
aircraft](https://twitter.com/SkyCirclesDC/status/1223995896536240133),
[blimp ](https://twitter.com/SkyCirclesLA/status/1213310909302493184 ),
or
[autogyro ](https://twitter.com/SkyCirclesLA/status/1216464781869121536 )
flying in circles, it will tweet a short description of the aircraft
and an image of the aircraft's track on a map.
2019-12-14 07:59:13 +00:00
2019-12-14 07:59:58 +00:00
2019-12-14 07:59:13 +00:00
2020-02-04 00:37:29 +00:00
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.
2020-06-12 02:38:25 +00:00
This code currently powers [13
bots](https://twitter.com/i/lists/1263724487435890688), including the
following bots:
2020-02-04 00:37:29 +00:00
* [@SkyCirclesLA ](https://twitter.com/SkyCirclesLA ), which covers
the Los Angeles metro area.
* [@SkyCirclesSF ](https://twitter.com/SkyCirclesSF ), the San
Francisco Bay area.
* [@SkyCirclesDC ](https://twitter.com/SkyCirclesDC ), for the
Washington D.C. area.
2020-06-12 02:38:25 +00:00
* [@SkyCirclesR2508 ](https://twitter.com/SkyCirclesR2508 ), for the
R-2508 airspace complex over Edwards Air Force Base.
* [@SkyCirclesNTTR ](https://twitter.com/SkyCirclesNTTR ), for the
Nevada Test and Training Range (including Groom Lake/ Area 51).
2020-02-04 00:37:29 +00:00
## Technologies used
2019-12-14 21:48:50 +00:00
This bot is written in Clojurescript, targeting Node.
2020-02-04 00:37:29 +00:00
The bot uses the [ADS-B Exchange
API](https://www.adsbexchange.com/data/) to get aircraft data in real
time.
It uses the [Pelias ](https://pelias.io/ ) 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".
2019-12-14 07:59:13 +00:00
2019-12-14 08:42:02 +00:00
## 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
2020-06-12 02:38:25 +00:00
(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.
2019-12-14 08:42:02 +00:00
2. The centroid of the last 3 minutes worth of positions must be more
2019-12-15 01:16:44 +00:00
than 2.5 km away from all known airports.
2019-12-14 08:42:02 +00:00
2020-09-13 00:47:59 +00:00
3. The aircraft must, at the moment of decision, be at an altitude of
2019-12-14 08:42:02 +00:00
300 feet or more.
2020-09-13 00:47:59 +00:00
4. Once an aircraft is considered to be circling, it will be tweeted
2019-12-15 01:16:44 +00:00
about. It won't be eligible to be considered circling/tweeted about
again until it stops circling and 30 minutes pass.
2019-12-14 08:42:02 +00:00
2020-02-04 00:37:29 +00:00
Many of the specific numbers in the above criteria can be customized
on a per-bot basis.
2019-12-14 08:42:02 +00:00
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).
2019-12-14 08:24:00 +00:00
## Prerequisites to running the bot
**Set up a Pelias instance containing information for the geographical
2020-02-04 00:37:29 +00:00
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.
2019-12-14 08:24:00 +00:00
**Get an API key for adsbexchange.com.** See
2020-02-04 00:37:29 +00:00
https://www.adsbexchange.com/data/. If you have a receiver and feed
2019-12-14 08:24:00 +00:00
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.
2020-02-04 00:37:29 +00:00
**Create a twitter account and get app access keys for it.** Follow the [instructions at
2019-12-14 08:24:00 +00:00
botwiki](https://botwiki.org/tutorials/how-to-create-a-twitter-app/).
2020-02-04 00:37:29 +00:00
**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.
2019-12-14 08:24:00 +00:00
## Running the bot
2020-02-04 00:37:29 +00:00
Put your ADS-B Exchange API key and twitter keys in `secrets.yaml` .
Create a `config.yaml` that looks like this:
```yaml
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
```
2020-01-18 23:27:43 +00:00
Make sure you have at least Node version 10.0.0 installed, and then
install the node dependencies:
2019-12-14 08:24:00 +00:00
`npm install`
Compile the clojurescript:
`npx shadow-cljs compile script`
Run the bot:
2019-12-18 22:14:55 +00:00
```
2020-05-03 23:22:08 +00:00
while :; do python intervalexec.py 10 node out/advisorycircular.js; sleep 5; done
2020-02-04 00:37:29 +00:00
```
2019-12-14 08:24:00 +00:00
2020-02-04 00:37:29 +00:00
`intervalexec.py` is a script that will try to run the bot script no
more than once every 10 seconds.
2019-12-14 08:24:00 +00:00
2019-12-14 08:28:27 +00:00
* **Do not run the script with a large radius, or adsbexchange.com will
2020-02-04 00:37:29 +00:00
ban your IP.**
2019-12-14 08:24:00 +00:00
2020-06-12 02:38:25 +00:00
* **Do not run the script more often than once every 15 seconds, or
2019-12-14 08:28:27 +00:00
adsbexchange.com will ban your IP.**
2020-04-04 23:32:33 +00:00
2020-09-13 00:47:59 +00:00
* **Do note that this brings up a test instance that is missing database
configuration necessary for tweeting.**
2020-04-04 23:32:33 +00:00
## Development
To run a test watcher:
```
npx shadow-cljs watch script test
```
2020-09-13 00:47:59 +00:00
## 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.
