Usage of the DataTurbine KML plugin

TrackDataPlugIn and TrackKMLPlugIn are DataTurbine PlugIns which format alt/lat/lon DataTurbine channel data into a KML document for viewing in Google Earth. These PlugIns come with the DataTurbine distribution; they are located within the Apache Tomcat directory at:

apache-tomcat-6.0.18/webapps/webTurbine/WEB-INF/classes

This document provides some information on using these PlugIns, as well as how to setup Google Earth for viewing the track data returned from these PlugIns.
 
TrackDataPlugIn
=============
TrackDataPlugIn fetches the low-level data (altitude, longitude, latitude) from the DataTurbine channels and returns it to TrackKMLPlugIn (for final processing into a KML document).  As such, your DataTurbine source needs to contain alt, lat, and lon channels. The default channel names assumed by TrackDataPlugIn are "Alt", "Lat", and "Lon".  If your DataTurbine Source doesn't use these exact channel names, you will need to specify your channel names in a TrackDataPlugIn config file, and then on the command line to start TrackDataPlugIn you use the "-f" command line flag to specify this config file's name.  Here is an example of this file:

        #
        # This file provides TrackPlugIn the names of the
        # alt, lat, lon, id, type, and classification RBNB channel names.
        #
        # Blank lines or lines that start with '#' will be skipped
        #
        # The left column indicates the type of channel (see codes below).
        # The right column provides the specific RBNB channel name this data will be acquired from.
        #
        # The channel name codes are as follows (these names must be exactly used in the left column):
        # alt (altitude channel)
        # lat (latitude channel)
        # lon (longitude channel)
        # id (track id channel)
        # type (type channel)
        # class (classification channel)
       
        alt GPS_Alt_MSL
        lat Latitude
        lon Longitude

When you launch TrackDataPlugIn, the following items must be included in the classpath: the path to the TrackDataPlugIn classes and also the path to rbnb.jar.  Here is an example:

        java -cp C:\PROGRA~1\RBNB\V3.2B5\apache-tomcat-6.0.18\webapps\webTurbine\WEB-INF\classes;C:\PROGRA~1\RBNB\V3.2B5\bin\rbnb.jar TrackDataPlugIn -f TrackDataConfig.txt -n TrackData

The "-f" flag specifies the name of the config file and the "-n" flag specifies the name that will be registered for your PlugIn with the DataTurbine server (that is, the name that you would use for making data requests).  If you run TrackDataPlugIn with a "-h" flag you can check out the other command line options available.

TrackKMLPlugIn
=============
TrackKMLPlugIn receives raw data (altitude, latitude, longitude) from TrackDataPlugIn and formats this data for output as a KML document.  This PlugIn uses an input config file to specify various options for how the track will look in Google Earth.  This file is specified with the "-f" command line option when launching TrackKMLPlugIn.  Here is a sample config file:
        #
        # This file specifies GUI options for TrackKMLPlugIn
        #
        # Blank lines or lines that start with '#' will be skipped
        #
       
        #
        # Display parameter options
        # Parameter Options
        # --------------------------------------------------------------------------------------------------
        # labelBy id/type/class/alt/latlon/altlatlon/none; any other entry will be treated as the constant label
        # sortBy id/type/class
        # iconBy type/class/dot/square/airplane/none
        # colorBy type/class/red/green/blue/yellow/purple/aqua; any other entry will be treated as the constant color (must be HEX number in format bbggrr)
        #
       
        labelBy Foo
        sortBy id
        iconBy airplane
        iconScale 1.0
        colorBy red
       
        #
        # To add current values as part of the label:
        # label_chan <chan1>=<nickname1>,<chan2>=<nickname2>,etc.
        #
        # - "chan" specifies a relative channel within the same Source as the track data is fetched from.
        # In other words, "chan" cannot be an absolute Source/Channel name.
        # - The "nickname" specifies the string that will be displayed in Google Earth with the data value.
        #
        label_chan GPS_Alt_MSL=Alt(m)
In this sample config file, we specify to use an airplane icon in Google Earth, label the icon "Foo", and color the track red.  This file also specifies to display the Altitude value along with the aircraft icon in Google Earth.
When you launch TrackKMLPlugIn, the following items must be included in the classpath: the path to the TrackKMLPlugIn classes and also the path to rbnb.jar.  Here is an example:

        java -cp C:\PROGRA~1\RBNB\V3.2B5\apache-tomcat-6.0.18\webapps\webTurbine\WEB-INF\classes;C:\PROGRA~1\RBNB\V3.2B5\bin\rbnb.jar TrackKMLPlugIn -C -f TrackKMLConfig.txt -n TrackKML
 
The "-f" flag specifies the name of the config file and the "-n" flag specifies the name that will be registered for your PlugIn with the DataTurbine server (that is, the name that you would use for making data requests).  If you run TrackKMLPlugIn with a "-h" flag you can check out the other command line options available.

Viewing tracks in Google Earth
========================
The following software needs to be running for a complete end to end solution:

  • DataTurbine server
  • An instance of TrackDataPlugIn and TrackKMLPlugIn
  • Your DataTurbine Source application, which puts alt/lat/lon data into the DataTurbine
  • Apache Tomcat server (comes with the DataTurbine distribution); supports an HTTP interface for fetching data from the DataTurbine
  • Optional: TimeDrive server (comes with the DataTurbine distribution); provides a TiVO-like interface for requesting historical or real-time data from the DataTurbine server
  • Google Earth, to view the KML documents fetched from the DataTurbine

Here are some instructions on getting the system going with Google Earth:

  1. Start DataTurbine server, Apache Tomcat server, your Source application, and instances of the track PlugIns
  2. Start Google Earth and create a "NetworkLink" object (which is used to periodically fetch KML documents via a URL).
    • The URL to include in the NetworkLink will be something like: http://localhost/RBNB/TrackKML/TrackData/Foo?d=500
    • Here, we are using "Foo" for the name of the DataTurbine source.  This URL requests 500 seconds worth of the most recent data (note the "?d=500" munge).
  3. If you want to create an even "slicker" system, instead of using a static URL such as the one above, start an instance of TimeDrive and allow the user to play/step through their data.
    • An instance of the TimeDrive server needs to be started; timedrive.jar is located in the same directory as rbnb.jar.
    • By default, TimeDrive uses port 4000.  If you need to specify a different port, you can use the "-s" command line flag.  If you use a different port, a further tweak needs to be made in the Tomcat "TimeDrive" servlet configuration file, located at "apache-tomcat-6.0.18\webapps\TimeDrive\WEB-INF\web.xml".
    • An example of launching TimeDrive: java -jar C:\PROGRA~1\RBNB\V3.2B5\bin\timedrive.jar -u localhost -d0 -m 2
    • When using TimeDrive, the URL you specify in the NetworkLink in Google Earth must change to something like: http://localhost/TimeDrive/RBNB/TrackKML/TrackData/Foo; note that we no longer need the time duration munge ("?d=500") because the user will specify start time and duration for the data request using the TimeDrive web interface.
    • To see the TimeDrive web interface, go to the following URL in a browser: http://localhost/TimeDrive
  4. You can also provide a Google Earth "setup" file for users, which specifies a desired collection of NetworkLinks.  The user simply loads this file into Google Earth (using File->Open).  Here is an example of a simple setup file.  In this case, Google Earth will automatically request a new KML document every 3 seconds.

    <?xml version="1.0" encoding="UTF-8"?>
    <kml xmlns="http://earth.google.com/kml/2.1">
    <Document>
    <Folder>
            <name>Foo</name>
            <description>
            <![CDATA[<a href="http://localhost/TimeDrive">TimeDrive</a>]]>
            </description>
            <open>1</open>
            <NetworkLink>
                    <name>Foo</name>
                    <visibility>0</visibility>
                    <open>0</open>
                    <Url>
                            <href>http://localhost/TimeDrive/RBNB/TrackKML/TrackData/Foo</href>
                           <refreshMode>onInterval</refreshMode>
                           <refreshInterval>3</refreshInterval>
                    </Url>
            </NetworkLink>
    </Folder>
    </Document>
    </kml>