Provided by: gpsd_2.30-1ubuntu3_i386
gpsd - interface daemon for GPS receivers
gpsd [-f GPS-devicename] [-F control-socket] [-S listener-port]
[-d DGPSIP-server] [-n] [-N] [-h] [-P pidfile] [-D debuglevel]
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.
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 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, 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, decrease
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.
gpsd can use differential-GPS corrections from a DGPS radio or over the
net, from a ground station running a DGPSIP server 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.
The program accepts the following options:
-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.
-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
-S Set TCP/IP port on which to listen for GPSD clients (default is
-d Query a specific differential-GPS (DGPSIP) 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.
-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
-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.
-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.
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.
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).
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, (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
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
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
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 ’?’ at start of session, before the
first full packet has been received from the GPS, because its
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.
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.
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 zero for any of these numbers should be taken to mean
that component of DOP is not available. See also the ’q’
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
(At protocol level 1, the F command failed if more than one
client was attached, and multiple devices were not supported.)
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
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
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.
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.
(At protocol level 1, there was no K command.)
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 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 and Evermore chipsets in
particular). With argument, set the mode if possible; the new
mode will be reported in the response. The "N=" form is rejected
if more than one client is attached to the channel.
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
Seconds since the Unix epoch, UTC. May have a fractional
part of up to .01sec precision.
Estimated timestamp error (%f, seconds, 95% confidence).
Latitude as in the P report (%f, degrees).
Longitude as in the P report (%f, degrees).
Altitude as in the A report (%f, meters).
horizontal error estimate
Horizontal error estimate as in the E report (%f,
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 (%f, meters/sec). Note: older versions of the O
command reported this field in knots.
Vertical velocity as in the U report (%f, meters/sec).
estimated error in course over ground
Error estimate for course (%f, degrees, 95% confidence).
estimated error in speed over ground
Error estimate for speed (%f, meters/sec, 95%
confidence). Note: older versions of the O command
reported this field in knots.
Estimated error for climb/sink (%f, meters/sec, 95%
p Returns the current position in the form "P=%f %f"; numbers are
in degrees, latitude first.
q Returns "Q=%d %f %f %f %f %f": a count of satellites used in the
last fix, and five dimensionless dilution-of-precision (DOP)
numbers -- spherical, horizontal, vertical, time, and total
geometric. 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 (or seconds) 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.
Note: Older versions of gpsd reported only the first three DOP
numbers, omitting time DOP and total DOP.
r Sets or toggles ’raw’ mode. Return "R=0" or "R=1" or "R=2". In
raw mode you read the NMEA data stream from each GPS. (Non-NMEA
GPSes get their communication format translated to NMEA on the
fly.) If the device is a source of RTCM-104 corrections, the
corrections are dumped in the textual format described in
The command ’r’ immediately followed by the digit ’1’ or the
plus sign ’+’ sets raw mode. The command ’r’ immediately
followed by the digit ’2’ sets super-raw mode; for non-NMEA
(binary) GPSes or RTCM-104 sources this dumps the raw binary
packet. The command ’r’ followed by the digit ’0’ or the minus
sign ’-’ clears raw mode. The command ’r’ with neither suffix
toggles raw mode.
Note: older versions of gpsd did not support super-raw mode.
s The NMEA status as "S=%d". 0=no fix, 1=fix, 2=DGPS-corrected
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
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
(At protocol level 1, the nonzero response was always 1.)
y Returns Y=, followed by a sentence tag, followed by a timestamp
(seconds since the Unix epoch, UTC) and 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.
(At protocol level 1, this response had no tag or timestamp.)
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. This may mean either that the device
being queried is offline, or (for position/velocity/time queries) that
it is online but has no fix.
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
reply: "GPSD,P=36.000000 123.000000\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 device-add 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 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.
GPS DEVICE MANAGEMENT
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
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 /dev/foo. 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 /dev/foo from the search list. send
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.
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.
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.
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 about 100mi (160km) of a DGPS ground
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.
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 facility is only available when the daemon is started from root.
If you’re going to use gpsd you probably want to run it -n mode so the
clock will be updated even when no clients are active.
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.
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.420 refid GPS
server 127.127.28.1 minpoll 4 maxpoll 4 prefer
fudge 127.127.28.1 refid GPS1
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
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.
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
remote refid st t when poll reach delay
+SHM(0) .GPS. 0 l 13 16 377 0.000 0.885
If you are running PPS then it will look like this:
remote refid st t when poll reach delay
-SHM(0) .GPS. 0 l 13 16 377 0.000 0.885
0.882 *SHM(1) .GPS1. 0 l 11 16 377 0.000
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-II, 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
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.
USE WITH D-BUS
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.
SECURITY AND PERMISSIONS ISSUES
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" 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 /dev/ttyS0.
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.
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).
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).
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.
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
If your GPS uses a SiRF chipset at firmware level 231, and it is after
1 Jan 2006, 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
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.
Autobauding on the Trimble GPSes can take as long as 5 seconds if the
device speed is not matched to the GPS speed.
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
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.
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, 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.
xgps(1), libgps(3), libgpsd(3), gpsprof(1), gpsfake(1), rtcm-104(5).
Remco Treffcorn, Derrick Brashear, Russ Nelson, Eric S. Raymond. This
manual page by Eric S. Raymond <firstname.lastname@example.org>. There is a project
page here: http://gpsd.berlios.de/.