GPSD(8)

NAME
gpsd - interface daemon for GPS receivers

SYNOPSIS

gpsd [-f GPS-devicename] [-S listener-port] [-d DGPS-server] [-n] [-N] [-h] [-P pidfile] [-D debuglevel] [-v]

DESCRIPTION

gpsd is a monitor daemon that watches a TCP/IP port (2947 by default), waiting for applications to request location information from a GPS. The GPS is expected to be direct-connected to the machine running gpsd 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 the client socket (e.g. by a USB hotplug script). Given a GPS device, gpsd discovers the correct port speed and protocol for it.

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, or the binary SiRF protocol used by SiRf-II and SiRF-Star chipsets, or the Garmin binary protocol used by the USB version of the Garmin 18 and other Garmin USB GPSes. gpsd effectively hides the differences among these.

Optionally, gpsd may get differential-GPS corrections from a ground station running a RTCM-S104 server; this will improve user error by roughly a factor of four. See [xref to refsect1] for discussion.

The program accepts the following options:

-f  Set GPS device name (default is /dev/gps).

-S  Set TCP/IP port (default is 2947).

-d  Query a differential-GPS (DGPS) server. If a suffix of the server name begins with ":" it is interpreted as a port number, overriding the default IANA-assigned port of 2101. For DGPS servers available for use with this option, see DGPS corrections over the Internet: http://www.wsrcc.com/wolfgang/gps/dgps-ip.html.

-n  Don't wait for a client to connect before polling the GPS. 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.

-N  Don't daemonize; run in foreground. Mainly useful for debugging.

-h  Display help message and terminate.

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

-D  Set debug level. At debug levels 2 and above, gpsd reports incoming sentence and actions to standard error.

-v  Dump version and exit.

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:

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

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, (currently always N) 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.

c   Returns, as "C=%d", the cycle time of updates in seconds.

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 zero.

e   Returns "E=%f %f %f": three estimated position errors in meters -- total, horizontal, and vertical (1-sigma or 66% 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 zero for any of these numbers should be taken to mean that component of DOP is not available. See also the 'q' command.

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 command may be followed by an '=', in which case all following printable characters up to the next CR/LF are interpreted as the name of a trial GPS device. If there are no other clients active, the trial device is opened and read to see if a GPS can be found there. If it can, the trial device becomes the active device and the trial device name is stored to be opened at the time of the next client request, replacing the old one. The response to this form of the command is to list the name of the active device.

i   Returns a text string identifying the GPS. The string may contain spaces and is terminated by CR-LF.

l   Returns three fields: a protocol revision number, the gpsd version, and a list of accepted request letters.

m   The NMEA mode as "M=%d". 0=no mode value yet seen, 1=no fix, 2=2D (no altitude), 3=3D (with altitude).

n   Get or set the the GPS driver mode. Without argument, reports the mode as "N=%d"; N=0 means NMEA mode and N=1 means alternate mode (binary if it has one, for SiRF chipsets in particular). With argument, set the mode if possible; the new mode will be reported in the response.

o   Attempts to return a complete time/position/velocity report as a unit. Any field for which data is not available being reported as ?. If there is no fix, the response is simply "O=?", otherwise a tag and timestamp are always reported. Fields are as follows, in order:

    tag A tag identifying the last sentence received. For NMEA devices this is just the NMEA sentence name; the talker-ID portion may be useful for distinguishing among results produced by different NMEA talkers in the same wire.

    timestamp
        Seconds since the Unix epoch, GMT. May have a fractional part of up to .01sec precision.

    time error
        Estimated timestamp error (%f, seconds).

    latitude
        Latitude as in the P report (%f, degrees).

    longitude
        Longitude as in the P report (%f, degrees).

    altitude
        Altitude as in the A report (%f, meters).

    horizontal error estimate
        Horizontal error estimate as in the E report (%f, meters).

    vertical error estimate
        Vertical error estimate as in the E report (%f, meters).

    course over ground
        Track as in the T report (%f, degrees).

    speed over ground
        Speed as in the V report (%f, knots).

    climb/sink
        Vertical velocity as in the U report (%f, meters/sec).

    estimated error in course over ground
        Error estimate for course (%f, degrees).

    estimated error in speed over ground
        Error estimate for speed (%f, knots).

    climb/sink
        Estimated error for climb/sink (%f, meters/sec).

    Note: this command is experimental and still under development.

p   Returns the current position in the form "P=%f %f"; numbers are in degrees, latitude first.

q   Returns "Q=%d %f %f %f": a count of satellites used in the last fix, and three dimensionless dilution-of-precision (DOP) numbers -- total, horizontal, and vertical. These are computed from the satellite geometry; they are factors by which to multiply the estimated UERE (user error in meters at specified confidence level due to ionospheric delay, multipath reception, etc.) to get actual circular error ranges in meters at the same confidence level. See also the 'e' command. Note: Some GPSes may fail to report these, or report only one of them (often HDOP); a value of 0.0 should be taken as an indication that the data is not available.

r   Sets or toggles 'raw' mode. Return "R=0" or "R=1". In raw mode you read the NMEA data stream from the GPS. (Non-NMEA GPSes get their communication format translated to NMEA on the fly.) The command 'r' immediately followed by the digit '1' or the plus sign '+' sets raw mode. The command 'r' followed by the digit '0' or the minus sign '-' clears raw mode. The command 'r' with neither suffix toggles raw mode.

s   The NMEA status as "S=%d". 0=no fix, 1=fix, 2=DGPS-corrected fix.

t   Track made good; course "T=%f" in degrees from true north.

u   Current rate of climb as "U=%f" in meters per second. Some GPSes (non-Sirf-II based) do not report this, in that case gpsd computes it using the altitude from the last fix (if available).

v   The current speed over ground as "V=%f" in knots.

w   Sets or toggles 'watcher' mode (see the descroiption below). Return "W=0" or "W=1".The command 'w' immediately followed by the digit '1' or the plus sign '+' sets watcher mode. The command 'w' followed by the digit '0' or the minus sign '-' clears watcher mode. The command 'w' with neither suffix toggles watcher mode.

x   Returns "X=0" if the GPS is offline, "X=%f" if online; in the latter case, %f is a timestamp from when the last sentence was received.

y   Returns Y= followed by a count not more than 12, followed by that many quintuples of satellite PRNs, elevation/azimuth pairs (elevation an integer formatted as %d in range 0-90, azimuth an integer formatted as %d in range 0-359), signal strengths in decibels, and 1 or 0 according as the satellite was or was not used in the last fix. Each number is followed by one space.

z   The Z command returns daemon profiling information of interest to gpsd developers. The format of this string is subject to change without notice.

Note that a response consisting of just ? following the = means that there is no valid data available.

Requests can be concatenated and sent as a string; gpsd will then respond with a comma-separated list of replies.

Every gpsd reply will start with the string "GPSD" followed by the replies. Examples:

          query: "p\n"
          reply: "GPSD,P=36.000000 123.000000\r\n"

          query: "d\n"
          reply: "GPSD,D=2002-11-16T02:45:05.12Z\r\n"

          query: "va\n"
          reply: "GPSD,V=0.000000,A=37.900000\r\n"

When clients are active but the GPS is not responding, gpsd will spin trying to open the GPS device once per second. Thus, it can be left running in background and survive having a GPS repeatedly unplugged and plugged back in. When it is properly installed along with hotplug notifier scripts feeding it F commands, gpsd should require no configuration or user action to find devices.

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.

Sending SIGHUP to a running gpsd forces it to close the GPS and all client connections. It will then attempt to reconnect to the GPS 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.

ACCURACY

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 not rely on GPS altitude for life-critical tasks such as landing an airplane.

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.

DGPS correction will reduce UERE from roughly 8 meters to roughly 2 meters, provided you are within 1000 kilometers or so of the DGPS ground station.

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.

The driver for SiRF-II binary mode only has leap-second correction for its timestamps as of 2005. It will not include any leap-second corrections introduced after 1 Jan 2006.

USE WITH NTP

gpsd can provide reference clock information to ntpd, to keep the system clock synchronized to the time provided by the GPS receiver. This is an experimental feature, currently only working with SiRF-II and Garmin binary mode. Making it work with other GPSes that report subsecond time resolution may come later.

To use the time information, you first need to install and configure ntp as usual. The package manager and system administration tools of the distribution you use may provide some assistance with this.

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.

Here is a sample ntp.conf configuration stanza telling ntpd how to read the GPS notfications:

server 127.127.28.0 minpoll 4 maxpoll 4
fudge 127.127.28.0 time1 0.035 refid GPS

The magic pseudo-IP address 127.127.28.0 identifies unit 0 of the ntpd shared-memory driver, which is what gpsd writes to. With this configuration, ntpd will read the timestamp posted by gpsd every 16 seconds. 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.

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):

    remote refid st t when poll reach delay offset jitter ========================================================================= +SHM(0) .GPS. 0 l 13 16 377 0.000 0.885 0.882

When the value under "reach" remains zero, check that gpsd is running and some application is connected to it. Make sure the receiver is locked on to at least one satellite, and the receiver is in SiRF-II or Garmin binary mode. When the SHM(0) line does not appear at all, check the system logs for error messages from ntpd.

When no other reference clocks appear in the NTP configuration, the system clock will lock onto the GPS clock. Because GPS clocks only return 0.01sec resolution, ntpd is unlikely to use this cue unless your system is off-net. 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.

LIMITATIONS

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.

APPLICABLE STANDARDS

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

gpsd parses the following NMEA sentences: RMC, GLL, GGA, GSA, GSV, 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, PGRME. Note that gpsd returns pure decimal degrees, not the hybrid degree/minute format described in the NMEA standard.

SEE ALSO

 xgps(1), libgps(3), libgpsd(3), gpsprof(1), gpsfake(1).

AUTHORS

Remco Treffcorn, Derrick Brashear, Russ Nelson, Eric S. Raymond. This manual page by Eric S. Raymond <esr@thyrsus.com>. There is a project page here: http://gpsd.berlios.de/.