search

sdr-enthusiasts / docker-planefence

GNU General Public License v3.0
96 stars 17 forks source link

readme

Docker-Planefence

What is it?

This repository contains Planefence, which is an add-on to ultrafeeder, readsb, dump1090, or dump1090-fa (referred to herein as your Feeder Station).

Planefence will create a log of aircraft heard by your Feeder Station that are within a "fence", that is, less than a certain distance and lower than a certain altitude from your station. This log is displayed on a website and is also made available in daily CSV files. Furthermore, Planefence can send a notification for every plane in the fence to Mastodon, Discord, and/or Twitter, and with some add-on software/hardware, you will be able to collect noise figures to see how loud the aircraft are that fly above your Feeder Station.

Planefence is deployed as a Docker container and is pre-built for the following architectures:

The Docker container is available at ghcr.io/sdr-enthusiasts/docker-planefence and can be pulled directy using this Docker command: docker pull ghcr.io/sdr-enthusiasts/docker-planefence.

Who is it for?

Here are some assumptions or prerequisites:

Install PlaneFence - Prerequisites

Note - this guide assumes that /home/pi is your home directory. If it is not (for example, Ubuntu builds use /home/ubuntu as their default account), please change all mentions of /home/pi to the applicable home directory path.

There must already be an instance of ultrafeeder, tar1090, dump1090[-fa], or readsb connected to a SDR somewhere in reach of your Planefence machine:

Getting ready

  1. If you are adding this to an existing stack of Docker containers on your machine, you can add the information from this project to your existing docker-compose.yml.
  2. If you are not adding this to an existing container stack, you should create a project directory: sudo mkdir -p /opt/planefence && sudo chmod a+rwx /opt/planefence && cd /opt/planefence . Then add a new docker-compose.yml there.
  3. Get the template docker-compose.yml file from here:
curl -s https://raw.githubusercontent.com/sdr-enthusiasts/docker-planefence/main/docker-compose.yml > docker-compose.yml

Planefence Configuration

Initial docker configuration

In the docker-compose.yml file, you should configure the following:

Planefence Settings Configuration

Plane-Alert Exclusions

In some circumstances you may wish to blacklist certain planes, or types of planes, from appearing in Plane-Alert and its Mastodon and Discord posts. This may be desireable if, for example, you're located near a military flight training base, where you could be flooded with dozens of notifications about T-6 Texan training aircraft every day, which could drown out more interesting planes. To that end, excluding planes can be accomplished using the PA_EXCLUSIONS= parameter in /opt/adsb/planefence/config/planefence.config. Currently, you may exclude whole ICAO Types (such as TEX2 to remove all T-6 Texans), specific ICAO hexes (e.g. AE1ECB), specific registrations and tail codes (e.g. N24HD or 92-03327), or any freeform string (e.g. UC-12, Mayweather, Kid Rock). Multiple exclusions should be separated by commas. Exclusions are case insensitive and spaces must be escaped with a slash \. An example:

PA_EXCLUSIONS=tex2,AE06D9,ae27fe,Floyd\ Mayweather,UC-12W

This would exclude all T-6 Texans, the planes with ICAO hexes AE06D9 (a Marine Corps UC-12F Huron) and AE27FE (a Coast Guard MH-60T), any planes with "Floyd Mayweather" anywhere in the database entry, and any planes with "UC-12W" anywhere in the database entry. URLs and image links are intentionally not searched.

Please note: this is a powerful feature which may produce unintended consequences. You should verify that it's working correctly by examining the container logs after making changes to planefence.config. You should see, e.g.:

tex2 appears to be an ICAO type and is valid, entries excluded: 479
AE06D9 appears to be an ICAO hex and is valid, entries excluded: 1
ae27fe appears to be an ICAO hex and is valid, entries excluded: 1
Floyd Mayweather appears to be a freeform search pattern, entries excluded: 1
UC-12W appears to be a freeform search pattern, entries excluded: 8
490 entries excluded.

Also note that after adding exclusions, any pre-existing entries for those excluded planes in your Plane Alert web user interface will not be entirely removed, but some fields will disappear. If you've made a mistake and revert your exclusion changes to planefence.config, affected entries in your web user interface will be fully restored after a few minutes.

Applying your setup

What does it look like when it's running?

API access to your data

Introduction

Planefence and Plane-Alert keep a limited amount of data available. By default, PlaneFence keeps 2 weeks of data around, while Plane-Alert isn't time limited. This data is accessible using a REST interface that makes use of HTTP GET. You can access this API from the directory where your Planefence or Plane-Alert web pages are deployed. For example:

API parameters and usage examples

The Planefence and Plane-Alert APIs accept awk-style Regular Expressions as arguments. For example, a tail number starting with N, followed by 1 digit, followed by 1 or more digits or letters would be represented by this RegEx: n[0-9][0-9A-Z]* . Query arguments are case-insensitive: looking for n or for N yields the same results. Each query must contain at least one of the parameters listed below. Optionally, the type parameter indicates the output type. Accepted values are json or csv; if omitted, json is the default value. (These argument values must be provided in lowercase.) Note that the call parameter (see below) will start with @ followed by the call (tail number or flight number as reported via ADS-B/MLAT/UAT) if the entry was tweeted. So make sure to start your call query with ^@? to include both tweeted an non-tweeted calls.

Planefence Query parameters

Parameter Description Example
hex Hex ID to return https://planeboston.com/planefence/pf_query.php?hex=^A[AB][A-F0-9]*&type=csv returns a CSV with any Planefence records of which the Hex IDs that start with A, followed by A or B, followed by 0 or more hexadecimal digits
tail Call sign (flight number or tail) to return https://planeboston.com/planefence/pf_query.php?call=^@?AAL[0-9]*&type=json returns any flights of which the call starts with "AAL" or "@AAL" followed by only numbers. (Note - the call value will start with @ if the entry was tweeted, in which case the tweet_url field contains a link to the tweet.)
start Start time, format yyyy/MM/dd hh:mm:ss https://planeboston.com/planefence/pf_query.php?start=2021/12/19.*&type=csv returns all entries that started on Dec 19, 2021.
end End time, format yyyy/MM/dd hh:mm:ss https://planeboston.com/planefence/pf_query.php?end=2021/12/19.*&type=csv returns all entries that ended on Dec 19, 2021.

Plane-Alert Query parameters

Parameter Description Example
hex Hex ID to return https://planeboston.com/plane-alert/pa_query.php?hex=^A[EF][A-F0-9]*&type=csv returns a CSV with any Planefence records of which the Hex IDs that start with A, followed by E or F, followed by 0 or more hexadecimal digits. (Note - this query returns most US military planes!)
tail Tail number of the aircraft https://planeboston.com/plane-alert/pa_query.php?tail=N14[0-9]NE&type=csv returns any records of which the tail starts with "N14", followed by 1 digit, followed by "NE".
name Aircraft owner's name https://planeboston.com/plane-alert/pa_query.php?name=%20Life\|%20MedFlight&type=csv returns any records that have " Life" or " MedFlight" in the owner's name.
equipment Equipment make and model https://planeboston.com/plane-alert/pa_query.php?equipment=EuroCopter returns any records of which the equipment contains the word "EuroCopter"
timestamp Time first seen, format yyyy/MM/dd hh:mm:ss https://planeboston.com/plane-alert/pa_query.php?timestamp=2022/01/03 returns any records from Jan 3, 2022.
call Callsign as reported by aircraft https://planeboston.com/plane-alert/pa_query.php?call=SAM returns any records of which the callsign contains "SAM".
lat Latitude first observation, in decimal degrees https://planeboston.com/plane-alert/pa_query.php?lat=^43 returns any records of which the latitude starts with "43" (i.e., 43 deg N)
lon Longitude first observation, in decimal degrees https://planeboston.com/plane-alert/pa_query.php?lon=^-68 returns any records of which the longitude starts with "-68" (i.e., 68 deg W)

Troubleshooting

Getting help

That's all!