gpsd.8

gpsd, a popular GPS daemon.

.\"Generated by db2man.xsl. Don't modify this, modify the source.
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "GPSD" 8 "" "" ""
.SH NAME
gpsd \- interface daemon for GPS receivers
.SH "SYNOPSIS"
.ad l
.hy 0
.HP 5
\fBgpsd\fR [\-f\ \fIGPS\-devicename\fR] [\-F\ \fIcontrol\-socket\fR] [\-S\ \fIlistener\-port\fR] [\-b] [\-n] [\-N] [\-h] [\-P\ \fIpidfile\fR] [\-D\ \fIdebuglevel\fR] [\-V] [[\fIsource\-name\fR]...]
.ad
.hy

.SH "DESCRIPTION"

.PP
gpsd is a monitor daemon that watches a TCP/IP port (2947 by default), waiting for applications to request information from GPSes or differential\-GPS radios attached to the host machine\&. Each GPS or radio is expected to be direct\-connected to the host via a USB or RS232C serial port\&. The port may be specified to gpsd at startup, or it may be set via a command shipped down a local control socket (e\&.g\&. by a USB hotplug script)\&. Given a GPS device by either means, gpsd discovers the correct port speed and protocol for it\&.

.PP
gpsd should be able to query any GPS that speaks either the standard textual NMEA 0183 protocol, or the binary Rockwell protocol used by EarthMate and some other GPSes, the TSIP binary protocol used by Trimble GPSes, or the binary SiRF protocol used by SiRFstar chipsets, or the Garmin binary protocol used by the USB version of the Garmin 18 and other Garmin USB GPSes, or the binary protocol used by Evermore chipsets, or the extended NMEA used by iTrax\&. gpsd effectively hides the differences among these\&. It also knows about and uses commands that tune the GPS for lower latency, decreased bandwidth usage, or increased accuracy on the San Jose Navigation FV18, the Sony CXD2951, the uBlox, and the Motorola OnCore GT+\&. It can read heading and attitude information from the True North Technologies Revolution 2X Digital compass\&.

.PP
gpsd can use differential\-GPS corrections from a DGPS radio or over the net, from a ground station running a DGPSIP server or a Ntrip broadcaster that reports RTCM\-S104 data; this will improve user error by roughly a factor of four\&. When gpsd opens a serial device emitting RTCM\-104, it automatically recognizes this and uses the device as a correction source for all connected GPSes\&.  See [xref to refsect1] and [xref to refsect1] for discussion\&.

.PP
The program accepts the following options:

.TP
\-f
Set a GPS device name\&. This option is deprecated and may be removed in a future version\&. Each command\-line argument will be treated as a device to be probed for the presence of a GPS; that, rather than the \-f option, is the preferred way of specifying GPS devices at startup\&.

.TP
\-F
Create a control socket for device addition and removal commands\&. You must specify a valid pathname on your local filesystem; this will be created as a Unix\-domain socket to which you can write commands that edit the daemon's internal device list\&.

.TP
\-S
Set TCP/IP port on which to listen for GPSD clients (default is 2947)\&.

.TP
\-d
This is a deprecated option which takes a differential\-GPS source as argument\&. See the description of argument interpretation below\&.

.TP
\-b
Broken\-device\-safety, otherwise known as read\-only mode\&. Some popular bluetooth and USB receivers lock up or become totally inaccessible when probed or reconfigured\&. This switch prevents gpsd from writing to a receiver\&. This means that gpsd cannot configure the receiver for optimal performance, but it also means that gpsd cannot break the receiver\&. A better solution would be for bluetooth to not be so fragile\&. A platform independent method to identify serial\-over\-bluetooth devices would also be nice\&.

.TP
\-n
Don't wait for a client to connect before polling whatever GPS is associated with it\&. The wait is a feature; many serial GPSes go to a standby mode (not drawing power) before the host machine asserts DTR, so waiting for the first actual request can save valuable battery power on portable equipment\&. This option combines well with \-D2 to enable monitoring of the GPS data stream\&.

.TP
\-N
Don't daemonize; run in foreground\&. Also suppresses privilege\-dropping\&. This switch is mainly useful for debugging\&. Its meaning may change in future versions\&.

.TP
\-h
Display help message and terminate\&.

.TP
\-P
Specify the name and path to record the daemon's process ID\&.

.TP
\-D
Set debug level\&. At debug levels 2 and above, gpsd reports incoming sentence and actions to standard error if gpsd is in the foreground (\-N) or to syslog if in the background\&.

.TP
\-V
Dump version and exit\&.

.PP
Arguments are interpreted as the names of data sources\&. Normally, a data source is the name of a local serial device from which the daemon may expect GPS data\&.

.PP
A data source name may also be a URL pointing to a specific differential\-GPS service (DGPSIP server or Ntrip broadcaster)\&.If the URL starts with "ntrip://" Ntrip will be used; if the URL starts with "dgpsip://", DGPSIP will be used\&. Gpsd also defaults to DGPSIP if no protocol is defined\&. For Ntrip services that require authentication, a prefix of the form "username:password@" can be added before the name of the Ntrip broadcaster\&. If a suffix of the service name begins with ":" it is interpreted as a port number, overriding the default IANA\-assigned port of 2101\&. For Ntrip service you also need to specify which stream to use; the stream is given in the form "/streamname"\&. So, an example DGPSIP URL could be "dgpsip://dgpsip\&.example\&.com" and a Ntrip URL could be "ntrip://foo:bar@ntrip\&.example\&.com:80/example\-stream"\&.

.PP
Internally, the daemon maintains a device list holding the pathnames of GPSes known to the daemon\&. Initially, this list is the list of device\-name arguments specified on the command line\&. That list may be empty, in which case the daemon will have no devices on its search list until they are added by a control\-socket command (see [xref to refsect1] for details on this)\&. Daemon startup will abort with an error if neither any devices nor a control socket are specified\&.

.PP
At any given time, each client will be listening to only one of the GPSes on the device list\&. By default, a client's device is the one that most recently shipped information to the daemon at the time the client first requests GPS information (that is, issues any command other than F, K, W=0 or R=0)\&.

.PP
The request protocol for gpsd clients is very simple\&. Each request normally consists of a single ASCII character followed by a newline\&. Case of the request character is ignored\&. Each request returns a line of response text ended by a CR/LF\&. Requests and responses are as follows, with %f standing for a decimal float numeral and %d for decimal integer numeral:

.TP
a
The current altitude as "A=%f", meters above mean sea level\&.

.TP
b
The B command with no argument returns four fields giving the parameters of the serial link to the GPS as "B=%d %d %c %d"; baud rate, byte size, parity, (N, O or E for no parity, odd, or even) and stop bits (1 or 2)\&. The command "B=%d" sets the baud rate, not changing parity or stop bits; watch the response, because it is possible for this to fail if the GPS does not support a speed\-switching command\&. In case of failure, the daemon and GPS will continue to communicate at the old speed\&. The B= form is rejected if more than one client is attached to the channel\&.

.TP
c
C with no following = asks the daemon to return the cycle time of the attached GPS, if any\&. If there is no attached device it will return "C=?"\&.

If the driver has the capability to change sampling rate the command "C=%f" does so, setting a new cycle time in seconds\&. The "C=" form is rejected if more than one client is attached to the channel\&.

If the driver has the capability to change sampling rate, this command always returns "C=%f %f" giving the current cycle time in seconds and the minimum possible cycle time at the current baud rate\&. If the driver does not have the capability to change sampling rate, this returns, as "C=%f", the cycle time in seconds only\&.

Either number may be fractional, indicating a GPS cycle shorter than a second; however, if >1 the cycle time must be a whole number\&. Also note that relatively few GPSes have the ability to set sub\-second cycle times; consult your hardware protocol description to make sure this works\&.

This command will return "C=?" at start of session, before the first full packet has been received from the GPS, because the GPS type is not yet known\&. To set up conditions for a real answer, issue it after some command that reads position/velocity/time information from the device\&.

.TP
d
Returns the UTC time in the ISO 8601 format, "D=yyyy\-mm\-ddThh:nmm:ss\&.ssZ"\&. Digits of precision in the fractional\-seconds part will vary and may be absent\&.

.TP
e
Returns "E=%f %f %f": three estimated position errors in meters -- total, horizontal, and vertical (95% confidence level)\&. Note: many GPSes do not supply these numbers\&. When the GPS does not supply them, gpsd computes them from satellite DOP using fixed figures for expected non\-DGPS and DGPS range errors in meters\&. A value of '?' for any of these numbers should be taken to mean that component of DOP is not available\&. See also the 'q' command\&.

.TP
f
Gets or sets the active GPS device name\&. The bare command 'f' requests a response containing 'F=' followed by the name of the active GPS device\&. The other form of the command is 'f=', in which case all following printable characters up to but not including the next CR/LF are interpreted as the name of a trial GPS device\&. If the trial device is in gpsd's device list, it is opened and read to see if a GPS can be found there\&. If it can, the trial device becomes the active device for this client\&.

The 'f=' command may fail if the specified device name is not on the daemon's device list\&. This device list is initialized with the paths given on the command line, if any were specified\&. For security reasons, ordinary clients cannot change this device list; instead, this must be done via the daemon's local control socket declared with the \-F option\&.

Once an 'f=' command succeeds, the client is tied to the specified device until the client disconnects\&.

Whether the command is 'f' or 'f=' or not, and whether it succeeds or not, the response always lists the name of the client's device\&.

(At protocol level 1, the F command failed if more than one client was attached, and multiple devices were not supported\&.)

.TP
g
With =, accepts a single argument which may have either of the values 'gps' or 'rtcm104', with case ignored\&. This specifies the type of information the client wants and forces a device assignment\&. Without =, forces a device assignment but doesn't force the type\&. This command is optional; if it is not given, the client will be bound to whatever available device the daemon finds first\&.

This command returns either '?' if no device of the specified type(s) could be assigned, otherwise a string ('GPS' or 'RTCM104') identifying the kind of information the attached device returns\&.

.TP
i
Returns a text string identifying the GPS\&. The string may contain spaces and is terminated by CR\-LF\&. This command will return '?' at start of session, before the first full packet has been received from the GPS, because its type is not yet known\&.

.TP
j
Get or set buffering policy; this only matters for NMEA devices which report fix data in several separate sentences during the poll cycle (and in particular it \fIdoesn't\fR matter for SiRF chips)\&. The default (j=0) is to clear all fix data at the start of each poll cycle, so until the sentence that reports a given piece of data arrives queries will report ?\&. Setting j=1 will disable this, retaining data from the previous cycle\&. This is a per\-user\-channel bit, not a per\-device one\&. The j=0 setting is hyper\-correct and never displays stale data, but may produce a jittery display; the j=1 setting allows stale data but smooths the display\&.

(At protocol level below 3, there was no J command\&. Note, this command is experimental and its semantics are subject to change\&.)

.TP
k
Returns a line consisting of "K=" followed by an integer count of of all GPS devices known to gpsd, followed by a space, followed by a space\-separated list of the device names\&. This command lists devices the daemon has been pointed at by the command\-line argument(s) or an add command via its control socket, and has successfully recognized as GPSes\&. Because GPSes might be unplugged at any time, the presence of a name in this list does not guarantee that the device is available\&.