adsms

Send SMS aircraft alerts based on ADS-B data

Usage

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

./adsms.py <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 adsb.one-style /hex/ API endpoint. For adsb.one, this should be https://api.adsb.one/v2/hex/. The final slash is important.
• codes (boolean): whether or not to append ICAO codes to the URL (false for local tracker; true for adsb.one API)
• tracker: a URL to a tar1090 tracker (e.g. https://globe.theairtraffic.com/)
• 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.

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.