path: root/gpsd.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC 
   "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "docbook/docbookx.dtd">
<refentry id='gpsd.1'>
<refmeta>
<refentrytitle>gpsd</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class='date'>9 Aug 2004</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>gpsd</refname>
<refname>gps</refname>
<refname>xgpsspeed</refname>
<refpurpose>interface daemon for GPS receivers, test client,
and speedometer</refpurpose>
</refnamediv>
<refsynopsisdiv id='synopsis'>

<cmdsynopsis>
  <command>gpsd</command>  
      <arg choice='opt'>-T <replaceable>GPS-type</replaceable></arg>
      <arg choice='opt'>-p <replaceable>GPS-devicename</replaceable></arg>
      <arg choice='opt'>-S <replaceable>listener-port</replaceable></arg>
      <arg choice='opt'>-t <replaceable>timeout</replaceable></arg>
      <arg choice='opt'>-d <replaceable>DGPS-server</replaceable></arg>
      <arg choice='opt'>-i <replaceable>initial-position</replaceable></arg>
      <arg choice='opt'>-n </arg>      
      <arg choice='opt'>-h </arg>
      <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
  <command>gps</command>  
      <arg choice='opt'>-T <replaceable>GPS-type</replaceable></arg>
      <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg>
      <arg choice='opt'>-p <replaceable>GPS-devicename</replaceable></arg>
      <arg choice='opt'>-h </arg>
</cmdsynopsis>
<cmdsynopsis>
  <command>xgpsspeed</command>  
      <arg choice='opt'><replaceable>X-options</replaceable></arg>
      <arg choice='opt'>-T <replaceable>GPS-type</replaceable></arg>
      <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg>
      <arg choice='opt'>-p <replaceable>GPS-devicename</replaceable></arg>
      <arg choice='opt'>-h </arg>
</cmdsynopsis>

</refsynopsisdiv>

<refsect1 id='description'><title>DESCRIPTION</title>

<refsect2 id='gpsd'><title>gpsd</title>

<para>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 will usually be direct-connected to the machine
running gpsd via a USB port or serial port, but may be attached to
another slave daemon reporting to this one.</para>

<para>Optionally, gpsd may get differential-GPS corrections from a
ground station running a RCTM-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.</para>

<para>The program accepts the following options:</para>
<variablelist remap='TP'>
<varlistentry>
<term>-p</term>
<listitem>
<para>Set GPS device name (default is <filename>/dev/gps</filename>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-T <replaceable>device-type</replaceable></term>
<listitem>
<para>Set GPS type, usually not necessary because most GPSes now speak
the standard NMEA 0183 protocol: possible values are n=NMEA generic,
t=TripMate, e=EarthMate, l=logfile.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-S</term>
<listitem><para>Set TCP/IP port (default is 2947).</para></listitem>
</varlistentry>
<varlistentry>
<term>-t</term>
<listitem><para>Set GPS session timeout (default is 5 
seconds).</para></listitem>
</varlistentry>
<varlistentry>
<term>-d</term>
<listitem>
<para>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
<ulink url='http://www.wsrcc.com/wolfgang/gps/dgps-ip.html'>
DGPS corrections over the Internet</ulink>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-i</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-n</term>
<listitem><para>Don't wait for a client to connect before polling
the GPS.  The wait is a feature; many serial GPSes go to a standby
node (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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-h</term>
<listitem><para>Display help message and terminate.</para></listitem>
</varlistentry>
<varlistentry>
<term>-D</term>
<listitem>
<para>Set debug level. At debug levels 2 and above, gpsd stays in
foreground and reports incoming sentence and actions to standard
error.</para>
</listitem>
</varlistentry>
</variablelist>

<para>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.  gpsd is tested with DeLorme's
TripMate and EarthMate, also with Garmin units.</para>

<para>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 newline.  Requests and responses are as 
follows, with %f standing for a decimal float numeral and %d for
decimal integer numeral:</para>

<variablelist>
<varlistentry>
<term>a</term>
<listitem><para>The current altitude as "A=%f", meters above mean sea level.</para></listitem>
</varlistentry>

<varlistentry>
<term>d</term>
<listitem><para>Returns the UTC time in the form "D=dd/mm/yyyy hh:nmm:ss".</para></listitem>
</varlistentry>

<varlistentry>
<term>l</term>
<listitem><para>Returns three fields: a protocol revision number,
the gpsd version, and a list of accepted request letters.</para></listitem>
</varlistentry>

<varlistentry>
<term>m</term>
<listitem><para>The gps mode as "M=%d". 1=no fix, 2=2D (no altitude), 3=3D (with altitude).</para></listitem>
</varlistentry>

<varlistentry>
<term>p</term>
<listitem><para>Returns the current position in the form "P=%f %f";
numbers are in degrees, latitude first.</para></listitem>
</varlistentry>

<varlistentry>
<term>q</term>
<listitem>
<para>Returns "Q=%d %d %f %f %f": a count of satellites in view, a
count of satellites used in the last fix, and three estimated position
errors in meters &mdash; position, horizontal, and vertical.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>r</term>
<listitem><para>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.)</para></listitem>
</varlistentry>

<varlistentry>
<term>s</term>
<listitem><para>The gps status as "S=%d". 0=no fix, 1=fix,
2=DGPS-corrected fix.</para></listitem>
</varlistentry>

<varlistentry>
<term>v</term>
<listitem><para>The current speed as "V=%f" in knots.</para></listitem>
</varlistentry>

<varlistentry>
<term>w</term>
<listitem><para>Toggles 'watcher' mode. Return "W=0" or "W=1". 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 &mdash;
e.g., a GPRMC sentence ships a "pvs" response because it contains
position, velocity and GPS status data.
</para></listitem>
</varlistentry>

<varlistentry>
<term>y</term> 
<listitem>
<para>Returns Y= followed by a count not more than 12, followed by
that many triples of satellite PRNs and elevation/azimuth pairs
(elevation an integer formatted as %d in range 0-90, azimuth an
integer formatted as %d in range
0-359). Each number is followed by one space.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>z</term>
<listitem>
<para>Returns Z= followed by a count not more than 12, followed by that many
pairs of satellite PRNs and signal-to-noise percentages (each
percentage is in the range 0-99). Each number is an integer formatted as
%d followed by one space.</para>
</listitem>
</varlistentry>
</variablelist>

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

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

<screen>
      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"
</screen>

<para>If the GPS stops sending updates to gpsd, gpsd will continue
presenting the last data it got for 5 seconds 5 seconds, then begin
sending back empty responses xinsisting only of the GPSD prefix.</para>

</refsect2>
<refsect2><title>gps</title>

<para>gps is a simple test client for gpsd with an X interface; it can
also connect direct to a GPS (not recommended, as that mode will not
restart a timed-out connection and cannot use differential-GPS
corrections).  It displays current GPS animation and (for GPSes that
support the feature) the locations of accessible satellites.</para>

<para>gps accepts -TDph options as for gpsd.</para>

</refsect2>
<refsect2><title>xgpsspeed</title>

<para>xgpsspeed is a speedometer that uses position information from
the GPS. It accepts -TDph options as for gpsd.</para>

</refsect2>
</refsect1>
<refsect1 id='standards'><title>APPLICABLE STANDARDS</title> 

<para>The official NMEA protocol standard is available on paper from
the <ulink url='http://www.nmea.org/pub/0183/'>National Marine
Electronics Association</ulink>. A description of the protocol is
<ulink url='http://vancouver-webpages.com/peter/nmeafaq.txt'>available on the
Web</ulink>.  gpsd parses the following NMEA sentences:
GPRMC, GPGLL, GPVTG, GPGGA, GPGSA, GPGSV. It also recognizes the
vendor extensions PMGNST and PRWIZCH.</para>

<para>The Rockwell protocol is described as an addendum on <ulink
url='http://www.gpsinformation.net/dale/nmea.htm'>this page about
NMEA</ulink>.</para>

<para>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.</para>

</refsect1>
<refsect1 id='maintainer'><title>MAINTAINER</title> 

<para>Russ Nelson <email>nelson@crynwr.com</email>.  This manual page
by Eric S. Raymond <email>esr@thyrsus.com</email>.  There is a project
page, with gps screenshots, <ulink
url="http://www.pygps.org/gpsd/gpsd.html">here</ulink>.</para>
</refsect1>

</refentry>