gpsd
8
9 Aug 2004
gpsd
interface daemon for GPS receivers
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 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.
-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, UTC. 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.
(At protocol level 1, the nonzero response was always 1.)
y
Returns Y= 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 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.
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, but is proprietary and expensive; the
maintainers of gpsd have made a point of
not looking at it. The GPSD
website 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
xgps1,
libgps3,
libgpsd3,
gpsprof1,
gpsfake1.
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.