HTTPS SSH
compeo-tools - scripts for interfacing with Braeuniger/Flytec GPS-varios
========================================================================

This is a collection of Perl scripts for accessing data stored on one of the
Braeuinger Compeo/Compeo+/Competino/Competino+ or Flytec 5020/5030/6020/6030
series of hang-gliding and paragliding GPS varios. It includes compeoigc for
downloading tracks in the standard IGC format, compeowpt for uploading and
downloading waypoints and routes, and compeoset for changing pilot and
glider information on the device.


Installing
----------

Unpack the distributed tar.gz file and copy the three Perl scripts to a
directory somewhere in your path. You may need to edit the #! line at the
beginning of each script to reflect the location of Perl on your system if
it isn't /bin/perl. You can also edit the value of $serialport in the first
few lines of each script to define the default serial port to which the
vario will be connected. This can be overridden using the COMPEO environment
variable and the -d option to the commands.

The compeo-tools scripts were developed on GNU/Linux and FreeBSD, but should
be reasonably portable. In particular, I expect them to run on most modern
unix platforms and elsewhere where the POSIX module is available. They have
no dependencies other than standard modules bundled with Perl. Please report
any problems or bugs to Chris Webb <chris@arachsys.com>.


Running the scripts setuid or setgid
------------------------------------

If the user running these tools should not otherwise be given access to the
serial port and if Perl is compiled with suidperl support, it is safe to set
the user or group sticky bit on all three scripts instead of changing the
ownership of the device node itself. For example, if group tty can access
the serial port, the scripts can be installed with group ownership tty and
with the group sticky (setgid) bit set.

If any of the utilities is run setuid or setgid, the serial port must be
correctly defined in $serialport near the start of the script as the COMPEO
environment variable and -d flag are silently ignored for security reasons.
The extra permissions are used only when opening the serial port.
Immediately after this, the effective user and group are restored to the
real (calling) user and group to prevent any unintended or malicious
privileged filesystem access.


compeoigc
---------

The compeoigc tool is used to list and download flight tracks. The option -d
is common to all subcommands and is used to specify the serial port connected
to the device.

Usage: compeoigc [-d PORT] [list]

  List all tracks stored on the device to STDOUT.

Usage: compeoigc [-d PORT] info

  Display the pilot name, device serial number and firmware version.

Usage: compeoigc [-d PORT] current
       compeoigc [-d PORT] TRACKNO

  Retrieve either the last viewed flight or track TRACKNO respectively. The
  resulting IGC file is printed to STDOUT. If no flight has been viewed in
  the flight log since power-on, 'compeoigc current' yields no output. (The
  behaviour of the PBRIGC NMEA command is not defined by the Compeo
  interface specification in this case.)

Usage: compeoigc [-d PORT] [-i] all

  Download all track logs from the device, storing each in the current
  directory in a file named YYYY-MM-DD-HH:MM.igc where YYYY-MM-DD is the
  date of the flight and HH:MM is the take-off time. If two or more tracks
  start in the same minute, names YYYY-MM-DD-HH:MM-N.igc for N = 1, 2, ...
  are used to distinguish them. No files will be overwritten: if a file of
  the same name already exists in the current directory, that track is not
  stored.

The output of compeoigc is plain text with the appropriate line termination
character(s) for the platform on which it is run, as understood by Perl. On
unix systems, each record in the resulting file(s) therefore ends with a
single LF. This behaviour is technically at variance with the IGC file
format as defined in appendix 1 of the IGC GNSS FR specification at

  http://www.fai.org/gliding/gnss

which specifies CR LF line-endings without regard to platform norms.
However, IGC files are more conveniently read and manipulated by other unix
tools and shell scripts without spurious control characters embedded in
them. The IGC specification also implies that the files should be stored and
transmitted as text rather than treated as an opaque binary file, so
correcting these line endings on unix platforms does not seem inappropriate.


compeowpt
---------

The compeowpt tool is used to upload and download waypoints and routes. The
option -d is common to all subcommands and is used to specify the serial
port connected to the device. Note that waypoint and route names are
case-sensitive on the Braeuniger/Flytec instruments.

Usage: compeowpt [-d PORT] [list]

  Download waypoints from the device, listing them on STDOUT. Each waypoint
  is reported on a separate line in the format

    LATITUDE,LONGITUDE,ALITUDE,NAME

  where LATITUDE and LONGITUDE are signed decimal degrees, ALTITUDE is in
  metres, and NAME is the name of the waypoint on the instrument and may be
  up to 17 ASCII characters long.

Usage: compeowpt [-d PORT] add [FILE]...

  Upload waypoints to the device, expecting the comma-separated format
  described above on STDIN or in the given files. If a waypoint of the given
  name already exists, it is replaced, otherwise a new waypoint is created.

Usage: compeowpt [-d PORT] del NAME

  If a waypoint called NAME exists on the device, delete it. Waypoints
  included in a route cannot be deleted.

Usage: compeowpt [-d PORT] clear

  Delete all stored waypoints from the device. Waypoints included in a route
  cannot be deleted. Braeuniger/Flytec instruments sometimes fail to clear
  all the unused waypoints correctly, although repeating the command a few
  times will usually remove the stragglers. (Please see the section on
  firmware bugs below. It's probably wise to confirm the waypoint list is
  indeed blank after issuing this command.)

Usage: compeowpt [-d PORT] getroute NAME

  Read the route NAME from the device, listing the waypoint names on
  successive lines of STDOUT. The special route name 'COMPETITION-ROUTE' can
  be used to retrieve the competition route.

Usage: compeowpt [-d PORT] gettask

  Read the competition route from the device, listing the waypoint names on
  successive lines of STDOUT. This is equivalent to using a name of
  COMPETITION-ROUTE with the getroute subcommand.

Usage: compeowpt [-d PORT] setroute NAME

  Read waypoint names from successive lines of STDIN and store the resulting
  route as NAME on the device. If a route of the given name already exists,
  it is replaced, otherwise a new route is created. The competition route
  can be specified as 'COMPETITION-ROUTE'.

Usage: compeowpt [-d PORT] settask

  Read waypoint names from successive lines of STDIN and store the resulting
  route as the competition route on the device, replacing any existing
  competition route. This is equivalent to using a name of COMPETITION-ROUTE
  with the setroute subcommand.

Usage: compeowpt [-d PORT] delroute NAME

  Delete the route NAME from the device if it exists. The competition route
  cannot be deleted by this command.

Usage: compeowpt [-d PORT] clearroutes

  Clear all normal routes from the device. The competition route is not
  removed by this command.


compeoset
---------

This is a very simple utility to set the pilot name, glider type and glider
id to be used in subsequent IGC flight logs. It is rather paranoid, checking
carefully for instruments known to be compatible because it uses the
manufacturer-specific PBRMEMW command to write data directly to the correct
EEPROM locations. These locations are identical for the Compeo/5030 and
Competino/5020 series, but may not be for future devices. (In particular, the
Compeo+/6030 and Competino+/6020 have not yet been tested.)

If your instrument is not recognised but you are sure that it stores these
fields in the same locations, you can use the -f option to override this
check. If you do so, please report any success or failure!


Usage: compeoset [-d PORT] [-f] pilot NAME
       compeoset [-d PORT] [-f] glidertype TYPE
       compeoset [-d PORT] [-f] gliderid ID


Braeuniger/Flytec firmware bugs
-------------------------------

Competino/5020 bugs which directly affect this software include:-

  * The '$PBRWPX,,*1F' NMEA sentence does not reliably clear the entire
    waypoint list, and must sometimes be issued multiple times to clear all
    the waypoints not in use in routes. This affects the reliability of the
    'compeowpt clear' command as mentioned above.

  * The COMPETITION-ROUTE is always present and cannot be deleted, but there
    doesn't appear to be any way of returning it to its initial empty state
    either. An attempt to use '$PBRRTR,00,01,00,COMPETITION-ROUTE*34' to set
    it to zero length has no effect, and the only way to empty the
    competition route so you can remove all of the waypoints appears to be
    by deleting all waypoints and routes via the instrument menu.

  * The IGC GNSS FR specification defines the B record barometric altitude
    as "having a fixed sea-level datum of 1013.25 HPa at 15 degrees C (i.e. 
    recording flight levels rather than height above ground or sea-level)"
    but the Braeuniger/Flytec device simply records the value of altimeter
    A1. This altimeter can be offset by the pilot, typically being set to
    match GPS height at the beginning of a flight. Moreoever, the offset
    from standard flight levels is not available in the IGC file so the
    error cannot be corrected by post-processing.

These problems were still present in version 1.18 of the Competino/5020
firmware, dated April 2007. I would be grateful to hear from users of the
Compeo/5030, Compeo+/6030, and Competino+/6020 whether or not the latest
firmware releases for their instruments also suffer from these bugs.

More generally, the Competino/5020 instruments still feel unreliable even
though they have been on the market for several years, going through quite a
few software revisions in that time. Crashes are relatively easy to induce,
error handling is eccentric, and cosmetic issues are rife---these include
inconsistent and untidy capitalisation and abbreviations in the menus and
displays, and use of physically nonsensical terms like 'L/D Gnd' for ground
glide slope. Whilst blemishes like these hardly constitute showstopping
bugs, they don't really inspire confidence in the code quality either.

Please feel free to complain to Braeuniger/Flytec about their poor software,
but many of these issues were brought to their attention years ago and they
do not seem inclined to address them. This is a pity, especially given the
relatively high cost of these instruments compared to a typical (better
specified and built) GPS PDA, and is yet another salutary demonstration of
the risk of buying devices that are dependent on closed, proprietary
firmware.


Contact
-------

compeo-tools was written by Chris Webb <chris@arachsys.com> and is
distributed as Free Software under the terms of the MIT license.