gpsd
1
9 Aug 2004
gpsd
gps
xgpsspeed
interface daemon for GPS receivers, test client,
and speedometer
gpsd
-T GPS-type
-p GPS-devicename
-S listener-port
-s baudrate
-d DGPS-server
-i initial-position
-n
-h
-D debuglevel
gps
X-options
-p server:port
-h
xgpsspeed
X-options
-p server:port
-h
DESCRIPTION
gpsd
gpsd is a monitor daemon that watches a TCP/IP port (2947 by
default), waiting for an application 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 which is
specified to gpsd at startup.
Optionally, gpsd may get differential-GPS corrections from a
ground station running a RTCM-S104 server; this will improve
position-fix accuracy from roughly 10 meters to roughly 2 meters,
provided you are within 1000 kilometers or so of the ground
station.
The program accepts the following options:
-p
Set GPS device name (default is /dev/gps).
-T device-type
Set GPS type, usually not necessary because most GPSes now speak
the standard NMEA 0183 protocol. For a list of driver types,
look at what gpsd -? writes to standard output.
-S
Set TCP/IP port (default is 2947).
-s
Set GPS communication speed in bits per second
(default is set by device type).
-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.
-i
Set initial longitude/latitude in degrees (TripMate only; helps
it develop a first fix more quickly). Required format is %f[NS]:%f[EW]; that
is a decimal number of degrees latitude, followed by the suffix N or
S, followed by a colon, followed by a decimal number of degrees
longitude, followed by the suffix E or W. The numbers may have
fractional parts to the right of a decimal point.
-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.
-h
Display help message and terminate.
-D
Set debug level. At debug levels 2 and above, gpsd stays in
foreground and reports incoming sentence and actions to standard
error.
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 request protocol for gpsd clients is very simple. Each
request 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.
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.
l
Returns three fields: a protocol revision number,
the gpsd version, and a list of accepted request letters.
m
The gps mode as "M=%d". 1=no fix, 2=2D (no altitude), 3=3D (with altitude).
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 estimated position errors in meters — position,
horizontal, and vertical.
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 gps 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.
v
The current speed 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=1" if the GPS is online, "X=0" if
not.
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.
Note that a response consisting of just ? following the =
response 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=11/16/2002 02:45:05\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 the GPS repeatedly unplugged
and plugged back in.
The recommended mode for clients is watcher mode. In watcher
mode gpsd ships a line of data to the client each time the the GPS
sends a sentence, but rather than being raw NMEA the line is a gpsd
response as if the user had just sent some set of gpsd commands. That
set of commands is the minimum for which the incoming sentence is
relevant — e.g., a GPRMC sentence ships a "pvs" response because
it contains position, velocity and GPS status data. Additionally,
watching clients get notifications in the form X=0 or X=1 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.
gps
gps is a simple test client for gpsd with an X interface. It
displays current GPS animation and (for GPSes that support the
feature) the locations of accessible satellites.
gps accepts an -h option as for gpsd. With the -p option you
may specify an alternate server:port to get data from. The misfeature of
previous version that allowed it to direct-connect to the serial device has
been removed.
xgpsspeed
xgpsspeed is a speedometer that uses position information from
the GPS. It accepts -ph options as for xgps. The misfeature of
previous version that allowed it to direct-connect to the serial device has
been removed.
APPLICABLE STANDARDS
The official NMEA protocol standard is available on paper from
the National Marine
Electronics Association. A description of the protocol is
available
on the Web. gpsd parses the following NMEA sentences: GPRMC,
GPGLL, GPVTG, GPGGA, GPGSA, GPGSV. Note that gpsd returns pure
decimal degrees, not the hybrid degree/minute format described in the
NMEA standard.
The Rockwell protocol is described as an addendum on this page about
NMEA.
gpsd does not yet speak the SiRF-II binary protocol, but SiRF-II
devices speak NMEA by default before being switched to binary and
should thus be accessible as generic GPS devices.
SEE ALSO
libgps3
libgpsd3
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, with gps screenshots, here.