gpsd.8

gpsd, a popular GPS daemon.

.PP
The recommended mode for clients is watcher mode\&. In watcher mode gpsd ships a line of data to the client each time the GPS gets either a fix update or a satellite picture, but rather than being raw NMEA the line is a gpsd 'o' or 'y' response\&. Additionally, watching clients get notifications in the form X=0 or X=%f when the online/offline status of the GPS changes, and an I response giving the device type when the user is assigned a device\&.

.PP
Clients should be prepared for the possibility that additional fields (such as heading or roll/pitch/yaw) may be added to the O command, and not treat the occurrence of extra fields as an error\&. The protocol number will be incremented if and when such fields are added\&.

.PP
Sending SIGHUP to a running gpsd forces it to close all GPSes and all client connections\&. It will then attempt to reconnect to any GPSes on its device list and resume listening for client connections\&. This may be useful if your GPS enters a wedged or confused state but can be soft\-reset by pulling down DTR\&.

.SH "GPS DEVICE MANAGEMENT"

.PP
gpsd maintains an internal list of GPS devices\&. If you specify devices on the command line, the list is initialized with those pathnames; otherwise the list starts empty\&. Commands to add and remove GPS device paths from the daemon's device list must be written to a local Unix\-domain socket which will be accessible only to programs running as root\&. This control socket will be located wherever the \-F option specifies it\&.

.PP
To point gpsd at a device that may be a GPS, write to the control socket a plus sign ('+') followed by the device name followed by LF or CR\-LF\&. Thus, to point the daemon at \fI/dev/foo\fR\&. send "+/dev/foo\\n"\&. To tell the daemon that a device has been disconnected and is no longer available, send a minus sign ('\-') followed by the device name followed by LF or CR\-LF\&. Thus, to remove \fI/dev/foo\fR from the search list\&. send "\-/dev/foo\\n"\&.

.PP
To send a control string to a specified device, write to the control socket a '!', followed by the device name, followed by '=', followed by the control string\&.

.PP
Your client may await a response, which will be a line beginning with either "OK" or "ERROR"\&. An ERROR reponse to an add command means the device did not emit data recognizable as GPS packets; an ERROR response to a remove command means the specified device was not in gpsd's device list\&. An ERROR response to a ! command means the daemon did not recognize the devicename specified\&.

.PP
The control socket is intended for use by hotplug scripts and other device\-discovery services\&. This control channel is separate from the public gpsd service port, and only locally accessible, in order to prevent remote denial\-of\-service and spoofing attacks\&.

.SH "ACCURACY"

.PP
The base user error (UERE) of GPSes is 8 meters or less at 66% confidence, 15 meters or less at 95% confidence\&. Actual horizontal error will be UERE times a dilution factor dependent on current satellite position\&. Altitude determination is more sensitive to variability to atmospheric signal lag than latitude/longitude, and is also subject to errors in the estimation of local mean sea level; base error is 12 meters at 66% confidence, 23 meters at 95% confidence\&. Again, this will be multiplied by a vertical dilution of precision (VDOP) dependent on satellite geometry, and VDOP is typically larger than HDOP\&. Users should \fInot\fR rely on GPS altitude for life\-critical tasks such as landing an airplane\&.

.PP
These errors are intrinsic to the design and physics of the GPS system\&. gpsd does its internal computations at sufficient accuracy that it will add no measurable position error of its own\&.

.PP
DGPS correction will reduce UERE from roughly 8 meters to roughly 2 meters, provided you are within about 100mi (160km) of a DGPS ground station\&.

.PP
On a 4800bps connection, the time latency of fixes provided by gpsd will be one second or less 95% of the time\&. Most of this lag is due to the fact that GPSes normally emit fixes once per second, thus expected latency is 0\&.5sec\&. On the personal\-computer hardware available in 2005, computation lag induced by gpsd will be negligible, on the order of a millisecond\&. Nevertheless, latency can introduce significant errors for vehicles in motion; at 50km/h (31mi/h) of speed over ground, 1 second of lag corresponds to 13\&.8 meters change in position between updates\&.

.SH "USE WITH NTP"

.PP
gpsd can provide reference clock information to ntpd, to keep the system clock synchronized to the time provided by the GPS receiver\&. This facility is only available when the daemon is started from root\&. If you're going to use gpsd you probably want to run it \fB\-n\fR mode so the clock will be updated even when no clients are active\&.

.PP
Note that deriving time from messages received from the GPS is not as accurate as you might expect\&. Messages are often delayed in the receiver and on the link by several hundred milliseconds, and this delay is not constant\&. On Linux, gpsd includes support for interpreting the PPS pulses emitted at the start of every clock second on the carrier\-detect lines of some serial GPSes; this pulse can be used to update NTP at much higher accuracy than message time provides\&. You can determine whether your GPS emits this pulse by running at \-D 5 and watching for carrier\-detect state change messages in the logfile\&. On OpenBSD gpsd makes use of the nmea(4) line discipline and the tty(4) timestamping facilities to export PPS time via the sensors framework\&. OpenBSD's ntpd uses these sensors to adjust the hardware clock and frequency\&. To make use of this feature, gpsd must be started as root so it can activate the timestamping and line discipline; after attempting to set up PPS, it will relinquish root privileges\&.

.PP
When gpsd receives a sentence with a timestamp, it packages the received timestamp with current local time and sends it to a shared\-memory segment with an ID known to ntpd, the network time synchronization daemon\&. If ntpd has been properly configured to receive this message, it will be used to correct the system clock\&.

.PP
Here is a sample \fIntp\&.conf\fR configuration stanza telling ntpd how to read the GPS notfications:

.nf

server 127\&.127\&.28\&.0 minpoll 4 maxpoll 4
fudge 127\&.127\&.28\&.0 time1 0\&.420 refid GPS

server 127\&.127\&.28\&.1 minpoll 4 maxpoll 4 prefer
fudge 127\&.127\&.28\&.1 refid GPS1

.fi

.PP
The magic pseudo\-IP address 127\&.127\&.28\&.0 identifies unit 0 of the ntpd shared\-memory driver; 127\&.127\&.28\&.1 identifies unit 1\&. Unit 0 is used for message\-decoded time and unit 1 for the (more accurate, when available) time derived from the PPS synchronization pulse\&. Splitting these notifications allows ntpd to use its normal heuristics to weight them\&.

.PP
With this configuration, ntpd will read the timestamp posted by gpsd every 16 seconds and send it to unit 0\&. The number after the parameter time1 is an offset in seconds\&. You can use it to adjust out some of the fixed delays in the system\&. 0\&.035 is a good starting value for the Garmin GPS\-18/USB, 0\&.420 for the Garmin GPS\-18/LVC\&.

.PP
After restarting ntpd, a line similar to the one below should appear in the output of the command "ntpq \-p" (after allowing a couple of minutes):

.IP
 
remote           refid      st t when poll reach  delay    offset  jitter
=========================================================================
+SHM(0)          \&.GPS\&.      0 l   13   16  377    0\&.000    0\&.885   0\&.882

.PP
If you are running PPS then it will look like this:

.IP
 
remote           refid      st t when poll reach  delay    offset  jitter
=========================================================================
\-SHM(0)          \&.GPS\&.      0 l   13   16  377    0\&.000    0\&.885   0\&.882
*SHM(1)          \&.GPS1\&.     0 l   11   16  377    0\&.000   \-0\&.059   0\&.006

.PP
When the value under "reach" remains zero, check that gpsd is running; and some application is connected to it or the '\-n' option was used\&. Make sure the receiver is locked on to at least one satellite, and the receiver is in SiRF binary, Garmin binary or NMEA/PPS mode\&. Plain NMEA will also drive ntpd, but the accuracy as bad as one second\&. When the SHM(0) line does not appear at all, check the system logs for error messages from ntpd\&.

.PP
When no other reference clocks appear in the NTP configuration, the system clock will lock onto the GPS clock\&. When you have previously used ntpd, and other reference clocks appear in your configuration, there may be a fixed offset between the GPS clock and other clocks\&. The gpsd developers would like to receive information about the offsets observed by users for each type of receiver\&. Please send us the output of the "ntpq \-p" command and the make and type of receiver\&.

.SH "USE WITH D-BUS"

.PP
On operating systems that support D\-BUS, gpsd can be built to broadcast GPS fixes to D\-BUS\-aware applications\&. As D\-BUS is still at a pre\-1\&.0 stage, we will not attempt to document this interface here\&. Read the gpsd source code to learn more\&.

.SH "SECURITY AND PERMISSIONS ISSUES"

.PP
gpsd must start up as root in order to open the NTPD shared\-memory segment, open its logfile, and create its local control socket\&. Before doing any processing of GPS data, it tries to drop root privileges by setting its UID to "nobody" (or another userid as set by configure) and its group ID to the group of the initial GPS passed on the command line -- or, if that device doesn't exist, to the group of \fI/dev/ttyS0\fR\&.

.PP
Privilege\-dropping is a hedge against the possibility that carefully crafted data, either presented from a client socket or from a subverted serial device posing as a GPS, could be used to induce misbehavior in the internals of gpsd\&. It ensures that any such compromises cannot be used for privilege elevation to root\&.

.PP
The assumption behind gpsd's particular behavior is that all the tty devices to which a GPS might be connected are owned by the same non\-root group and allow group read/write, though the group may vary because of distribution\-specific or local administrative practice\&. If this assumption is false, gpsd may not be able to open GPS devices in order to read them (such failures will be logged)\&.

.PP
In order to fend off inadvertent denial\-of\-service attacks by port scanners (not to mention deliberate ones), gpsd will time out inactive client connections\&. Before the client has issued a command that requests a channel assignment, a short timeout (60 seconds) applies\&. There is no timeout for clients in watcher or raw modes; rather, gpsd drops these clients if they fail to read data long enough for the outbound socket write buffer to fill\&. Clients with an assigned device in polling mode are subject to a longer timeout (15 minutes)\&.

.SH "LIMITATIONS"

.PP
If multiple NMEA talkers are feeding RMC, GLL, and GGA sentences to the same serial device (possible with an RS422 adapter hooked up to some marine\-navigation systems), an 'O' response may mix an altitude from one device's GGA with latitude/longitude from another's RMC/GLL after the second sentence has arrived\&.

.PP
gpsd may change control settings on your GPS (such as the emission frequency of various sentences or packets) and not restore the original settings on exit\&. This is a result of inadequacies in NMEA and the vendor binary GPS protocols, which often do not give clients any way to query the values of control settings in order to be able to restore them later\&.

.PP
If your GPS uses a SiRF chipset at firmware level 231, and it is after 31 May 2007, reported UTC time may be off by the difference between 13 seconds and whatever leap\-second correction is currently applicable, from startup until complete subframe information is received (normally about six seconds)\&. Firmware levels 232 and up don't have this problem\&. You may run gpsd at debug level 4 to see the chipset type and firmware revision level\&.

.PP
When using SiRF chips, the VDOP/TDOP/GDOP figures and associated error estimates are computed by gpsd rather than reported by the chip\&. The computation does not exactly match what SiRF chips do internally, which includes some satellite weighting using parameters gpsd cannot see\&.

.PP
Autobauding on the Trimble GPSes can take as long as 5 seconds if the device speed is not matched to the GPS speed\&.

.PP
If you are using an NMEA\-only GPS (that is, not using SiRF or Garmin or Zodiac binary mode) and the GPS does not emit GPZDA at the start of its update cycle (which most consumer\-grade NMEA GPSes do not) and it is after 2099, then the century part of the dates gpsd delivers will be wrong\&.

.SH "FILES"

.TP
\fI/dev/ttyS0\fR
Prototype TTY device\&. After startup, gpsd sets its group ID to the owner of this device if no GPS device was specified on the command line does not exist\&.

.SH "APPLICABLE STANDARDS"

.PP
The official NMEA protocol standard is available on paper from the National Marine Electronics Association: \fIhttp://www.nmea.org/pub/0183/\fR, but is proprietary and expensive; the maintainers of gpsd have made a point of not looking at it\&. The GPSD website: \fIhttp://gpsd.berlios.de/\fR links to several documents that collect publicly disclosed information about the protocol\&.

.PP
gpsd parses the following NMEA sentences: RMC, GGA, GLL, GSA, GSV, VTG, ZDA\&. It recognizes these with either the normal GP talker\-ID prefix, or with the II prefix emitted by Seahawk Autohelm marine navigation systems, or with the IN prefix emitted by some Garmin units\&. It recognizes one vendor extension, the PGRME emitted by some Garmin GPS models\&.

.PP
Note that gpsd returns pure decimal degrees, not the hybrid degree/minute format described in the NMEA standard\&.

.SH "SEE ALSO"

.PP
 \fBgps\fR(1), \fBlibgps\fR(3), \fBlibgpsd\fR(3), \fBgpsprof\fR(1), \fBgpsfake\fR(1), \fBgpsctl\fR(1), \fBgpscat\fR(1), \fBrtcm\-104\fR(5)\&.

.SH "AUTHORS"

.PP
Remco Treffcorn, Derrick Brashear, Russ Nelson, Eric S\&. Raymond, Chris Kuethe\&. This manual page by Eric S\&. Raymond <esr@thyrsus\&.com>\&. There is a project site at here: \fIhttp://gpsd.berlios.de/\fR\&.