Skip to content

Latest commit

 

History

History
272 lines (202 loc) · 10.3 KB

README.md

File metadata and controls

272 lines (202 loc) · 10.3 KB

dump1090 Real-Time Signal Statistics (signalstats1090)

PyPI PyPI - Python Version PyPI - License

This project provides a web application for real-time monitoring of ADS-B messages using dump1090 to help you with optimizing reception performance. The application computes and displays message rates, signal strength, distance statistics, and coverage statistics. It also provides a radar chart showing the distribution of messages by distance and bearing.

How to use the dashboard

Once you've installed the dashboard application, you can access it by opening a web browser and navigating to the URL where the application is running. The default URL is http://localhost:8000 if you are running the application on the local machine. If you are running the application on a different machine, replace localhost with the IP address or hostname of the machine where the application is running, e.g. http://mypiaware:8000.

Using the dashboard you can tune the gain of your receiver to optimize the reception performance. The goal is to maximize the number of messages received while keeping the signal strength within a reasonable range. The radar chart shows the distribution of messages by distance and bearing, which can help you identify areas with poor reception. dump109-fa provides a built-in feature to adjust the gain automatically, but you can also adjust it manually based on the statistics provided by the dashboard. Also try setting the gain to zero. Once you've modified the gain, restart dump1090 to apply the changes and then observe the statistics on the dashboard. Automatic gain adjustment can take several minutes to stabilize, so be patient.

Features

  • Message Rate Statistics: Computes and displays message rates over different intervals (5s, 15s, 30s, 60s, 300s).
  • Signal Strength Statistics: Computes and displays minimum, maximum, and average signal strength over 30 seconds.
  • Distance Statistics: Computes and displays minimum, maximum, and percentile distances over 30 seconds.
  • Coverage Statistics: Displays coverage statistics in a radar chart, showing the distribution of messages by distance and bearing.
  • RSSI/Distance Ratio: Displays the ratio of RSSI to distance for each bearing segment.

Screenshot

Getting Started

Prerequisites

  • dump1090 running on the same machine or accessible via network.
  • Python 3.10+ installed on your machine. Note: Raspbian typically comes with Python pre-installed. Also ensure that support for venv is installed (sudo apt-get install python3-venv).
  • Find out the latitude and longitude of your antenna. You can use Google Maps or similar services to find this information. Mode-S/ADS-B messages only contain partial position information, so the application needs the antenna location to compute the geo-coordinates of aircraft.

Installation

The app can be run on the same Raspberry Pi that runs dump1090 or on a different machine. If you are running dump1090 on a different machine, you need to specify the host and port of the dump1090 server when running the application.

There are three described options to install and run the application:

Raspberry Pi Installation (as a service)

To install and run the application as a service on Raspberry Pi, you can use the provided setup script. First, ensure that the the Prequisites are met. Then follow the steps below:

1. Download the setup script
wget -qO- https://raw.githubusercontent.com/clemensv/signalstats1090/main/setup.sh > ~/signalstats1090_setup.sh
chmod +x ~/signalstats1090_setup.sh
2. Install and start the service

Call the script with the required arguments and any optional arguments you want to set. The script will install the package and create a systemd service that starts the web server automatically at boot.

~/signalstats1090_setup.sh install --antenna-lat <antenna_lat> --antenna-lon <antenna_lon>

Replace <antenna_lat> and <antenna_lon> with the coordinates of your receiver.
If dump1090 is running on a remote host, adjust the --dump1090-host and --dump1090-port as needed.
The script creates a systemd service that starts automatically at boot.

All arguments for the setup script

  • --host: Host to run the web server on (default: 0.0.0.0).
  • --port: Port to run the web server on (default: 8000).
  • --antenna-lat: Latitude of the antenna (required).
  • --antenna-lon: Longitude of the antenna (required).
  • --dump1090-host: Host running dump1090 (default: localhost).
  • --dump1090-port: Port for dump1090 (default: 30005).
3. Start the service

After the installation, you can start the service and verify that it's running using the following commands:

sudo systemctl start signalstats1090
sudo systemctl status signalstats1090
4. Access the dashboard

Open a web browser and navigate to the URL where the application is running. The default URL is http://localhost:8000 if you are running the application on the local machine. If you are running the application on a different machine, replace localhost with the IP address or hostname of the machine where the application is running, e.g. http://mypiaware:8000.

5. Update or uninstall the service

You can always update the service package to the latest version by running:

~/signalstats1090_setup.sh update

To uninstall the service, run:

~/signalstats1090_setup.sh uninstall

Raspberry Pi Installation (as an app)

On Raspberry Pi, ensure Python 3 is installed (usually pre-installed on Raspbian). Then create a virtual environment in your home directory and install the package into it:

sudo apt-get update
sudo apt-get install python3-venv
python3 -m venv ~/signalstats1090
source ~/signalstats1090/bin/activate
pip install signalstats1090

Once installed, you can run the application using:

signalstats1090 run --antenna-lat <antenna_lat> --antenna-lon <antenna_lon>

The app supports the following commands and options:

Commands:

  • run: Run the web server.
  • config: Set default values for command line arguments for the run command.

Options:

  • --host: Host to run the web server on (default: 0.0.0.0).
  • --port: Port to run the web server on (default: 8000).
  • --antenna-lat: Antenna latitude (required for running the server).
  • --antenna-lon: Antenna longitude (required for running the server).
  • --dump1090-host: Host running dump1090 (default: localhost).
  • --dump1090-port: Port for dump1090 (default: 30005).

With the config command, you can permanently set the default values for the command line arguments. This way, you don't have to specify them every time you run the application:

signalstats1090 config --antenna-lat <antenna_lat> --antenna-lon <antenna_lon>

Then you can run the application without specifying the --antenna-lat and --antenna-lon arguments:

signalstats1090 run

When starting a new session, activate the virtual environment again before running the app.

source ~/signalstats1090/bin/activate

To uninstall the application, simply remove the directory:

rm -rf ~/signalstats1090

Installation Elsewhere

If you want to run the application on a Mac or PC or anywhere else you have Python installed, you can follow these steps:

1. Install the package

With all the Prequisites met, you can install the package using:

pip install signalstats1090

If you cloned the Git repository, and you want to play around with the code you can install the package from the local directory as editable using pip install -e ..

2. Run the server

Run the server using the following command:

signalstats1090 run --antenna-lat <antenna_lat> --antenna-lon <antenna_lon> --dump1090-host <dump1090_host>

The --antenna-lat and --antenna-lon arguments are required. You can find the latitude and longitude of your antenna using Google Maps or similar services.

If dump1090 is running on a different host, you can specify the --dump1090-host and --dump1090-port arguments. The default host is localhost and the default port is 30005 (the default port for Beast output).

If you need to run the web server on a different host or port, you can specify the --host and --port arguments. The default host is 0.0.0.0 which listens on all interfaces. The default port is 8000.

signalstats1090 run --host <host> --port <port> --antenna-lat <antenna_lat> --antenna-lon <antenna_lon> --dump1090-host <dump1090_host> --dump1090-port <dump1090_port>
3. Access the dashboard

Open a web browser and navigate to the URL where the application is running. The default URL is http://localhost:8000 if you are running the application on the local machine. If you are running the application on a different machine, replace localhost with the IP address or hostname of the machine where the application is running, e.g. http://mypiaware:8000.

Charts

  • Message Rate Chart: Displays message rates over different intervals (5s, 15s, 30s, 60s, 300s).
  • Signal Strength Chart: Displays minimum, average, and maximum signal strength over 30 seconds.
  • Distance Chart: Displays minimum, maximum, and percentile distances over 30 seconds.
  • Distance Histogram Chart: Displays the count of position readings in 30km buckets (up to 300km).
  • Coverage Chart: Displays coverage statistics in a radar chart, showing the distribution of messages by distance and bearing.
  • RSSI/Distance Ratio Chart: Displays the ratio of RSSI to distance for each bearing segment.

License

This project is licensed under the MIT License.