Latest revision as of 09:22, 6 August 2010

Introduction

The Silent Wings Viewer protocol is an HTTP based protocol with a set of commands that match a set of URL's with parameters that typically correspond to a set of PHP scripts. There are generally two phases of the tracking protocol, first initialization where the client sets up the tracking for a given competition day based on input from the user. The next phase is the actual tracking where the client requests fix data from the tracking server at regular intervals.

Here is a schematic illustration of a typical tracking session:

Protocol

The following section contains a description of the available protocol commands used by the viewer client.

The general format for each command is:

http://server/command.php?param1=foo&param2=bar

etc.

Most of the commands return a series of tags much like HTML tags, only with curly brackets instead of angle brackets. For example:

getprotocolinfo.php?username=jane&cpassword=87f89daecd2dbe1bc62bb2f20bb81f55

returns:

{version}1.3{/version}{date}20080811{/date}{time}1218457469{/time}

Authentication

Most of the commands require a user name and password as input. These are specified in the username/password parameters:

http://tracking.silentwings.no//getactivecontests.php?username=john&cpassword=85f8addecd2dbf8bc62bb0f20bb31f51&version=1.2

The password should be given in encrypted form. The password is encrypted with user name as «encryption salt», i.e as the MD5 digest of the following string:

<password><username>

There should be no whitespace between the clear text password and the username. To authenticate you need to encrypt the clear text password with the same hash string (username) and compare the two encrypted passwords.

Commands

getprotocolinfo

This command is normally used during startup of the client to get the protocol version number and server time of the tracking server.

Command:

getprotocolinfo.php

Parameters:

username=<user name>
cpassword=<encrypted password>

Returns:

{version}1.3{/version}{date}20080811{/date}{time}1218457469{/time}

Tags:

• version Version number string. Should be 1.3 to be in compliance with this document.
• date Server date: YYYYMMDD
• time Server time in seconds since 1/1 1970

getactivecontests

This command is used in the init phase to retrieve a list of available contests on the server.

Command:

getactivecontests.php

Parameters:

username=<user name>
cpassword=<encrypted password>
version=<version number>

Returns:

Returns a list of available competitions on this server.

Example:

{contestname}FAIGP2005{/contestname}{contestdisplayname}1st FAI Grand PrixMondial{/contestdisplayname}{datadelay}15{/datadelay}{utcoffset}+01:00{/utcoffset}
{countrycode}FR{/countrycode}{site}St. Auban{/site}{fromdate}20050903{/fromdate}
{todate}20050912{/todate}{lat}44.1959{/lat}{lon}5.98849{/lon}{alt}{/alt}
{contestname}GawlerGrandPrix{/contestname}{contestdisplayname}Australian Gliding GrandPrix{/contestdisplayname}{datadelay}6{/datadelay}{utcoffset}+10:30{/utcoffset}
{countrycode}AU{/countrycode}{site}Gawler{/site}{fromdate}20061228{/fromdate}
{todate}20070106{/todate}{lat}-34.6{/lat}{lon}138.71{/lon}{alt}48{/alt}

Tags:

• contestname Internal name for this contest. Should be a short name with no whitespace or special characters.
• contestdisplayname Full name of competition as it should be presented in the GUI of the application.
• datadelay Initial delay (in minutes) of the tracker data. This value can be changed at a later stage with the datadelay tag in the gettrackerdata command.
• utcoffset UTC Offset in HH:MM format at the contest site.
• countrycode ISO Country code at the contest site.
• site String – name of the contest site.
• lat,lon,alt Global position of contest site.

getcontestinfo

This command is used in the init phase to get information about a given contest. This command can return two different kinds of data depending on whether or not a date is given. If no date is given, a list of contest days is returned.

Command:

getcontestinfo.php

Parameters:

username=<user name>
cpassword=<encrypted password>
contestname=<contest name>
date=<YYYYMMDD>

Returns:

If no date is given, a list of the available contest days is returned like this:

{date}20050903{/date}{task}1{/task}{validday}0{/validday}
{date}20050904{/date}{task}1{/task}{validday}0{/validday}
{date}20050907{/date}{task}1{/task}{validday}0{/validday}
{date}20050909{/date}{task}1{/task}{validday}1{/validday}
{date}20050910{/date}{task}1{/task}{validday}1{/validday}
{date}20050911{/date}{task}1{/task}{validday}1{/validday}

Tags:

• date the date of the competion day
• task Boolean flag, 0,1 tells if we have a task for this competition day
• validday Boolean flag tells if the day is a valid competition day.

If a date is given, the CUC file (SeeYou competition file) for that date is returned including task and pilot info. The CUC file is transmitted verbatim. See the SeeYou documentation for more info on the CUC file format if necessary. The CUC file must contain a [pilots] block which maps all the pilots to a tracker ID. The tracker ID should be put into the IGC Logger field (4th field). Multiple loggers can be separated with comma in this field. The tracker ID is taken to be the last logger ID in the list.

Example:

[Pilots]
"John", "Doe", 26356, "CAIXX00,1052", ...

Here we have an IGC logger first (CAIXX00) and the tracker last (1052). Next there should be a [Day] block for each competition day with the task for this competition day

gettrackerdata

This command returns the actual fix data for a given tracker unit. This command is sent at regular intervals by the tracking client. For Silent Wings Viewer, the current default interval for these requests is 60 seconds.

Command:

gettrackerdata.php

Parameters:

querytype=getintfixes
contestname=<contest name>
trackerid=<tracker id>
username=<user name>
cpassword=<encrypted password>
starttime=<YYYYMMDDHHMMSS>
endtime=<YYYYMMDDHHMMSS>
compression=<none | gzip>

Returns:

{datadelay}6{/datadelay}
1052,20061230045824,-34.60305,138.72063,49.0,0
1052,20061230045828,-34.60306,138.72067,48.0,0
1052,20061230045832,-34.60306,138.72071,48.0,0
1052,20061230045836,-34.60306,138.72075,47.0,0
1052,20061230045840,-34.60306,138.72079,46.0,0
1052,20061230045844,-34.60307,138.72083,45.0,0
...

The fix format is as follows:

<tracker id>,<timestamp>,<latitude>,<longitude>,<altitude>,<status>

The latitude and longitude are given in decimal degrees, altitude in meters. The status flag indicates the GPS status of the fix. A zero indicates that the GPS fix was bad and the last good fix is used. A status of 1 indicates a valid fix.

If the compression parameter is set to gzip, the returned data, including the datadelay tag, should be gzip compressed. This is highly recommended to reduce the data traffic.

Tags:

• datadelay currently allowed minimun delay for this tracker. This can be changed dynamically by the

organiser, so that we have more delay in the beginning of the competition than towards the final glide, as per FAI Grand Prix rules.