                           GARNIX v16.2

Copyright (C) 1996-2007 Anton Helm, Farnborough, Hampshire, UK

This file is distributed under the terms listed in the document
"copying.gx", available from Anton Helm at the address above.
A copy of "copying.gx" should accompany this file; if not, a copy
should be available from where this file was obtained.  This file
may not be distributed without a verbatim copy of "copying.gx".

This file is distributed WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.



1) Invoking GARNIX

Type

garnix -h

for a list of command line options.

GARNIX first looks for <garnix.cfg> to configure your com port.
Then it tries to connect to your garmin and reads the device ID
and current time.

If no command line options are given GARNIX reads the current position.

GARNIX can upload/download/convert waypoints, routes and trackpoints.

If you want to upload data you must specify a file with the
-f option.

GARNIX auto-detects the following input file formats:
*) GARNIX data format (see below)
*) OziExlorer data formats
*) Waypoint+ text format

If you don't specify an output file on download or conversion,
the data is printed on the screen. You can use |, > or >> to
redirect output data to another program or file.

Output file format is GARNIX data format unless you specify
-o for OziExplorer or -y for Waypoint+ text format.

GARNIX is in download mode unless you specify -u (upload) or 
-c (convert) at the command line.

You cannot mix upload, download and conversion.


2) Data

Waypoints:
If you want to upload/download/convert waypoints specify -w at the
command line.

Routes:
If you want to upload/download/convert routes specify -r at the command line.

Trackpoints:
If you want to upload/download/convert trackpoints specify -t at the
command line.

Any combination of -w, -r and -t is valid, duplicate switches are ignored.

Single waypoint:
If you want to upload/download/convert a single waypoint specify
-W <waypoint name> at the command line.
-W and -w don't mix.

Single route:
If you want to upload/download/convert a single route specify
-R <route number> at the command line.
-R and -r don't mix.

Single Track:
If you want to upload/download/convert a single track specify
-T <track name> at the command line.
-T and -t don't mix.


3) Coordinate conversion

*** From GARNIX version v12 on standalone-GEO is no longer required
*** for coordinate conversion. GARNIX is now linked with LIBGEO.
*** Standalone version of GEO is no longer required and no longer used
*** by GARNIX. Datum, ellipsoid amd grid configuration files
*** are now packed with GARNIX. These files are mandatory
*** for GARNIX working properly. Keep them somewhere in your PATH.
*** Avoid duplicates!

If you specify a datum and/or grid when downloading GARNIX performs
conversions

-d <datum name>
-g <grid name>
-z <zone name>

are the corresponding command line options.

NOTE: These three names are case sensitive!
If you are not sure about the actual names, take a look at
the *.cfg files of GARNIX.


4) Other Features

GARNIX can power down your Garmin GPS with the -p command line option.
You can combine -p with all other commands. It will be executed
as the LAST COMMAND, no matter which position it had on the
command line. To force GARNIX to power down your GPS device WITHOUT
asking for confirmation use the -P command line option.

GARNIX doesn't connect to your Garmin GPS if you convert data files only.
Therefore it is not necessary to have it powered up or connected for this
operation. This implies that the "power down" command cannot be combined
with file conversion.


5) GARNIX File Format:

GARNIX files are plain text files. They can contain waypoints
and/or routes and/or tracks and comment.

Anything between a ';' (semicolon) and the end of a line is a comment.
GARNIX puts some comment lines at the beginning of each downloaded or converted
file containing the Garmin ID (if downloading) and the date/time of the
download/conversion.

***
*** These and all other comments are lost when converting files !
***

Wayppoints:
A waypoint can be in DMS or grid coordinates.
In case of DMS:

<lat> <lon> <altitude> <datum> <name> <comment> [<map symbol> <display mode>] ;

In case of grid:

<northing> <easting> <altitude> <datum> <grid> <zone> <name> <comment> [<map symbol> <display mode>] ;

<lat> and <lon> can be in any DMS format.
                GARNIX output uses  (degree sign), ' and " for DMS
                but deg, min and sec can be used for input if your
                text editor has problems with the degree sign.
                NOTE: Minutes and seconds are optional. I.e. you can also use decimal degrees.
<northing> and <easting> are in km.
<altitude>      is in m.
<datum>, <grid> and <zone> according to LIBGEOs config files.
<name>          Waypoint name, if the device supports fewer characters then given, the name 
                will be truncated.
<comment>       This is the comment string sent/received to/from the GPS.
                If the device supports fewer characters then given, the comment will be truncated. 
                Do not confuse this with file comments which can be written after 
                a ';' (Semicolon).
<map symbol>    Symbol name as listed below. Positive integer
                numbers can be used for backward compatibility.
                (Not all symbols are supported by all devices. If a symbol
                is not supported the default waypoint symbol is used.)
<display mode>  If specified - is either N (default), C, S or X.
                N ... name and symbol
                C ... comment and symbol
                S ... symbol only
                X ... hide
                (Not all devices support all display modes. If a mode
                given is not supported it will default to N.)

All fields except <map symbol> and <display mode> are required.
If <grid> <datum> <zone> <name> <comment> starts with a digit
or a special character it has to be wrapped with double quotes (").
Empty comments are valid and can be written as "".
The <display mode> can be omitted and defaults to 'N'.
<map symbol> can be omitted. In this case no <display mode> can
be specified and the [] have to be omitted.

Symbol names (Not all garmin devices support all symbol names):
anchor, bell, diamond_grn, diamond_red, dive1, dive2, dollar, fish, 
fuel, horn, house, knife, light, mug, skull, square_grn, square_red, 
wbuoy, wpt_dot, wreck, null, mob, buoy_ambr, buoy_blck, buoy_blue, 
buoy_grn, buoy_grn_red, buoy_grn_wht, buoy_orng, buoy_red, buoy_red_grn,
buoy_red_wht, buoy_violet, buoy_wht, buoy_wht_grn, buoy_wht_red, dot, 
rbcn, boat_ramp, camp, restrooms, showers, drinking_wtr, phone, 
first_aid, info, parking, park, picnic, scenic, skiing, swimming, dam, 
controlled, danger, restricted, null_2, ball, car, deer, shpng_cart, 
lodging, mine, trail_head, truck_stop, user_exit, flag, circle_x, 
open_24hr, fhs_facility, bot_cond, tide_pred_stn, anchor_prohib, 
beacon, coast_guard, reef, weedbed, dropoff, dock, marina, bait_tackle, 
stump, is_hwy, us_hwy, st_hwy, mi_mrkr, trcbck, golf, sml_cty, med_cty, 
lrg_cty, freeway, ntl_hwy, cap_cty, amuse_pk, bowling, car_rental, 
car_repair, fastfood, fitness, movie, museum, pharmacy, pizza, post_ofc, 
rv_park, school, stadium, store, zoo, gas_plus, faces, ramp_int, st_int, 
weigh_sttn, toll_booth, elev_pt, ex_no_srvc, geo_place_mm, geo_place_wtr,
geo_place_lnd, bridge, building, cemetery, church, civil, crossing, 
hist_town, levee, military, oil_field, tunnel, beach, forest, summit, 
lrg_ramp_int, lrg_ex_no_srvc, badge, cards, snowski, iceskate, wrecker, 
border, geocache, geocache_fnd, cntct_smiley, cntct_ball_cap, cntct_big_ears,
cntct_spike, cntct_goatee, cntct_afro, cntct_dreads, cntct_female1, 
cntct_female2, cntct_female3, cntct_ranger, cntct_kung_fu, cntct_sumo, 
cntct_pirate, cntct_biker, cntct_alien, cntct_bug, cntct_cat, cntct_dog, 
cntct_pig, hydrant, flag_blue, flag_green, flag_red, pin_blue, pin_green, 
pin_red, block_blue, block_green, block_red, bike_trail, circle_red, 
circle_green, circle_blue, diamond_blue, oval_red, oval_green, oval_blue, 
rect_red, rect_green, rect_blue, square_blue, letter_a_red, letter_b_red, 
letter_c_red, letter_d_red, letter_a_green, letter_c_green, letter_b_green,
letter_d_green, letter_a_blue, letter_b_blue, letter_c_blue, letter_d_blue, 
number_0_red, number_1_red, number_2_red, number_3_red, number_4_red, 
number_5_red, number_6_red, number_7_red, number_8_red, number_9_red, 
number_0_green, number_1_green, number_2_green, number_3_green, 
number_4_green, number_5_green, number_6_green, number_7_green, 
number_8_green, number_9_green, number_0_blue, number_1_blue, 
number_2_blue, number_3_blue, number_4_blue, number_5_blue, number_6_blue, 
number_7_blue, number_8_blue, number_9_blue, triangle_blue, triangle_green,
triangle_red, food_asian, food_deli, food_italian, food_seafood, food_steak, 
airport, int, ndb, vor, heliport, private, soft_fld, tall_tower, short_tower, 
glider, ultralight, parachute, vortac, vordme, faf, lom, map, tacan, seaplane


Routes:
BEGIN ROUTE <number> <comment>;
<waypoints>
END ROUTE;

<waypoints> can be way waypoints in the above format. It is not necessary
to rewrite a complete waypoint entry if a waypoint occurs more then once.
Simply write
<name>;
if the waypoint was already defined somewhere above. There is no difference
whether you define a waypoint inside a route or outside.

If you download routes and waypoints into one file, duplicate waypoints
are referenced by their names and in the waypoint section of the file only
waypoints which are NOT IN ANY ROUTE are listed.

Some garmin models create an automatic comment for routes (from the
first and the last waypoint name). This comment cannot be downloaded.


Tracks:
From GARNIX v15 on tracks need to have a BEGIN and END similar to routes.
This is to support devices that can store named tracks.

BEGIN TRACK <name>;
<trackpoints>
END TRACK;

<trackpoints> can be in DMS or grid coordinates.
In case of DMS:

<lat> <lon> <altitude> <datum> <date/time> ;

In case of grid:

<northing> <easting> <altitude> <datum> <grid> <zone> <date/time> ;

where the fields are defined as above.
<date/time> contains the creation date/time of the trackpoint.
Unfortunately most Garmin devices set the creation time of uploaded
trackpoints to 0. Therefore the <date/time> field is irrelevant for
uploading as long as it keeps to the <date/time> syntax which is:

hh:mm:ss-YYYY/MM/DD

(The former hh:mm:ss-YY/MM/DD has been replaced to avoid Y2k problems.
But you can still read old files.)

NOTE: Not all garmin devices allow uploading of tracks.


6) Configuration Files:

Where does GARNIX look for configuration files?
* First GARNIX looks into the current directory
* Then GARNIX reads the PATH environment variable and 
  looks into every directory (from left to right...) until
  it finds the file.

<datum.cfg> is a LIBGEO configuration file that contains
datum parameters. If you want to add a datum you can edit this file.
Note: Datum names should not contain any whitespace or special characters.
Aliases are provided for some datum for compatibility with OziExplorer.
These aliases can contain whitespace and some special characters. 
However if they do the aliases need to be wrapped with "". E.g.:
ALIAS: "WGS 84" WGS84

<ell.cfg> is a LIBGEO configuration file that contains ellipsoid data
used by datums in <datum.cfg>. It is unlikely that you need to edit 
this file.

<grid.cfg> is a LIBGEO configration file hat contains grid definitions.
If you want to add a new grid you can edit this file.

<garnix.cfg> contains the com-port definitions grid and datum 
defaults (if any). If <garnix.cfg> doesn't exist, default values 
are used. Anything between the first semicolon in a line and the 
end of the line is considered a comment and ignored.

Default values are:

port:   	1; (for DOS)
port:		"/dev/ttyS0"; (for posix systems)
datum:  	"WGS84";

If you use a USB-Serial converter on OSX (e.g. with the PL2303 chipset)
then your serial port is most likely at "/dev/cu.usbserial"

You can also specify a grid:
e.g.:

grid:   	"UTM";

to set the default output to UTM (you can use any other grid).
Use -n on the command line to override this default and 
set output to DMS.

Use -m on the command line to override this default and 
set output to decimal degrees.

If you specified a grid, you can also specify a grid zone in <garnix.cfg>
e.g.:

zone:   	"5";

to force output to be in coordinates of given zone name (or number)
even if the coordinate value is actually outside this zone.

You can force GARNIX to use deg/min/sec instead /'/" for output.
specify the following command in <garnix.cfg> :
deg_min_sec;

You can force GARNIX to use decimal degrees (no minutes, seconds) for output.
specify the following command in <garnix.cfg> :
dec_deg;
NOTE: deg_min_sec and dec_deg can be combined.

Certain parameters for OziExplorer data files can be set in <garnix.cfg>:

Symbol size:
ozi_ssz:		17;

Font Size:
ozi_fsz:		6;

Background colour:
ozi_bcl:		65535;

Foreground (Font) colour:
ozi_fcl:		0;

Track line width:
ozi_tlw:		2;



Some remarks on working with OziExplorer files:

While the rte files contain most waypoint information they lack
altitude. If you have both an rte and a wpt file, upload the wpt file
AFTER the rte file so that you overwrite the rte waypoints with the 
ones from the wpt file, so you don't lose the altitude information.
This is also the reason why GARNIX creates both wpt and rte files
when you command downloading routes only (the wpt file in this case
contains only the waypoints used in routes).

OziExplorer plt files contain only one track. When downloading more
than one track multiple files are created by appending two digits
to the stem of the filename.

GARNIX does not use the same datum definitions or names as OziExplorer.
Some of the datums provided in <datum.cfg> are calculated with more
accurate formulas (9 parameters) and therfore can lead to slightly 
different results than when using OziExplorer (5 parameters).
GARNIX will only output OziExplorer files based on WGS84 datum.
GARNIX will attempt to convert OziExplorer files if they use a different
datum. If you get an error message that a certain datum was not found,
please check <datum.cfg> and if necessary add the datum parameters 
or an alias. Several such aliases are already provided in <datum.cfg>.

Please note that OziExplorer is very sensitive to text file formats.
If you create/manipulate files on a non-Windows platform and you 
experience difficulties loading them into OziExplorer this is most likely
because the files don't have the DOS-style CR+LF format.
GARNIX will always produce CR+LF for OziExplorer files but if you
edit them in a text editor or transfer them between systems, this 
format might be changed.

OziExplorer data files contain floating point time stamps.
Converting these into seconds (as used in garmin devices) requires 
rounding. Especially on repeated file conversions you will notice
slight differences in the time stamps resulting from this rounding.




Additionally <garnix.cfg> can contain a command for invoking
a preprocessor on the input files.

******************************************************************
* THIS FEATURE IS NOW DEPRECATED. IT WILL BE REMOVED FROM FUTURE *
* VERSIONS OF GARNIX!                                            *
******************************************************************

DON'T USE THIS FEATURE IF YOU DONT KNOW HOW PREPROCESSORS WORK!

Example:
You can use the GNU C preprocessor (cpp) with the following
statement in <garnix.cfg> :

cpp:            "cpp -P -undef -traditional";

The command in quotes is simply the command which is sent
to the OS when cpp is invoked. The input and output filenames
are appended automatically. The preprocessor is only invoked when
the <cpp:> statement in <garnix.cfg> exists. To avoid confusion
this feature is disabled by default. 

Some temporary files are created during preprocessor operation.
These files reside in your systems temporary directory (either
TEMP, TMP or TEMDIR from yor environment). If this directory is
read-only or there is no more diskspace you might get errors.
All temporary files are deleted when GARNIX terminates normally.

<cpp> is not part of GARNIX. Get it from DJGPP distribution.
for the DOS version of GARNIX or Cygwin for the Windows 
version. Most Linux systems have <cpp> installed.
With <cpp> you can use such preprocessor features like

#include
#define

etc. You can create waypoint and route library files and include them
into your datafile.
