FlightGazer

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

🚩 About

This is a personal 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).

As usual, this project was developed before being tracked by git.

Note

Fun fact: this is also the author's second-only Python project.

Table of Contents

• About
• What it looks like
• Features
• Setup
  • Prerequisites (Important)
  • Installation & Getting Started
  • Configuration
  • Making Things Easier (Recommended)
• Usage
  • Interactive Mode
  • Optional Behaviors
  • Shutting Down & Restarting
  • Misc
• How to Update
• Uninstall
• FAQ's
• Known Issues
• Support & Discussion
• Changelog & Contributing
• Additional Related/Similar Projects
• Highlights Across Media
• License & Warranty
• Acknowledgements

👀 What it looks like

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)

💪 Features

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

Show/Hide

Summary

• 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, and/or extended calendar info

Adaptive & flexible

• Automatically switches to other aircraft if more than one is within the area
• Can emulate an RGB Matrix display in a browser if you don't have the actual hardware
• Does not need to run on the same hardware that dump1090 is running from
• Reads dump978 data if it's present as well
• Customizable features such as:
  • Range of which aircraft need to be in for detailed tracking
  • Height filtering
  • Units (aeronautical, metric, or imperial)
  • Clock style (12 hour or 24 hour)
  • Brightness based on time of day or when there's an active aircraft shown
  • API limiting per day, by monthly cost, or even by the hour (those API calls can get expensive)
  • Writing to a stats file that keeps count of number of aircraft flying by per day (and API usage as well)
  • Track a specific aircraft once it's detected by your ADS-B receiver
  • Colors 🌈
  • Switch between font styles
  • and more
• Known to work with PiAware/FlightFeeder, ADSBExchange, Ultrafeeder, and ADSB.im setups
  • Setups that were initially built around using AirNav Radar's rbfeeder or Flightradar24's Pi24 need a single settings change (see Tips)

Other good stuff

• Highly optimized and fast
  • Worst case takes ~25ms on average from raw data to fully parsed, filtered, run through the selection algorithm, and formatted
    • The above statistic taken from a Rasberry Pi Zero 2W w/ 32-bit OS operating as a 99.9th percentile (worldwide) ADS-B+UAT receiver at peak traffic while sending data to multiple ADS-B aggregators with MLAT
• Useful and detailed console output that shows the inner workings of FlightGazer
• Small memory footprint once settled (10-40 MiB)
• Fully Python based
  • The python script has been verified to run in both Linux (Debian) and Windows. (MacOS untested)
• All installed components confirmed to run on ARMv7, ARMv8, x86_64, i686
• Runs from a initialization script that handles everything such as initial setup and running the python script (Linux only)
  • Set up to automatically start on boot via systemd
• Easily update to latest builds here on Github
  • Automagically migrate settings, even if new options appear or are removed in the future
• A web interface that makes it easier to configure, check, and update FlightGazer (as a separate project)
• Program state is available in a json file for use elsewhere
• Logs events when you detect aircraft beyond typical ADS-B range limits (DXing)
• Robust and hard-to-break
• Unique tools and fonts that can be used in other projects (don't forget to credit me)
• Constant development
• Adequate documentation

Screen Layout

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)

🛠️ Setup

⚠️ Prerequisites (Important)

Show/Hide

Using this project assumes you have the following:

MINIMUM

• A working dump1090 instance or similar interface where aircraft.json can be read/accessed
  • Ex: tar1090/readsb, piaware/skyaware, dump1090-fa, dump1090-mutability
    • Note: the script will automatically look at these locations and choose which one works
  • This script does not need to be on the same device that dump1090 is running from (see Configuration section)
  • Your ADS-B decoder must output in aeronautical units (nautical miles, knots, feet)
• The latest Python (>=3.9)
• At least 100 MB of available disk space
• A working internet connection for setup
• for Linux distros:
  • Basic knowledge of how to use bash or similar terminal
  • ssh access if running headless
  • apt as the package manager
  • Root access (necessary for accessing the RGBMatrix hardware)
  • systemd based system

Highly Recommmended

• The rgbmatrix library installed and present on the system
  • Refer to adafruit's guide on how to get this working if it's not installed already
  • If the rgbmatrix library is installed:
    • It needs to be accessible as a Python module globally or in the same home directory of the user that installed FlightGazer
    • Must be built using the adafruit script
    • Note: if using a Raspberry Pi, the core rgbmatrix library doesn't run on a Pi 5 or newer. Use a Pi 4 or older.
  • rgbmatrix does not need to be installed to run FlightGazer, however. (see Usage section)
• The physical RGB matrix hardware (again, not strictly necessary)
  • Recommended: Using the adafruit matrix bonnet
  • Using 64x32 sized, HUB75 type matrix display (this is the only layout this script was designed for)
  • Other matrix displays and setups can be used as well using advanced settings
• Your location set in dump1090
• A console that can interpret ANSI escape sequences (should be most modern ones)
• If using a Raspberry Pi, use a model that has multiple CPU cores (Raspberry Pi 3/Raspberry Pi 2W or newer)
• Not using a combined feed for the data source (you would know if you set this up)

For Enhanced Functionality

• A FlightAware API key (optional) for getting additional aircraft information such as origin/destination airports
  • It is highly recommended to generate a key that will only be used for FlightGazer for accurate cost tracking
• a running dump978 instance if you're in the US and live near airports that handle general aviation more than commercial flights

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. 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).

Starting from scratch and want to follow the least amount of steps?

1. Follow this guide entirely and use a Raspberry Pi
2. Get SSH access (go to System → Management)
   1. Press the Show Password button in the Generate New Root Password section
   2. Copy the password and press the Accept button
   3. With your SSH client, log into the device at root@[IP address of the device]
3. Continue the below steps and install the web interface as well

📶 Installation & Getting Started

Make sure you meet the above prerequisites. To begin:

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

Important

Once the above command is completed, it is recommended to configure your setup now before running the initialization file.
See the Configuration section below, then return to this step.

if running Linux (Debian) / Raspberry Pi

then run the following:

sudo bash FlightGazer-init.sh

which will set up everything needed to run FlightGazer and then will start FlightGazer afterwards.
If you'd like to change the setup behavior before the first run, check out the options.

if running Windows

You will need to put in some elbow grease here.

[!IMPORTANT] You're likely not going to be running rgbmatrix on Windows. Instead, use RGBMatrixEmulator.

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

If you don't care for running in a virtual environment, skip the python3 -m venv and cd "path\to..." lines and install the packages globally.
Then, read here.

🎚️ Configuration

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

Note

If the configuration file is missing or has invalid values, the main script has built-in fallbacks. It will alert you as necessary.
(Just don't try to purposely break the script!)

Adjusting Colors

Edit colors.py in the setup folder of FlightGazer.

Tricks & Tips

Configuration details for a remote dump1090 installation (eg: FlightAware-provided FlightFeeder)

Set CUSTOM_DUMP1090_LOCATION to the IP address of the device running dump1090.
Example: http://192.168.xxx.xxx:8080 or http://192.168.xxx.xxx/skyaware
And then set PREFER_LOCAL to false.

If you initially built your ADS-B receiver around RadarBox24/AirNav Radar's rbfeeder or Flightradar24's Pi24 image

rbfeeder and Pi24 setups don't provide a web interface that FlightGazer can look at.
FlightGazer can only run directly on those systems and must be installed on those devices (dump1090 data cannot be read remotely).
Set PREFER_LOCAL to true so that FlightGazer can read the data from these setups.

If you managed to install a working web interface like tar1090 with these setups then you're an advanced user and you already know what you're doing.

Connecting to a separate dump978 feeder (over the network)

Set CUSTOM_DUMP978_LOCATION to the IP address of the dump978 system.
Example: http://192.168.xxx.xxx:8978
If dump1090 is running on the same system FlightGazer is running off of, leave PREFER_LOCAL to true.
FlightGazer was designed to handle reading from both a local dump1090 instance and a remote dump978 system at the same time.
However, if your network goes down or the dump978 system disconnects, this will cause FlightGazer to pause its processing as if dump1090 failed as well.
Also important to note, if your dump978 instance uses a different set location than your dump1090 one, the distance data for UAT aircraft will be overridden by your dump1090 location.

Turning off the screen at night

ENABLE_TWO_BRIGHTNESS: true
BRIGHTNESS_2: 0

If you don't want it to turn off at sunset,
USE_SUNRISE_SETSET: false
then set BRIGHTNESS_SWITCH_TIME to whatever time you want.

Note that FlightGazer will still be running and driving the screen even with a brightness of 0 so CPU usage will remain the same.

Only turn on the screen when there's an aircraft nearby (no clock)

BRIGHTNESS: 0
ENABLE_TWO_BRIGHTNESS: false
ACTIVE_PLANE_DISPLAY_BRIGHTNESS: <your value here>

Hiding elements on the display

Go to the color config file and set whatever element you don't want to show to BLACK.
Example: seconds_color = BLACK

Reduce flickering on a physical RGB matrix display

• Do the PWM mod
• Reserve a CPU core solely for the display
• Lower the value for LED_PWM_BITS (though 8 seems good enough)
• Switch CPU governor to performance or add force_turbo=1 to a Raspberry Pi's config.txt file

💻 Making Things Easier (Recommended)

Want to make dealing with FlightGazer easier without having to use terminal commands all the time? (the author sure did)
Install the web interface that manages basically everything to do with FlightGazer.
The web interface can be installed using:

sudo bash /path/to/FlightGazer/install-FlightGazer-webapp.sh

The web interface can be accessed via
http://<IP-address-of-device-running-FlightGazer>/flightgazer
or on port 9898/flightgazer if there's no web server present on the device running FlightGazer.

(back to top)

🏃‍♂️ Usage

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.

Important

By default, the script is designed to run at boot (via systemd with flightgazer.service).
You can check its status with:

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

⚙️ Interactive Mode

However, the script and python file are also 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.

🔡 Optional Behaviors

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.

Table of operating modes

Flag	Enables interactive mode in FlightGazer?	What it does
(no flag)	❌	Default operating mode when not run as a service. Minimizes console output when running non-interactively. Will use rgbmatrix. Uses RGBMatrixEmulator as a fallback.
-d	✅	Do not load any display driver. Only print console output. Overrides -e.
-e	❌	Use RGBMatrixEmulator as the display driver instead of actual hardware. Display by default can be seen in an internet browser. (see the Tip below)
-f	✅	No Filter mode. Ignores set RANGE and HEIGHT_LIMIT settings and shows all aircraft detected. Display will never show aircraft details and remain as a clock. Useful for low traffic areas.
-t	✅	Run in tmux. Useful for long-running interactive sessions. Default operating mode when started as a service.
-c	❌	Only install/force-check dependencies and don't start the main script.
-v	❌	Enable verbose/debug messages to be displayed/logged from the main script.
-l	❌	Live/Demo mode. Does not install service and runs FlightGazer from dependencies in /tmp.
-h	❌	Print the help message.

Tip

An important one is -e, which switches the display renderer from rgbmatrix to RGBMatrixEmulator. This is useful in case you are not able to run the display output on physical hardware and is the fallback when actual hardware is not available.
Note: Running the emulator is slow!, especially on single-board computers such as the Raspberry Pi.
Animations might be choppy or laggy depending on your system and enabled settings. (expect about 12 FPS on a Raspberry Pi 3/Zero 2W)

By default, RGBMatrixEmulator can be viewed through a web browser:

• http://<IP-address-of-device-running-FlightGazer>:8888
• http://localhost:8888 (on the device running FlightGazer)

Advanced use

There's nothing stopping you from calling the python file directly. However FlightGazer-init.sh was designed to make running it smoother by handling the initial setup, making sure all the dependencies are there before running the actual python script, and automatically using the full paths for both the virtual python environment binaries and for the script itself, along with handling any arguments/flags that need to be passed.

You can run it like so:

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

The main python file accepts almost all the same arguments as the initialization script, but you can always pass -h to see all possible operating modes.

🔕 Shutting Down & Restarting

To shutdown FlightGazer, do any one of the following:

Show/Hide

# 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:

Show/Hide

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

or, you may start it manually.

👓 Misc

What the initialization script does

• Checks if there is an internet connection
• Checks if first_run_complete exists
  • Checks last modified date: if greater than 3 months, runs updates for installed dependencies
  • If file exists and is new-ish, then this isn't an initial installation and we just run the main python script
• Updates package list
• Installs:
  • python3-dev
  • libjpeg-dev
  • python3-numpy
  • python3-venv
  • tmux
• Create a new systemd service flightgazer.service if not present
  • Also creates a systemd service for the boot splash screen flightgazer-bootsplash.service as well, only if the rgbmatrix library is present
• Write out RGBMatrixEmulator config file
• Makes virtual python environment at etc/FlightGazer-pyvenv
• Updates pip as necessary and installs the following python packages in the virtual environment:
  • requests
  • pydispatcher
  • schedule
  • psutil (usually provided in Raspberry Pi OS)
  • suntime
  • ruamel.yaml
  • orjson
  • RGBMatrixEmulator
    if the web app is installed as well:
  • Flask
  • gunicorn
• Downloads the tar1090-db aircraft database and generates a sqlite3 database that can be used by FlightGazer
• Writes first_run_complete blank file to etc/FlightGazer-pyvenv to show initial setup is done
• Runs main python script with desired flags

Running on Windows

No fancy initialization script here. Run FlightGazer as so:

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

or, if you didn't set up the virtual environment:

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

Pass -h to see all operating modes.

Useful commands

Terminating FlightGazer-related processes manually (Linux):

# 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}')

Changing systemd startup command

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

Disabling startup at boot

sudo systemctl disable flightgazer.service

Deploy the full FlightGazer package in one go:

sudo bash /path/to/FlightGazer/FlightGazer-init.sh -c \
&& echo y | sudo bash /path/to/FlightGazer/install-FlightGazer-webapp.sh \
&& sudo systemctl start flightgazer
# :D

Cool python modules you can use in other projects

Check the utilities directory.

(back to top)

⬆️ How to Update

It is recommended to use the most up-to-date versions!

Version v.2.x and newer:

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

or, 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

Windows

You can run git clone --depth=1 https://github.com/WeegeeNumbuh1/FlightGazer \a\different\directory and manually migrate your config.

Upgrading from v.1.x to v.2.x and newer

Use the alternative approach above.
The migrator cannot migrate v.1.x configuration files to the newer format so you must manually migrate your settings.

(back to top)

🚮 Uninstall

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

Windows

Simply delete the folder (and the virtual python environment if you set that up as well).

❔ Frequently Asked Questions (not really but they could pop up)

FAQ's (Open these before raising an issue)

Q: My RGB display is blank when running this, what broke?
A: Check the HAT_PWM_ENABLED value in config.yaml and make sure it matches your hardware setup.
Additionally, this project assumes the use of the adafruit rgbmatrix bonnet and only 1 HUB75-based RGB panel. Other setups are not supported.
Getting the RGB display to work is beyond the scope of this project if it wasn't working before using FlightGazer.

Q: I broke it 🥺
A: Try running the updater first. If it's still broken, uninstall then reinstall FlightGazer.

Q: I restarted/updated my system but it took longer for FlightGazer to start. What's going on?
A: The initialization script that starts FlightGazer checks if there are any updates to the dependencies it uses.
If it has been over three (3) months since it last checked, then the next time it restarts, it will run these checks. It usually takes a few minutes to do this, but if your internet connection is slow or the system is loaded with other processes, then it could take longer.

Q: Okay, but this update is taking a really long time. Then, it just stops after awhile. Is it broken?
A: First, restart the whole system. Then, let FlightGazer do the update again (it should do this automatically at system startup). If it stops again, try starting FlightGazer one more time. It should succeed at this point.

Q: I see a dot on the right of the aircraft readout display. What is it?
A: That is an indicator of how many aircraft are within your defined area. The number of dots lit up indicate how many are present. There will always be at least one lit up, all the way to 6. If the number is greater than 1, FlightGazer will start switching between aircraft to show you what else is flying in your area.

Q: Can I customize the colors?
A: Click here

Q: Can I customize the layout beyond what can be done in config.yaml (clock, aircraft info, etc)?
A: Sure, just change some things in the script. Have fun. (also, you can just fork this project)
(note: any changes done to the main script will be overwritten if you update with the updater)

Q: Why use the FlightAware API? Why not something more "free" like adsbdb or adsb.lol?
A: In my experience, adsbdb/adsb.lol cannot handle chartered/position-only flights (i.e. general aviation, military, etc) and are lacking (correct) information for some flights. Because these open APIs rely on crowdsourcing and are maintained by a small group of people, the data offered by these APIs is prone to being outdated or incorrect. After testing, these APIs just aren't rigorous enough to be used for this project. It's better to have no information than misinformation. Plus, FlightGazer is still useful without having journey info anyway. I do wish FlightAware had a much lighter API endpoint for pulling very basic information like what this project uses.

Q: FlightGazer detected a plane and it couldn't determine a journey. This same plane showed up again a few minutes later and the result didn't change. What happened?
A: If this plane is blocked from public tracking, there will never be a result. If you know it isn't, try lowering the value for FLYBY_STALENESS.
This situation has been seen when a plane just takes off and the API FlightGazer uses hasn't begun tracking the plane just yet, therefore there isn't a result that the API can give. When this plane shows up again, FlightGazer will reuse the same API result since it would not count this as a new flyby, a metric controlled by FLYBY_STALENESS.

Q: Why use a different font for the Callsign? I don't like how it looks different by default next to other readouts.
A: If it's too bothersome, set ALTERNATIVE_FONT to true in the config file to make it more uniform.
Reasoning: The original/default font is perfect with numerical readouts that update frequently (eg: speed, RSSI, altitude, seconds, etc) as the general glyph shape doesn't change between updates.
The alternative font is perfect for the callsign because callsigns are alphanumeric, the readout changes less often, and the alternative font offers quick differentation between between homoglyphs ('0' vs 'O', '5' vs 'S') compared to the default font. Additionally, with fields that aren't alphanumeric (country code) or use a limited set of the alphabet (direction + distance), there's less of a need for the alternative font's advantages.

Q: Some of your code is not pythonic!!!1!!111
A: but it works, does it not?
(it should be >98% pythonic at this point)

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

(back to top)

🐛 Known Issues, Shortcomings, and Reporting Issues

Show/Hide

• Flyby stats are not 100% accurate (but can be close, depending on your FLYBY_STALENESS setting in your config)

  • This stat relies on the number of unique aircraft seen, not each occurrence of an actual flyby
    • This is somewhat by design, covering the case of living near a general aviation airport and having the same plane do numerous touch-and-go landings
  • For example, if plane with hex ID abcdef passes by at 06:00, then passes by again at 18:00, it won't count as a flyby
    This has been fixed in v.1.3.0 with the addition of a new parameter, FLYBY_STALENESS

• If using No Filter mode and restarting FlightGazer often, we can artifically inflate the flyby count

  • FlightGazer has a feature where it will write out stats before shutting down so that it can reload those stats upon restart (if it's the same day). The flyby count is simply a number and has no additional information such as the IDs of aircraft
  • Upon reload, FlightGazer fills in dummy IDs equal to the value of the last written flyby count in its internal list of aircraft IDs it keeps track of for flybys
  • The flyby count runs under the assumption that the flyby area itself is small, but since No Filter removes that restriction, it's a free-for-all
  • This is not usually a problem, as long as we don't restart often in the same day
  • May not ever get fixed

• On rare occasions are times when there will be two entries of the same aircraft (only when using No Filter mode)

  • This is an edge case that's been noted since the v.0.x days, mainly due to a dual receiver setup
  • It has been associated with aircraft that uses a dual mode transponder or there is TIS-B contact of the same aircraft on UAT while it's present over ADS-B
  • So far there is no fix planned for this as this does not break core functionality
    • At worst it confuses the aircraft selector algorithm but even then it still selects normally
    • May be mitigated in the far future
  • This has been mitigated in v.2.6.3 and newer, fully fixed in v.5.0.0; FlightGazer will use the best entry it encounters when not using No Filter mode

• If FlightGazer crashes when run in tmux via systemctl, it will always report an exit status of 0

  • Complicated to fix due to all the signal handling between the main script, the initialization script, and systemd
  • May not actually get fixed (simply just code better, smh)
  • I think it's okay now

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 (and settings_migrate.log if present) which can be found in the FlightGazer directory.

(back to top)

💬 Support & Discussion

* (dust) *

✏️ Changelog, Planned Features, and Contributing

Read: Changelog.txt.

Faraway ideas:

• Docker image? (unlikely)
• Settings management from webpage Available here

As FlightGazer is mainly a personal project, it is currently not open to contributions. Pull requests will be rejected.
Suggestions, comments, and bug reports are always welcomed and encouraged.
Additionally, word-of-mouth helps plenty!
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)

📖 Additional Related/Similar Projects

• 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 functionality of the stats file FlightGazer writes out

(back to top)

🎖️ Highlights Across Media

* (dust) *

⚖️ License & Warranty

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.

✅ Acknowledgements

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)