'\" t
.\" Title: gps
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1
.\" Date: 9 Aug 2004
.\" Manual: GPSD Documentation
.\" Source: The GPSD Project
.\" Language: English
.\"
.TH "GPS" "1" "9 Aug 2004" "The GPSD Project" "GPSD Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
cgps, gegps, gps, lcdgps, xgps, xgpsspeed \- test clients for gpsd
.SH "SYNOPSIS"
.HP \w'\fBcgps\fR\ 'u
\fBcgps\fR [\-D\ \fIdebug\-level\fR] [\-h] [\-l\ [[d]\ |\ [m]\ |\ [s]]] [\-m] [\-s] [\-u\ [[i]\ |\ [n]\ |\ [m]]] [\-V] [\fIserver\fR [\fI:port\fR [\fI:device\fR]]]
.HP \w'\fBgegps\fR\ 'u
\fBgegps\fR [\-d\ \fIdirectory\fR] [\-h] [\-i] [\-V]
.HP \w'\fBlcdgps\fR\ 'u
\fBlcdgps\fR [\-h] [\-j] [\-l\ [[d]\ |\ [m]\ |\ [s]]] [\-s] [\-u\ [[i]\ |\ [n]\ |\ [m]]] [\-V] [\fIserver\fR [\fI:port\fR [\fI:device\fR]]]
.HP \w'\fBxgps\fR\ 'u
\fBxgps\fR [\-?] [\-D\ \fIdebug\-level\fR] [\-h] [\-l\ [[d]\ |\ [m]\ |\ [s]]] [\-u\ [[i]\ |\ [n]\ |\ [m]]] [\-r\ \fIdegrees\fR] [\-V] [\fIserver\fR [\fI:port\fR [\fI:device\fR]]]
.HP \w'\fBxgpsspeed\fR\ 'u
\fBxgpsspeed\fR [\-\-debug\ \fIdebug\-level\fR] [\-\-device\ \fIdevice\fR] [\-h] [\-\-host\ \fIhost\fR] [\-\-landspeed] [\-\-maxspeed\ \fImaxspeed\fR] [\-\-nautical] [\-\-port\ \fIport\fR] [\-\-speedunits\ {[mph]\ |\ [kph]\ |\ [knots]}] [\-V] [\fIserver\fR [\fI:port\fR [\fI:device\fR]]]
.SH "DESCRIPTION"
.PP
These are the demonstration clients shipped with
gpsd\&. They have some common options:
.PP
The
\fB\-h\fR
option causes each client to emit a summary of its options and then exit\&.
.PP
The
\fB\-V\fR
option causes each client to dump the package version and exit\&.
.PP
The
\fB\-l\fR
option, when present, sets the format of latitude and longitude reports\&. The value \*(Aqd\*(Aq produces decimal degrees and is the default\&. The value \*(Aqm\*(Aq produces degrees and decimal minutes\&. The value \*(Aqs\*(Aq produces degrees, minutes, and decimal seconds\&.
.PP
xgps,
cgps, and
lcdgps
look at variables in the environment to figure out what units they should default to using for display \(em imperial, nautical, or metric\&. Here are the variables and values they check:
.sp
.if n \{\
.RS 4
.\}
.nf
GPSD_UNITS one of:
imperial = miles/feet
nautical = knots/feet
metric = km/meters
LC_MEASUREMENT
en_US = miles/feet
C = miles/feet
POSIX = miles/feet
[other] = km/meters
LANG
en_US = miles/feet
C = miles/feet
POSIX = miles/feet
[other] = km/meters
.fi
.if n \{\
.RE
.\}
.PP
These preferences may be overridden by the
\fB\-u\fR
option\&.
.PP
Where present, the
\fB\-u\fR
option can be used to set the system units for display; follow the keyword with \*(Aqi\*(Aq for \*(Aqimperial\*(Aq for American units (International Feet in altitude and error estimates, miles per hour in speeds), \*(Aqn\*(Aq for \*(Aqnautical\*(Aq (feet in altitude and error estimates, knots in speed) or \*(Aqm\*(Aq for \*(Aqmetric\*(Aq (meters in altitude and error estimates, kilometers per hour in speeds)\&.
.PP
Note: The USA Survey Foot is not supported\&.
.PP
The
\fB\-D\fR
option, when present, sets a debug level; it is primarily for use by GPSD developers\&. It enables various progress messages to standard error\&.
.PP
By default, clients collect data from all compatible devices on localhost, using the default GPSD port 2947\&. An optional argument to any client may specify a server to get data from\&. A colon\-separated suffix is taken as a port number\&. If there is a second colon\-separated suffix, that is taken as a specific device name to be watched\&. However, if the server specification contains square brackets, the part inside them is taken as an IPv6 address and port/device suffixes are only parsed after the trailing bracket\&. Possible cases look like this:
.PP
The options for xgps can be placed in the XGPSOPTS environment variable\&. XGPSOPTS is processed before the CLI options\&.
.PP
localhost:/dev/ttyS1
.RS 4
Look at the default port of localhost, trying both IPv4 and IPv6 and watching output from serial device 1\&.
.RE
.PP
example\&.com:2317
.RS 4
Look at port 2317 on example\&.com, trying both IPv4 and IPv6\&.
.RE
.PP
71\&.162\&.241\&.5:2317:/dev/ttyS3
.RS 4
Look at port 2317 at the specified IPv4 address, collecting data from attached serial device 3\&.
.RE
.PP
[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5
.RS 4
Look at port 2317 at the specified IPv6 address, collecting data from attached serial device 5\&.
.RE
.PP
Not all clients shipped with GPSD are documented here\&. See also the separate manual pages for
\fBgpspipe\fR(1)
and
\fBgpsmon\fR(1)
and
\fBgpxlogger\fR(1)
\&.
.SS "xgps"
.PP
xgps
is a simple test client for
gpsd
with an X interface\&. It displays current GPS position/time/velocity information and (for GPSes that support the feature) the locations of accessible satellites\&.
.PP
In the sky view, satellites are color\-coded to indicate quality of signal; consult the data display to the left for exact figures in dB\&. Square icons indicate SBAS/WAAS/EGNOS satellites, circles indicate ordinary GPS satellites\&. Filled icons were used in the current fix, outline icons were not\&.
.PP
The \-r option accepts an argument in degrees, to rotate the skyview counterclockwise\&.
.SS "xgpsspeed"
.PP
xgpsspeed
is a speedometer that uses position information from the GPS\&. It accepts an \-h option and optional argument as for
gps, or a \-V option to dump the package version and exit\&.
.PP
The default display mode is a speed and track presentation modeled after a marine navigation display; for backward compatibility the \-\-nautical option forces this mode\&. The \-\-landspeed option produces a simple speedometer\&.
.PP
The \-speedunits option can be used to set the speed units for display; follow the keyword with knots for nautical miles per hour, kph for kilometres per hour, or mph for miles per hour\&. The default is miles per hour\&.
.PP
In the nautical mode only, \-\-maxspeed sets the maximum on the speedometer\&.
.SS "cgps"
.PP
cgps
is a client resembling
xgps, but without the pictorial satellite display and able to run on a serial terminal or terminal emulator\&.
.PP
The
\fB\-s\fR
option prevents
cgps
from displaying the data coming from the daemon\&. This display can also be toggled with the s command\&.
.PP
The
\fB\-m\fR
option will display your magnetic track (as opposed to your true track)\&. This is a calculated value, not a measured value\&. Magnetic variation is always potentially subject to large errors, but is usually better than two degrees\&.
.PP
cgps
terminates when you send it a SIGHUP or SIGINT; given default terminal settings this will happen when you type Ctrl\-C at it\&. It will also terminate on \*(Aqq\*(Aq
.SS "lcdgps"
.PP
A client that passes
gpsd
data to
lcdproc, turning your car computer into a very expensive and nearly feature\-free GPS receiver\&. Currently assumes a 4x40 LCD and writes data formatted to fit that size screen\&. Also displays 4\- or 6\-character Maidenhead grid square output\&.
.SS "gegps"
.PP
This program collects fixes from
gpsd
and feeds them to a running instance of Google Earth for live location tracking\&.
.PP
The
\fB\-d\fR
argument is the location of the Google Earth installation directory\&. If not specified, it defaults to the current directory\&.
.PP
If you have the free (non\-subscription) version, start by running with the
\fB\-i\fR
option to drop a clue in the Google Earth installation directory, as \*(AqOpen_in_Google_Earth_RT_GPS\&.kml\*(Aq, then open that file in Places (File > Open\&.\&.\&.)\&. Run
gegps
in the normal way after that\&.
.SH "ENVIRONMENT"
.PP
The
\fBXGPSOPTS>\fR
environment variable may be set to pass commonly used command line options to
\fBxgps\fR
and
\fBxgpsspeed\fR\&. This is often used to set the
\fB\-u\fR
option for locale specific units\&.
\fBXGPSOPTS\fR
is processed before the CLI options\&.
.SH "SEE ALSO"
.PP
\fBgpsd\fR(8),
\fBlibgps\fR(3),
\fBlibgpsmm\fR(3),
\fBgpsfake\fR(1),
\fBgpsctl\fR(1),
\fBgpscat\fR(1),
\fBgpsprof\fR(1)\&.
\fBgpspipe\fR(1)\&.
\fBgpsmon\fR(1)\&.
\fBgpxlogger\fR(1)\&.
.SH "AUTHORS"
.PP
Remco Treffcorn, Derrick Brashear, Russ Nelson & Eric S\&. Raymond, Jeff Francis (cgps), Chen Wei
(gegps & xgpsspeed), Robin Wittler
(xgpsspeed)\&.
.PP
This manual page by Eric S\&. Raymond