adsb-ultrafeeder is a ADS-B data collector container that can be used to:

• retrieve ADS-B data from your SDR or other device
• display it on a local map, including options to show tracks, heatmaps, and system performance graphs
• forward the data to one or more aggregators using BEAST/BEAST-REDUCE/BEAST-REDUCE-PLUS format
• send MLAT data to these aggregators
• receive and consolidate MLAT results data (built-in mlathub)
• Interface with external visualization tools such as Grafana using statistics data available in InfluxDB and Prometheus format

In order to accomplish this, the container makes use of the following underlying technologies:

• SDR-Enthusiasts Docker Base-Image
• Wiedehopf's branch of readsb
• Wiedehopf's tar1090 graphical interface
• Wiedehopf's graphs1090
• MLAT Client

It builds and runs on linux/amd64, linux/arm/v7 (linux/armhf) and linux/arm64 architectures.

• An example docker-compose.yml file can be found in this repository.
• The accompanying environment variable values are defined in the .env file in this repository

Once you have installed Docker, you can follow these lines of code to get up and running in very little time:

sudo mkdir -p -m 777 /opt/adsb
cd /opt/adsb
wget https://raw.githubusercontent.com/sdr-enthusiasts/docker-adsb-ultrafeeder/main/docker-compose.yml
wget https://raw.githubusercontent.com/sdr-enthusiasts/docker-adsb-ultrafeeder/main/.env

Then edit the docker-compose.yml and .env files and make any changes as needed. Please configure ALL variables in .env:

nano docker-compose.yml
nano .env

Finally, bring up the stack. This may take a minute as it will automatically download the container and start it up:

docker compose up -d

Some common ports are as follows (which may or may not be in use depending on your configuration):

The container's web interface is rendered to port 80 in the container. This can me mapped to a port on the host using the docker-compose ports directive. In the example above, the container's website is made available at port 8078 on the host system.

Json position output:

• outputs an aircraft object for every new position received for an aircraft if the --json-trace-interval has elapsed for that aircraft
• to make it output every received position, set READSB_JSON_TRACE_INTERVAL to 0.1
• each json object will be on a new line
• https://github.com/wiedehopf/readsb/blob/dev/README-json.md

Aircraft.json:

• https://github.com/wiedehopf/readsb/blob/dev/README-json.md
• available on the same port as the web interface, example: http:https://192.168.x.yy:8087/data/aircraft.json

The sections below describe how to configure each part of the container functionality. Each section describes what's needed to come up with a minimally viable configuration, followed by additional / optional parameters that can also be set.

The following parameters must be set (mandatory) for the container to function:

READSB_EXTRA_ARGS just passes arguments to the commandline, you can check this file for more options for wiedehofp's readsb fork: https://github.com/wiedehopf/readsb/blob/dev/help.h

There are two ways to provide ADSB data to the Ultrafeeder:

• provide the container with access to a SDR or other hardware device that collects ADSB data
• allow the container to connect to a ADSB data source in Beast, Raw, or SBS format

These methods are not mutually exclusive - you can use both at the same time if you want.

If you want to connect your SDR to the container, here's how to do that:

If you have set READSB_GAIN=autogain, then the system will take signal strength measurements to determine the optimal gain. The AutoGain functionality is based on a (slightly) modified version of Wiedehopf's AutoGain. AutoGain will only work with rtlsdr style receivers.

There are 2 distinct periods in which the container will attempt to figure out the gain:

• The initial period of 2 hours, in which an adjustment is done every 5 minutes
• The subsequent period, in which an adjustment is done once every day

Please note that in order for the initial period to complete, the container must run for 90 minutes without restarting.

When taking measurements, if the percentage of "strong signals" (i.e., ADSB messages with RSSI > 3 dB) is larger than 6%, AutoGain will reduce the receiver's gain by 1 setting. Similarly, if the percentage of strong signals is smaller than 2.5%, AutoGain will increment the receiver's gain by 1 setting. When AutoGain changes the gain value, the readsb component of the container will restart. This may show as a disconnect / reconnected in container logs.

We recommend running the initial period during times when there are a lot of planes overhead, so the system will get a good initial view of what signals look like when traffic is at its peak for your location. If you forgot to do this for any reason, feel free to give the AutoGain reset command (see below) during flights busy hour.

Although not recommended, you can change the measurement intervals and low/high cutoffs with these parameters:

If you need to reset AutoGain and start over determining the gain, you can do so with this command:

docker exec -it ultrafeeder /usr/local/bin/autogain1090 reset

In addition to (or instead of) connecting to a SDR or hardware device to get ADSB data, the container also supports ingesting data from a TCP port. Here are some parameters that you need to configure if you want to make this happen:

Instead of (or in addition to) using BEASTHOST, you can also define ADSB data ingests using the READSB_NET_CONNECTOR parameter. This is the preferred way if you have multiple sources or destinations for your ADSB data. This variable allows you to configure incoming and outgoing connections. The variable takes a semicolon (;) separated list of host,port,protocol[,uuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX], where:

• host is an IP address. Specify an IP/hostname/containername for incoming or outgoing connections.
• port is a TCP port number
• protocol can be one of the following:
  • beast_reduce_out: Beast-format output with lower data throughput (saves bandwidth and CPU)
  • beast_reduce_plus_out: Beast-format output with extra data (UUID). This is the preferred format when feeding the "new" aggregator services
  • beast_out: Beast-format output
  • beast_in: Beast-format input
  • raw_out: Raw output
  • raw_in: Raw input
  • sbs_out: SBS-format output
  • vrs_out: SBS-format output
• uuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX is an optional parameter that sets the UUID for this specific instance. It will override the global UUID parameter. This is only needed when you want to send different UUIDs to different aggregators.

NOTE: If you have a UAT dongle and use dump978 to decode this, you should use READSB_NET_CONNECTOR to ingest UAT data from dump978. See example below

    environment:
    ...
      - READSB_NET_CONNECTOR=dump978,37981,raw_in;another-data-aggregator.com,30005,beast_reduce_plus_out
    ...

There are many optional parameters relating to the ingestion of data and the general networking functioning of the readsb program that implements this functionality.

The Container creates an interactive web interface displaying the aircraft, based on Wiedehopf's widely used tar1090 software.

The web interface is rendered to port 80 in the container. This can me mapped to a port on the host using the docker-compose ports directive.

All of the variables below are optional.

Note - due to design limitations of readsb, the tar1090 graphical interface will by default ONLY show MLAT results from the aggregators/MLAT sources that were defined with the MLAT_NET_CONNECTOR parameter. If you want to show any additional MLAT results (for example, those from piaware), you should add a separate READSB_NET_CONNECTOR for them.

• For documentation on the aircraft.json format see this page: https://github.com/wiedehopf/readsb/blob/dev/README-json.md
• TAR1090_ENABLE_AC_DB causes readsb to load the tar1090 database as a csv file from this repository: https://github.com/wiedehopf/tar1090-db/tree/csv

ADS-B over UAT data is transmitted in the 978 MHz band, and this is used in the USA only. To display the corresponding graphs, you should:

1. Set the following environment parameters:

  - ENABLE_978=yes
  - URL_978=http:https://dump978/skyaware978

2. Install the docker-dump978 container. Note - only containers downloaded/deployed on/after Feb 8, 2023 will work.

Note that you must configure URL_978 to point at a working skyaware978 website with aircraft.json data feed. This means that the URL http:https://dump978/skyaware978/data/aircraft.json must return valid JSON data to this tar1090 container.

Users of AirSpy devices can enable extra graphs1090 graphs by configuring the following:

• Set the following environment parameter:

      - ENABLE_AIRSPY=yes

• To provide the container access to the AirSpy statistics, map a volume in your docker-compose.yml file as follows:

    volumes:
      - /run/airspy_adsb:/run/airspy_adsb
      ...

To allow the container access to the Disk IO data, you should map the following volume:

    volumes:
      - /proc/diskstats:/proc/diskstats:ro
      ...

By default, the system will use the temperature available at Thermal Zone 0. This generally works well on Raspberry Pi devices, and no additional changes are needed.

On different devices, the Core Temperature is mapped to a different Thermal Zone. To ensure the Core Temperature graph works, follow these steps

First check out which Thermal Zone contains the temperature you want to monitor. On your host system, do this:

for i in /sys/class/thermal/thermal_zone* ; do echo "$i - $(cat ${i}/type) - $(cat ${i}/temp 2>/dev/null)"; done

Something similar to this will be show:

/sys/class/thermal/thermal_zone0 - acpitz - 25000
/sys/class/thermal/thermal_zone1 - INT3400 Thermal - 20000
/sys/class/thermal/thermal_zone2 - TSKN - 43050
/sys/class/thermal/thermal_zone3 - NGFF - 32050
/sys/class/thermal/thermal_zone4 - TMEM - 39050
/sys/class/thermal/thermal_zone5 - pch_skylake - 40500
/sys/class/thermal/thermal_zone6 - B0D4 - 54050
/sys/class/thermal/thermal_zone7 - iwlwifi_1 -
/sys/class/thermal/thermal_zone8 - x86_pkg_temp - 57000

Repeat this a few times to ensure that the temperature varies and isn't hardcoded to a value. In our case, either Thermal Zone 5 (pch_skylake is the Intel Core name) or Thermal Zone 8 (the temp of the entire SOC package) can be used. Once you have determined which Thermal Zone number you want to use, map it to a volume like this. Make sure that the part to the left of the first : reflects your Thermal Zone directory; the part to the right of the first : should always be /sys/class/thermal/thermal_zone0:ro.

Note that you will have to add - privileged: true capabilities to the container. This is less than ideal as it will give the container access to all of your system devices and processes. Make sure you feel comfortable with this before you do this.

    privileged: true
    volumes:
      - /sys/class/thermal/thermal_zone8:/sys/class/thermal/thermal_zone0:ro
      ...

Note - on some systems (DietPi comes to mind), /sys/class/thermal/ may not be available.

Legacy: We recommend AGAINST enabling this feature as it has been replaced with http:https://dockerhost:port/?replay. timelapse1090 writes a lot of data to disk, which could shorten the lifespan of your Raspiberry Pi SD card. The replacement functionality is better and doesn't cause any additional disk writes.

If you have configured the container as described above, you should be able to browse to the following web pages: You should now be able to browse to:

• http:https://dockerhost/ to access the tar1090 web interface.
• http:https://dockerhost/?replay to see a replay of past data
• http:https://dockerhost/?heatmap to see the heatmap for the past 24 hours
• http:https://dockerhost/?heatmap&realHeat to see a different heatmap for the past 24 hours
• http:https://dockerhost/?pTracks to see the tracks of all planes for the past 24 hours
• http:https://dockerhost/graphs1090/ to see performance graphs

No paths need to be mapped through to persistent storage. However, if you don't want to lose your range outline and aircraft tracks/history and heatmap / replay data on container restart, you can optionally map these paths:

An "MLAT Hub" is an aggregator of MLAT results from several sources. Since the container is capable of sending MLAT data to multiple ADSB aggregators (like adsb.lol/fi/one, etc), we built in a capability to:

• collect the MLAT results from all of these services
• ingest MLAT results from other containers (FlightAware, Radarbox, etc.)
• make the consolidated MLAT results available on a port in Beast or SBS (BaseStation) format
• create outbound connections using any supported format to send your Beast data wherever you want

Note - due to design limitations of readsb, the tar1090 graphical interface will by default ONLY show MLAT results from the aggregators/MLAT sources that were defined with the MLAT_NET_CONNECTOR parameter. If you want to show any additional MLAT results (for example, those from piaware), you should add a separate READSB_NET_CONNECTOR for them. Adding these sources only to MLATHUB_NET_CONNECTOR will make the data available on the MLATHUB, but won't display them on your tar1090 map.

Generally, there is little to configure, but there are a few parameters that you can set or change:

This image contains Telegraf, which will be used to capture metrics from readsb if an output is enabled.

In order for Telegraf to output metrics to an InfluxDBv2 time-series database, the following environment variables can be used:

In order for Telegraf to serve a Prometheus endpoint, the following environment variables can be used:

You can look at individual messages and what information they contain, either for all or for an individual aircraft by hex:

# only for hex 3D3ED0
docker exec -it ultrafeeder /usr/local/bin/viewadsb --show-only 3D3ED0

# for all aircraft
docker exec -it ultrafeeder /usr/local/bin/viewadsb --no-interactive

# show position / CPR debugging for hex 3D3ED0
docker exec -it ultrafeeder /usr/local/bin/viewadsb --cpr-focus 3D3ED0

All logs are to the container's stdout and can be viewed with docker logs -t [-f] container.

Please feel free to open an issue on the project's GitHub.

We also have a Discord channel, feel free to join and converse.