gpsd/man/cgps.adoc

= cgps(1)
:date: 25 February 2021
:keywords: gps, gpsd, cgps
:manmanual: GPSD Documentation
:mansource: GPSD Version {gpsdver}
:robots: index,follow
:sectlinks:
:toc: macro
:type: manpage
:webfonts!:

include::../www/inc-menu.adoc[]

== NAME

cgps - curses terminal client for gpsd

== SYNOPSIS

*cgps* [OPTIONS] [server[:port[:device]]]

*cgps* -h

*cgps* -V

== DESCRIPTION

*cgps* is an ncurses based *gpsd* client. It is able to run on a serial
terminal or terminal emulator. It resembles *xgps*(1), but without the
pictorial satellite display and does not require X or other windowing
system.

*cgps* does not require root privileges. It will also run fine as root.
Running under sudo will cause loss of functionality.

None of the error estimates provided by *gpsd*, and displayed by *cgps*,
should be taken as anything other than "goodness" levels.  GNSS receiver
manufactures often do not document the basis for their estimates.  Those
that do document their estimates are inconsistent about what they mean.

== OPTIONS

*-?*, *-h*, *--help*::
  Print a summary of options and then exit.
*-D LVL*, *--debug LVL*::
  Sets the debug level; it is primarily for use by GPSD developers. It
  enables various progress messages to standard error.
*-l FMT*, *--llfmt FMT*::
  Sets the format of latitude and longitude reports. The value 'd'
  produces decimal degrees and is the default. The value 'm' produces
  degrees and decimal minutes. The value 's' produces degrees, minutes,
  and decimal seconds.
*-s*, *--silent*::
  Prevents *cgps* from displaying the raw data coming from the daemon. This
  display can also be toggled with the s command.
*-m*, *--magtrack*::
  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.
*-u UNITS*, *--units UNITS*::
  Set the system units for display; follow the keyword with 'i' for
  'imperial' for American units (International Feet in altitude and
  error estimates, miles per hour in speeds), 'n' for 'nautical' (feet
  in altitude and error estimates, knots in speed) or 'm' for 'metric'
  (meters in altitude and error estimates, kilometers per hour in
  speeds).
+
Note: The USA Survey Foot is not supported.
*-V*, *--version*::
  Print the package version and exit.

== ARGUMENTS

By default, clients collect data from the local *gpsd* daemon running
on localhost, using the default GPSD port 2947. The optional argument
to any client may override this behavior: *[server[:port[:device]]]*

For further explanation, and examples, see the *ARGUMENTS* section in
the *gps*(1) man page

== COMMANDS

*cgps* terminates when you send it a SIGHUP or SIGINT; given default
terminal settings this will happen when you type Ctrl-C at it.

*cgps* will accept a few single letter commands while running:

*c*:: Clear the bottom window.
*d*:: Show lat/lon dd.dddddddd, dd mm.mmmmmm and dd mm ss.ssss
*h*:: Popup a help window.
*i*:: Use imperial units.
*m*:: Use metric units.
*n*:: Use nautical units.
*q*:: Clear screen and exit
*s*:: Toggle showing raw JSON data in the bottom window.
*t*:: Toggle true/magnetic track.

== ENVIRONMENT

The environment variable *GPSD_UNITS* is checked if no unit system is
specified on the command line. It may be set to 'i'. 'imperial', 'm',
'metric', or 'n', 'nautical'.

+LC_MEASUREMENT+ and then +LANG+ are checked if no unit system has
been specified on the command line, or in +GPSD_UNITS+. If the value
is 'C', 'POSIX', or begins with 'en_US' the unit system is set to
imperial. The default if no system has been selected defaults to metric.

== RETURN VALUES

*0*:: on success.
*1*:: on failure

== SEE ALSO

*gegps*(1), *gpsctl*(1), *gps*(1), gpsprof*(1), *gpsfake*(1),
*gpscat*(1), *gpspipe*(1), *gpsmon*(1), xgps*(1). *xgpsspeed*(1)

*libgps*(3), *libgpsmm*(3)

*gpsd*(8)

== RESOURCES

*Project web site:* {gpsdweb}

== COPYING

This file is Copyright 2013 by the GPSD project +
SPDX-License-Identifier: BSD-2-clause