Updated README.
This commit is contained in:
John Wiseman
parent
eee2acbc5e
commit
4fc7215a02
142
README.md
142
README.md
@ -1,19 +1,55 @@
|
||||
# Advisory Circular
|
||||
|
||||
This is a twitter bot that alerts you when aircraft fly in circles.
|
||||
You can see it in action at
|
||||
[@SkyCirclesLA](https://twitter.com/SkyCirclesLA).
|
||||
This is a twitter bot that tweets when it detects aircraft flying in
|
||||
circles.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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 the following bots:
|
||||
|
||||
* [@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.
|
||||
|
||||
## Technologies used
|
||||
|
||||
This bot is written in Clojurescript, targeting Node.
|
||||
|
||||
The bot uses the adsbexchange.com API to get aircraft data in
|
||||
realtime. 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 adsbexchange.com "global radar
|
||||
view".
|
||||
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".
|
||||
|
||||
## Criteria for tweeting
|
||||
|
||||
@ -38,6 +74,9 @@ The bot will consider an aircraft to be "circling" if:
|
||||
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
|
||||
@ -48,24 +87,48 @@ 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.** 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 `los-angeles-metro`
|
||||
project.
|
||||
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
|
||||
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.
|
||||
|
||||
**Get access keys for a twitter account.** Follow the [instructions at
|
||||
**Create a twitter account and get app access keys for it.** Follow the [instructions at
|
||||
botwiki](https://botwiki.org/tutorials/how-to-create-a-twitter-app/).
|
||||
|
||||
**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 adsbexchange.com API key and twitter keys in `secrets.yaml`.
|
||||
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
|
||||
```
|
||||
|
||||
|
||||
|
||||
Create an initial history database:
|
||||
|
||||
@ -83,50 +146,15 @@ Compile the clojurescript:
|
||||
Run the bot:
|
||||
|
||||
```
|
||||
node out/script.js --adsbx-url https://adsbexchange.com/api/aircraft/json \
|
||||
--pelias-url http://my-pelias.local:4000/v1 \
|
||||
--lat <lat> --lon <lon> --radius <radius>`
|
||||
|
||||
Specify your geographical region of interest by specifying a circle at
|
||||
`<lat>`, `<lon>` with a radius of `<radius>` miles.
|
||||
|
||||
The bot will run once. The adsbexchange.com API only provides
|
||||
instantaneous positions, so the bot will have to run many times and
|
||||
collect some history before it's able to detect any circles.
|
||||
|
||||
```
|
||||
while :
|
||||
do
|
||||
node out/script.js --adsbx-url https://adsbexchange.com/api/aircraft/json --pelias-url http://my-pelias.local:4000/v1 --lat <lat> --lon <lon> --radius <radius>
|
||||
sleep 10
|
||||
done
|
||||
while :; do python intervalexec.py 10 node out/script.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.** I use a radius of 40 miles.
|
||||
ban your IP.**
|
||||
|
||||
* **Do not run the script more ofen than once every 10 seconds, or
|
||||
adsbexchange.com will ban your IP.**
|
||||
|
||||
|
||||
## To do
|
||||
|
||||
- [ ] If we don't have neighbourhood or locality (just county), try to
|
||||
use the locality of a nearby venue. E.g. "2 miles from
|
||||
Glendale."
|
||||
- [ ] Solve the issue of needing a differently sized buffer zone for
|
||||
different airports--2 miles distance from LAX is still
|
||||
practically inside the aiport. Add list with custom airport
|
||||
coords and radii? Get access to OSM polygons and compute our own
|
||||
distances?
|
||||
- [ ] Add type information to tweet status, e.g. "Eurocopter AS350".
|
||||
- [ ] Lookup registration info. Possible sources: FAA,
|
||||
adsbexchange.com, janky-ass basestation.sqb's that have been
|
||||
passed around for a decade.
|
||||
- [ ] Find a source of aircraft images we can use.
|
||||
- [ ] Use Wikipedia graph to rank landmarks? More inbound links to a
|
||||
page means it has higher significance?
|
||||
- [ ] Add support for Mastodon/ActivityPub.
|
||||
- [ ] Generate our own maps instead of using adsbx's? The adsbx map
|
||||
isn't always in sync with the data from the API.
|
||||
- [ ] Run at global scale!
|
||||
|
||||
Loading…
Reference in New Issue
Block a user