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" [
<!ENTITY gpsdsock         "/var/run/gpsd.sock">
]>
<refentry id='gpsd.8'>
<refmeta>
<refentrytitle>gpsd</refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo class='date'>9 Aug 2004</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>gpsd</refname>
<refpurpose>interface daemon for GPS receivers</refpurpose>
</refnamediv>
<refsynopsisdiv id='synopsis'>

<cmdsynopsis>
  <command>gpsd</command>  
      <arg choice='opt'>-f <replaceable>GPS-devicename</replaceable></arg>
      <arg choice='opt'>-F <replaceable>control-socket</replaceable></arg>
      <!-- arg choice='opt'>-R
      <replaceable>rtcm-listener-port</replaceable></arg -->
      <arg choice='opt'>-S <replaceable>listener-port</replaceable></arg>
      <arg choice='opt'>-b </arg>
      <arg choice='opt'>-n </arg>      
      <arg choice='opt'>-N </arg>      
      <arg choice='opt'>-h </arg>
      <arg choice='opt'>-P <replaceable>pidfile</replaceable></arg>
      <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg>
      <arg choice='opt'>-V </arg>
      <arg rep='repeat'>
           <group><replaceable>source-name</replaceable></group>
      </arg>
</cmdsynopsis>
</refsynopsisdiv>

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

<para><application>gpsd</application> 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
<application>gpsd</application> 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,
<application>gpsd</application> discovers the correct port speed and
protocol for it.</para>

<para><application>gpsd</application> 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 SiRFstar 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. <application>gpsd</application> effectively hides the
differences among these. It also knows about and uses commands that
tune the GPS for lower latency, decreased 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.</para>

<para><application>gpsd</application> can use differential-GPS
corrections from a DGPS radio or over the net, from a ground station
running a DGPSIP server or a Ntrip broadcaster that reports RTCM-S104
data; this will improve user error by roughly a factor of four.  When
<application>gpsd</application> opens a serial device emitting
RTCM-104, it automatically recognizes this and uses the device as a
correction source for all connected GPSes.  <!-- If no server is
specified, <application>gpsd</application> will hunt for one.--> See
<xref linkend='accuracy'/> and <xref linkend='files'/> for
discussion.</para>

<!-- para><application>gpsd</application> may itself serve DGPSIP data
from an attached RTCM-104 source to other instances of
<application>gpsd</application> connecting on port 2101.</para -->

<para>The program accepts the following options:</para>
<variablelist remap='TP'>
<varlistentry>
<term>-f</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-F</term>
<listitem>
<para>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 device list.</para>
</listitem>
</varlistentry>
<!-- varlistentry>
<term>-R</term>
<listitem><para>Set TCP/IP port on which to listen for DGPSIP clients
(default is 2101). The option -R 0 will disable serving DGPSIP
clients.</para></listitem>
</varlistentry -->
<varlistentry>
<term>-S</term>
<listitem><para>Set TCP/IP port on which to listen for GPSD clients 
(default is 2947).</para></listitem>
</varlistentry>
<varlistentry>
<term>-d</term>
<listitem><para>This is a deprecated option which takes a differential-GPS 
source as argument.  See the description of argument interpretation
below.</para></listitem>
</varlistentry>
<varlistentry>
<term>-b</term>
<listitem><para>Broken-device-safety, otherwise known as read-only mode. Some
popular bluetooth and USB receivers lock up or become totally inaccessible when
probed or reconfigured. This switch prevents gpsd from writing to a receiver.
This means that gpsd cannot configure the receiver for optimal performance,
but it also means that gpsd cannot break the receiver. A better solution
would be for bluetooth to not be so fragile. A platform independent method
to identify serial-over-bluetooth devices would also be nice.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-n</term>
<listitem><para>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 stream.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-N</term>
<listitem><para>Don't daemonize; run in foreground.  Also suppresses 
privilege-dropping.  This switch is mainly useful for debugging.
Its meaning may change in future versions.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-h</term>
<listitem><para>Display help message and terminate.</para></listitem>
</varlistentry>
<varlistentry>
<term>-P</term>
<listitem>
<para>Specify the name and path to record the daemon's process ID.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-D</term>
<listitem>
<para>Set debug level. At debug levels 2 and above,
<application>gpsd</application> reports incoming sentence and actions
to standard error.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-V</term>
<listitem>
<para>Dump version and exit.</para>
</listitem>
</varlistentry>
</variablelist>

<para>Arguments are interpreted as the names of data sources.  
Normally, a data source is the name of a local serial device from
which the daemon may expect GPS data.</para>

<para>A data source name may also be a URL pointing to a specific
differential-GPS service (DGPSIP server or Ntrip broadcaster).If the
URL starts with "ntrip://" Ntrip will be used; if the URL starts with
"dgpsip://", DGPSIP will be used.  <application>Gpsd</application>
also defaults to DGPSIP if no protocol is defined.  For Ntrip services
that require authentication, a prefix of the form "username:password@"
can be added before the name of the Ntrip broadcaster.  If a suffix of
the service name begins with ":" it is interpreted as a port number,
overriding the default IANA-assigned port of 2101.  For Ntrip service
you also need to specify which stream to use; the stream is given in
the form "/streamname". So, an example DGPSIP URL could be
"dgpsip://dgpsip.example.com" and a Ntrip URL could be
"ntrip://foo:bar@ntrip.example.com:80/example-stream". <!-- If this
option is not given, <application>gpsd</application> will hunt for a
DGPSIP server. --></para>



<para>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 linkend='devices'/> for details on this).  Daemon startup will
abort with an error if neither any devices nor a control socket are
specified.</para>

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

<para>The request protocol for <application>gpsd</application> 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:</para>

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

<varlistentry>
<term>b</term>
<listitem><para>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 the channel.</para></listitem>
</varlistentry>

<varlistentry>
<term>c</term>
<listitem>
<para>C with no following = asks the daemon to return the cycle time
of the attached GPS, if any.  If there is no attached device it will
return "C=?".</para>

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

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

<para>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.</para>
 
<para>This command will return "C=?" at start of session, before the
first full packet has been received from the GPS, because the GPS 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.</para></listitem>

</varlistentry>

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

<varlistentry>
<term>e</term>
<listitem>
<para>Returns "E=%f %f %f": three estimated position errors in meters
&mdash; total, horizontal, and vertical (95% confidence
level).  Note: many GPSes do not supply these numbers.  When the
GPS does not supply them, <application>gpsd</application> computes
them from satellite DOP using fixed figures for expected non-DGPS 
and DGPS range errors in meters.  A value of '?' for any of these
numbers should be taken to mean that component of DOP is not available.
See also the 'q' command.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>f</term>
<listitem><para>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 <application>gpsd</application>'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.</para>

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

<para>Once an 'f=' command succeeds, the client is tied to the
specified device until the client disconnects.</para>

<para>Whether the command is 'f' or 'f=' or not, and whether it succeeds
or not, the response always lists the name of the client's device.</para>

<para>(At protocol level 1, the F command failed if more than one
client was attached, and multiple devices were not supported.)</para>
</listitem>
</varlistentry>

<varlistentry>
<term>g</term>
<listitem>
<para>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 finds first.</para>

<para>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 device returns.</para>
</listitem>
</varlistentry>

<!--
<varlistentry>
<term>h</term>
<listitem>
<para>Heading, "H=%f" in degrees from true north.  Only available from
True North Technologies or comparable digital compass devices (c.f. 't')</para>
</listitem>
</varlistentry>
-->

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

<varlistentry>
<term>j</term>
<listitem>
<para>Get or set buffering policy; this only matters for NMEA devices
which report fix data in several separate sentences during the poll
cycle (and in particular it <emphasis>doesn't</emphasis> matter for
SiRF chips).  The default (j=0) is to clear all fix data at the start
of each poll cycle, so until the sentence that reports a given piece
of data arrives queries will report ?.  Setting j=1 will disable this,
retaining data from the previous cycle.  This is a per-user-channel
bit, not a per-device one.  The j=0 setting is hyper-correct and never
displays stale data, but may produce a jittery display; the j=1 setting
allows stale data but smooths the display.</para>

<para>(At protocol level below 3, there was no J command.  Note, this
command is experimental and its semantics are subject to change.)</para> 
</listitem>
</varlistentry>

<varlistentry>
<term>k</term>
<listitem><para>Returns a line consisting of "K=" followed by an
integer count of of all GPS devices known to
<application>gpsd</application>, 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.</para>

<para>(At protocol level 1, there was no K command.)</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 NMEA mode as "M=%d". 0=no mode value yet seen, 
1=no fix, 2=2D (no altitude), 3=3D (with altitude).</para></listitem>
</varlistentry>

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

<varlistentry>
<term>o</term>
<listitem>
<para>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:</para>

<variablelist>
<varlistentry>
<term>tag</term> <listitem><para>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.</para></listitem>
</varlistentry>

<varlistentry>
<term>timestamp</term>
<listitem><para>Seconds since the Unix epoch, UTC. May have a
fractional part of up to .01sec precision.</para></listitem>
</varlistentry>

<varlistentry>
<term>time error</term>
<listitem><para>Estimated timestamp error (%f, seconds, 
95% confidence).</para></listitem>
</varlistentry>

<varlistentry>
<term>latitude</term>
<listitem><para>Latitude as in the P report (%f, degrees).</para></listitem>
</varlistentry>

<varlistentry>
<term>longitude</term>
<listitem><para>Longitude as in the P report (%f, degrees).</para></listitem>
</varlistentry>

<varlistentry>
<term>altitude</term>
<listitem><para>Altitude as in the A report (%f, meters).  If the mode
field is not 3 this is an estimate and should be treated as
unreliable.</para></listitem>
</varlistentry>

<varlistentry>
<term>horizontal error estimate</term>
<listitem><para>Horizontal error estimate as in the E report 
(%f, meters).</para></listitem>
</varlistentry>

<varlistentry>
<term>vertical error estimate</term>
<listitem><para>Vertical error estimate as in the E report 
(%f, meters).</para></listitem>
</varlistentry>

<varlistentry>
<term>course over ground</term>
<listitem><para>Track as in the T report (%f, degrees).</para></listitem>
</varlistentry>

<varlistentry>
<term>speed over ground</term>
<listitem><para>Speed (%f, meters/sec). Note: older versions 
of the O command reported this field in knots.</para></listitem>
</varlistentry>

<varlistentry>
<term>climb/sink</term>
<listitem><para>Vertical velocity as in the U report 
(%f, meters/sec).</para></listitem>
</varlistentry>

<varlistentry>
<term>estimated error in course over ground</term>
<listitem><para>Error estimate for course (%f, degrees, 95% confidence).</para></listitem>
</varlistentry>

<varlistentry>
<term>estimated error in speed over ground</term>
<listitem><para>Error estimate for speed (%f, meters/sec, 95% 
confidence). Note: older experimental versions of the O command 
reported this field in knots.</para></listitem>
</varlistentry>

<varlistentry>
<term>estimated error in climb/sink</term>
<listitem><para>Estimated error for climb/sink 
(%f, meters/sec, 95% confidence).</para></listitem>
</varlistentry>

<varlistentry>
<term>mode</term>
<listitem><para>The NMEA mode (%d, ?=no mode value yet seen, 
1=no fix, 2=2D, 3=3D). (This field was not reported at protocol
levels 2 and lower.)</para></listitem>
</varlistentry>

</variablelist>
</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 %f %f %f %f %f": a count of satellites used in the
last fix, and five dimensionless dilution-of-precision (DOP) numbers
&mdash; 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.</para>

<para>Note: Older versions of <application>gpsd</application> reported
only the first three DOP numbers, omitting time DOP and total DOP.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>r</term>
<listitem><para>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
<citerefentry><refentrytitle>rtcm104</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>

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

<para>Note: older versions of <application>gpsd</application> did not
support super-raw mode.</para>
</listitem>
</varlistentry>

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

<varlistentry>
<term>t</term>
<listitem>
<para>Track made good; course "T=%f" in degrees from true north.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>u</term>
<listitem><para>Current rate of climb as "U=%f" in meters per second.
Some GPSes (not SiRF-based) do not report this, in that case 
<application>gpsd</application> computes it using the altitude from
the last fix (if available).</para></listitem>
</varlistentry>

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

<varlistentry>
<term>w</term>
<listitem><para>Sets or toggles 'watcher' mode (see the description
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.</para></listitem>
</varlistentry>

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

<para>(At protocol level 1, the nonzero response was always 1.)</para> 
</listitem>
</varlistentry>

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

<para>(At protocol level 1, this response had no tag or timestamp.)</para> 
</listitem>
</varlistentry>

<varlistentry>
<term>z</term> <listitem><para>The Z command returns daemon profiling
information of interest to <application>gpsd</application>
developers. The format of this string is subject to change without
notice.</para></listitem>
</varlistentry>

<varlistentry>
<term>$</term> <listitem><para>The $ command returns daemon profiling
information of interest to <application>gpsd</application>
developers. The format of this string is subject to change without
notice.</para></listitem>
</varlistentry>

</variablelist>

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

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

<para>Every <application>gpsd</application> 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=2002-11-16T02:45:05.12Z\r\n"

      query:       "va\n"
      reply:       "GPSD,V=0.000000,A=37.900000\r\n"
</screen>

<para>When clients are active but the GPS is not responding,
<application>gpsd</application> 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, <application>gpsd</application> 
should require no configuration or user action to find devices.</para>

<para>The recommended mode for clients is watcher mode.  In watcher
mode <application>gpsd</application> 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, and an I response giving the device type when the 
user is assigned a device.</para>

<para>Clients should be prepared for the possibility that additional
fields (such as heading or roll/pitch/yaw) may be added to the O
command, and not treat the occurrence of extra fields as an error.
The protocol number will be incremented if and when such fields
are added.</para>

<para>Sending SIGHUP to a running <application>gpsd</application>
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.</para>

</refsect1>
<refsect1 id='devices'><title>GPS DEVICE MANAGEMENT</title> 

<para><application>gpsd</application> 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 specifies it.</para>

<para>To point <application>gpsd</application> 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
<filename>/dev/foo</filename>. 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 <filename>/dev/foo</filename> from the search
list. send "-/dev/foo\n".</para>

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

<para>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
<application>gpsd</application>'s device list. An ERROR response to a
! command means the daemon did not recognize the devicename
specified.</para>

<para>The control socket is intended for use by hotplug scripts and 
other device-discovery services.  This control channel is separate 
from the public <application>gpsd</application> service port, and only
locally accessible, in order to prevent remote denial-of-service and
spoofing attacks.</para>

</refsect1>
<refsect1 id='accuracy'><title>ACCURACY</title> 

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

<para>These errors are intrinsic to the design and physics of the GPS
system.  <application>gpsd</application> does its internal
computations at sufficient accuracy that it will add no measurable
position error of its own.</para>

<para>DGPS correction will reduce UERE from roughly 8 meters to
roughly 2 meters, provided you are within about 100mi (160km) of a
DGPS ground station.</para>

<para>On a 4800bps connection, the time latency of fixes provided by
<application>gpsd</application> 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 <application>gpsd</application> 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.</para>

</refsect1>
<refsect1 id='ntp'><title>USE WITH NTP</title> 

<para>gpsd can provide reference clock information to
<application>ntpd</application>, 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 <application>gpsd</application> you probably want to run it
<option>-n</option> mode so the clock will be updated even when no
clients are active.</para>

<para>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, <application>gpsd</application>
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. On OpenBSD <application>gpsd</application>
makes use of the nmea(4) line discipline and the tty(4) timestamping
facilities to export PPS time via the sensors framework. OpenBSD's ntpd
uses these sensors to adjust the hardware clock and frequency. To make
use of this feature, <application>gpsd</application> must be started
as root so it can activate the timestamping and line discipline; after
attempting to set up PPS, it will relinquish root privileges.</para>

<para>When <application>gpsd</application> 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
<application>ntpd</application>, the network time synchronization
daemon.  If <application>ntpd</application> has been properly
configured to receive this message, it will be used to correct the
system clock.</para>

<para>Here is a sample <filename>ntp.conf</filename> configuration
stanza telling <application>ntpd</application> how to read the GPS
notfications:</para>

<programlisting>
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
</programlisting>

<para>The magic pseudo-IP address 127.127.28.0 identifies unit 0 of
the <application>ntpd</application> 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
<application>ntpd</application> to use its normal heuristics to weight
them.</para>

<para>With this configuration, <application>ntpd</application> will
read the timestamp posted by <application>gpsd</application> 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.</para>

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

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

<para>If you are running PPS then it will look like this:</para>

<screen> 
remote           refid      st t when poll reach  delay    offset  jitter
=========================================================================
-SHM(0)          .GPS.      0 l   13   16  377    0.000    0.885   0.882
*SHM(1)          .GPS1.     0 l   11   16  377    0.000   -0.059   0.006
</screen>

<para>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 binary, 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 from ntpd.</para>

<para>When no other reference clocks appear in the NTP configuration,
the system clock will lock onto the GPS clock.  When you have previously
used <application>ntpd</application>, and other reference clocks appear
in your configuration, there may be a fixed offset between the GPS clock
and other clocks.  The <application>gpsd</application> 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.</para>

</refsect1>
<refsect1 id='dbus'><title>USE WITH D-BUS</title> 

<para>On operating systems that support D-BUS,
<application>gpsd</application> 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
<application>gpsd</application> source code to learn more.</para>

</refsect1>
<refsect1 id='security'><title>SECURITY AND PERMISSIONS ISSUES</title> 

<para><application>gpsd</application> 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" (or another
userid as set by configure) and its group ID to the group of the initial
GPS passed on the command line &mdash; or, if that device doesn't exist,
to the group of <filename>/dev/ttyS0</filename>.</para>

<para>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 <application>gpsd</application>.
It ensures that any such compromises cannot be used for privilege
elevation to root.</para>

<para>The assumption behind <application>gpsd</application>'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,
<application>gpsd</application> may not be able to open GPS devices in
order to read them (such failures will be logged).</para>

<para>In order to fend off inadvertent denial-of-service attacks by
port scanners (not to mention deliberate ones),
<application>gpsd</application> 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,
<application>gpsd</application> 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).</para>

</refsect1>
<refsect1 id='limitations'><title>LIMITATIONS</title> 

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

<para><application>gpsd</application> 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 them later.</para>

<para>If your GPS uses a SiRF chipset at firmware level 231, and it is
after 31 May 2007, 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 <application>gpsd</application> at
debug level 4 to see the chipset type and firmware revision
level.</para>

<para>When using SiRF chips, the VDOP/TDOP/GDOP figures and associated
error estimates are computed by <application>gpsd</application> rather
than reported by the chip.  The computation does not exactly match
what SiRF chips do internally, which includes some satellite weighting
using parameters <application>gpsd</application> cannot see.</para>

<para>Autobauding on the Trimble GPSes can take as long as 5 seconds
if the device speed is not matched to the GPS speed.</para>

<para>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
<application>gpsd</application> delivers will be wrong.</para>

</refsect1>
<refsect1 id='files'><title>FILES</title>

<variablelist>
<varlistentry>
<term><filename>/dev/ttyS0</filename></term>
<listitem>
<para>Prototype TTY device. After startup,
<application>gpsd</application> sets its group ID to the owner of this
device if no GPS device was specified on the command line does not
exist.</para>
</listitem>
</varlistentry>
<!--
<varlistentry>
<term><filename>/usr/share/gpsd/dgpsip-servers</filename></term>
<listitem>
<para>A text file listing DGPSIP servers worldwide.  If no DGPSIP
server is specified at startup (via the -d option)
<application>gpsd</application> will look here to find the 
nearest one.  Each line has three space-separated fields: 
latitude (decimal degrees), longitude (decimal degrees) and
a server name (optionally followed by a colon and a port number).
Text following # on a line is ignored.  Blank lines are ignored.</para>
</listitem>
</varlistentry>
-->
</variablelist>

</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>, but is proprietary and expensive; the
maintainers of <application>gpsd</application> have made a point of
not looking at it.  The <ulink url="http://gpsd.berlios.de/">GPSD
website</ulink> links to several documents that collect publicly
disclosed information about the protocol.</para>

<para><application>gpsd</application> parses the following NMEA
sentences: RMC, GGA, GLL, GSA, GSV, VTG, 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, the PGRME emitted by some Garmin GPS models.</para>

<para>Note that <application>gpsd</application> returns pure decimal
degrees, not the hybrid degree/minute format described in the NMEA
standard.</para>

</refsect1>
<refsect1 id='see_also'><title>SEE ALSO</title>
<para>
<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>rtcm-104</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
</refsect1>

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

<para>Remco Treffcorn, Derrick Brashear, Russ Nelson, Eric S. Raymond,
Chris Kuethe.  This manual page by Eric S. Raymond
<email>esr@thyrsus.com</email>.  There is a project site at <ulink
url="http://gpsd.berlios.de/">here</ulink>.</para>
</refsect1>

</refentry>