piaware: the client that feeds your ADS-B receiver to FlightAware

Five programs, one data path

The repository is the basis of the piaware Debian install package, and it splits into five programs that divide the work. The piaware program establishes an encrypted session to FlightAware and forwards data, and it is the piece that does the talking. piaware-config configures it, controlling authentication, updates and multilateration. piaware-status checks the status of the whole arrangement. faup1090 is run by piaware to connect to dump1090 or some other program producing Beast style ADS-B data and to translate between its format and FlightAware's. fa-mlat-client is also run by piaware, to gather data for multilateration. The primary language of the repository is Tcl, and the top level of the tree shows the shape of a classic Unix package with a package/ directory for the Tcl library, programs/ for each executable, etc/ for the system configuration, scripts/ for the init and service integration, doc/ for the manual pages, and a Makefile that drives the sub-builds. The licence is BSD-2-Clause, and there is a separate MLAT-RESULTS-LICENSE.md for the multilateration results data, which is the one part of the stack with different terms.

The connection is TLS, and the account is tied to a UUID

The piaware program establishes a compressed, encrypted TLS connection to FlightAware, and on initial login the client is assigned a UUID that is used to identify the piaware instance and associate it with a FlightAware account. That detail matters for anyone running more than one receiver, because the identity of your feeder is a property of the installation rather than of the data it sends. The data path itself is a translation chain. piaware starts faup1090 to translate ADS-B data from a raw Beast format feed on port 30005 into a filtered ADS-B format, and the filtered data is then uploaded to FlightAware over the previously established TLS connection. So your receiver produces a Beast format stream, faup1090 filters and reformats it, and piaware ships it. Every five minutes piaware also sends a message containing basic health information about the local machine, such as system clock, CPU temperature, CPU load, basic filesystem capacity and system uptime. That telemetry is what FlightAware uses to see whether a feeder is alive, and it is also the reason a stopped clock or a full disk shows up as a quiet map rather than as missing aircraft. The README also notes that piaware uses several techniques to keep the connection established and will disconnect and reconnect if something goes wrong.

Multilateration is the part with a privacy and a clock dependency

Piaware starts the multilateration client fa-mlat-adept on request, and the mechanism is worth understanding before you enable it. fa-mlat-client extracts raw messages from port 30005 and selectively forwards them by UDP to the FlightAware servers. UDP is used because this message forwarding is time-sensitive but not so important that dropping a message matters, and the multilateration control messages go over the main piaware TCP connection. The consequence is that multilateration computes a position from the arrival times of the same transmission seen by several receivers, and every receiver needs a synchronised clock for that to work. Once you are feeding raw messages, your receiver's contribution is helping to locate aircraft that are not over your own antenna. The results come back to you, and the README describes the default in detail. By default, multilateration positions resulting from the data you feed to FlightAware are returned to you by sending them to the local dump1090 process on port 30104, and dump1090 then includes them on the web map it generates. There is an overall switch to turn the whole thing off.

$ sudo piaware-config mlat-results no

And a way to send the results somewhere else, in a different format.

  # Connect to localhost:30104 and send multilateration results in Beast format.
  # Listen on port 310003 and provide multilateration results in Basestation format to anyone who connects

$ sudo piaware-config mlat-results-format "beast,connect,localhost:30104 basestation,listen,31003"

The port change from 30004 to 30104, and why it matters

The README spends a paragraph on a port number, which is unusual and worth reading because the reasoning is a good example of defensive defaulting. The default configuration now connects to port 30104, not 30004, and the default FlightAware dump1090 configuration has been updated to match. The stated reason is to avoid accidentally feeding multilateration results to an older dump1090 that is not multilateration aware and might end up feeding the results to places you do not want to feed them to. If you really do want to feed to port 30004, and you know that is not going to cause problems with results going where they should not, you can return to the older behaviour.

$ sudo piaware-config mlat-results-format "beast,connect,localhost:30004"

The configuration is read once when piaware starts, which is the operational rule to remember. If you change the configuration you should then restart piaware, and the command for that is the legacy service one.

$ sudo service piaware restart

The repository also documents a systemd service file, since piaware is started as a systemd service, and the modern equivalents are start, stop and restart with systemctl, with systemctl status piaware to check the current state.

piaware-config, and the switches that decide who controls your feeder

Running piaware-config with no arguments shows the current configuration, and adding the -showall argument shows all settings including those using default values, which is the flag to use when you are trying to work out why something is behaving in a way you did not ask for. Two separate switches control who can restart your feeder. The allow-auto-updates setting governs whether piaware accepts requests for automatic updates, requested by FlightAware, and the allow-manual-updates setting governs whether it accepts requests for manual updates, requested by you through the FlightAware website control panel. Updates default to enabled for Piaware sdcard images and disabled for package installs, which is a sensible split, since an image build is expected to self-maintain while a package install on someone's own system should not be restarted from a remote control panel without the operator choosing that.

# disable auto updates:
$ sudo piaware-config allow-auto-updates no
# disable manual updates:
$ sudo piaware-config allow-manual-updates no

Multilateration data is sent to FlightAware by default, and the switch to stop that is a single setting.

# disable multilateration:
$ sudo piaware-config allow-mlat no

So the configuration surface is small and each item is a permission: whether FlightAware can restart your machine, whether your raw feed leaves your network, and where the computed positions go.

Diagnosing with piaware-status and reading the logs

piaware-status examines your system and tries to figure out what is going on, and the README lists what it reports. It will report on whether dump1090, faup1090 and piaware are running or not, it will identify what program, if any, is producing data on port 30005, and whether or not piaware is connected to FlightAware. That is a well chosen set of checks, because the failure modes of this stack are almost always one of four things, the receiver is not running, the translator is not running, nothing is producing the raw feed on the expected port, or the upload is not working. The status tool distinguishes all four in one pass, which is more than you get by reading the log. The log itself is at /var/log/piaware.log, and it is rotated weekly, with older logs at /var/log/piaware.log.0, /var/log/piaware.log.1 and so on. The rotation is worth noting for a different reason, since the health message sent every five minutes means a working log tells you about a machine that stopped reporting, which is often the first sign of a clock problem or a full disk.

Building from source needs more than this repository

The building section is where most self-builders get stuck, and the README is clear about it. This repository provides only part of the overall piaware package, and you must also build fa-mlat-client and faup1090 and put them in the right places. The recommended route is the piaware_builder repository, which is a mostly automated build that knows how to assemble and build the different parts, and it is the build used to produce the Raspbian piaware release packages that FlightAware provides, and it should also work on other Debian based systems. The top level Makefile is a thin wrapper that descends into the sub-directories, and the comment at the top of it explains the variables the sub-makefiles understand. DESTDIR is a prefix put before all destination paths when installing and is used for packaging, PREFIX is the base directory to install to and defaults to /usr, TCLLAUNCHER is the path to a tcllauncher binary to install and defaults to tcllauncher from the path, and TCLSH is the path to a tclsh to use to build package indexes, defaulting to tclsh or tcl8.5 or tcl8.6 from the path. The install target descends into package, each of the three piaware programs, pirehose, doc, scripts and etc. The repository also carries mediawiki documents for the build, the best practices, the image notes and the release notes, plus a Home.md, which tells you the project keeps its user documentation in a wiki format rather than in the README.

Editorial conclusion

Adopt piaware if you run a dump1090 based ADS-B receiver and want your aircraft positions to appear on the FlightAware map, and you are prepared to accept that your positions depend on a third party's network and a shared clock. Skip it if you only want your own local tracking, since a self-hosted decoder gives you that without uploading anything. Verify first that faup1090 and fa-mlat-client are built and in place, since this repository does not provide them, that the mlat results port matches the dump1090 you are running, and that your multilateration settings will not send your raw feed to the shared servers without you having decided that.

Frequently asked questions

Official sources

1. flightaware/piaware on GitHub
2. Issues
3. License: BSD-2-Clause
4. README