Skip to content

Latest commit

 

History

History
297 lines (198 loc) · 10.5 KB

INSTALL.md

File metadata and controls

297 lines (198 loc) · 10.5 KB

Introduction

This guide provides step-by-step instructions for installing skies-adsb. The instructions outlined here apply to both:

  • New Raspberry Pi installations running 64-bit OS
  • Localhost or headless installations on existing systems

Follow each step carefully to set up the core dependencies and configuration needed to deploy and run the application.

Table of Contents

Prerequisites

Important Notes

  • Unix command line experience is required to build and deploy skies-adsb
  • Follow all installation steps in sequence unless explicitly noted as optional
  • Installation process has been streamlined but requires careful attention to detail

Required Software

  • Git
  • Python 3.x or higher
  • QGIS (for map working with map layers)
  • VSCode recommended for Python/JavaScript development
  • Modern web browser with WebGL support (Chrome/Firefox recommended)

Development Environment

Recommended workstation requirements:

  • Operating System: Linux (Ubuntu/Fedora) or macOS
  • Storage: 5GB free disk space
  • Memory: 8GB RAM minimum
  • CPU: Quad-core processor

Note: Development and testing was done on Ubuntu and Fedora workstations

Step 1 - Clone the skies-adsb repository

On your workstation clone the skies-adsb GitHub repository:

cd /path/to/your/git/projects
git clone https://github.com/machineinteractive/skies-adsb.git

Step 2 - Setup Python environment

This step setups up a Python Virtual Environment with all the dependencies needed to run the Python scripts included with the app.

cd /path/to/skies-adsb
python3 -m venv .venv
source .venv/bin/activate
pip3 install flask flask-cors geopandas osmtogeojson requests websockify
deactivate

Step 3 - Install Node.js and npm

The skies-adsb web app requires Node.js and npm. If you already have these installed, you can skip to Step 7.

For a clean Node.js installation, use nvm (Node Version Manager) - the recommended way to install and manage Node.js:

  1. Install nvm by following the official instructions at:

https://github.com/nvm-sh/nvm

  1. Once nvm is installed, install the latest Node.js version:
nvm install node
  1. Logout and login again before continuing to Step 4

Step 4 - Initialize the Node.js Dependencies

Install required node modules by running:

cd /path/to/skies-adsb
npm install

This will install all dependencies specified in package.json.

Step 5 - Create src/.env File

The src/.env file is used to store numerous environment variables which are necessary for building and running skies-adsb.

cd /path/to/skies-adsb
cp docs/dot-env-template src/.env

Step 6 - Setup Flask Server

The Flask server acts as a proxy for aviation-related APIs to fetch realtime aircraft and weather information.

Create the Flask server configuration file:

cd /path/to/skies-adsb
cp docs/flask-config-template.json flask/config.json

This creates the minimum necessary config.json for the Flask server.

For additional functionality like FlightAware AeroAPI integration to get flight status information, see the instructions in the Flask README.

Note: Use of the FlightAware AeroAPI is optional (paid service):

  • It is required for flight status information
  • It is not needed for basic ADS-B data visualization

Step 7 - Set Your Geolocation Coordinates

The skies-adsb app uses geolocation coordinates as a reference point for:

  • Map layer rendering
  • Aircraft position tracking relative to your ADS-B receiver
  • Distance and bearing calculations

The app does not automatically detect location. You must set these coordinates manually.

To get your coordinates:

  1. Visit OpenStreetMap
  2. Search for your location
  3. Right-click on your exact position
  4. Select "Show address"
  5. Note the latitude and longitude values

Add these coordinates to your /path/to/skies-adsb/src/.env file:

VITE_DEFAULT_ORIGIN_LATITUDE=<DEFAULT ORIGIN LATITUDE>
VITE_DEFAULT_ORIGIN_LONGITUDE=<DEFAULT ORIGIN LONGITUDE>

Example using Miami International Airport (KMIA):

VITE_DEFAULT_ORIGIN_LATITUDE=25.7955406
VITE_DEFAULT_ORIGIN_LONGITUDE=-80.2918816

Step 8 - Download Natural Earth Datasets

skies-adsb uses Natural Earth datasets and FAA Airspace Shapefiles for building map layers. Due to GitHub file size limitations, you must download and install these data files separately by following the steps below.

1:10m Scale Datasets

From https://www.naturalearthdata.com/downloads/10m-cultural-vectors/

  • Click "Download all 10m cultural themes"

From https://www.naturalearthdata.com/downloads/10m-physical-vectors/

  • Click "Download all 10m physical themes"

1:110m Scale Datasets

From https://www.naturalearthdata.com/downloads/110m-cultural-vectors/

  • Click "Download all 110m cultural themes"

From https://www.naturalearthdata.com/downloads/110m-physical-vectors/

  • Click "Download all 110m physical themes"

Copy the files:

  • 10m_cultural.zip
  • 10m_physical.zip
  • 110m_cultural.zip
  • 110m_physical.zip

to the directory:

/path/to/skies-adsb/maps/data

Step 9 - Download FAA Airspace Shapefile

Download the FAA Airspace Shapefile:

  1. Go to FAA Airspace Data
  2. Click "Download"
  3. Choose "Shapefile" format

Save the downloaded Class_Airspace.zip file.

Copy the Class_Airspace.zip file to:

/path/to/skies-adsb/maps/data

Step 10 - Extract the Datasets

The install-datasets.sh script will extract the Natural Earth and FAA Airspace datasets to their required locations for use by the build-map-layers.py script.

cd /path/to/skies-adsb/maps/data
./install-datasets.sh

Step 11 - Build your map layers

This step is necessary to build map layers specific to your ADS-B installation location. Without map layers, you'll only see a skybox and aircraft. If you prefer not to use map layers, the simulation includes a reference polar grid that can be toggled on/off via the settings GUI.

cd /path/to/skies-adsb
cd maps
chmod +x build_map_layers.sh
./build-map-layers.sh

for more information see this document:

Build Map Layers Guide

Custom Map Layers

Examples of custom map layers: Miami International (KMIA), LaGuardia (KLGA), and Mexico City International (MMMX) airports

Reference Polar Grid

Reference Polar Grid

Test your map layers

At this point you can see what your map layers look like by running the following command:

cd /path/to/skies-adsb
npx vite --host

This will launch the Vite development HTTP server.

Step 12 - Configure Visualization Settings

The following table lists the default visualization settings in src/utils.js. These settings control various aspects of the 3D visualization including camera behavior, skybox dimensions, and aircraft tracking parameters.

Constant Default Value Description
DEFAULT_SCALE 1.0 / 250.0 Default scale for geometry
CAMERA_FOV 75 Camera field of view in degrees
CAMERA_NEAR 0.1 Camera Near clipping plane distance
CAMERA_FAR 10000.0 Camera Far clipping plane distance
SKYBOX_RADIUS 3000.0 Radius of the skybox (must be ≤ half of CAMERA_FAR)
FOLLOW_CAM_DISTANCE 24.0 Default follow camera distance from aircraft
POLAR_GRID_RADIUS 3000.0 Radius of the polar grid (should match SKYBOX_RADIUS)
POLAR_GRID_RADIALS 16 Number of radial lines in the polar grid
POLAR_GRID_CIRCLES 5 Number of concentric circles in the polar grid
POLAR_DIVISIONS 64 Number of divisions in the polar grid
POLAR_GRID_COLOR_1 "#81efff" Primary color for polar grid
POLAR_GRID_COLOR_2 "#81efff" Secondary color for polar grid
AIRCRAFT_TTL 15.0 Aircraft time-to-live in seconds
AIRCRAFT_TRAIL_UPDATE_FREQUENCY 75 Trail update frequency based on telemetry update count
AIRCRAFT_MAX_TRAIL_POINTS 5000 Maximum number of points in aircraft trail

These values can be modified in the src/util.js file to adjust the visualization behavior to your preferences. Note that some values are interdependent (e.g., SKYBOX_RADIUS must be less than or equal to half of CAMERA_FAR).

Next Steps

After completing the base installation, follow one of these guides to finalize your setup:

Choose the guide that matches your deployment scenario.