A passion project years in the making. The tracker runs as a system service on a Raspberry Pi driving a 64×32 RGB LED matrix and is configured entirely through a web UI. It shows the time, weather, moon phases, overhead flights, active alerts, and can track specific flights end-to-end. Multiple clocks in the same house sync intelligently so you're never burning duplicate API credits.
Open a browser on any device on your network and go to http://hostname.local:8080 (use the Pi's hostname, not your username).
From this page you can:
- Fill out and update all settings — including WiFi network — without touching any raw files
- View system stats and current API usage per service at the bottom
- Mirror the clock display live in your browser, with a pop-out option that floats always-on-top and is freely resizable — useful for keeping an eye on the display from another room or monitor
Upgrading from an older version? Make a copy of your existing config file before pulling, then use it to fill in the new config format.
- Displays time, date, current temperature, and forecast
- Forecast modes:
- 3-day forecast — the default view showing three days at a glance
- Daily forecast — breaks the current day into Morning / Afternoon / Evening / Night periods
- Hybrid — automatically shows the daily breakdown during certain hours of the day and switches to the 3-day view the rest of the time; configure the time windows in the config
- Temperature color is based on current humidity (white → blue gradient)
- Time color shifts at sunrise and sunset
- Date line shows moon phase with a purple-to-white gradient that tracks the lunar cycle
- Display dims at predefined times set in the config
- Toggle between 12 hr / 24 hr and imperial / metric
When enabled, the clock scales down and shows active alerts beneath it. All alerts sync to a secondary screen if you run one.
- FAA Airport Alerts — ground stops, departure delays, and more for major US airports
- NWS Weather Alerts — real-time warnings for your local area
- ISS Pass-by Countdown — live countdown when the ISS is minutes away from passing overhead (works anywhere)
Detects aircraft in your bounding box every 30 seconds via OpenSky and displays:
-
Origin → Destination airport codes with distances to each
-
Airport codes color-coded by delay status:
Departure delay Color 0–20 min Green 20–40 min Yellow 40–60 min Orange 1–4 hrs Red 4–8 hrs Purple 8+ hrs Blue Arrival Color On time / early Green 0–30 min late Yellow 30–60 min late Orange 1–4 hrs late Red 4–8 hrs late Purple 8+ hrs late Blue Grey = actual time not yet available (common near airports)
-
Arrow between codes acts as a progress bar: red at departure, green near arrival
-
Airline IATA name, flight number, abbreviated aircraft type, and distance / direction / altitude to your location
-
Airline ICAO logo — especially useful for regional carriers operating under multiple brands (e.g., Republic Airways flying as United Express, Delta Connection, or American Eagle)
Track a specific flight from departure to landing via the web UI at http://hostname.local:8080.
How to use:
- Enter a flight number (must use the 3-letter ICAO airline code — e.g., UAL1134 not UA1134)
- If the flight is active, tracking starts immediately
- If it hasn't departed yet, save it and tracking begins automatically once ADSB confirms wheels-up — no credits burned until then
- Regional flights may not be supported due to API constraints
What the display shows:
- Airline logo, name, and route in the header
- Dynamic progress bar with a moving arrow icon (turns red when live position data is unavailable, e.g. over the ocean)
- Bottom line: time and distance remaining, aircraft type, airspeed, and altitude with a climb/descent indicator
- When the flight lands, the display automatically returns to the weather forecast
- Overhead flight detection continues normally throughout
The system exhausts free tiers before touching paid ones, and rotates through multiple keys automatically:
| Service | Role | Cost |
|---|---|---|
| ADSB.lol/OpenSky Network | Primary position scout — required | Free |
| AirLabs | 1,000 credits/mo | Free |
| FlightAware | 1,000 lookups | Free 5$ worth of credits a month |
| FlightRadar24 | 30,000 lookups | 9$/mo |
Stack as many keys as you want across providers. The system rotates automatically. You can order them however you wish based on what accounts you have. You also can have 1 or all 3 providers.
Credit efficiency features:
- ADSB signal must confirm takeoff before any route API is called
- ETA calculated locally from current airspeed, position, and descent pattern — no repeated polling
- Most flights consume one credit total for the entire tracking duration
For households with multiple clocks:
- One Pi is designated Master — it handles all API lookups and weather fetching
- Slave units pull data from the Master over the local network
- Single weather API key covers all clocks
- The loading pulse in the top-right corner tells you status at a glance:
- White — pinged OpenSky
- Yellow — route found via AirLabs
- Green — route found via FR24 (or Slave connected to Master)
- Cyan — route found via FlightAware
- Red — Slave cannot reach Master
The tracker logs the closest and farthest flights it detects:
- Top N closest flights to your location (configurable via
MAX_CLOSEST) - Top N farthest flights by origin or destination (configurable via
MAX_FARTHEST)
Automatic email alerts fire when a new record is set, sent from flight.tracker.alerts2025@gmail.com with flight details and a link to an interactive map (link valid 30 days; maps also always viewable on your local web page). Emails can be disabled while keeping the log files and local web stats.
The web UI includes a stats dashboard showing real-time analytics: average daily flight counts, per-service API usage, and projected monthly consumption — so you can pick the API combination that matches your local sky traffic.
Run the tracker as a dedicated system service rather than via crontab:
sudo systemctl enable its-a-plane
sudo systemctl start its-a-planeBuilt on Colin Waddell's its-a-plane-python. Additional forks and inspiration from a10kiloham, yashmulgaonkar, and ajplotkin — thanks especially to ajplotkin for the alerts feature.
This is a solo passion project built entirely in my spare time. Every feature you see has been researched, coded, tested, and debugged by myself. As the feature set grows, so does the complexity of keeping everything working together. I do my best to keep things stable, but please be patient and kind if something isn't perfect as it's getting very time consuming to test each feature every time I update. If you'd like to show your appreciation (especially if I help you troubleshoot), consider getting me a coffee! I've shared this project in good faith—please don't take advantage of it. paypal.me/c0wsaysmoo
Please please please reread the instructions carefully if you have any issues. Most issues are by not following them properly. If you absolutly can't figure it out shoot me a message. I am also on reddit under Mediocre-Opposite225
tracker.mp4
Had to remount the Pi since the display ribbon bumped into the panel
The difference in size between P4 and P2.5 panel. I use P4 for the living room and P2.5 for my desk.
The close.txt file. Farthest.txt looks the same.
Map will show the top 3 (by default) farthest flights, and the top 3 closest ping'd flights to your location. Solid lines is the flown section and dashed is unflown. Uses actual flight path travelled (if available) then uses calculated Great-circle distance for the remainder. If no flight path travelled available then uses Great-circle distance for both. (If you want to reset your maps to take advantage of the newer flight path data, delete the farthest.txt file and reboot)
The email
The local webpage to track flights or to look at your maps/logs/stats. You can look at the overall stats or click on the dates at the bottom to look at stats for individual days
signal-2026-06-05-104654.mp4
How the display looks while it is tracking a flight
Showing a weather alert and an airport alert. If there are multiple alerts it cycles between them every 4 seconds.
This is what I used to make mine. Other than the Pi and the Bonnet you can use whatever you want. You will need a computer with a SD card reader to setup the Pi and to do the install. You won't need it after it is setup.
- Raspberry Pi 3A+ You can use the Pi 3B+/Pi 4 as well. (If you use a Pi 4 you'll need to adjust the "GPIO_SLOWDOWN" in the config file since it's more powerful than the Pi 3). It's just more expensive and you don't need the ethernet jack. You can also get them at Microcenter. I tried with a Pi Zero, but couldn't get rid of the flicking completely even with soldering. I have not tried with a Pi 5, it requires different instructions with the Bonnet. If someone gets it running on the Pi 5 please let me know and I'll update the instructions.
- Adafruit bonnet
- 64x32 RGB P4 panel (I used a P4 panel measuring approximately 10 inches by 5 inches. If you prefer a smaller screen, you can opt for P3 or P2.5 panels etc, as long as they are 64x32 in size. These are available on Amazon and other websites. If the colors appear inverted, adjust the display file by changing 'RGB' to 'RBG.')
- Tinted acrylic makes the screen so much easier to read and looks nicer 10/10 recommend. Keep in mind that the acrylic panel is slightly larger than the P4 screen when you make the case.
- double sided tape (I use it to attach the acrylic to the panel)
- MicroSD card (any size)
- 5V 4A power supply (powers both the Pi and the bonnet)
- CPU heatsink (this is the smaller heatsink)
- 2x20 pin extender to prevent the bonnet from resting on it (the smaller heatsink you may not need the extender, but a normal size heatsink you will)
- Optional power button (though not really necessary)
- Soldering iron only required for PWM bridge or power button. The Pi 3 seems to be ok without the PWM bridge, but anything less and you'll want to.
- The case I built using a strip of 2in x 1/4in wood that I clampted and glued togother.
- However my friend made this case that you can 3D print.
- M2.5 machine screws to screw the bonnet onto the Pi and to screw the Pi onto the case from Ace Hardware.
Before starting the setup, sign up for the following APIs. The free tiers are sufficient to get started.
| Service | Purpose | Sign Up |
|---|---|---|
| Tomorrow.io | Weather data | app.tomorrow.io/signup |
| OpenSky Network | Primary flight detection (required) | opensky-network.org |
| AirLabs | Route & status data (1,000 free credits/mo) | airlabs.co/signup |
| FlightAware AeroAPI | Route lookup fallback ($5 free credit/mo which is about 1,000 calls) | flightaware.com/aeroapi/signup/personal |
| Flight Radar 24 | Route lookup fallback ($9 subscription a month but 30,000 calls.) | fr24api.flightradar24.com/docs/getting-started. |
Have these keys handy — you'll enter them in the config file during Step 13.
Each provider offers free credits that the system will automatically rotate through before moving to the next tier. You can stack multiple keys from the same provider to extend your capacity.
- Single key for both AirLabs + FlightAware → ~66 flights/day
- Two keys for both AirLabs + FlightAware → ~130 flights/day, and so on
FlightRadar24 is a paid tier at $9/mo for 30,000 calls — more than enough for several users sharing a single key, especially when combined with AirLabs and FlightAware free credits.
The config page (hostname.local:8080/config) keeps a running tally of your API usage for each service, and the stats page shows your daily flight average so you can estimate how many credits you'll need per month. If you run out of credits the tracker will still work, but route information won't be displayed.
Once you get your Raspberry Pi up and running, you can follow this guide to set up the project.
Using the official Raspberry Pi Imager, go to Other and select Raspberry Pi OS 64-bit Lite (the Pi Zero only supports 32-bit Lite). Note: These instructions are for Bookworm and Trixie.
When using the Imager make sure these settings are selected to enable SSH and make sure your WiFi information is typed in EXACTLY or it won't connect when turned on.
Make sure you select the correct timezone since that is what is displayed on the clock. You can always change it later.
I use MobaXterm on Windows to SSH into the Pi since it allows you to see the folder structure and edit files directly without using the command prompt. After SSH-ing into the Pi, proceed with the following steps.
sudo apt-get update
sudo apt-get install -y git python3-dev python3-pip python3-pillow cython3 python3-setuptools build-essentialClone and build hzeller's library:
git clone https://github.com/hzeller/rpi-rgb-led-matrix.git
cd rpi-rgb-led-matrix
makeThe wheel compilation requires more memory than the Pi 3's 1GB provides. Without this it will crash mid-install.
sudo apt-get install -y dphys-swapfile
sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfileAdd this line: CONF_SWAPSIZE=512
Save with Ctrl+O, Enter, Ctrl+X, then:
sudo dphys-swapfile setup
sudo dphys-swapfile swaponVerify with free -h — you should see ~512MB (or more) under Swap. You can disable swap after installation is complete to reduce SD card wear:
sudo dphys-swapfile swapoff
sudo systemctl disable dphys-swapfileInstall the Python installer dependency and run the Adafruit setup script:
sudo pip3 install adafruit-python-shell --break-system-packages
wget https://github.com/adafruit/Raspberry-Pi-Installer-Scripts/raw/main/rgb-matrix.py
python3 -m venv --system-site-packages env
source env/bin/activate
sudo -E env PATH=$PATH python3 rgb-matrix.pyYou can solder a bridge between GPIO 4 and 18 to enable PWM for less screen flicker and smoother scrolling. It is optional — it will work without the bridge.
During the script:
- Interface board type: Bonnet (Option 1)
- Quality if you soldered the jumper, Convenience if not
After the script completes, copy the rgbmatrix module to system Python so it works without a venv:
sudo cp -r ~/env/lib/python3.13/site-packages/rgbmatrix /usr/lib/python3/dist-packages/
python3 -c "import rgbmatrix; print('ok')"You should see ok printed. If not, do not continue.
Test to make sure the panel works before doing anything else. You're looking for a "HELLO WORLD" yellow happy face, with HELLO in green and WORLD in red (depending on the panel, instead of RGB it's RBG. You can fix this in the config page later if the colors are inverted). If it's only partially displaying or showing colors in the wrong place, reattach the bonnet to the Pi. Do not continue unless the test runs perfectly.
cd ~/rpi-rgb-led-matrix/examples-api-useIf you did not solder:
sudo ./demo -D 1 runtext.ppm --led-rows=32 --led-cols=64 --led-limit-refresh=60 --led-slowdown-gpio=2 --led-gpio-mapping=adafruit-hatIf you did solder:
sudo ./demo -D 1 runtext.ppm --led-rows=32 --led-cols=64 --led-limit-refresh=60 --led-slowdown-gpio=2 --led-gpio-mapping=adafruit-hat-pwmClone the tracker:
cd ~
git clone https://github.com/c0wsaysmoo/plane-tracker-rgb-pi
If the bridge on the bonnet is soldered, you'll need to set HAT_PWM_ENABLED=True in the config file. It's False by default
After cloning the files, move everything to the main folder, as some files need to be in /home/path/ rather than /home/path/plane-tracker-rgb-pi/ You'll need to combine the two logos folders since Github only allows 1,000 files per folder so I had to split them.
mv ~/plane-tracker-rgb-pi/* ~/
mkdir -p ~/logos
mv ~/logo/* ~/logos/
mv ~/logo2/* ~/logos/
rmdir ~/logo ~/logo2
pip install pytz requests beautifulsoup4 folium selenium pillow flask ephem --break-system-packages
If Bookworm
sudo setcap 'cap_sys_nice=eip' /usr/bin/python3.11
If Trixie
sudo setcap 'cap_sys_nice=eip' /usr/bin/python3.13
chmod +x ~/its-a-plane-python/its-a-plane.py
Test the script manually by running
~/its-a-plane-python/its-a-plane.py
Open a terminal on your Pi and run:
cd ~/its-a-plane-python
pwdCopy the path it shows — you'll need it in the next step. It will look something like /home/pi/its-a-plane-python or /home/flight/its-a-plane-python.
Run these commands from inside your project folder (after the cd above):
cat > /tmp/its-a-plane.service << EOF
[Unit]
Description=Plane Tracker
After=network.target
[Service]
User=$(whoami)
WorkingDirectory=$HOME
ExecStart=$(pwd)/its-a-plane.py
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
EOF
⚠️ Important: Run thecdcommand first or the paths will be wrong!
sudo cp /tmp/its-a-plane.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable its-a-plane
sudo systemctl start its-a-planeCheck it's running:
sudo systemctl status its-a-planeYou should see Active: active (running) in green. If it shows an error, jump to the Troubleshooting section below.
You can only do so IF the clock is running. So start it and then in a broswer connected to the network go to http://hostname.local:8080 and click on "Configuration" After you fill in the config file save and reboot. Remember that "hostname" is the name of your PI (not your username)
If you want the Restart App button in the web config page to work, you need to allow your user to restart the service without a password:
sudo visudoThis opens a text editor. Scroll to the very bottom and add this line (replace pi with your actual username — same as what whoami showed you):
pi ALL=(ALL) NOPASSWD: /bin/systemctl restart its-a-plane
# nmcli (NetworkManager / Raspberry Pi OS Bookworm+)
pi ALL=(ALL) NOPASSWD: /usr/bin/nmcli
Save and exit (ctrl x, y, enter). Now the web UI restart button will work.
| What you want to do | Command |
|---|---|
| Check if it's running | sudo systemctl status its-a-plane |
| Restart it | sudo systemctl restart its-a-plane |
| Stop it | sudo systemctl stop its-a-plane |
| Start it | sudo systemctl start its-a-plane |
| Watch live logs | sudo journalctl -u its-a-plane -f |
| See last 50 log lines | sudo journalctl -u its-a-plane -n 50 |
| See logs since last crash | sudo journalctl -u its-a-plane -b |
Optional: Add a Power Button If you'd like to add a power button, you can solder the button to the GND/SCL pins on the bonnet. Then, run the following commands:
git clone https://github.com/Howchoo/pi-power-button.git
./pi-power-button/script/install