Xplage: Convert X-Plane Datagrams to Google Earth ‘Moving Map’ Displays

Xplage is a software utility that listens on an IP network for UDP datagrams representing the geographical coordinates of the simulated flight path of an instance of the X-Plane® flight simulator, then transforms them into a series of continuously updated KML files that Google Earth® can ingest to create “moving map” displays.

Xplage repeatedly generates two different KML files at a refresh interval specified by the user.  The first is used by Google Earth to display an overhead map with North at the top and an icon in the center of the satellite image to indicate the position of the simulated aircraft.  In this view, the Google Earth “eye” is fixed directly above the airplane.  Each refresh cycle shifts the map in the direction of the flight path so as to keep the icon centered.  The second KML file is used by Google Earth to display a perspective view of the terrain ahead of the simulated aircraft.  In this view, the eye may be thought of as being directly in front of the airplane and pointing slightly downward.  Each refresh cycle repaints the perspective based on the simulated aircraft's roll and pitch orientation.

Note that because the refresh rates of xplage and Google Earth are independent and asynchronous, these moving map images lag slightly behind the flight simulation.  In effect, they represent still photo frames that capture the position of the aircraft a short time before they are displayed.  This delay can be as great as the sum of the two refresh intervals.  In other words, if xplage is set to refresh at one-second intervals and Google Earth is set to refresh at two-second intervals, the moving map images may lag as much as three seconds behind the actual position of the simulated aircraft.  Delays in fetching satellite imagery through the public Internet from Google's servers may also contribute to the time lag.

Distributions

The xplage program is distributed primarily as open source code in the C programming language subject to the terms of the GNU General Public License.  The program was designed and tested on Solaris/X86 (release 10) with both Oracle’s native compiler and the GNU C compiler.  Compilation with GNU C has also been verified on Apple OS X (release 10.6), Ubuntu Linux (release 11.2), and—using the Cygwin development suite—Microsoft Windows NT (release 6, a.k.a. Vista).  It should require no more than minimal coaxing to compile the source code on other platforms that support the POSIX application programming interface.

Unsupported and minimally tested binaries compiled for X86 target platforms (the OS X executable is a “universal binary”) may also be downloaded from this page.  Both the source code and the distributed binaries by default listen on UDP port 49000 and place their output in an “xp2ge” subdirectory of the standard HTML document hierarchy for the Apache web server on the target platform: i.e., <baseDirectory>/xp2ge/overhead.kml for the overhead map view and <baseDirectory>/xp2ge/perspective.kml for the perspective view.  A man page describing the program's run-time options is included in both the source and binary distributions, as is a ReadMe file which provides supplemental information about using xplage in your environment.

Installation and Configuration

To use xplage, you need to download it from one of the distributions on this page, configure X-Plane to transmit data to it, and then set up Google Earth to read and display the files that xplage produces.

Compiling the C Source Code The source distribution archive contains the code, a Makefile and a few helper scripts.  No manual modifications should be necessary to produce an executable program on any of the tested operating system environments.  Download and unpack the archive (e.g., “gzcat xplage.tar.gz | tar xf —” or whatever is appropriate in your environment). On Solaris (the development platform), compilation may be accomplished by changing your current working directory to the directory where you unpacked the distribution and typing “make.”  On Apple OS X, use “make osx.”  On Ubuntu Linux, the magic words are “make linux.”  On Microsoft Windows, they are “make nt.”  Other operating systems may require more elaborate incantations and possibly minor changes to the source code.

1. Select Preferred Distribution

As noted above, xplage is available in source and binary distributions.  Whether you compile the C source code yourself or use the precompiled binary for your computer, you can deposit the executable program in any directory (“folder”) that is convenient.  You can install it on any computer on your local network as long as that computer can communicate with the computers you use to run X-Plane and Google Earth; it has been designed to use minimal hardware resources, so there should be no problem installing it on the same computer that will be running one of those programs.  Normally, you should run xplage in a terminal emulator (“command prompt”) in order to use its interactive controls and to view the current coordinates it is processing, which it types in the emulation window.

2. Configure X-Plane

Once xplage is ready to execute on your computer, you need to configure X-Plane to send telemetry to the computer where xplage is installed. The details of how to do this vary slightly with different versions of X-Plane, but the basic idea is the same.

X-Plane 10

First, configure X-Plane to transmit the simulated latitude, longitude, altitude, heading, pitch and roll to the computer where xplage is installed. This is done by checking the appropriate boxes in the first column of the X-Plane Data Input and Output > Data Set page. Then set the network address (“IP number”) of the computer which where xplage will receive the data from the X-Plane Net Connections > Data page.

X-Plane 9

First, configure X-Plane to transmit the simulated latitude, longitude, altitude, heading, pitch and roll to the computer where xplage is installed. This is done by checking the appropriate boxes in the first column of the X-Plane Data Input and Output > Data Set page. Then set the network address (“IP number”) of the computer which where xplage will receive the data from the X-Plane Net Connections > Inet3 page.

X-Plane 8

First, configure X-Plane to transmit the simulated latitude, longitude, altitude, heading, pitch and roll to the computer where xplage is installed. This is done by checking the appropriate boxes in the first column of the X-Plane Data Input and Output > Data Set page. Then set the network address (“IP number”) of the computer which where xplage will receive the data from the X-Plane Data Input and Output > Inet2 page.

3. Set Up Google Earth to Display Map(s)

Finally, you need to set up Google Earth to read the sequence of KML files that xplage produces.  This is done using Google Earth's “network link” feature.  Actually, if the KML files are being transmitted to the computer where Google Earth is running, Google Earth can read them directly from the local filesystem (the computer's disk).  Or you can use an HTTP server (a web server) to make the files available to any computer on your local network.  The free Apache web server software is a good product to use for a private web server if you don't already have one on your network.  Having Google Earth read files from a local filesystem is simpler to set up. On the other hand, if you plan to have run Google Earth on two computers, with one computer displaying the overhead map view and the second displaying the map view, you will probably want to set up an HTTP server.

This configuration regime probably sounds more complicated than it is.  On the tested operating systems, the entire process can be accomplished in less than half an hour. Be sure to check out the ReadMe document that is included in both the source and binary distributions for additional guidance on using xplage in your particular environment.

The Track File

In addition to the files containing KML directives, xplage can optionally produce a file containing lines of comma-separated values, one for each sampling interval, representing the geographical coordinates and orientation of the simulated aircraft. This file can't be read by Google Earth or—as far as I know—any other existing commercial software. Rather, it is intended to serve as an intermediate format for programmers who want to take advantage of xplage to collect and pre-process UDP datagrams from X-Plane. It relieves the programmer of the need to read the X-Plane telemetry through the network and convert it into a form that can easily be parsed by other programs.

As a demonstration of how this track file could be exploited, the distribution bundle includes a shell script, track2kml, which transforms a track file into KML directives which Google Earth can use to display a rotatable, tiltable 3D animated path of the flight of the simulated aircraft. See the man page and the ReadMe file for more information.

A Note on the Design

Xplage is not a trivial program, but its logic is easy to understand once you grasp its structure. When it is executed, it parses its command line options and sets up a UDP socket to listen for incoming X-Plane datagrams. Then the main routine launches three asynchronous lightweight child processes which respectively wait for an incoming datagram from the simulator, the end of the specified interval for updating the KML output files, or a manual interrupt from the user. When the user issues a request to the interrupt thread to exit the program, all four processes are simultaneously terminated.

I am unable to commit to responding to enhancement requests or reports of run-time problems with the binaries, but I will attempt to fix any bugs in the current version of the distributed source code.

Chris Kern
Washington, D.C.
December, 2007