skyview/README.md

# SkyView - Multi-Source ADS-B Aircraft Tracker

A high-performance, multi-source ADS-B aircraft tracking application that connects to multiple dump1090/readsb receivers using Beast binary or VRS JSON formats and provides a modern web interface with advanced visualization capabilities.

## ✨ Features

### Multi-Source Data Fusion
- **Multiple Formats**: Support for both Beast binary (port 30005) and VRS JSON (port 33005) protocols
- **Multiple Receivers**: Connect to unlimited dump1090/readsb sources simultaneously
- **Mixed Sources**: Use Beast and VRS sources together in the same system
- **Intelligent Merging**: Smart data fusion with signal strength-based source selection
- **High-throughput Processing**: High-performance concurrent message processing

### Advanced Web Interface
- **Interactive Maps**: Leaflet.js-based mapping with aircraft tracking
- **Low-latency Updates**: WebSocket-powered live data streaming
- **Mobile Responsive**: Optimized for desktop, tablet, and mobile devices
- **Multi-view Dashboard**: Map, Table, Statistics, Coverage, and 3D Radar views

### Professional Visualization
- **Signal Analysis**: Signal strength visualization and coverage analysis
- **Range Circles**: Configurable range rings for each receiver
- **Flight Trails**: Historical aircraft movement tracking  
- **3D Radar View**: Three.js-powered 3D visualization 
- **Statistics Dashboard**: Aircraft count timeline *(additional charts under construction)* 🚧
- **Smart Origin**: Auto-calculated map center based on receiver locations
- **Map Controls**: Center on aircraft, reset to origin, toggle overlays
- **Signal Heatmaps**: Coverage heatmap visualization *(under construction)* 🚧

### Aircraft Data Enhancement
- **Complete Mode S Decoding**: Position, velocity, altitude, heading
- **Aircraft Identification**: Callsign, category, country, registration
- **Enhanced Callsign Lookup**: Multi-source airline database with 6,162+ airlines and 83,557+ airports
- **Aviation Data Integration**: OpenFlights and OurAirports databases with automatic updates
- **ICAO Country Database**: Comprehensive embedded database with 70+ allocations covering 40+ countries
- **Multi-source Tracking**: Signal strength from each receiver
- **Historical Data**: Position history with configurable retention
- **Database Optimization**: Automatic VACUUM operations and storage efficiency monitoring

## 🚀 Quick Start

### Using Command Line

```bash
# Single source
./skyview -sources "primary:Local:localhost:30005:51.47:-0.46"

# Multiple sources  
./skyview -sources "site1:North:192.168.1.100:30005:51.50:-0.46,site2:South:192.168.1.101:30005:51.44:-0.46"

# Using configuration file
./skyview -config config.json
```

### Using Debian Package

```bash
# Install
sudo dpkg -i skyview_0.0.3_amd64.deb

# Configure 
sudo nano /etc/skyview/config.json

# Start service
sudo systemctl start skyview
sudo systemctl enable skyview
```

## ⚙️ Configuration

### Configuration File Structure

```json
{
  "server": {
    "host": "",
    "port": 8080
  },
  "sources": [
    {
      "id": "primary",
      "name": "Primary Receiver (Beast)",
      "host": "localhost",
      "port": 30005,
      "format": "beast",
      "latitude": 51.4700,
      "longitude": -0.4600,
      "altitude": 50.0,
      "enabled": true
    },
    {
      "id": "secondary",
      "name": "Secondary Receiver (VRS JSON)",
      "host": "192.168.1.100",
      "port": 33005,
      "format": "vrs",
      "latitude": 51.4800,
      "longitude": -0.4500,
      "altitude": 75.0,
      "enabled": true
    }
  ],
  "settings": {
    "history_limit": 1000,
    "stale_timeout": 60,
    "update_rate": 1
  },
  "origin": {
    "latitude": 51.4700,
    "longitude": -0.4600,
    "name": "Custom Origin"
  }
}
```

### Data Format Configuration

SkyView supports two ADS-B data formats:

#### Beast Binary Format
- **Port**: Typically 30005
- **Format**: Binary protocol developed by FlightAware
- **Source**: dump1090, dump1090-fa, readsb with `--net-bo-port 30005`
- **Configuration**: `"format": "beast"` (default if not specified)
- **Advantages**: Compact binary format, includes precise timestamps and signal strength

#### VRS JSON Format  
- **Port**: Typically 33005
- **Format**: JSON objects with aircraft arrays
- **Source**: readsb with `--net-vrs-port 33005`
- **Configuration**: `"format": "vrs"`
- **Advantages**: Human-readable JSON, simpler to parse and debug
- **Update Interval**: Configurable with `--net-vrs-interval` (default 5 seconds)

Both formats can be used simultaneously in the same SkyView instance for maximum flexibility and redundancy.

### Command Line Options

```bash
skyview [options]

Options:
  -config string
        Configuration file path
  -server string
        Server address (default ":8080")  
  -sources string
        Comma-separated Beast sources (id:name:host:port:lat:lon)
  -verbose
        Enable verbose logging
```

## 🗺️ Web Interface

Access the web interface at `http://localhost:8080`

### Views Available:
- **Map View**: Interactive aircraft tracking with receiver locations
- **Table View**: Sortable aircraft data with multi-source information  
- **Statistics**: Aircraft count timeline *(additional charts planned)* 🚧
- **Coverage**: Signal strength analysis *(heatmaps under construction)* 🚧
- **3D Radar**: Three-dimensional aircraft visualization *(controls under construction)* 🚧

### 🚧 Features Under Construction
Some advanced features are currently in development:
- **Message Rate Charts**: Per-source message rate visualization
- **Signal Strength Distribution**: Signal strength histogram analysis  
- **Altitude Distribution**: Aircraft altitude distribution charts
- **Interactive Heatmaps**: Leaflet.heat-based coverage heatmaps
- **3D Radar Controls**: Interactive 3D view manipulation (reset, auto-rotate, range)
- **Enhanced Error Notifications**: User-friendly toast notifications for issues

## 🔧 Building

### Prerequisites
- Go 1.21 or later
- Make

### Build Commands

```bash
make build          # Build binary
make deb            # Create Debian package  
make docker-build   # Build Docker image
make test           # Run tests
make clean          # Clean artifacts
```

## 🐳 Docker

```bash
# Build
make docker-build

# Run  
docker run -p 8080:8080 -v $(pwd)/config.json:/app/config.json skyview
```

## 📊 API Reference

### REST Endpoints
- `GET /api/aircraft` - All aircraft data
- `GET /api/aircraft/{icao}` - Individual aircraft details
- `GET /api/sources` - Data source information
- `GET /api/stats` - System statistics
- `GET /api/origin` - Map origin configuration
- `GET /api/coverage/{sourceId}` - Coverage analysis
- `GET /api/heatmap/{sourceId}` - Signal heatmap

### WebSocket
- `ws://localhost:8080/ws` - Low-latency updates

## 🛠️ Development

### Project Structure
```
skyview/
├── cmd/skyview/           # Main application
├── assets/                # Embedded static web assets
├── internal/
│   ├── beast/             # Beast format parser
│   ├── modes/             # Mode S decoder  
│   ├── merger/            # Multi-source merger
│   ├── client/            # Beast TCP clients
│   └── server/            # HTTP/WebSocket server
├── debian/                # Debian packaging
└── scripts/               # Build scripts
```

### Development Commands
```bash
make dev            # Run in development mode
make format         # Format code
make lint           # Run linter  
make check          # Run all checks
```

## 📦 Deployment

### Systemd Service (Debian/Ubuntu)
```bash
# Install package
sudo dpkg -i skyview_0.0.3_amd64.deb

# Configure sources in /etc/skyview/config.json
# Start service
sudo systemctl start skyview
sudo systemctl enable skyview

# Check status
sudo systemctl status skyview
sudo journalctl -u skyview -f
```

### Manual Installation
```bash
# Build binary
make build

# Create user and directories
sudo useradd -r -s /bin/false skyview-adsb
sudo mkdir -p /etc/skyview-adsb /var/lib/skyview-adsb /var/log/skyview-adsb
sudo chown skyview-adsb:skyview-adsb /var/lib/skyview-adsb /var/log/skyview-adsb

# Install binary and config
sudo cp build/skyview /usr/bin/
sudo cp build/skyview-data /usr/bin/
sudo cp config.example.json /etc/skyview-adsb/config.json
sudo chown root:skyview-adsb /etc/skyview-adsb/config.json
sudo chmod 640 /etc/skyview-adsb/config.json

# Create systemd service
sudo cp debian/lib/systemd/system/skyview-adsb.service /lib/systemd/system/
sudo cp debian/lib/systemd/system/skyview-database-update.service /lib/systemd/system/
sudo cp debian/lib/systemd/system/skyview-database-update.timer /lib/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable skyview-adsb
sudo systemctl enable skyview-database-update.timer
sudo systemctl start skyview-adsb
sudo systemctl start skyview-database-update.timer
```

### Database Management

SkyView includes powerful database management capabilities through the `skyview-data` command:

```bash
# Update aviation data sources (airlines, airports)
skyview-data update

# Optimize database storage and performance  
skyview-data optimize

# Check database optimization statistics
skyview-data optimize --stats-only

# List available data sources
skyview-data list

# Check current database status
skyview-data status
```

The system automatically:
- Updates aviation databases on service startup
- Runs weekly database updates via systemd timer
- Optimizes storage with VACUUM operations
- Monitors database efficiency and statistics

### Configuration

SkyView supports comprehensive configuration including external aviation data sources:

- **3 External Data Sources**: OpenFlights Airlines (~6,162), OpenFlights Airports (~7,698), OurAirports (~83,557)
- **Database Management**: Automatic optimization, configurable retention, backup settings
- **Privacy Controls**: Privacy mode for air-gapped operation, selective source control
- **Performance Tuning**: Connection pooling, cache settings, update intervals

See **[Configuration Guide](docs/CONFIGURATION.md)** for complete documentation of all options.

## 🔒 Security

The application includes security hardening:
- Runs as unprivileged user
- Restricted filesystem access
- Network isolation where possible
- Systemd security features enabled

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 Contributing

1. Fork the repository
2. Create feature branch  
3. Make changes with tests
4. Submit pull request

## 🆘 Support

- [Issues](https://kode.naiv.no/olemd/skyview/issues)
- [Documentation](https://kode.naiv.no/olemd/skyview/wiki)
- [Configuration Examples](https://kode.naiv.no/olemd/skyview/src/branch/main/examples)

---

**SkyView** - Professional multi-source ADS-B tracking with Beast format support.