# Flight Display âī¸
**Fully Configurable 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. Now with **comprehensive configuration support** for complete customization!
## ⨠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
- âī¸ **Fully configurable** - JSON-based configuration for all aspects of the application
- đ¨ **Customizable colors & thresholds** - Adjust altitude thresholds, distance ranges, display limits
- đ **Flexible APIs** - Configure endpoints, timeouts, and data sources
- đŠī¸ **Aircraft type recognition** - Customizable aircraft type mappings and patterns
## đ What's New in v1.0.0
â
**Complete Configuration System** - All hardcoded values are now configurable
â
**JSON Configuration Files** - Easy-to-edit configuration with example templates
â
**Backwards Compatibility** - All existing usage patterns still work
â
**Environment-Specific Configs** - Different settings for different use cases
â
**Enhanced Documentation** - Comprehensive configuration guides
## đ Installation
### Option 1: Install from PyPI (Recommended)
```bash
pip install flight-display
```
### Option 2: Install from source
```bash
# 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
```bash
# Install dependencies
pip install -r requirements.txt
# or with uv
uv pip install -r requirements.txt
# Run directly
python main.py
```
## đŽ Usage
### Quick Start
```bash
# 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 and update interval
flight-display --radius 100 --interval 30
```
### Configuration System
**NEW!** Flight Display now supports comprehensive JSON-based configuration:
```bash
# Create an example configuration file
flight-display --create-config
# Use your custom configuration
cp config_example.json config.json
# Edit config.json to your preferences
flight-display --config config.json
```
### Command Line Options
```bash
# 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: from config or 50km)
flight-display --radius 100
# Set update interval (default: from config or 10 seconds)
flight-display --interval 30
# Use custom configuration file
flight-display --config my-config.json
# Skip online airline database for faster startup
flight-display --no-online-db
# Create example configuration file
flight-display --create-config
```
## âī¸ Configuration
Flight Display supports comprehensive JSON configuration files. All aspects of the application can be customized without modifying code.
### Quick Configuration Setup
1. **Generate example config:**
```bash
flight-display --create-config
```
2. **Copy and customize:**
```bash
cp config_example.json config.json
# Edit config.json with your preferences
```
3. **Use your configuration:**
```bash
flight-display # Automatically uses config.json if present
# OR
flight-display --config my-custom-config.json
```
### What's Configurable
| Category | Examples |
|----------|----------|
| **Display** | Colors, thresholds, table format, aircraft limit |
| **Location** | Default coordinates, fallback location, radius |
| **Aircraft Types** | Type mappings (Boeing 737 â B737), unknown codes |
| **Registration** | Country patterns (N â US, G- â UK), private aircraft |
| **APIs** | Endpoints, timeouts, retry behavior |
| **Units** | Conversion factors, distance calculations |
### Example Customizations
**Change default location:**
```json
{
"location": {
"default_latitude": 51.5074,
"default_longitude": -0.1278,
"default_location_name": "London, UK"
}
}
```
**Adjust display settings:**
```json
{
"display": {
"max_aircraft_displayed": 20,
"high_altitude_threshold": 35000,
"default_update_interval": 5
}
}
```
**Add custom aircraft types:**
```json
{
"aircraft_types": {
"type_mappings": {
"Cessna 172": "C172",
"Piper Cherokee": "PA28"
}
}
}
```
For complete configuration documentation, see [CONFIGURATION.md](CONFIGURATION.md).
# 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)
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Start with auto-detection
flight-display
```
### London Heathrow Area
```bash
flight-display --lat 51.4700 --lon -0.4543 --radius 50
```
### New York Area with Custom Settings
```bash
flight-display --lat 40.7128 --lon -74.0060 --radius 75 --interval 10
```
### Quick Start (No Airline DB)
```bash
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
```bash
# 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! âī¸**
Raw data
{
"_id": null,
"home_page": null,
"name": "flight-display",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "adsb, aircraft, aviation, configurable, departure-board, flight, radar, tracker",
"author": "Flight Display Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/cf/1c/ac6c9ea0b79084fd5538b586beba8c95f0528cbd8b5819c4ee2c55da978a/flight_display-1.0.0.tar.gz",
"platform": null,
"description": "# Flight Display \u2708\ufe0f\n\n**Fully Configurable Aircraft Tracker with Airport Departure Board Style Display**\n\nA 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. Now with **comprehensive configuration support** for complete customization!\n\n## \u2728 Features\n\n- \ud83c\udf0d **Auto-location detection** - Automatically detects your location using IP geolocation\n- \ud83d\udce1 **Real-time aircraft tracking** - Uses OpenSky Network's free API for live aircraft data\n- \ud83c\udfaf **Adaptive radius search** - Automatically expands search radius to find aircraft\n- \ud83c\udfe2 **Airline identification** - Enhanced operator detection with online airline database\n- \ud83c\udfa8 **Beautiful display** - Color-coded departure board style interface\n- \u26a1 **Rate limit handling** - Smart retry logic for API reliability\n- \u2699\ufe0f **Fully configurable** - JSON-based configuration for all aspects of the application\n- \ud83c\udfa8 **Customizable colors & thresholds** - Adjust altitude thresholds, distance ranges, display limits\n- \ud83c\udf10 **Flexible APIs** - Configure endpoints, timeouts, and data sources\n- \ud83d\udee9\ufe0f **Aircraft type recognition** - Customizable aircraft type mappings and patterns\n\n## \ud83c\udf89 What's New in v1.0.0\n\n\u2705 **Complete Configuration System** - All hardcoded values are now configurable \n\u2705 **JSON Configuration Files** - Easy-to-edit configuration with example templates \n\u2705 **Backwards Compatibility** - All existing usage patterns still work \n\u2705 **Environment-Specific Configs** - Different settings for different use cases \n\u2705 **Enhanced Documentation** - Comprehensive configuration guides \n\n## \ud83d\ude80 Installation\n\n### Option 1: Install from PyPI (Recommended)\n\n```bash\npip install flight-display\n```\n\n### Option 2: Install from source\n\n```bash\n# Clone the repository\ngit clone <repository-url>\ncd flight-display\n\n# Install the package\npip install -e .\n# or with uv\nuv pip install -e .\n```\n\n### Option 2: Run directly with Python\n\n```bash\n# Install dependencies\npip install -r requirements.txt\n# or with uv\nuv pip install -r requirements.txt\n\n# Run directly\npython main.py\n```\n\n## \ud83c\udfae Usage\n\n### Quick Start\n\n```bash\n# Auto-detect location and start tracking\nflight-display\n\n# Use specific coordinates (latitude, longitude)\nflight-display --lat 40.7128 --lon -74.0060\n\n# Set custom search radius and update interval\nflight-display --radius 100 --interval 30\n```\n\n### Configuration System\n\n**NEW!** Flight Display now supports comprehensive JSON-based configuration:\n\n```bash\n# Create an example configuration file\nflight-display --create-config\n\n# Use your custom configuration\ncp config_example.json config.json\n# Edit config.json to your preferences\nflight-display --config config.json\n```\n\n### Command Line Options\n\n```bash\n# Auto-detect location and start tracking\nflight-display\n\n# Use specific coordinates (latitude, longitude)\nflight-display --lat 40.7128 --lon -74.0060\n\n# Set custom search radius (default: from config or 50km)\nflight-display --radius 100\n\n# Set update interval (default: from config or 10 seconds)\nflight-display --interval 30\n\n# Use custom configuration file\nflight-display --config my-config.json\n\n# Skip online airline database for faster startup\nflight-display --no-online-db\n\n# Create example configuration file\nflight-display --create-config\n```\n\n## \u2699\ufe0f Configuration\n\nFlight Display supports comprehensive JSON configuration files. All aspects of the application can be customized without modifying code.\n\n### Quick Configuration Setup\n\n1. **Generate example config:**\n ```bash\n flight-display --create-config\n ```\n\n2. **Copy and customize:**\n ```bash\n cp config_example.json config.json\n # Edit config.json with your preferences\n ```\n\n3. **Use your configuration:**\n ```bash\n flight-display # Automatically uses config.json if present\n # OR\n flight-display --config my-custom-config.json\n ```\n\n### What's Configurable\n\n| Category | Examples |\n|----------|----------|\n| **Display** | Colors, thresholds, table format, aircraft limit |\n| **Location** | Default coordinates, fallback location, radius |\n| **Aircraft Types** | Type mappings (Boeing 737 \u2192 B737), unknown codes |\n| **Registration** | Country patterns (N \u2192 US, G- \u2192 UK), private aircraft |\n| **APIs** | Endpoints, timeouts, retry behavior |\n| **Units** | Conversion factors, distance calculations |\n\n### Example Customizations\n\n**Change default location:**\n```json\n{\n \"location\": {\n \"default_latitude\": 51.5074,\n \"default_longitude\": -0.1278,\n \"default_location_name\": \"London, UK\"\n }\n}\n```\n\n**Adjust display settings:**\n```json\n{\n \"display\": {\n \"max_aircraft_displayed\": 20,\n \"high_altitude_threshold\": 35000,\n \"default_update_interval\": 5\n }\n}\n```\n\n**Add custom aircraft types:**\n```json\n{\n \"aircraft_types\": {\n \"type_mappings\": {\n \"Cessna 172\": \"C172\",\n \"Piper Cherokee\": \"PA28\"\n }\n }\n}\n```\n\nFor complete configuration documentation, see [CONFIGURATION.md](CONFIGURATION.md).\n\n# Use fixed radius (disable adaptive search)\nflight-display --no-adaptive --radius 50\n\n# Quiet mode (less verbose output)\nflight-display --quiet\n\n# Show help\nflight-display --help\n```\n\n### Legacy Usage (Backward compatible)\n\n```bash\n# Auto-detect location\npython main.py\n\n# Manual coordinates\npython main.py 40.7128 -74.0060\n```\n\n## \ud83d\udcca Display Information\n\nThe departure board displays the following information for each aircraft:\n\n| Column | Description |\n| ------------ | ------------------------------------- |\n| **CALLSIGN** | Aircraft callsign or registration |\n| **OPERATOR** | Airline or operator name |\n| **TYPE** | Aircraft type (e.g., B737, A320) |\n| **ALTITUDE** | Current altitude with color coding |\n| **SPEED** | Ground speed in knots |\n| **TRACK** | Heading in degrees |\n| **V/SPEED** | Vertical rate with directional arrows |\n| **DISTANCE** | Distance from your location |\n\n### Color Coding\n\n- **\ud83d\udd34 Red**: Close aircraft (<10km), ground level, descending rapidly\n- **\ud83d\udfe1 Yellow**: Medium distance (10-25km), low altitude (10,000-30,000ft)\n- **\ud83d\udfe2 Green**: Far aircraft (>25km), cruising altitude (>30,000ft), climbing\n- **\ud83d\udd35 Cyan**: High altitude cruise (>30,000ft)\n\n## \ud83d\udd27 Configuration Options\n\n### Command Line Arguments\n\n```bash\n# Location Options\n--lat, --latitude FLOAT Your latitude coordinate\n--lon, --longitude FLOAT Your longitude coordinate\n\n# Display Options\n--radius, -r FLOAT Search radius in km (default: 25)\n--interval, -i INT Update interval in seconds (default: 15)\n--max-radius FLOAT Maximum search radius for adaptive search (default: 200)\n\n# Data Options\n--no-online-db Skip fetching online airline database\n--no-adaptive Disable adaptive radius search\n\n# Output Options\n--quiet, -q Reduce output verbosity\n--version, -v Show version information\n--help, -h Show help message\n```\n\n## \ud83c\udf10 Data Sources\n\n- **OpenSky Network**: Free ADS-B aircraft position data\n- **OpenFlights Database**: Airline ICAO codes and operator information\n- **IP Geolocation**: Automatic location detection via ipapi.co and ipinfo.io\n\n## \ud83d\udea8 Rate Limiting\n\nThe tool includes smart rate limiting handling:\n\n- **Automatic retries** with exponential backoff\n- **Respectful API usage** with appropriate delays\n- **User-friendly messages** explaining any delays\n- **Graceful fallbacks** when APIs are unavailable\n\n## \ud83d\udee0\ufe0f Development\n\n### Project Structure\n\n```\nflight-display/\n\u251c\u2500\u2500 src/flight_display/\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\n\u2502 \u251c\u2500\u2500 tracker.py # Core aircraft tracking logic\n\u2502 \u2514\u2500\u2500 cli.py # Command-line interface\n\u251c\u2500\u2500 main.py # Backward compatibility wrapper\n\u251c\u2500\u2500 main_legacy.py # Legacy implementation\n\u251c\u2500\u2500 pyproject.toml # Package configuration\n\u2514\u2500\u2500 README.md # This file\n```\n\n### Building and Testing\n\n```bash\n# Install in development mode\npip install -e .\n\n# Test the CLI\nflight-display --help\n\n# Test with specific coordinates\nflight-display --lat 51.5074 --lon -0.1278 --radius 50\n```\n\n## \ud83d\udcdd Examples\n\n### Basic Usage\n\n```bash\n# Start with auto-detection\nflight-display\n```\n\n### London Heathrow Area\n\n```bash\nflight-display --lat 51.4700 --lon -0.4543 --radius 50\n```\n\n### New York Area with Custom Settings\n\n```bash\nflight-display --lat 40.7128 --lon -74.0060 --radius 75 --interval 10\n```\n\n### Quick Start (No Airline DB)\n\n```bash\nflight-display --no-online-db --radius 30\n```\n\n## \ud83d\udd0d Troubleshooting\n\n### No Aircraft Found\n\n- **Check your location**: Make sure you're in an area with air traffic\n- **Increase radius**: Try `--radius 100` or higher\n- **Check time**: More aircraft during business hours and near airports\n- **API issues**: Wait a few minutes and try again\n\n### API Rate Limiting\n\n- The tool handles rate limits automatically with retries\n- If persistent, wait 5-10 minutes before trying again\n- OpenSky API is free but has usage limits\n\n### Installation Issues\n\n```bash\n# Update pip/uv first\npip install --upgrade pip\nuv self update\n\n# Clean install\npip uninstall flight-display\npip install -e .\n```\n\n## \ud83d\udcdc License\n\nMIT License - See LICENSE file for details.\n\n## \ud83e\udd1d Contributing\n\nContributions welcome! Please feel free to submit issues and pull requests.\n\n---\n\n**Happy flight tracking! \u2708\ufe0f**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Aircraft Tracker - Fully configurable airport departure board style display using ADS-B data",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/rohankhatua/flight-display",
"Issues": "https://github.com/rohankhatua/flight-display/issues",
"Repository": "https://github.com/rohankhatua/flight-display"
},
"split_keywords": [
"adsb",
" aircraft",
" aviation",
" configurable",
" departure-board",
" flight",
" radar",
" tracker"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f5594376eefe9c58abd2e2d100e9594e3ca4c16f13e714029ec9f29cbc75821f",
"md5": "41c4310a5b0983171325805c5f78f003",
"sha256": "231eee7f6f34b8c44ff20f0afde85e7dfd8eaf880b5071e6d3ef9b397c63033e"
},
"downloads": -1,
"filename": "flight_display-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "41c4310a5b0983171325805c5f78f003",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 20360,
"upload_time": "2025-07-26T07:38:38",
"upload_time_iso_8601": "2025-07-26T07:38:38.127588Z",
"url": "https://files.pythonhosted.org/packages/f5/59/4376eefe9c58abd2e2d100e9594e3ca4c16f13e714029ec9f29cbc75821f/flight_display-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cf1cac6c9ea0b79084fd5538b586beba8c95f0528cbd8b5819c4ee2c55da978a",
"md5": "cc56bbba8906bc050a7560e89ac1e308",
"sha256": "24cdedc02c981026906302560c2754d599c78cf77e5f31704be796f06fb7e04e"
},
"downloads": -1,
"filename": "flight_display-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "cc56bbba8906bc050a7560e89ac1e308",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 17715,
"upload_time": "2025-07-26T07:38:39",
"upload_time_iso_8601": "2025-07-26T07:38:39.679378Z",
"url": "https://files.pythonhosted.org/packages/cf/1c/ac6c9ea0b79084fd5538b586beba8c95f0528cbd8b5819c4ee2c55da978a/flight_display-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-26 07:38:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rohankhatua",
"github_project": "flight-display",
"github_not_found": true,
"lcname": "flight-display"
}
JSON
