Measuring reception performance: graphs1090, polar plots and the Heywhatsthat range forecast

The antenna is up, the stick is running, the map is teeming with aircraft – but how good is your station, really? “Feels like more than yesterday” does not help when you want to know whether the new cable, the preamplifier or the extra half meter of mast height paid off. There are three tools for that, and they complement each other perfectly: graphs1090 for statistics over time, the range outline in tar1090 as a polar plot per compass direction, and the Heywhatsthat forecast as a theoretical upper limit. This guide shows you how to set up all three and what the curves reveal about your receiver.

The short answer

You measure your ADS-B receiver’s reception performance by installing graphs1090 and watching the charts for message rate, aircraft, range and signal level over several days. You set the gain so that 0.5 to 5 percent of messages are stronger than -3 dBFS. For directional dependence you look at the actual range outline in tar1090, and as a yardstick you load the theoretical range from Heywhatsthat onto the same map with getupintheair.sh. Where the two lines are far apart, there is potential for improvement.

Installing graphs1090

graphs1090 comes from the developer wiedehopf, who also maintains readsb and tar1090. The tool reads your decoder’s stats.json file, stores the values in RRD databases with collectd and draws charts from them. The prerequisite is readsb, dump1090-fa or another dump1090 variant. How to set up the base is shown in Installing readsb and tar1090; if you use PiAware, you already have a suitable decoder in dump1090-fa.

Installation takes a single command:

sudo bash -c "$(curl -L -o - https://github.com/wiedehopf/graphs1090/raw/master/install.sh)"

Then you open http://<your-pi-ip>/graphs1090 in the browser. According to the project page, /perf or port 8542 also work. If your receiver runs in the sdr-enthusiasts Ultrafeeder container, you do not need to install anything: graphs1090 is already built in there and sits at /graphs1090/ on the map port – more on that in Feeding multiple ADS-B networks with Ultrafeeder.

Two settings you should change right away

The configuration is in /etc/default/graphs1090. Two options are handy for spotters in Central Europe:

Option	Default	Recommendation
range	nautical (nautical miles)	metric for kilometers
colorscheme	default	dark if you look at it at night

After saving, sudo systemctl restart graphs1090 applies the change. In the same file you can also set the size of the charts and fixed upper limits for individual axes – useful if you want to compare before-and-after images and the automatic scaling would otherwise fool you.

One detail on data safety: by default graphs1090 keeps the data in memory and writes it to the SD card once a day to spare it. That survives restarts without a problem, but a sudden power outage can cost you the values since the last write. So shut the Pi down cleanly before pulling the plug. In addition, the tool creates weekly backups, which it keeps for eight weeks.

Reading the most important charts

At the top of the page you choose the time period: from 2 hours through 24 hours, 7 and 30 days up to several years. For judging a change, 48 hours and 7 days are usually the most meaningful views. Four charts matter most for reception quality:

Chart	What it shows	How to recognize good values
Message Rate	messages per second, plus the share of strong signals	high rate over the course of the day, red share in the target range
Aircraft Seen / Tracked	total aircraft, broken down by ADS-B, MLAT and TIS-B position and without position	few aircraft without position relative to the total
Range	maximum range, median distance, nearest aircraft, quartile range	stable maximum values, no sudden drop
Signal Level	median level, weakest and strongest signal, with readsb also noise	weakest signal at about -25 to -30 dBFS

Message Rate: your station’s pulse

The message rate is the most honest metric because it counts every single decoded Mode S message. It follows the traffic: at night it drops sharply, during the day it rises with the waves of long-haul arrivals and departures. What matters is therefore not the absolute value but the comparison of equal periods – Tuesday against Tuesday, not Sunday night against Friday noon.

This chart also contains the red area “Messages > -3dBFS” with a percentage figure. It marks messages that arrive so strongly that the stick reaches its limit. This value is your most important lever for the gain – more on that in a moment. Background on the message types is provided by Transponder Mode A, C and S explained.

Aircraft Seen: positions and gaps

The aircraft chart distinguishes where a position comes from: ADS-B, MLAT or TIS-B. Aircraft without position are aircraft whose transponder you do hear, but which either do not transmit a position themselves or from which too few messages arrive. A high share without position is a good reason to take part in MLAT: how multilateration calculates positions from several stations is explained in MLAT/multilateration.

Range: maximum, median, quartiles

The range chart shows more than just the maximum distance. Besides the max range you see the median distance of all aircraft and an area for the range between the first and third quartile. The maximum alone is deceptive: a single aircraft at high altitude during unusual weather can set a record that has little to do with everyday reception. It is more meaningful whether the median and the quartiles move upward after a change.

Good to know: by default graphs1090 evaluates only ADS-B positions for range. Positions from other sources such as ADS-C or HFDL can, according to the repository, be included with a small change to a graphs1090 script, which has to be redone after every update – for judging your 1090 MHz antenna, though, you are better off sticking with the default.

Signal Level: understanding dBFS

The signal level is given in dBFS – decibels relative to the full scale of the analog-to-digital converter. 0 dBFS is the maximum, everything below is negative. The chart shows the average median level, the weakest and the strongest signal and, with readsb, the noise. If the strongest signal sits permanently at the upper edge, you are overloading. If the weakest signal is very close to the noise, you lack gain or your cable swallows too much.

Optimizing gain with graphs1090

Many stations run with too much gain. That sounds paradoxical, because more amplification sounds like more range. In practice, though, nearby aircraft then overload the stick, and strong signals drown out weak ones. wiedehopf explicitly points out that the RTL-SDR’s hardware AGC does not work as hoped for ADS-B and effectively sets a very high gain.

His gain guide gives clear target values for the share of messages above -3 dBFS:

Situation	Target value
Normal case	0.5 to 5 percent
Unsure	about 2 percent
Right at the airport	up to about 10 percent acceptable, 5 percent or less preferred
Focus on low-flying aircraft nearby	0.5 percent or below

As a second check, the signal chart helps: the weakest signal should be roughly between -25 and -30 dBFS, and down to -35 dBFS if you focus on the near range.

Here is how to proceed:

If you want to save yourself the trial and error, use readsb’s autogain function. According to the documentation it is tuned for ADS-B and is activated with --gain=auto; with --gain=auto-verbose it logs its changes. This is something different from the stick’s hardware AGC. Which sticks can be controlled well at all is compared in SDR sticks for ADS-B compared; if you work with an Airspy, you will find the particulars in Airspy Mini/R2 for ADS-B.

Polar plot: range per compass direction

graphs1090 tells you how far you hear – but not in which direction. That is exactly what a polar plot shows: for every bearing it plots the greatest measured distance, so an outline forms around your location. With a perfect all-round view it would be an even circle. In reality the line has spikes, bulges and dents – and those are exactly what is interesting.

The actual range outline in tar1090

readsb keeps such an outline automatically. By default the decoder stores the data of the last 24 hours; with the --range-outline-hours option you can change the period. tar1090 draws the line as a dynamic “actual range outline” over the map. In the tar1090 configuration you set the color, line width and whether the line is visible on first load.

The URL parameter ?pTracks is also worthwhile: it shows the tracks of the last hours – eight hours by default according to the tar1090 documentation – and so makes visible where your coverage is dense and where the tracks break off. With the altitude filter you can also see whether, in one direction, you are mainly missing low-flying aircraft. How to use tar1090 on a PC as a full-fledged radar is explained in Flight tracking on a PC with tar1090 and Virtual Radar.

Other programs also offer range displays, such as Virtual Radar Server or the local interface of the Plane Finder client. For all of them the same applies: measure with the data of your own antenna only. A merged data stream with MLAT results or data from other stations artificially inflates the line.

What the shape reveals

Pattern in the polar plot	Probable cause
sharp, narrow notch	chimney, mast, neighboring building close to the antenna
wide, dented sector	slope, high-rise, roof surface, your own house wall
uniformly small all around	antenna too low, cable losses, too little or far too much gain
one direction clearly farther	clear view over plains or water, often toward the main traffic flow
range fluctuates over the year	foliage on trees, wet vegetation, weather conditions

Heywhatsthat: the theoretical yardstick

A dent in the polar plot does not mean you are doing something wrong. Maybe there is simply a mountain there. To tell the difference you need your location’s theoretical range. That is provided by heywhatsthat.com: from terrain data of the 2000 SRTM Shuttle mission, the service calculates a panorama of everything visible from your location. The “up in the air” function uses it to work out how far aircraft at a given altitude stand above the horizon.

Because 1090 MHz signals need a clear line of sight, this line is a good forecast of the maximum. The tar1090 guide names two limitations, though: obstacles closer than about 100 feet to the antenna are not factored in, and trees are not taken into account. The coarse elevation grid also does not reliably represent individual buildings.

Creating a panorama

1. On heywhatsthat.com choose “New Panorama”.
2. Set the antenna location exactly – by clicking on the map or via coordinates.
3. Enter the height above ground. The default is six feet, i.e. eye level; for a rooftop antenna you enter the actual mounting height.
4. Submit and wait until the calculation is done.
5. Below the map, use “up in the air” to display the outlines for different flight altitudes.

The URL of the finished panorama contains an ID. You need it for the next step.

Showing the forecast in tar1090

tar1090 comes with a small script that loads the data directly from Heywhatsthat:

sudo /usr/local/share/tar1090/getupintheair.sh YOUR-ID

Without further arguments the script fetches the line for 12,192 meters, i.e. 40,000 feet. For a comparison with lower traffic you load two lines:

sudo /usr/local/share/tar1090/getupintheair.sh YOUR-ID 3048,12192

That shows the limits for 10,000 and 40,000 feet. The script queries the data with a refraction factor of 0.25, so it accounts for the slight curvature of radio waves in the atmosphere. In the Ultrafeeder container you instead enter the panorama ID in the HEYWHATSTHAT_PANORAMA_ID environment variable.

Comparing measurement and forecast

Now two lines lie on top of each other: the measured outline from readsb and the theoretical one from Heywhatsthat. The comparison is where the real insight comes from:

• Measured close to the 40,000 ft line: Your station gets out what the terrain allows. More range only comes with more height.
• Measured clearly inside, but evenly: The technology is holding you back. Candidates are cable losses, a missing preamplifier or a wrongly set gain. Solutions are described in Boosting ADS-B range with LNA and filter.
• Measured inside in individual sectors only: A local obstacle that Heywhatsthat does not know – buildings, trees, your own roof surface. Often a different mounting location is enough here; how to find it is shown in Finding the best antenna location.
• Measured outside in one direction: Occurs in unusual weather with enhanced propagation, or when foreign positions get into your data. Check whether you really evaluate only your own ADS-B data.

The rule of thumb for the radio horizon from our location guide also helps with perspective: the range in kilometers is roughly 4.12 × (√antenna height + √flight altitude), both in meters. Heywhatsthat does nothing different, only with real terrain instead of a smooth sphere.

A measurement log for antenna experiments

When you compare antennas – say the home-built spider against a coax collinear from Build your own 1090 MHz antenna – keep a small log. Before every change, note the date, gain, percentage of strong signals, average message rate at peak traffic time, median distance and a screenshot of the outline. Then change exactly one thing and measure for at least one full day, preferably a week. Anyone who changes two things at once does not know afterward what worked.

For spotters, a well-measured station has a very practical benefit: you know how far your own map is reliable and can estimate when an approach to your home airport shows up – whether at the Munich Airport visitors’ hill with a view of Munich Airport or at the Affenfelsen in Hamburg. Later you match your photos against the recorded data; how that works is explained in Matching sightings with ADS-B logs.

Conclusion

Measuring reception performance is not rocket science, but it takes the right tools and a bit of patience. graphs1090 gives you the history of message rate, range and signal level and, with the share of strong signals, shows whether your gain is right. The range outline in tar1090 reveals in which direction your antenna is blind, and Heywhatsthat tells you whether that is down to the terrain or to your setup. Anyone who looks at these three layers together optimizes purposefully instead of by guesswork – and ends up with a station whose limits he knows exactly.