gpsd.xml

gpsd, a popular GPS daemon.

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