Skywatch

SkyWatch Python Script

Skywatch is a python script that reads the aircraft.json file from a readsb install and checks it against a list of aircraft you provide in the watchlist.txt file. If there’s a match, it sends an alert via telegram. It will also alert on certain squawk codes. This has only been tested using the raspberry pi image from adsbexchange, but it should work on any readsb setup. If using a different image/install then all you need to do is find the code and replace http://adsbexchange.local/tar1090/data/aircraft.json with http://YOUR_IP_OR_HOSTNAME_HERE/tar1090/data/aircraft.json

Installation and Setup

Follow the steps below to install and setup the script and create and use your own telegram bot. These steps assume you’re using the adsbexchange image, but the steps should be similar if using something else. Adjust as needed.

Script install

The script installation is easy. All you need to do is log into your raspberry pi and run the following commands below:

Install and run git to get the SkyWatch files

The adsbexhange image does not have git installed. This is needed to download the script.

sudo apt update
sudo apt install git --yes

Now, with git installed, we can download the skywatch files with the following command:

cd ~ && git clone https://github.com/TheCommsChannel/SkyWatch.git

We’ll now have a new directory called SkyWatch on the Raspberry Pi. We can check this by typing in the ls command which will show a list of files and directories. There will likely only be one if this is a fresh Raspberry Pi install. We can now go into this directory by tpying in cd SkyWatch

Telegram Bot Setup and Script Configuration

The SkyWatch directory contains all of the files needed. If we type in the ls command here to list everything, we should all of the files needed for SkyWatch. The files we need to configure are going to be skywatch.py and watchlist.txt. Before we configure those, we need to create a Telegram Bot and get the information needed from it.

Bot Creation

Open up Telegram and search for “BotFather” and open a chat with it. Send the command /newbot and then follow the prompts for the bot name and username. The bot name can be anything (I’m using SkyWatch). The username does need to be something unique that hasn’e been taken yet. I’m using tc2_skywatch_bot and you could do something similar and just replace tc2 with whatever you want.

You’ll then be provided with the bot’s token. Take note of this as this needs to be entered in the TELEGRAM_BOT_TOKEN section of the skywatch.py script. Since you’re likely setting this bot up from a phone and likely running these commands on a computer, you’ll need to copy this token and send it to yourself somehow (email for example) so you can paste the token when needed in the following steps.

Next, click on the link provided by BotFather, usually t.me/thebotnamehere. This will take you to your bot and you can hit start.

Then you can go to the following link for checking the Telegram Chat ID.

https://api.telegram.org/botYOURBOTTOKENHERE/getUpdates

On this page you should see a section that says

"chat": {
    "id": 1234567890,
    "first_name": "YourName"
    "type": "private"
}

This number after "id": is the Telegram Chat ID you will need to enter into the skywatch.py script in the next steps

Editing the skywatch.py script

Now that we have the Telegram Bot Token and the Chat ID, we can now enter these into the skywatch.py script. To do this, run the following command

nano skywatch.py

This will open up the skywatch.py script in a text editor called nano. There will be a section in the script where you enter in the Telegram Bot Token and the Chat ID. Look for the following section towards the top of the script

TELEGRAM_BOT_TOKEN = ""
TELEGRAM_CHAT_ID = ""

Enter in the Bot Token and the Chat ID we retrieved earlier in between the qoutes " “. It should look like the following example when you’re done. Just replace what you see here with your own.

TELEGRAM_BOT_TOKEN = "987654321:AAE1234ipLL"
TELEGRAM_CHAT_ID = "1234567890"

After we’re done editing, we need to save by doing the following:

  • Hold CTRL and hit X

  • Hit Y

  • Hit ENTER

The script is now configured and you’re ready to receive alerts from it to Telegram.

Adding aircraft to the watchlist

We’re now ready to add aircraft we want to alert on to the watchlist. This is done using the watchlist.txt file by adding one flight/plane per line in the file. Every aircraft has a unique Hex Code ID and many will usually have a Flight ID. We can use either of these when entering what we want to alert on in the watchlist.txt file. We can also use * as a wildcard. For example, if we wanted to alert on all United Airlines planes, these flight IDs are usually UAL and then some number UAL1234. If we wanted to alert on all of them, we would enter in UAL* as a line in the watchlist.txt file.

After we’re done editing, we need to save by doing the following:

  • Hold CTRL and hit X

  • Hit Y

  • Hit ENTER

Testing the the script and running it in the background

Now that the script is configured and we have a list of aircraft or flight IDs to alert on in the watchlist.txt file, We are ready to run the script.

Testing the script

First, lets test the script by running the following command:

python skywatch.py

This will start the script and if all went well, we shouldn’t see any errors and we should receive an alert via telegram when a flight matching the criteria is detected. If there are no aircraft up that match the critera, we can look at the flight map and look for aircraft currently flying for testing purposes. Ideally select a specific flight e.g. UAL1234 for this test instead of UAL* as that will generate a lot of alerts since there are generally many of them up at any given time.

Running the script in the background

If all went well with the test, we can run the script in the background by running the following command:

python skywatch.py &

This will run the script in the background so it will continue to run and alert us for any aircraft we specified in the watchlist.

Updating the watchlist

If you need to make changes or add additional flights to the watchlist, you can follow the Adding aircraft to the watchlist section above. Just remember that if we’re logging back into the Raspberry Pi after logging off, we will need to go back into the SkyWatch directory to edit the watchlist.txt file. This command should get you back there cd ~/SkyWatch

After editing the watchlist.txt file the script needs to be stopped and started to see the changes. To stop the script, we need to find its process ID by running the following command

ps aux | egrep '[s]kywatch'

You should then see something similar to this below

pi@adsbexchange:/ $ ps aux | egrep '[s]kywatch'
pi        7596  0.1  0.7  36692 28324 pts/0    S    09:25   0:01 python skywatch.py

This first number that shows up is the process ID (you’ll likely have a different number). Now that we have the process ID, we can use it to stop the script using the command below. Just change 7596 in the example to whatever number you get for the process ID.

kill -15 7596

After hitting ENTER to run the command, the script should now be stopped. You can confirm this by running the command we ran to find the process ID again

ps aux | egrep '[s]kywatch'

You should get no output when running this command now since it couldn’t find any process with the script running anymore.

Restarting the script

After making any changes to the watchlist.txt file, we need to start the script back up. To do this, we need to make sure we’re in the SkyWatch directory by running the following command

cd ~/SkyWatch

We can now start the script back up and have it run in the background like we did earlier by running the following command

python skywatch.py &