This document describes how to setup and deploy the skies-adsb app to a Raspberry Pi Zero 2 W (or newer 64-bit Raspberry Pi model) connected to a RTL-SDR receiver on your home network.
Note: if you have an existing RPI ADS-B installation this guide will make changes to the RPI setup. If you do not wish to alter your RPI setup then please use the Localhost+Headless Setup Guide instead.
Note: skies-adsb was developed under Linux. This document assumes your workstation is running Linux or macOS.
- Introduction
- Terms Used
- What You Will Need & Shopping List
- Hardware and reference materials used to build this project
- Step 1 - Prerequisites
- Step 2 - Raspberry Pi (RPI) Setup
- Step 3 - Setup src/.env file variables
- Step 4 - Choose and Configure ADS-B Driver
- Step 5 - Deploy and run the RPI skies-adsb install-skies-adsb.sh Script
- Step 6 - Connect your RTL-SDR receiver
- Step 7 - Build and Deploy the skies-adsb web app to the Raspberry Pi
- Step 8 - Test the skies-adsb Installation
| Term | Meaning |
|---|---|
| RPI | Raspberry Pi |
| Default RPI Username | pi |
| Default RPI Hostname | raspberrypi.local |
| Default RPI IP Address | 192.168.1.123 |
The minimum hardware needed to build this project is:
- 1 Raspberry Pi Zero 2 W or newer 64-bit Raspberry Pi model
- 1 32gb microSD card
- 1 RTL-SDR Receiver that works with readsb or dump1090-mutability
- 1 ADS-B 1090MHz Antenna (see recommendations below)
- a Linux or Mac workstation for Raspberry Pi setup
NOTE: If you wish to keep the costs as low as possible (and get the best reception), then I suggest using a Raspberry Pi Zero 2 W kit combined with the ADSBexchange.com Blue R820T2 RTL2832U kit.
| Amount | Item |
|---|---|
| 1 | 5.5dBi 1090/978 N-Type Female Antenna - 26-inch |
| 1 | 10ft SMA Male to N Male Pure Cable |
| 1 | IP54 Waterproof Box with Large Capacity Outdoor Weatherproof Box |
This guide assumes that you have set up your local environment as described here:
Please follow the steps in the install guide above before continuing.
Follow the RPI OS installation instructions here:
NOTE: THE SETUP INSTRUCTIONS WILL ASSUME YOU ARE USING THE RASPBERRY PI IMAGER
I strongly suggest using the RPI Imager to do the initial installation as this will save you time with the initial setup.
You must use the 64-bit version of Raspberry Pi OS. I recommend using Raspberry Pi OS Lite as no GUI is needed.
For this project I am using:
- Raspberry Pi Zero 2 W
- Raspberry Pi 3
Both are running Raspberry Pi OS Lite (64-bit)
NOTE: For purposes of the setup tutorial I'm assuming the default RPI username and hostname are used:
username: pi
hostname: raspberrypi.local
ip: 192.168.1.123
From the Raspberry Pi Imager:
- Choose your destination device
- Select the 64-bit Raspberry Pi OS Lite as your OS image
- Select your Storage
- Press Next
- You will be presented with a dialog "Use OS customization"
- Press "Edit Settings"
- Set the hostname to something like: raspberrypi.local
- Set your username and password. You must use the username: pi
- Configure your wireless LAN
- Set the locale settings. Make sure you set your Time zone and Keyboard layout.
- Press Save
Once you have written your image then boot and log into your RPI.
Boot your RPI. Verify that you can ssh into your RPI:
Once you login determine which IP address has been assigned to your RPI using the hostname command as follows:
hostname -I
and write down this IP address. It will be needed for setting up the skies-adsb web app.
You can also check for your IP address from a Linux or Mac workstation with the following command:
# assuming network at 192.168.1.0 - change as needed to match yours
nmap -sn 192.168.1.0/24
This command will print out a list of devices with their hostname and IP address that are present on your local network. Replace the subnet with your subnet as needed.
The src/.env file contains environment variables used to build and deploy the skies-adsb web app. These variables control various aspects of the application's behavior and deployment settings.
Start by creating a src/.env file with the required variables needed to get the app running. The optional variables can be added later once basic functionality is working.
Please refer to the tables below for descriptions of what each variable does.
Create a src/.env file with these minimum required variables:
VITE_DEFAULT_ORIGIN_LATITUDE=<YOUR LATITUDE>
VITE_DEFAULT_ORIGIN_LONGITUDE=<YOUR LONGITUDE>
VITE_SKIES_ADSB_RPI_USERNAME=<Default RPI username>
VITE_SKIES_ADSB_RPI_HOST=<Default RPI IP address>VITE_DEFAULT_ORIGIN_LATITUDE=25.7919
VITE_DEFAULT_ORIGIN_LONGITUDE=-80.2871
VITE_SKIES_ADSB_RPI_USERNAME=pi
VITE_SKIES_ADSB_RPI_HOST=192.168.1.123
# set default skybox to night
VITE_SETTINGS_DEFAULT_SKYBOX=NIGHT
# by default do not show all aircraft trails at the same time
VITE_SETTINGS_SHOW_ALL_TRAILS=false
# by default do not show roads
VITE_SETTINGS_SHOW_ROADS=false| Variable Name | Explanation | Value | Default | Platform | Example |
|---|---|---|---|---|---|
| VITE_DEFAULT_ORIGIN_LATITUDE | Default latitude for default origin location (from Step 1) | number | none | All | 25.7919 |
| VITE_DEFAULT_ORIGIN_LONGITUDE | Default longitude for default origin location (from Step 1) | number | none | All | -80.2871 |
| VITE_SKIES_ADSB_RPI_USERNAME | Default RPI username with sudo privileges | string | pi | RPI | pi |
| VITE_SKIES_ADSB_RPI_HOST | Default RPI IP address | string | none | RPI | 192.168.1.123 |
| Variable Name | Explanation | Value | Default |
|---|---|---|---|
| VITE_SETTINGS_DEFAULT_SKYBOX | Set Default Skybox Theme | string (DAWN_DUSK, DAY, or NIGHT) | DAWN_DUSK |
| VITE_SETTINGS_SHOW_ALL_TRAILS | Controls visibility of aircraft trails for all tracked flights | boolean | true |
| VITE_SETTINGS_SHOW_AERODROMES | Controls visibility of aerodrome and runways locations | boolean | true |
| VITE_SETTINGS_SHOW_ORIGINS | Controls display of origin name labels | boolean | true |
| VITE_SETTINGS_SHOW_AIRSPACE_CLASS_B | Controls visibility of Class B airspace boundaries | boolean | true |
| VITE_SETTINGS_SHOW_AIRSPACE_CLASS_C | Controls visibility of Class C airspace boundaries | boolean | true |
| VITE_SETTINGS_SHOW_AIRSPACE_CLASS_D | Controls visibility of Class D airspace boundaries | boolean | true |
| VITE_SETTINGS_SHOW_URBAN_AREAS | Controls display of urban area boundaries | boolean | true |
| VITE_SETTINGS_SHOW_ROADS | Controls visibility of major roads and highways | boolean | true |
| VITE_SETTINGS_SHOW_LAKES | Controls visibility of lakes and large water bodies | boolean | true |
| VITE_SETTINGS_SHOW_RIVERS | Controls visibility of rivers and waterways | boolean | true |
| VITE_SETTINGS_SHOW_STATES_PROVINCES | Controls display of state/province boundaries | boolean | true |
| VITE_SETTINGS_SHOW_COUNTIES | Controls visibility of county boundaries | boolean | true |
You have three driver options for the RTL-SDR:
- dump1090-mutability (default) - Included in Raspberry Pi OS
- readsb - More modern (actively developed) driver - Not included with Raspberry Pi OS but compatible and easily installed
- existing - Use an existing receiver
This driver comes preinstalled with Raspberry Pi OS (Raspbian). It works out of the box with minimal configuration needed. You can customize settings after installation if desired - see the configuration section below.
The dump1090-mutability driver provides basic ADS-B decoding capabilities and is a good choice for getting started quickly.
This is an actively developed and modern RTL-SDR driver that works with Debian-based systems like Raspberry Pi OS. The default configuration works well out of the box, though it can be customized if needed (see documentation links below).
Important Note for RTL-SDR Blog V4 SDR Users: If you're using a RTL-SDR Blog V4 SDR, you'll need to install additional drivers first:
- See installation instructions at:
- https://github.com/wiedehopf/adsb-scripts/wiki/Automatic-installation-for-readsb#installation
- https://www.rtl-sdr.com/V4/
Note: In outdoor setups, readsb has shown better reliability with fewer dropped positions compared to dump1090-mutability.
The skies-adsb app works with any receiver that outputs SBS BaseStation formatted data on a TCP socket. To use an existing receiver, you'll need its IP address and SBS output port number.
For example, if your receiver outputs SBS data on IP 192.168.1.100 port 30003, you would use:
./install-skies-adsb.sh -e 192.168.1.100:30003This will configure skies-adsb to receive data from your existing ADS-B receiver instead of setting up a new RTL-SDR receiver.
With the .env file created in step 3 you are ready to set up the RPI to host the skies-adsb app.
Copy the setup files over to the RPI as follows:
cd /path/to/skies-adsb/raspberrypi
chmod +x deploy.sh
./deploy.shSSH into the RPI and run the install-skies-adsb.sh script:
This script will setup the RPI to run skies-adsb.
NOTE: by default the install script will update and upgrade your Raspberry Pi before installing dependencies.
| Command | Description | Optional Argument |
|---|---|---|
| -s | Skip Raspberry Pi update + upgade | none |
| -d | Install RTL-SDR dump1090-mutability driver - Basic ADS-B decoder included with Raspberry Pi OS | none |
| -r | Install RTL-SDR readsb driver - Modern, actively developed ADS-B decoder with enhanced features | none |
| -e | Use existing ADS-B receiver | <ADS-B RECEIVER IP ADDRESS>:<SBS PORT> |
Example Install with dump1090-mutability driver:
./install-skies-adsb.sh -dExample Install with readsb driver:
./install-skies-adsb.sh -rExample Use existing ADS-B receiver:
./install-skies-adsb.sh -e <ADS-B RECEIVER IP ADDRESS>:<SBS PORT>
example:
./install-skies-adsb.sh -e 192.168.1.123:30003Example multiple arguments skip upgrade and install readsb driver:
./install-skies-adsb.sh -s -rIf you selected the option:
./install-skies-adsb.sh -dAt some point in the installation process the dump1090-mutability config dialog will pop up:
be sure to select "Yes" for "Start dump1090 automatically". If you make a mistake you can always re-run the dump1090-mutability setup as follows from the RPI:
sudo dpkg-reconfigure dump1090-mutabilityWhen the install-skies-adsb.sh script finishes it will reboot the RPI. When the RPI boots up again ssh into the RPI and verify that the flask and websocket proxy are listening on ports 5000 and 30006 respectively.
ssh [email protected]
ss -tlpyou should see an output similar to the one below:
State Recv-Q Send-Q Local Address:Port Peer Address:Port Process
LISTEN 0 128 0.0.0.0:5000 0.0.0.0:_ users:(("flask",pid=499,fd=5),("flask",pid=499,fd=3))
LISTEN 0 1024 0.0.0.0:http 0.0.0.0:_
LISTEN 0 100 0.0.0.0:30006 0.0.0.0:_ users:(("websockify",pid=572,fd=3))
LISTEN 0 128 0.0.0.0:ssh 0.0.0.0:_
LISTEN 0 1024 [::]:http [::]:_
LISTEN 0 128 [::]:ssh [::]:_You can also verify the skies-adsb and skies-flask services are running as follows:
ssh [email protected]
sudo systemctl status skies-adsb-websockify
sudo systemctl status skies-adsb-flaskfor more detailed service logs you can issue the following commands:
ssh [email protected]
sudo journalctl -u skies-adsb-websockify
sudo journalctl -u skies-adsb-flaskNow lets setup your RTL-SDR receiver.
If you did not install a RTL-SDR driver in Step 5 you can skip this step and proceed to Step 7
By using a R820T2 based RTL-SDR receiver everything should work out of the box thanks to the readsb or dump1090-mutability package installed on the RPI in Step 5.
Now lets verify that the receiver works.
Shutdown the RPI:
ssh [email protected]
sudo shutdown -h nowonce the RPI is shutdown:
- disconnected the power
- plug in your RTL-SDR device to any of the available USB ports on the RPI.
- reconnect the power
Once the RPI boots up you can verify that the RLT-SDR receiver ADS-B data is being decoded using netcat:
ssh [email protected]
sudo apt install -y netcat-openbsd
nc localhost 30003you should see a stream of raw ADS-B data. Press CTRL-C to stop.
alternatively you can just verify that the ports 30001 to 30005 are listening for connections:
ssh [email protected]
ss -tlpyou should see something like:
LISTEN 0 1024 0.0.0.0:80 0.0.0.0:*
LISTEN 0 511 127.0.0.1:30104 0.0.0.0:*
LISTEN 0 100 0.0.0.0:30006 0.0.0.0:* users:(("websockify",pid=460,fd=3))
LISTEN 0 128 0.0.0.0:22 0.0.0.0:*
LISTEN 0 128 0.0.0.0:5000 0.0.0.0:* users:(("flask",pid=464,fd=3))
LISTEN 0 511 127.0.0.1:30001 0.0.0.0:*
LISTEN 0 511 127.0.0.1:30003 0.0.0.0:*
LISTEN 0 511 127.0.0.1:30002 0.0.0.0:*
LISTEN 0 511 127.0.0.1:30005 0.0.0.0:*
LISTEN 0 511 127.0.0.1:30004 0.0.0.0:*
LISTEN 0 1024 [::]:80 [::]:*
LISTEN 0 128 [::]:22 [::]:*Now lets setup the workstation build environment so we can build and deploy the skies-adsb web app.
NOTE: This step is only if you installed the dump1090-mutability package.
By default, dump1090-mutability only accepts connections from localhost. To allow connections to port 30003 from other machines on your network, follow these steps to reconfigure dump1090-mutability:
ssh [email protected]
sudo dpkg-reconfigure dump1090-mutabilityWARNING: Only modify these settings if you understand the security implications of allowing remote connections.
be sure to select "Yes" for "Start dump1090 automatically".
Continue the configuration with the default settings (unless you know what you are doing) and you will reach the following screen:
Clear out the value there so it looks like this:
press OK and continue with the dump1090-mutability configuration.
Once the configuration is finished you can verify that dump1090-mutability can be accessed remotely as follows:
ssh [email protected]
ss -tlpYou should see something like:
State Recv-Q Send-Q Local Address:Port Peer Address:Port Process
LISTEN 0 1024 0.0.0.0:80 0.0.0.0:*
LISTEN 0 511 0.0.0.0:30005 0.0.0.0:*
LISTEN 0 511 0.0.0.0:30004 0.0.0.0:*
LISTEN 0 100 0.0.0.0:30006 0.0.0.0:* users:(("websockify",pid=460,fd=3))
LISTEN 0 511 0.0.0.0:30001 0.0.0.0:*
LISTEN 0 511 0.0.0.0:30003 0.0.0.0:*
LISTEN 0 511 0.0.0.0:30002 0.0.0.0:*
LISTEN 0 128 0.0.0.0:22 0.0.0.0:*
LISTEN 0 128 0.0.0.0:5000 0.0.0.0:* users:(("flask",pid=464,fd=3))
LISTEN 0 511 0.0.0.0:30104 0.0.0.0:*
LISTEN 0 1024 [::]:80 [::]:*
LISTEN 0 511 [::]:30005 [::]:*
LISTEN 0 511 [::]:30004 [::]:*
LISTEN 0 511 [::]:30001 [::]:*
LISTEN 0 511 [::]:30003 [::]:*
LISTEN 0 511 [::]:30002 [::]:*
LISTEN 0 128 [::]:22 [::]:*
LISTEN 0 511 [::]:30104 [::]:*Build the skies-adsb web app as follows:
cd /path/to/skies-adsb
npm run buildwhen the "npm run build" script is finished you can deploy the web app to the RPI as follows:
cd /path/to/skies-adsb
chmod +x deploy_web_app.sh
./deploy_web_app.shThe default skies-adsb web root directory is /var/www/html/skies-adsb. You can customize this by modifying the WEBROOT variable in deploy_web_app.sh:
WEBROOT="/var/www/html/skies-adsb"Change this path as needed for your environment.
At this point from your workstation you should be able to open a web browser and navigate to:
http://raspberrypi.local/skies-adsbNOTE: The app works on all of the recent versions of the major browsers: Chrome (Desktop+Mobile), Firefox (Desktop), and Safari (Desktop+Mobile).
and you should see either:
- A wireframe map showing your local geography and points of interest, or
- A wireframe reference grid at the center of the display
You may or may not see any air traffic depending on your geographic location.
If you see no air traffic, check that:
- Your RTL-SDR receiver is properly connected and receiving signals
- You have correctly set your latitude/longitude coordinates as described in Step 1
- There are aircraft flying within range of your receiver (typically 50-150 miles depending on conditions)
You can verify signal reception by checking the raw ADS-B data feed:
ssh [email protected]
nc localhost 30003If you see data flowing, the receiver is working. If not, try:
- Moving the antenna to a better location
- Using a longer antenna cable to place it higher
- Checking RTL-SDR connections
At this point feel free to take your setup outside, enjoy the outdoors, and do some plane spotting.
I hope you enjoy using the app.