Flights Around Me

Local-first pipeline that ingests ADS-B data from your receiver, enriches it, and renders a real-time dashboard. Everything is designed to run on a Raspberry Pi with no dependency on public flight-tracking feeds.

Rationale

I live on a hill overlooking a wide plain, with an airport about 10 km away. From my home office window I watch planes taking off and landing throughout the day, often passing just 500 meters above my house. Some are small, others enormous, and they always spark the same questions: Where is this flight coming from or heading to? Which airline is it? What type of aircraft?

In the past I used sites like FlightRadar24 and FlightAware to randomly lookup planes, but this required active engagement by clicking specific aircrafts to get more info about them. So when I bumped into the PiAware project I decided to use it to setup a personal dashboard to gain passive visibility of flights around me, using my own antenna and ADS-B receiver.

This is an example of the result (my home is at the yellow dot, and the airport at the red dot):

---

Hardware

This article explains the details of building your own FlightAware ADS-B ground station. At the minimum, you will need this hardware:

• A Raspberry Pi with PiAware. Since we'll be using the Pi for running the dashboard as well (fam-view), you will need a Raspberry Pi 4 with at least 2GB RAM (preferably 4GB)
• USB SDR ADS-B Receiver
• 1090 MHz Antenna

You can optionally attach a monitor so you have the main views always active. You can however reach these views from other computers on your local network.

This is what my setup looks like:

---

API

The project uses FlightAware's AeroAPI for retrieving information about flights, airports and operators. The API is used by the fam-etl service and incurs costs, which is why the services/remote-fam-etl.sh script is available to remotely start/stop the fam-etl service.

There is a 5USD free usage credit per month for all users, which extends to 10USD for ADS-B Feeders.

The project caches information about operators, airports and flights in order to minimize costs. But building the cache could result in significant costs, depending on the amount of air traffic picked up by your ADS-B receiver. One config setting to be careful about is CRUISING_DISTANCE_TO_IGNORE_KM (in fam_etl/config.py), which I keep fairly low (~5km) so that the random high-cruising flights don't generate additional cost.

---

High Level Diagram

The following diagram outlines the interactions between the main components of the system

---

Code Generation

Almost all of the code was generated by OpenAI Codex (GPT-5-Codex) under my detailed guidance.

---

Repository Layout

• fam_etl/ – ETL that reads dump1090 output, enriches it with calculations and information from FlightAware APIs, and generates view.json, which is used by fam_view. See fam_etl/README.md.
• fam_view/ – Streamlit dashboard that renders flights by phase and on a pydeck map. See fam_view/README.md.
• services/ – systemd unit templates and a helper to manage the ETL service remotely. See services/README.md.
• scripts/ – Utility scripts with their own Poetry env (e.g. Redis sync). See scripts/README.md.
• sample_data/ – Example JSON payloads for testing and development.

---

Quick Start

1. Set up the ETL
   cd fam_etl && poetry install
   Run once manually:
   poetry run python fam_etl/main.py
   For unattended runs, create run_fam_etl.sh and the fam-etl.service described in fam_etl/README.md.

2. Launch the dashboard
   cd fam_view && poetry install
poetry run streamlit run fam_view/dashboard.py
   Use --server.headless true when running on the Pi without auto-opening a browser. Configure env vars (e.g. FAM_VIEW_FILE) as needed.

3. Services (optional)
   Systemd units live in services/. streamlit-dashboard.service is meant to stay enabled on the Pi; fam-etl.service is disabled by default to control costs. Manage ETL remotely with services/remote-fam-etl.sh start|stop|status.

4. Sample data
   sample_data/ holds example ADS-B and airport JSON files (aircraft-01.json, airport-LRTR.json, etc.) you can feed into the ETL or dashboard during development.

---

Environment

Create a .env in the project root using .env_sample as your template:

cp .env_sample .env
# edit .env to set dump1090 paths, view.json location, poll interval, API key, and coordinates

Every field is described inline in .env_sample; update values for your Pi user, file locations, FlightAware API key, and station/airport coordinates before running the ETL or dashboard.

---

Notes & Troubleshooting

• Poetry is used per component; install dependencies from within each subfolder.
• The ETL writes view.json (default /var/lib/flights-around-me/view.json). The dashboard auto-refreshes and reads directly from that file.
• For Redis sync and other utilities, activate the scripts virtualenv and run via poetry run to ensure dependencies are isolated.