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

• Complete Mode S Decoding: Position, velocity, altitude, heading
• Aircraft Identification: Callsign, category, country, registration
• ICAO Country Database: Comprehensive embedded database with 70+ allocations covering 40+ countries
• Multi-source Tracking: Signal strength from each receiver
• Historical Data: Position history and trail visualization

🚀 Quick Start

Using Command Line

# 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

# 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

{
  "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

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

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

🐳 Docker

# 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

make dev            # Run in development mode
make format         # Format code
make lint           # Run linter  
make check          # Run all checks

📦 Deployment

Systemd Service (Debian/Ubuntu)

# 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

# Build binary
make build

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

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

# Create systemd service
sudo cp debian/lib/systemd/system/skyview.service /lib/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable skyview
sudo systemctl start skyview

🔒 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 file for details.

🤝 Contributing

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

🆘 Support

• Issues
• Documentation
• Configuration Examples

---

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