{"id":21332016,"url":"https://github.com/quantumbagel/pyaerial","last_synced_at":"2026-01-04T21:31:47.020Z","repository":{"id":227757019,"uuid":"752678112","full_name":"quantumbagel/PyAerial","owner":"quantumbagel","description":"PyAerial is scanning software for ADS-B in pure Python.","archived":false,"fork":false,"pushed_at":"2024-09-12T17:10:00.000Z","size":24182,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-09-13T06:21:41.196Z","etag":null,"topics":["ads-b","adsb","internship-project","kafka-producer","mongo","mongodb","plane-tracking","pymongo","python","python3","quantumbagel","requests-python","rtl-sdr","rtlsdr"],"latest_commit_sha":null,"homepage":"https://quantumbagel.github.io/PyAerial","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/quantumbagel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-04T14:03:42.000Z","updated_at":"2024-09-12T17:10:03.000Z","dependencies_parsed_at":"2024-05-02T16:42:44.568Z","dependency_job_id":"42fec134-8428-46a2-96a2-9815bfbe953e","html_url":"https://github.com/quantumbagel/PyAerial","commit_stats":null,"previous_names":["quantumbagel/pyaerial"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantumbagel%2FPyAerial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantumbagel%2FPyAerial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantumbagel%2FPyAerial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantumbagel%2FPyAerial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quantumbagel","download_url":"https://codeload.github.com/quantumbagel/PyAerial/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225814896,"owners_count":17528295,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ads-b","adsb","internship-project","kafka-producer","mongo","mongodb","plane-tracking","pymongo","python","python3","quantumbagel","requests-python","rtl-sdr","rtlsdr"],"created_at":"2024-11-21T22:45:42.490Z","updated_at":"2026-01-04T21:31:46.972Z","avatar_url":"https://github.com/quantumbagel.png","language":"Python","readme":"# PyAerial\n\n_scanning software for ADS-B / ModeS\na.k.a. airstrik 2.0_\n\n\n## Project Concept\n\nPyAerial is the successor to [the now archived airstrik.py](https://github.com/quantumbagel/airstrik.py). It has achieved full feature parity with its predecessor while also offering much more freedom for use cases.\n\nPyAerial will scan for nearby planes using the ModeS/ADS-B protocol and provide an early-warning system for planes / helicopters that enter user-defined geofences, as well as programmable actions for the program to take (e.g. sending a POST request with data about the event or communicating with a Kafka server)\n\n### Features\n\n- Can handle ADS-B messages for altitude, position, airborne/landing velocities, callsign/geodesic, and more! See Junzi Sun's [book \"The 1090 Megahertz Riddle\" for more information.](https://mode-s.org/decode)\n- [OpenSky Network](https://opensky-network.org/) integration for more information about plane ownership\n- Smart ETA position calculations\n- Alerts via Kafka that contain relevant information about the airplane (see example)\n- MongoDB support / modular saving framework if other databases are needed\n- Extremely versatile configuration with many different options for every possible use case\n\n\n## Formatting\n### Configuration file example\n```\ngeneral:\n mongodb: mongodb://localhost:27017\n backdate_packets: 10\n remember_planes: 30\n packet_method: dump1090\n status_message_top_planes: 5\n advanced_status: true\n hz: 2\n logs: info # debug, info, warning, or error\n\nhome:\n latitude: 36.6810752\n longitude: -78.8758528\n\ncomponents: # TODO: components\n easy:\n eta:\n maximum: 120\n altitude:\n maximum: 10000\n\nzones:\n main: # smaller area randomly picked out for testing\n coordinates:\n [[35.753821, -78.909304],\n [35.755597, -78.904969],\n [35.756642, -78.898232],\n [35.755214, -78.892738],\n [35.753333, -78.888490],\n [35.749293, -78.889606],\n [35.747343, -78.891494],\n [35.746507, -78.895742],\n [35.747482, -78.900806],\n [35.748910, -78.906085],\n [35.751348, -78.910205]]\n levels:\n warn:\n category: really_high_priority\n requirements: easy\n seconds: 60\n alert:\n category: really_high_priority\n requirements: easy\n seconds: 60\n\n alternate: # Most of raleigh area\n coordinates:\n [[36.279595, -79.349321],\n [35.943933, -79.534100],\n [35.560548, -79.501141],\n [35.058494, -79.138592],\n [35.049501, -78.776043],\n [35.184300, -78.248700],\n [35.435327, -78.017987],\n [35.801494, -77.963055],\n [36.112746, -77.974041],\n [36.254624, -78.226727],\n [36.334318, -78.666180],\n [36.325467, -78.929852],\n [36.343168, -79.259442]]\n levels:\n not_inline_test:\n category: warn\n requirements: easy\n seconds: 60\n inline_test:\n category:\n method: print\n save:\n telemetry_method: all\n calculated_method: all\n requirements: easy\n seconds: 60\n\ncategories:\n really_high_priority:\n method: print\n save:\n telemetry_method: all\n calculated_method: all\n warn:\n method: print\n save:\n telemetry_method: all\n calculated_method: all\n alert:\n method: print\n save:\n telemetry_method: all\n calculated_method: all\n\n```\n\nAll names for anything can be customized in the `constants.py` file.\n\n\n\n### Alert packet example\n```\n{'icao': 'AD61DE',\n 'callsign': 'SWA1693',\n 'type': 'warn', \n 'payload':\n {'altitude': 617.22,\n 'latitude': 35.767181396484375,\n 'longitude': -78.92131805419922},\n 'zone': 'main',\n 'eta': 52} # This plane didn't have OpenSky integration, which is inside the 'opensky' key.\n```\n\n## Configuration Options\n\n| Configuration Option | What does it control? | constants.py variable |\n|------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------|\n| `general` | Contains options relative to the entire program's scope that didn't fit anywhere else. | `CONFIG_GENERAL` |\n| `general/mongodb` | The URI of the MongoDB instance to connect to if MongoDB is set as the method to save packets | `CONFIG_GENERAL_MONGODB` |\n| `general/backdate_packets` | How many latitude/longitude packets back we look to perform a rough average when we calculate the heading. More = less variance, less = more variance. | `CONFIG_GENERAL_BACKDATE` |\n| `general/remember_planes` | How many seconds since the last packet we should keep the plane in RAM before saving it to MongoDB | `CONFIG_GENERAL_REMEMBER` |\n| `general/point_accuracy_threshold` | The degree accuracy used for determining if we should \"chase\" geofences. This is just an optimization. | `CONFIG_GENERAL_PAT` |\n| `general/packet_method` | How the program should gather packets. Options: `dump1090` or `python`. Dump1090 is significantly better, but requires `dump1090 --raw --net` to be running in another terminal. | `CONFIG_GENERAL_PACKET_METHOD` |\n| `general/status_message_top_planes` | How many of the \"top planes\" (most messages sent) to display in the status message sent every tick at the INFO logging level. | `CONFIG_GENERAL_TOP_PLANES` |\n| `general/advanced_status` | Whether \"advanced status\" should be used. THis contains more data, with callsigns and packet type breakdowns. Example: `INFO:Main:Tracking 5 planes. Top 5: AB5DE1/WUP31 (358, {5: 50, 3: 51, 0: 253, 1: 4}), A3965C/FFT3373 (216, {0: 115, 5: 50, 3: 46, 1: 5}), A95A1C/AAL2349 (177, {0: 143, 3: 19, 5: 14, 1: 1}), A80D40/JBU2929 (21, {0: 13, 5: 3, 3: 4, 1: 1})` | `CONFIG_GENERAL_ADVANCED_STATUS` |\n| `general/hz` | How many ticks per second to attempt. This is a maximum, not a minimum. | `CONFIG_GENERAL_HZ` |\n| `home` | Contains the position of the ADS-B tracker. This is used to calculate globally accurate positions from the ADS-B packets. | `CONFIG_HOME` |\n| `home/latitude` | The latitude of the ADS-B tracker | `CONFIG_HOME_LATITUDE` |\n| `home/longitude` | The longitude of the ADS-B tracker | `CONFIG_HOME_LONGITUDE` |\n| `zones` | Contains information about the geofences and their different warning levels | `CONFIG_ZONES` |\n| `zones/[zone]/coordinates` | A list of lists containing the decimal lat/long coordinates that compose the geofence. | `CONFIG_ZONES_COORDINATES` |\n| `zones/[zone]/levels` | Contains information about the levels of triggers the geofence has. | `CONFIG_ZONES_LEVELS` |\n| `zones/[zone]/levels/[level]/category` | The category (information about how to save and alert) that this level of the geofence is tied to | `CONFIG_ZONES_LEVELS_CATEGORY` |\n| `zones/[zone]/levels/[level]/time` | The maximum ETA the plane must have relative to the geofence to trigger this level. | `CONFIG_ZONES_LEVELS_TIME` |\n| `categories` | Stores the categories (information for how alerts and saving works). Categories will only be used if they are put in at least one geofence | `CONFIG_CATEGORIES` |\n| `categories/[category]/method` | Which method to use when alerting. Current options: `print`, `kafka` | `CONFIG_CAT_METHOD` |\n| `categories[category]/arguments` | If applicable, put arguments for the method in here. The only option is `server` for the `kafka` method currently. | `CONFIG_CAT_ALERT_ARGUMENTS` |\n| `categories/[category]/save` | Filters for saving to MongoDB. Existing methods: `all`, `none`, `decimate(X)`, `sdecimate(X,Y)` | `CONFIG_CAT_SAVE` |\n| `categories/[category]/save/telemetry_method` | What method to use for the telemetry data (stuff received by the ADS-B receiver with no inference). | `CONFIG_CAT_SAVE_TELEMETRY_METHOD` |\n| `categories/[category]/save/calculated_method` | What method to use for the calculated data (stuff we inferred from the ADS-B information, including corrected versions of telemetry data we already receive). | `CONFIG_CAT_SAVE_CALCULATED_METHOD` |\n\n\n## Dependencies\n\n```\nshapely # Other geographic math.\ngeopy # Some geographic math, mostly distance.\npymodes # some ADS-B decoding hex math\nrequests # hexdb.io's ICAO callsign API\npyrtlsdr # Pure-python ADS-B decoder\nkafka-python # Using the Kafka alert method\npymongo # Interfacing with MongoDB\nruamel.yaml # For reading the configuration file\n```\n\n`dump1090-fa` is required for the `dump1090` packet method to function. The command `dump1090 --net --raw` should work out-of-the-box. You can also broadcast raw ADSB messages over TCP port `30002` and the interface will also work.\n\n## TODOS\n\n- [ ] Finish `statviewer.py`\n- [ ] Configuration validator\n- [ ] Explanation for MongoDB saving filters in README\n- [ ] Add potential ray calculation bugfix that could possibly cause problems\n- [x] Add multireceiver support for packet redundancy\n- [ ] KML support for geofences\n- [ ] Fix bug with `ast` misparsing requirement names with numbers in them\n- [ ] Update README with latest versioning requirements\n- [ ] Callsign hexdb multithreading\nFeel free to report any bugs or issues you find. Happy tracking!\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquantumbagel%2Fpyaerial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquantumbagel%2Fpyaerial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquantumbagel%2Fpyaerial/lists"}