DEVELOPMENT.md

Introduction

This document describes how to setup a development environment to hack on skies-adsb.

Table of Contents

• Introduction
• Table of Contents
• Prerequisites
• Application Architecture
  • The application consists of three main components:
    • Web Frontend (skies-adsb/src)
    • Backend Service (skies-adsb/flask)
    • Map Generator (skies-adsb/maps)
• Tech Stack
  • Languages
  • Frameworks
  • Development Tools
  • Key Libraries
  • Assets
• Contributing to skies-adsb
• Development Environment Setup
  • Available npm scripts
• HOWTO
  • Updating the Web App
  • Updating the Flask app and RPI System services
• Notes

Prerequisites

This guide assumes that you have set up your local environment as described here:

INSTALL.md

Please follow the steps in the install guide above before continuing.

Application Architecture

The primary goal of this project was to create 1980s-style 3D vector graphic visualization of ADS-B data. Think Alien, Escape From New York, Max Headroom, and WarGames.

skies-adsb focuses on simplicity and avoids replicating features of existing plane tracking web apps. Its core principles are:

• minimize complexity
• minimize dependencies
• utilize free and open-source software (FOSS) data, libraries, and tools
• provide equal support for desktop and mobile
• run on any WebGL-capable browser

The application consists of three main components:

Web Frontend (skies-adsb/src)

• Three.js-based 3D visualization of aircraft ADS-B data
• Interactive user controls and UI elements

Backend Service (skies-adsb/flask)

• Flight status and summary data proxy
• METAR weather proxy

Map Generator (skies-adsb/maps)

• Generates GeoJSON map layers from Natural Earth, FAA, and OpenStreetMap data

Tech Stack

Languages

• JavaScript
• HTML5
• CSS
• Python 3

Frameworks

• three.js - 3D graphics library
• Flask - Python web framework

Development Tools

• VScode - Code editor
• Vite - Build tool
• npm - Package manager
• nvm - Node version manager

Key Libraries

• GeoPandas - Geospatial data handling
• GSAP - Animation
• sphericalmercator - Map projections
• dat.gui - UI controls
• stats.js - Performance monitoring
• Troika Text - Three.js text rendering

Assets

• Fonts
  • IBM Plex Mono
  • Orbitron
• Material Icons

Contributing to skies-adsb

If you wish to contribute to skies-adsb please fork the project and submit changes via pull-requests.

Development Environment Setup

1. Install and configure VSCode

• Recommended for JavaScript development and Python virtual environments
• Excellent integration with project tooling
• Download from: https://code.visualstudio.com/

2. Follow the Localhost+Headless Setup Guide here: Localhost+Headless Setup Guide

3. Once setup is complete, start the development server:

cd /path/to/skies-adsb
./use_existing_adsb.sh

This will launch the application in development mode with live reload enabled.

Available npm scripts

Start the Vite development server:

npm run dev

Build the skies-adsb web app for distribution:

npm run build

Start the Flask app development server

npm run dev-flask

HOWTO

Updating the Web App

If you make local changes to the skies-adsb web app and want to deploy them to your Raspberry Pi, follow these steps:

1. Build your maps:

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

2. Build the web app:

cd /path/to/skies-adsb
npm run build

3. Deploy the web app:

cd /path/to/skies-adsb
./deploy_web_app.sh

Updating the Flask app and RPI System services

To update the Flask app or services on your RPI:

cd /path/to/skies-adsb/raspberrypi
./update_flask_app.sh

Notes

For information about working with the Flask app please see the Flask app README:

Flask App README