From eea6378d7633f89595489a402963f00f6e1ac52f Mon Sep 17 00:00:00 2001
From: John Wiseman <jjwiseman@gmail.com>
Date: Sat, 14 Dec 2019 00:24:00 -0800
Subject: [PATCH] Added helpful instructions.

---
 README.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 78 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index cf61b16..2e9bca3 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,87 @@
 # Advisory Circular
 
 This is a twitter bot that alerts you when any aircraft is circling.
+You can see it in action at
+[@SkyCirclesLA](https://twitter.com/SkyCirclesLA).
 
 ![Example tweet](Screen Shot 2019-12-13.png?raw=true "Example tweet")
 
 
+## 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.
+
+**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.
+
+**Get access keys for a twitter account.** Follow the [instructions at
+botwiki](https://botwiki.org/tutorials/how-to-create-a-twitter-app/).
+
+
+## Running the bot
+
+Put your adsbexchange.com API key and twitter keys in `secrets.yaml`.
+
+Create an initial history database: `echo '{}' > advisory-circular.db`
+
+Install node dependencies:
+
+`npm install`
+
+Compile the clojurescript:
+
+`npx shadow-cljs compile script`
+
+Run the bot:
+
+`node out/script.js --url https://adsbexchange.com/api/aircraft/json --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 --url https://adsbexchange.com/api/aircraft/json --lat <lat> --lon <lon> --radius <radius>
+  sleep 10
+done
+```
+
+* Do not run the script with a large radius, or adsbexchange.com will
+  ban your IP. I use a radius of 40 miles.
+
+* 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 a locality of a nearby venue.
-- [ ] Add list with custom airport coords and radii.
-- [ ] Lookup registration info. Possible sources: FAA, adsbexchange.com.
-- [ ] Use Wikipedia graph to rank landmarks?
+- [ ] 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?
+- [ ] Lookup registration info. Possible sources: FAA,
+      adsbexchange.com, janky-ass basestation.sqb's that have been
+      passed around for a decade.
+- [ ] Add type information to tweet status, e.g. "Eurocopter AS350".
+- [ ] Use Wikipedia graph to rank landmarks? More inbound links to a
+      page = 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!