FlightGazer

A comprehensive flight-tracking and logging program that renders ADS-B aircraft info to an RGB-Matrix display.

This is a personal/hobbyist project that was heavily inspired by Colin Waddell's project, but supplements flight information of nearby aircraft with real-time ADS-B (Automatic Dependendent Surveillance - Broadcast) and UAT (Universial Access Transceiver) data from dump1090 and dump978.
Uses the tar1090 database for aircraft type and owner along with an internal database for airline lookup by callsign.
Uses the FlightAware API to get an aircraft's departure and destination airports.

Designed primarily to run on a Raspberry Pi and Raspberry Pi OS, but can be run on other setups (your mileage may vary).

Show/Hide images (animated gifs)

FlightGazer is a nifty-looking flight tracking system (and clock!).
Gracefully handles situations when multiple aircraft enter and leave your designated area.
Highly configurable with different layouts and numerous other options to show all the information you could need.
Track a specific aircraft once it's detected by your receiver while still being able to track aircraft in your area.
Shows a cool splash screen on startup.
Neat 👍

I like this, how do I build my own?

Coming Soon™.
If you want one, I can also build one for you. (also Coming Soon™)

(back to top)

The Changelog has all the details, but as a bulleted list:

• Visualize and figure out what aircraft are flying nearby your location, in a cool-looking way!
  • Shows an aircraft's callsign (or registration as fallback), distance and direction from your location, the aircraft's country of registration, current altitude, and speed, all provided from dump1090
  • With API access you also can see the origin and destination airport, as well as how long the aircraft has been flying
  • If you don't want to use the API, there's an available "Enhanced Readout" mode that shows even more aircraft info from dump1090, such as latitude, longitude, ground track, vertical speed, and RSSI
  • With v.6.0.0 and newer, you can see additional info like aircraft type, airline, and owner, all without needing API access
  • There are a total of 3 different layouts for aircraft info!
• It's a neat looking clock when there aren't any aircraft flying overhead
  • When dump1090 is running, shows overall stats like how many aircraft you're tracking at the moment, how many aircraft flew by today, and the furthest aircraft you can detect
  • Display sunrise and sunset times, detailed signal stats for your ADS-B receiver, extended calendar info, and even local weather info
• Extensive logging and console output capabilities as a core function
• Easily configured, controlled, monitored, and updated within a web browser
• Can emulate an RGB Matrix display in a web browser if you don't have the actual hardware
• Works offline once initial setup is complete (albeit, with no API functionality and as long as dump1090 is running on the same system)
• Designed to run 24/7

Show/Hide

Layout	Description
	Clock 1. Time, day of week, date 2. Center readout 3. Flyby counter – Number of aircraft that have been in your designated area today 4. Tracking counter – How many aircraft your receiver is currently tracking 5. Range – The distance of the farthest aircraft your receiver can detect
	Journey Readout 1. Aircraft's callsign 2. Aircraft's current distance and direction from your site 3. Country of the aircraft 4. Current altitude of the aircraft 5. Current speed of the aircraft 6. Time the aircraft has spent in the air 7. Origin airport 8. Destination airport 9. Current count of aircraft in your specified tracking area 10. UAT indicator 11. Progress bar indicating how long the current aircraft will be displayed
	Journey Plus 1. Scrolling marquee (enabled with Show Even More Info) or aircraft ground track and vertical speed 2. Ground track of the aircraft (or RSSI of signal when Show Even More Info is disabled)
	Enhanced Readout 1. Current position of the aircraft 2. Ground track of the aircraft 3. Current vertical speed of the aircraft 4. RSSI – (Received Signal Strength Index) how strong of a signal from the aircraft as detected by the receiver (in dBFS)

(back to top)

tl;dr You need a running dump1090 instance and if it's not running on the same device as FlightGazer you need to know a valid URL to access its data.
You don't actually need a physical RGB display, but it's recommended. You can install this hardware later if you choose to do so.
Other ADS-B decoders will not work. Your site location needs to be set for most of the functionality to work.
Note: FlightGazer will not work with UAT-only setups and assumes single-site decoders (not a combined feed).

Make sure you meet the above prerequisites.
There are two approaches:

• Using the web-app (recommended)
• Installing the traditional way (a little more involved)

To begin:

git clone --depth=1 https://github.com/WeegeeNumbuh1/FlightGazer
cd FlightGazer

Now, choose either one of these methods:

Run this command exactly:

sudo bash FlightGazer-init.sh -c && echo y | sudo bash install-FlightGazer-webapp.sh

Watch the output closely. If the install is successful, near the end of the output will be the URL that you need to navigate to in order to complete the setup.
Once at that webpage, configure settings first and start/restart FlightGazer to apply those settings. Done!

If you want finer control over the installation process and didn't use the web-app method above, follow these steps:

• Edit the configuration first (see the section below)
• Run sudo bash FlightGazer-init.sh
  • Optional: if you just want to try out FlightGazer without a permanent install, pass the -l flag at the end of the above command
  • Additional operating modes are explained here
• To make management easier later on, install the web-app
  • Run sudo bash install-FlightGazer-webapp.sh

Edit config.yaml which is found in the same directory as the main script itself.
If you changed any setting, FlightGazer must be restarted for the change to take effect.
Example:

cd /path/to/Flightgazer
nano config.yaml
# press Ctrl+O to save, Ctrl+X to exit

Edit colors.py in the setup folder of FlightGazer.

For useful settings with specific setups (e.g. remote dump1090 feeders, custom webinterfaces, etc.), see the tips-n-tricks document.

(back to top)

The main python script (FlightGazer.py) is designed to be started by the FlightGazer-init.sh file.
When FlightGazer is installed, you can use the command sudo systemctl start flightgazer to start it if it's not already running.

sudo tmux attach -d -t FlightGazer # press 'Ctrl+B' then 'd' to close
# or
systemctl status flightgazer # press 'q' to exit
# or
less /path/to/FlightGazer/FlightGazer-log.log # read the log output, press 'q' to quit
# or
less /run/FlightGazer/current_state.json
# or
journalctl -u flightgazer # use arrow keys to navigate, press 'q' to exit

The script and python file are designed to run interactively in a console. If you run the following command manually:

sudo bash /path/to/FlightGazer/FlightGazer-init.sh

The script automatically detects that you're running interactively and will display realtime output, like so:

Example output

Note: In the above gif, FlightGazer is operating in verbose mode. When normally running, there's way less information overload.

FlightGazer-init.sh supports optional arguments that adjust the behaviors of the FlightGazer installation and main python script. Expand the table below to see all possible operating modes. Multiple flags can be passed as well.

sudo /etc/FlightGazer-pyvenv/bin/python3 /path/to/FlightGazer/FlightGazer.py

When FlightGazer does not detect the physical RGB Matrix hardware/software, it falls back to using the display emulator.
To see the display, you can:

• Navigate to the web-app and follow the link to it, or
• Go directly to http://<IP-address-of-device-running-FlightGazer>:8888

A viable setup if not using an RGB Matrix display is to:

• Use a second device (laptop, tablet, smart fridge, smart home display, etc.)
• Setting the display to never sleep
• Going to the emulator page in a web browser
• Set the window to full screen

When FlightGazer is running, it writes a JSON to /run/FlightGazer/current_state.json and updates every LOOP_INTERVAL (2 seconds by default).
Additionally, if you're using the web-app, this same JSON is also available at the /data/current_state.json endpoint.
You can poll this data for your own use (e.g. a InfluxDB/Telegraf/Grafana stack) and get stats like aircraft details, how long aircraft are in your area, FlightGazer's operating performance, and more.

See the JSON details for a full explanation of this data.

There's also an additional file flybys.csv in the same directory that FlightGazer resides in, which tracks hourly cumulative counts of aircraft flybys and API stats. This file is also used by FlightGazer to maintain its daily counts whenever it's restarted.

It's easier with the web-app.
If that's not in use, to shutdown FlightGazer, do any one of the following:

# preferred method
sudo systemctl stop flightgazer

sudo tmux attach -d -t FlightGazer
# then, press 'Ctrl+C' to stop

# if you started FlightGazer interactively and manually
Ctrl+C

To restart, simply do the following:

sudo systemctl restart flightgazer &
# or, if it's currently not running:
sudo systemctl start flightgazer &

See the Output Reference document.

pip install psutil
python3 -m venv --system-site-packages "\path\to\new-python-venv"
cd "\path\to\new-python-venv\Scripts"
pip install requests pydispatcher schedule suntime ruamel.yaml orjson RGBMatrixEmulator

\path\to\new-python-venv\Scripts\python \path\to\FlightGazer\FlightGazer.py -i -e

python \path\to\FlightGazer\FlightGazer.py -i -e

# Just the main FlightGazer process
kill -15 $(ps aux | grep '[F]lightGazer\.py' | awk '{print $2}')
# The web interface (using systemctl is recommended over this)
kill -15 $(ps aux | grep 'FG-webapp.py' | awk '{print $2}')

sudo nano /etc/systemd/system/flightgazer.service
systemctl daemon-reload

sudo systemctl disable flightgazer.service

(back to top)

Use the web-app .
or:

Version v.2.x and newer:

# recommended
sudo bash /path/to/FlightGazer/update.sh

To use the most up-to-date version of the update script:

# alternative approach
cd /path/to/FlightGazer
wget -O update.sh https://raw.githubusercontent.com/WeegeeNumbuh1/FlightGazer/refs/heads/main/update.sh
sudo bash update.sh

(back to top)

sudo bash /path/to/FlightGazer/uninstall.sh

👉 Read This First

If your question isn't listed in the FAQ's, open an issue here on GitHub.

• This is unavoidable due to the need to interact with low-level hardware to drive the RGB display.
  • The rgbmatrix library is capable of dropping root privleges, however doing so will cause essential write operations to fail.
    • Additionally, not running as root will reduce performance, which we need the most of since this is all based on Python.
  • The FlightGazer service is designed to be a system service and starts the main script with higher CPU and disk priority.
  • Related processes like the web-app must also run as root since it needs to be able to start or stop the FlightGazer service.
  • Even though the emulator does not need to run as root, it will still inherit root permissions due to the way FlightGazer runs.
    • Same goes for running in NO_DISPLAY mode (-d).
• If you're not comfortable with this, do not use this project.
  • or, suggest code changes which may reduce the attack surface.

See also: Other Quirks & Features™

Found a bug? Want to suggest a new feature? Open an issue here on GitHub.

If you do encounter an issue, provide a copy of FlightGazer-log.log which can be found in the FlightGazer directory.
If using the web-app, also provide the FlightGazer-initialization.log which can be downloaded from "Details and Logs".

(back to top)

* (dust) *

Catch up on lore: Changelog.txt.

Faraway ideas:

• Docker image? (unlikely)
• Settings management from webpage → Available here
• Support display output to a FlightFeeder Pro?

Suggestions, comments, and bug reports are always welcomed and encouraged.
Additionally, word-of-mouth helps plenty! If you're already this far into the readme, spread the word!
If you'd like to make your own edits that changes the way the project operates, please fork this project.
If there's something not addressed here, please reach out to me directly.

(back to top)

• Another dump1090 x rgbmatrix project, but renders out a minimap instead and uses larger RGB matrix panels
  • Fun fact: I used the same font from the above project for FlightGazer
• This All About Circuits Article from 2017
  • Uses all the same core components that this project relies on at a surface-level: FlightAware's API (the older Firehose one), dump1090, rgbmatrix
• Planefence, a logger for all the aircraft that flyby your location
  • Inspired the base functionality of FlightGazer
• Skystats, a fancier way to show aircraft stats
  • FlightGazer does aircraft stats via the log, but the above is a prettier way to see similar data (FlightGazer still tracks different aspects not covered by Skystats)
• MLB-LED-Scoreboard, instead of planes, track baseballs (another project that uses these RGB matrix panels)

(back to top)

* (dust) *

FlightGazer is licensed under the GPLv3 license.
In terms of warranty:

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

If you intend to use this project, the code must remain open source.

Huge shout out to RGBMatrixEmulator. This tool was invaluable for getting the layout dialed in and figuring out the logic needed to update the display correctly, all while avoiding having to program directly on the Raspberry Pi itself (VSCode Remote on a Zero 2W is literally impossible, I've tried).

^ Thanks to the fellow tech nerds in here for all the suggestions over the evolution of this project

(back to top)