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 <firstname.lastname@example.org>. 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 <email@example.com> and is distributed as Free Software under the terms of the MIT license.