flight-display

Flight Display ✈️

Aircraft Tracker with Airport Departure Board Style Display

A beautiful Python CLI tool that tracks nearby aircraft and displays them in an airport departure board style interface using real-time ADS-B data from the OpenSky Network.

✨ Features

• 🌍 Auto-location detection - Automatically detects your location using IP geolocation
• 📡 Real-time aircraft tracking - Uses OpenSky Network's free API for live aircraft data
• 🎯 Adaptive radius search - Automatically expands search radius to find aircraft
• 🏢 Airline identification - Enhanced operator detection with online airline database
• 🎨 Beautiful display - Color-coded departure board style interface
• ⚡ Rate limit handling - Smart retry logic for API reliability
• 🛠️ Flexible configuration - Customizable radius, update intervals, and coordinates

🚀 Installation

Option 1: Install as a CLI tool (Recommended)

# Clone the repository
git clone <repository-url>
cd flight-display

# Install the package
pip install -e .
# or with uv
uv pip install -e .

Option 2: Run directly with Python

# Install dependencies
pip install -r requirements.txt
# or with uv
uv pip install -r requirements.txt

# Run directly
python main.py

🎮 Usage

CLI Tool (After installation)

# Auto-detect location and start tracking
flight-display

# Use specific coordinates (latitude, longitude)
flight-display --lat 40.7128 --lon -74.0060

# Set custom search radius (default: 25km)
flight-display --radius 100

# Set update interval (default: 15 seconds)
flight-display --interval 30

# Skip online airline database for faster startup
flight-display --no-online-db

# Use fixed radius (disable adaptive search)
flight-display --no-adaptive --radius 50

# Quiet mode (less verbose output)
flight-display --quiet

# Show help
flight-display --help

Legacy Usage (Backward compatible)

# Auto-detect location
python main.py

# Manual coordinates
python main.py 40.7128 -74.0060

📊 Display Information

The departure board displays the following information for each aircraft:

Column	Description
CALLSIGN	Aircraft callsign or registration
OPERATOR	Airline or operator name
TYPE	Aircraft type (e.g., B737, A320)
ALTITUDE	Current altitude with color coding
SPEED	Ground speed in knots
TRACK	Heading in degrees
V/SPEED	Vertical rate with directional arrows
DISTANCE	Distance from your location

Color Coding

• 🔴 Red: Close aircraft (<10km), ground level, descending rapidly
• 🟡 Yellow: Medium distance (10-25km), low altitude (10,000-30,000ft)
• 🟢 Green: Far aircraft (>25km), cruising altitude (>30,000ft), climbing
• 🔵 Cyan: High altitude cruise (>30,000ft)

🔧 Configuration Options

Command Line Arguments

# Location Options
--lat, --latitude FLOAT    Your latitude coordinate
--lon, --longitude FLOAT   Your longitude coordinate

# Display Options
--radius, -r FLOAT         Search radius in km (default: 25)
--interval, -i INT         Update interval in seconds (default: 15)
--max-radius FLOAT         Maximum search radius for adaptive search (default: 200)

# Data Options
--no-online-db            Skip fetching online airline database
--no-adaptive             Disable adaptive radius search

# Output Options
--quiet, -q               Reduce output verbosity
--version, -v             Show version information
--help, -h                Show help message

🌐 Data Sources

• OpenSky Network: Free ADS-B aircraft position data
• OpenFlights Database: Airline ICAO codes and operator information
• IP Geolocation: Automatic location detection via ipapi.co and ipinfo.io

🚨 Rate Limiting

The tool includes smart rate limiting handling:

• Automatic retries with exponential backoff
• Respectful API usage with appropriate delays
• User-friendly messages explaining any delays
• Graceful fallbacks when APIs are unavailable

🛠️ Development

Project Structure

flight-display/
├── src/flight_display/
│   ├── __init__.py         # Package initialization
│   ├── tracker.py          # Core aircraft tracking logic
│   └── cli.py             # Command-line interface
├── main.py                # Backward compatibility wrapper
├── main_legacy.py         # Legacy implementation
├── pyproject.toml         # Package configuration
└── README.md              # This file

Building and Testing

# Install in development mode
pip install -e .

# Test the CLI
flight-display --help

# Test with specific coordinates
flight-display --lat 51.5074 --lon -0.1278 --radius 50

📝 Examples

Basic Usage

# Start with auto-detection
flight-display

London Heathrow Area

flight-display --lat 51.4700 --lon -0.4543 --radius 50

New York Area with Custom Settings

flight-display --lat 40.7128 --lon -74.0060 --radius 75 --interval 10

Quick Start (No Airline DB)

flight-display --no-online-db --radius 30

🔍 Troubleshooting

No Aircraft Found

• Check your location: Make sure you're in an area with air traffic
• Increase radius: Try --radius 100 or higher
• Check time: More aircraft during business hours and near airports
• API issues: Wait a few minutes and try again

API Rate Limiting

• The tool handles rate limits automatically with retries
• If persistent, wait 5-10 minutes before trying again
• OpenSky API is free but has usage limits

Installation Issues

# Update pip/uv first
pip install --upgrade pip
uv self update

# Clean install
pip uninstall flight-display
pip install -e .

📜 License

MIT License - See LICENSE file for details.

🤝 Contributing

Contributions welcome! Please feel free to submit issues and pull requests.

Happy flight tracking! ✈️