Send SMS aircraft alerts based on ADS-B data
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Samuel Sloniker d5570bcec7 Add geofencing and API support 11 months ago
adsms Add geofencing and API support 11 months ago
debian Add Discord webhook support 11 months ago
.gitignore Debian packaging 12 months ago
LICENSE Initial commit 12 months ago Add geofencing and API support 11 months ago
adsms.service Fix adsms.service 12 months ago
example_config.json Fix mismatch between installer and config 12 months ago Add Discord webhook support 11 months ago
pyproject.toml Add Discord webhook support 11 months ago
requirements.txt Add Discord webhook support 11 months ago Add shebang to 12 months ago
screenshot.jpg Upload screenshot 12 months ago


Send SMS aircraft alerts based on ADS-B data

Screenshot of text sent by adsms


Copy the configuration file, make any necessary changes, and run:

./ <configuration_file>

Configuration file

All values are required. All are strings unless otherwise specified. All times are in seconds.

  • textbelt_key: your Textbelt API key. This is always required, but can be set to an invalid value if you do not plan to use SMS.
  • data: a URL to a readsb/tar1090 aircraft.json endpoint (for a local tracker), or an /hex/ API endpoint. For, this should be The final slash is important.
  • codes (boolean): whether or not to append ICAO codes to the URL (false for local tracker; true for API)
  • tracker: a URL to a tar1090 tracker (e.g.
  • database: an SQLite file in which to store subscriptions
  • pid_file: path to which to write the PID (set to empty string to not write a PID file)
  • max_age: maximum age of aircraft pings; pings older than this will be ignored
  • min_disappearance: the minimum time for which an aircraft must go "off the radar" before disappearing for new pings to trigger notifications again
  • delay: time to wait after processing all rules before running the loop again

Database Schema

adsms uses a SQLite database to store subscriptions and information about tracked aircraft. Currently, the only table is subscriptions.


The subscriptions table has the following columns:

Column Name Data Type Description
rowid INTEGER Unique identifier for the subscription.
phone TEXT Identifier to receive notifications for this subscription.
icao TEXT ICAO address of the aircraft to track.
description TEXT Description of the aircraft being tracked.
last_seen INTEGER Timestamp of the last time this aircraft was seen by the system.
platform TEXT The method by which to send the message.
min_lat REAL The minimum latitude of the geofence.
min_lon REAL The minimum longitude of the geofence.
max_lat REAL The maximum latitude of the geofence.
max_lon REAL The maximum longitude of the geofence.

This table stores information about each subscription, including the contact information to send notifications to, the ICAO address of the aircraft to track, a description of the aircraft, and the last time it was seen by the system.

adsms can send messages by SMS using Textbelt or by Discord using webhooks. For SMS, use textbelt for platform and the phone number for phone; for Discord, use discord_webhook for platform and the webhook URL for phone. (The field is called phone because adsms originally only supported SMS.)

When adding new entries, set last_seen to 0.

If you want to notify whenever an aircraft is seen anywhere, use -90 for min_lat, -180 for min_lon, 90 for max_lat, and 180 for max_lon. This will cover the entire globe.

Use of ChatGPT

Portions of both this README and the adsms code have been partially written with ChatGPT.