gpsd.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!--
   3 This file is Copyright (c) 2010 by the GPSD project
   4 BSD terms apply: see the file COPYING in the distribution root for details.
   5 -->
   6 <!DOCTYPE refentry PUBLIC
   7    "-//OASIS//DTD DocBook XML V4.1.2//EN"
   8    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
   9 <!ENTITY gpsdsock        "/var/run/gpsd.sock">
  10 ]>
  11 <refentry id='gpsd.8'>
  12 <refentryinfo><date>9 Aug 2004</date></refentryinfo>
  13 <refmeta>
  14 <refentrytitle>gpsd</refentrytitle>
  15 <manvolnum>8</manvolnum>
  16 <refmiscinfo class="source">The GPSD Project</refmiscinfo>
  17 <refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
  18 </refmeta>
  19 <refnamediv id='name'>
  20 <refname>gpsd</refname>
  21 <refpurpose>interface daemon for GPS receivers</refpurpose>
  22 </refnamediv>
  23
  24 <refsynopsisdiv id='synopsis'>
  25
  26 <cmdsynopsis>
  27   <command>gpsd</command>
  28       <arg choice='opt'>-F <replaceable>control-socket</replaceable></arg>
  29       <!-- arg choice='opt'>-R
  30       <replaceable>rtcm-listener-port</replaceable></arg -->
  31       <arg choice='opt'>-S <replaceable>listener-port</replaceable></arg>
  32       <arg choice='opt'>-b </arg>
  33       <arg choice='opt'>-l </arg>
  34       <arg choice='opt'>-G </arg>
  35       <arg choice='opt'>-n </arg>
  36       <arg choice='opt'>-N </arg>
  37       <arg choice='opt'>-h </arg>
  38       <arg choice='opt'>-P <replaceable>pidfile</replaceable></arg>
  39       <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg>
  40       <arg choice='opt'>-V </arg>
  41       <arg rep='repeat'>
  42            <group><replaceable>source-name</replaceable></group>
  43       </arg>
  44 </cmdsynopsis>
  45 </refsynopsisdiv>
  46
  47 <refsect1 id='quickstart'><title>QUICK START</title>
  48
  49 <para>If you have a GPS attached on the lowest-numbered USB port of a
  50 Linux system, and want to read reports from it on TCP/IP port 2947, it
  51 will normally suffice to do this:</para>
  52
  53 <programlisting>
  54 gpsd /dev/ttyUSB0
  55 </programlisting>
  56
  57 <para>For the lowest-numbered serial port:</para>
  58
  59 <programlisting>
  60 gpsd /dev/ttyS0
  61 </programlisting>
  62
  63 <para>Change the device number as appropriate if you need to use a
  64 different port. Command-line flags enable verbose logging, a control
  65 port, and other optional extras but should not be needed for basic
  66 operation; the one exception, on very badly designed hardware, might
  67 be <option>-b</option> (which see).</para>
  68
  69 <para>On Linux systems supporting udev, <application>gpsd</application>
  70 is normally started automatically when a USB plugin event fires (if it
  71 is not already running) and is handed the name of the newly active
  72 device. In that case no invocation is required at all.</para>
  73
  74 <para>For your initial tests set your GPS hardware to speak NMEA, as
  75 <application>gpsd</application> is guaranteed to be able to process
  76 that. If your GPS has a native or binary mode with better perfornance
  77 that <application>gpsd</application> knows how to speak,
  78 <application>gpsd</application> will autoconfigure that mode.</para>
  79
  80 <para>You can verify correct operation by first starting
  81 <application>gpsd</application> and then
  82 <application>xgps</application>, the X windows test client.</para>
  83
  84 <para>If you have problems, the GPSD project maintains a <ulink
  85 url="http://gpsd.berlios.de/faq.html">FAQ</ulink> to assist
  86 troubleshooting.</para>
  87
  88 </refsect1>
  89 <refsect1 id='description'><title>DESCRIPTION</title>
  90
  91 <para><application>gpsd</application> is a monitor daemon that collects
  92 information from GPSes, differential-GPS radios, or AIS receivers
  93 attached to the host machine.  Each GPS, DGPS radio, or AIS receiver
  94 is expected to be direct-connected to the host via a USB or RS232C
  95 serial device.  The serial device may be specified to
  96 <application>gpsd</application> at startup, or it may be set via a
  97 command shipped down a local control socket (e.g. by a USB hotplug
  98 script). Given a GPS device by either means,
  99 <application>gpsd</application> discovers the correct port speed and
 100 protocol for it.</para>
 101
 102 <para><application>gpsd</application> should be able to query any GPS
 103 that speaks either the standard textual NMEA 0183 protocol, or the
 104 (differing) extended NMEA dialects used by MKT-3301, iTrax, Motorola
 105 OnCore, Sony CXD2951, and Ashtech/Thales devices.  It can also
 106 interpret the binary protocols used by EverMore, Garmin, Navcom,
 107 Rockwell/Zodiac, SiRF, Trimble, and uBlox ANTARIS devices. It can read
 108 heading and attitude information from the Oceanserver 5000 orv TNT
 109 Revolution digital compasses.</para>
 110
 111 <para>The GPS reporting formats supported by your instance of
 112 <application>gpsd</application> may differ depending on how it was
 113 compiled; general-purpose versions support many, but it can be built
 114 with protocol subsets down to a singleton for use in constrained
 115 environments. For a list of the GPS protocols supported by your
 116 instance, see the output of <command>gpsd -l</command></para>
 117
 118 <para><application>gpsd</application> effectively hides the
 119 differences among the GPS types it supports. It also knows about and
 120 uses commands that tune these GPSes for lower latency. By using
 121 <application>gpsd</application> as an intermediary applications
 122 avoid contention for serial devices.</para>
 123
 124 <para><application>gpsd</application> can use differential-GPS
 125 corrections from a DGPS radio or over the net, from a ground station
 126 running a DGPSIP server or a Ntrip broadcaster that reports RTCM-104
 127 data; this will shrink position errors by roughly a factor of four.
 128 When <application>gpsd</application> opens a serial device emitting
 129 RTCM-104, it automatically recognizes this and uses the device as a
 130 correction source for all connected GPSes that accept RTCM corrections
 131 (this is dependent on the type of the GPS; not all GPSes have the
 132 firmware capability to accept RTCM correction packets). See
 133 <xref linkend='accuracy'/> and <xref linkend='files'/> for discussion.</para>
 134
 135 <para>Client applications will communicate with <application>gpsd</application>
 136 via a TCP/IP port, 2947 by default).  Both IPv4 and IPv6 connections
 137 are supported and a client may connect via either.</para>
 138
 139 <para>The program accepts the following options:</para>
 140 <variablelist remap='TP'>
 141 <varlistentry>
 142 <term>-F</term>
 143 <listitem>
 144 <para>Create a control socket for device addition and removal
 145 commands.  You must specify a valid pathname on your local filesystem;
 146 this will be created as a Unix-domain socket to which you can write
 147 commands that edit the daemon's internal device list.</para>
 148 </listitem>
 149 </varlistentry>
 150 <varlistentry>
 151 <term>-S</term>
 152 <listitem><para>Set TCP/IP port on which to listen for GPSD clients
 153 (default is 2947).</para></listitem>
 154 </varlistentry>
 155 <varlistentry>
 156 <term>-b</term>
 157 <listitem><para>Broken-device-safety mode, otherwise known as read-only
 158 mode. Some popular bluetooth and USB receivers lock up or become
 159 totally inaccessible when probed or reconfigured. This switch prevents
 160 gpsd from writing to a receiver.  This means that
 161 <application>gpsd</application> cannot configure the receiver for
 162 optimal performance, but it also means that
 163 <application>gpsd</application> cannot break the receiver. A better
 164 solution would be for Bluetooth to not be so fragile. A platform
 165 independent method to identify serial-over-Bluetooth devices would
 166 also be nice.</para></listitem>
 167 </varlistentry>
 168 <varlistentry>
 169 <term>-G</term>
 170 <listitem><para>This flag causes <application>gpsd</application> to
 171 listen on all addresses (INADDR_ANY) rather than just the loopback
 172 (INADDR_LOOPBACK) address. For the sake of privacy and security, TPV
 173 information is now private to the local machine until the user makes
 174 an effort to expose this to the world.</para></listitem>
 175 </varlistentry>
 176 <varlistentry>
 177 <term>-l</term>
 178 <listitem><para>List all drivers compiled into this
 179 <application>gpsd</application> instance. The letters to the left of
 180 each driver name are the <application>gpsd</application>
 181 control commands supported by that driver.</para>
 182 </listitem>
 183 </varlistentry>
 184 <varlistentry>
 185 <term>-n</term>
 186 <listitem>
 187 <para>Don't wait for a client to connect before polling
 188 whatever GPS is associated with it. Many GPSes go to a standby mode
 189 (drawing less power) before the host machine asserts DTR, so waiting
 190 for the first actual request saves battery power.</para>
 191 </listitem>
 192 </varlistentry>
 193 <varlistentry>
 194 <term>-N</term>
 195 <listitem><para>Don't daemonize; run in foreground.  Also suppresses
 196 privilege-dropping.  This switch is mainly useful for debugging.</para>
 197 </listitem>
 198 </varlistentry>
 199 <varlistentry>
 200 <term>-h</term>
 201 <listitem><para>Display help message and terminate.</para></listitem>
 202 </varlistentry>
 203 <varlistentry>
 204 <term>-P</term>
 205 <listitem>
 206 <para>Specify the name and path to record the daemon's process ID.</para>
 207 </listitem>
 208 </varlistentry>
 209 <varlistentry>
 210 <term>-D</term>
 211 <listitem>
 212 <para>Set debug level. At debug levels 2 and above,
 213 <application>gpsd</application> reports incoming sentence and actions
 214 to standard error if <application>gpsd</application> is in the foreground
 215 (-N) or to syslog if in the background.</para>
 216 </listitem>
 217 </varlistentry>
 218 <varlistentry>
 219 <term>-V</term>
 220 <listitem>
 221 <para>Dump version and exit.</para>
 222 </listitem>
 223 </varlistentry>
 224 </variablelist>
 225
 226 <para>Arguments are interpreted as the names of data sources.
 227 Normally, a data source is the device pathname of a local device from
 228 which the daemon may expect GPS data. But there are three other
 229 special source types recognized, for a total of four:</para>
 230
 231 <variablelist>
 232 <varlistentry>
 233 <term>Local serial or USB device</term>
 234 <listitem>
 235 <para>A normal Unix device name of a serial or USB device to which a
 236 sensor is attached. Example:
 237 <filename>/dev/ttyUSB0</filename>.</para>
 238 </listitem>
 239 </varlistentry>
 240 <varlistentry>
 241 <term>TCP feed</term>
 242 <listitem>
 243 <para>A URI with the prefix "tcp://", followed by a hostname, a
 244 colon, and a port number. The daemon will open a socket to the
 245 indicated address and port and read data packets from it, which will
 246 be interpreted as though they had been issued by a serial device. Example:
 247 <filename>tcp://data.aishub.net:4006</filename>.</para>
 248 </listitem>
 249 </varlistentry>
 250 <varlistentry>
 251 <term>UDP feed</term>
 252 <listitem>
 253 <para>A URI with the prefix "udp://", followed by a hostname, a
 254 colon, and a port number. The daemon will open a socket listening for
 255 UDP datagrams arriving on the indicated address and port, which will
 256 be interpreted as though they had been issued by a serial device. Example:
 257 <filename>udp://127.0.0.1:5000</filename>.</para>
 258 </listitem>
 259 </varlistentry>
 260 <varlistentry>
 261 <term>Ntrip caster</term>
 262 <listitem>
 263 <para>A URI with the prefix "ntrip://" followed by the name of an
 264 Ntrip caster (Ntrip is a protocol for broadcasting differential-GPS
 265 fixes over the net). For Ntrip services that require authentication, a
 266 prefix of the form "username:password@" can be added before the name
 267 of the Ntrip broadcaster.  For Ntrip service, you must specify which
 268 stream to use; the stream is given in the form "/streamname". An
 269 example DGPSIP URI could be "dgpsip://dgpsip.example.com" and a Ntrip
 270 URI could be
 271 "ntrip://foo:bar@ntrip.example.com:80/example-stream". Corrections
 272 from the caster will be send to each attached GPS with the capability
 273 to accept them.</para>
 274 </listitem>
 275 </varlistentry>
 276 <varlistentry>
 277 <term>DGPSIP server</term>
 278 <listitem>
 279 <para>A URI with the prefix "dgpsip://" followed by a hostname, a
 280 colon, and an optional colon-separated port number (defaulting to
 281 2101). The daemon will handshake with the DGPSIP server and
 282 read RTCM2 correction data from it. Corrections
 283 from the server will be set to each attached GPS with the capability
 284 to accept them.Example:
 285 <filename>dgpsip://dgps.wsrcc.com:2101</filename>.</para>
 286 </listitem>
 287 </varlistentry>
 288 </variablelist>
 289
 290 <para>(The "ais:://" source type supported in some older versions of
 291 the daemon has been retired in favor of the more general
 292 "tcp://".)</para>
 293
 294 <para>Internally, the daemon maintains a device pool holding the
 295 pathnames of devices and remote servers known to the
 296 daemon. Initially, this list is the list of device-name arguments
 297 specified on the command line.  That list may be empty, in which case
 298 the daemon will have no devices on its search list until they are
 299 added by a control-socket command (see <xref linkend='devices'/> for
 300 details on this).  Daemon startup will abort with an error if neither
 301 any devices nor a control socket are specified.</para>
 302
 303 <para>Clients communicate with the daemon via textual request and
 304 responses. It is a bad idea for applications to speak the protocol
 305 directly: rather, they should use the
 306 <application>libgps</application> client library and take appropriate
 307 care to conditionalize their code on the major and minor protocol
 308 version symbols.</para>
 309
 310 </refsect1>
 311 <refsect1 id='protocol'><title>REQUEST/RESPONSE PROTOCOL</title>
 312
 313 <para>The GPSD protocol is built on top of JSON, JaveScript
 314 Object Notation. Use of this metaprotocol to pass structured
 315 data between daemon and client avoids the non-extensibility
 316 problems of the old protocol, and permits a richer set of record types
 317 to be passed up to clients.</para>
 318
 319 <para>A request line is introduced by "?" and may include multiple
 320 commands.  Commands begin with a command identifier, followed either
 321 by a terminating ';' or by an equal sign "=" and a JSON object treated
 322 as an argument.  Any ';' or newline indication (either LF or CR-LF)
 323 after the end of a command is ignored. All request lines must be
 324 composed of US-ASCII characters and may be no more than 80 characters
 325 in length, exclusive of the trailing newline.</para>
 326
 327 <para>Responses are JSON objects all of which have a "class" attribute
 328 the value of which is either the name of the invoking command
 329 or one of the strings "DEVICE" or "ERROR". Their length
 330 limit is 1024 characters, including trailing newline.</para>
 331
 332 <para>The remainder of this section documents the core GPSD protocol.
 333 Extensions are docomented in the following sections. The extensions
 334 may not be supported in your <application>gpsd</application> instance
 335 if it has been compiled with a restricted feature set.</para>
 336
 337 <para>Here are the core-protocol responses:</para>
 338
 339 <variablelist>
 340 <varlistentry>
 341 <term>TPV</term>
 342 <listitem>
 343 <para>A TPV object is a time-position-velocity report. The "class" and "mode"
 344 fields will reliably be present.  Others may be reported or not
 345 depending on the fix quality.</para>
 346
 347 <table frame="all" pgwide="0"><title>TPV object</title>
 348 <tgroup cols="3" align="left" colsep="1" rowsep="1">
 349 <thead>
 350 <row>
 351         <entry>Name</entry>
 352         <entry>Always?</entry>
 353         <entry>Type</entry>
 354         <entry>Description</entry>
 355 </row>
 356 </thead>
 357 <tbody>
 358 <row>
 359         <entry>class</entry>
 360         <entry>Yes</entry>
 361         <entry>string</entry>
 362         <entry>Fixed: "TPV"</entry>
 363 </row>
 364 <row>
 365         <entry>tag</entry>
 366         <entry>No</entry>
 367         <entry>string</entry>
 368         <entry>Type tag associated with this GPS sentence; from an NMEA
 369         device this is just the NMEA sentence type..</entry>
 370 </row>
 371 <row>
 372         <entry>device</entry>
 373         <entry>No</entry>
 374         <entry>string</entry>
 375         <entry>Name of originating device</entry>
 376 </row>
 377 <row>
 378         <entry>time</entry>
 379         <entry>No</entry>
 380         <entry>numeric</entry>
 381         <entry>Seconds since the Unix epoch, UTC. May have a
 382         fractional part of up to .01sec precision.</entry>
 383 </row>
 384 <row>
 385         <entry>ept</entry>
 386         <entry>No</entry>
 387         <entry>numeric</entry>
 388         <entry>Estimated timestamp error (%f, seconds, 95% confidence).</entry>
 389 </row>
 390 <row>
 391         <entry>lat</entry>
 392         <entry>No</entry>
 393         <entry>numeric</entry>
 394         <entry>Latitude in degrees: +/- signifies West/East</entry>
 395 </row>
 396 <row>
 397         <entry>lon</entry>
 398         <entry>No</entry>
 399         <entry>numeric</entry>
 400         <entry>Longitude in degrees: +/- signifies North/South.</entry>
 401 </row>
 402 <row>
 403         <entry>alt</entry>
 404         <entry>No</entry>
 405         <entry>numeric</entry>
 406         <entry>Altitude in meters.</entry>
 407 </row>
 408 <row>
 409         <entry>epx</entry>
 410         <entry>No</entry>
 411         <entry>numeric</entry>
 412         <entry>Longitude error estimate in meters, 95% confidence.</entry>
 413 </row>
 414 <row>
 415         <entry>epy</entry>
 416         <entry>No</entry>
 417         <entry>numeric</entry>
 418         <entry>Latitude error estimate in meters, 95% confidence.</entry>
 419 </row>
 420 <row>
 421         <entry>epv</entry>
 422         <entry>No</entry>
 423         <entry>numeric</entry>
 424         <entry>Estimated vertical error in meters, 95% confidence.</entry>
 425 </row>
 426 <row>
 427         <entry>track</entry>
 428         <entry>No</entry>
 429         <entry>numeric</entry>
 430         <entry>Course over ground, degrees from true north.</entry>
 431 </row>
 432 <row>
 433         <entry>speed</entry>
 434         <entry>No</entry>
 435         <entry>numeric</entry>
 436         <entry>Speed over ground, meters per second.</entry>
 437 </row>
 438 <row>
 439         <entry>climb</entry>
 440         <entry>No</entry>
 441         <entry>numeric</entry>
 442         <entry>Climb (positive) or sink (negative) rate, meters per
 443         second.</entry>
 444 </row>
 445 <row>
 446         <entry>epd</entry>
 447         <entry>No</entry>
 448         <entry>numeric</entry>
 449         <entry>Direction error estimate in degrees, 95% confifdence.</entry>
 450 </row>
 451 <row>
 452         <entry>eps</entry>
 453         <entry>No</entry>
 454         <entry>numeric</entry>
 455         <entry>Speed error estinmate in meters/sec, 95% confifdence.</entry>
 456 </row>
 457 <row>
 458         <entry>epc</entry>
 459         <entry>No</entry>
 460         <entry>numeric</entry>
 461         <entry>Climb/sink error estinmate in meters/sec, 95% confifdence.</entry>
 462 </row>
 463 <row>
 464         <entry>mode</entry>
 465         <entry>Yes</entry>
 466         <entry>numeric</entry>
 467         <entry>NMEA mode: %d, 0=no mode value yet seen, 1=no fix, 2=2D, 3=3D.</entry>
 468 </row>
 469
 470 </tbody>
 471 </tgroup>
 472 </table>
 473
 474 <para>When the C client library parses a response of this kind, it
 475 will assert validity bits in the top-level set member for each
 476 field actually received; see gps.h for bitmask names and values.</para>
 477
 478 <para>Here's an example:</para>
 479
 480 <programlisting>
 481 {"class":"TPV","tag":"MID2","device":"/dev/pts/1",
 482     "time":1118327688.280,"ept":0.005,
 483     "lat":46.498293369,"lon":7.567411672,"alt":1343.127,
 484     "eph":36.000,"epv":32.321,
 485     "track":10.3788,"speed":0.091,"climb":-0.085,"mode":3}
 486 </programlisting>
 487 </listitem>
 488 </varlistentry>
 489
 490 <varlistentry>
 491 <term>SKY</term>
 492 <listitem>
 493 <para>A SKY object reports a sky view of the GPS satellite positions.
 494 If there is no GPS device available, or no skyview has been reported
 495 yet, only the "class" field will reliably be present.</para>
 496
 497 <table frame="all" pgwide="0"><title>SKY object</title>
 498 <tgroup cols="3" align="left" colsep="1" rowsep="1">
 499 <thead>
 500 <row>
 501         <entry>Name</entry>
 502         <entry>Always?</entry>
 503         <entry>Type</entry>
 504         <entry>Description</entry>
 505 </row>
 506 </thead>
 507 <tbody>
 508 <row>
 509         <entry>class</entry>
 510         <entry>Yes</entry>
 511         <entry>string</entry>
 512         <entry>Fixed: "SKY"</entry>
 513 </row>
 514 <row>
 515         <entry>tag</entry>
 516         <entry>No</entry>
 517         <entry>string</entry>
 518         <entry>Type tag associated with this GPS sentence; from an NMEA
 519         device this is just the NMEA sentence type..</entry>
 520 </row>
 521 <row>
 522         <entry>device</entry>
 523         <entry>No</entry>
 524         <entry>string</entry>
 525         <entry>Name of originating device</entry>
 526 </row>
 527 <row>
 528         <entry>time</entry>
 529         <entry>No</entry>
 530         <entry>numeric</entry>
 531         <entry>Seconds since the Unix epoch, UTC. May have a
 532         fractional part of up to .01sec precision.</entry>
 533 </row>
 534 <row>
 535         <entry>xdop</entry>
 536         <entry>No</entry>
 537         <entry>numeric</entry>
 538         <entry>Longitudinal dilution of precision, a dimensionsless
 539         factor which should be multiplied by a base UERE to get an
 540         error estimate.</entry>
 541 </row>
 542 <row>
 543         <entry>ydop</entry>
 544         <entry>No</entry>
 545         <entry>numeric</entry>
 546         <entry>Latitudinal dilution of precision, a dimensionsless
 547         factor which should be multiplied by a base UERE to get an
 548         error estimate.</entry>
 549 </row>
 550 <row>
 551         <entry>vdop</entry>
 552         <entry>No</entry>
 553         <entry>numeric</entry>
 554         <entry>Altitude dilution of precision, a dimensionsless
 555         factor which should be multiplied by a base UERE to get an
 556         error estimate.</entry>
 557 </row>
 558 <row>
 559         <entry>tdop</entry>
 560         <entry>No</entry>
 561         <entry>numeric</entry>
 562         <entry>Time dilution of precision, a dimensionsless
 563         factor which should be multiplied by a base UERE to get an
 564         error estimate.</entry>
 565 </row>
 566 <row>
 567         <entry>hdop</entry>
 568         <entry>No</entry>
 569         <entry>numeric</entry>
 570         <entry>Horizontal dilution of precision, a dimensionsless
 571         factor which should be multiplied by a base UERE to get a
 572         circular error estimate.</entry>
 573 </row>
 574 <row>
 575         <entry>pdop</entry>
 576         <entry>No</entry>
 577         <entry>numeric</entry>
 578         <entry>Spherical dilution of precision, a dimensionsless
 579         factor which should be multiplied by a base UERE to get an
 580         error estimate.</entry>
 581 </row>
 582 <row>
 583         <entry>gdop</entry>
 584         <entry>No</entry>
 585         <entry>numeric</entry>
 586         <entry>Hyperspherical dilution of precision, a dimensionsless
 587         factor which should be multiplied by a base UERE to get an
 588         error estimate.</entry>
 589 </row>
 590 <row>
 591         <entry>xdop</entry>
 592         <entry>No</entry>
 593         <entry>numeric</entry>
 594         <entry>Longitudinal dilution of precision, a dimensionsless
 595         factor which should be multiplied by a base UERE to get an
 596         error estimate.</entry>
 597 </row>
 598 <row>
 599         <entry>satellites</entry>
 600         <entry>Yes</entry>
 601         <entry>list</entry>
 602         <entry>List of satellite objects in skyview</entry>
 603 </row>
 604
 605 </tbody>
 606 </tgroup>
 607 </table>
 608
 609 <para>Many devices compute dilution of precision factors but do nit
 610 include them in their reports.  Many that do report DOPs report only
 611 HDOP, two-dimensial circular error. <application>gpsd</application>
 612 always passes through whatever the device actually reports, then
 613 attempts to fill in other DOPs by calculating the appropriate
 614 determinants in a covariance matrix based on the satellite view. DOPs
 615 may be missing if some of these determinants are singular. It can even
 616 happen that the device reports an error estimate in meters when the
 617 correspoding DOP is unavailable; some devices use more sophisticated
 618 error modeling than the covariance calculation.</para>
 619
 620 <para>The satellite list objects have the following elements:</para>
 621
 622 <table frame="all" pgwide="0"><title>Satellite object</title>
 623 <tgroup cols="3" align="left" colsep="1" rowsep="1">
 624 <thead>
 625 <row>
 626         <entry>Name</entry>
 627         <entry>Always?</entry>
 628         <entry>Type</entry>
 629         <entry>Description</entry>
 630 </row>
 631 </thead>
 632 <tbody>
 633 <row>
 634         <entry>PRN</entry>
 635         <entry>Yes</entry>
 636         <entry>numeric</entry>
 637         <entry>PRN ID of the satellite</entry>
 638 </row>
 639 <row>
 640         <entry>az</entry>
 641         <entry>Yes</entry>
 642         <entry>numeric</entry>
 643         <entry>Azimuth, degrees from true north.</entry>
 644 </row>
 645 <row>
 646         <entry>el</entry>
 647         <entry>Yes</entry>
 648         <entry>numeric</entry>
 649         <entry>Elevation in degrees.</entry>
 650 </row>
 651 <row>
 652         <entry>ss</entry>
 653         <entry>Yes</entry>
 654         <entry>numeric</entry>
 655         <entry>Signal strength in dB.</entry>
 656 </row>
 657 <row>
 658         <entry>used</entry>
 659         <entry>Yes</entry>
 660         <entry>boolean</entry>
 661         <entry>Used in current solution?</entry>
 662 </row>
 663 </tbody>
 664 </tgroup>
 665 </table>
 666
 667 <para>Note that satellite objects do not have a "class" field.., as
 668 they are never shipped outside of a SKY object.</para>
 669
 670 <para>When the C client library parses a SKY response, it
 671 will assert the SATELLITE_SET bit in the top-level set member.</para>
 672
 673 <para>Here's an example:</para>
 674
 675 <programlisting>
 676 {"class":"SKY","tag":"MID2","device":"/dev/pts/1","time":1118327688.280
 677     "xdop":1.55,"hdop":1.24,"pdop":1.99,
 678     "satellites":[
 679         {"PRN":23,"el":6,"az":84,"ss":0,"used":false},
 680         {"PRN":28,"el":7,"az":160,"ss":0,"used":false},
 681         {"PRN":8,"el":66,"az":189,"ss":44,"used":true},
 682         {"PRN":29,"el":13,"az":273,"ss":0,"used":false},
 683         {"PRN":10,"el":51,"az":304,"ss":29,"used":true},
 684         {"PRN":4,"el":15,"az":199,"ss":36,"used":true},
 685         {"PRN":2,"el":34,"az":241,"ss":43,"used":true},
 686         {"PRN":27,"el":71,"az":76,"ss":43,"used":true}]}
 687 </programlisting>
 688
 689 </listitem>
 690 </varlistentry>
 691
 692 <varlistentry>
 693 <term>ATT</term>
 694 <listitem>
 695 <para>An ATT object is a vehicle-attitude report. It is returned by
 696 digital-compass and gyroscope sensors; depending on device, it may
 697 include: heading, pitch, roll, yaw, gyroscope, and magnetic-field
 698 readings. Because such sensors are often bundled as part of
 699 marine-navigation systems, the ATT response may also include
 700 water depth.</para>
 701
 702 <para>The "class", "mode", and "tag" fields will reliably be present.  Others
 703 may be reported or not depending on the specific device type.</para>
 704
 705 <table frame="all" pgwide="0"><title>ATT object</title>
 706 <tgroup cols="3" align="left" colsep="1" rowsep="1">
 707 <thead>
 708 <row>
 709         <entry>Name</entry>
 710         <entry>Always?</entry>
 711         <entry>Type</entry>
 712         <entry>Description</entry>
 713 </row>
 714 </thead>
 715 <tbody>
 716 <row>
 717         <entry>class</entry>
 718         <entry>Yes</entry>
 719         <entry>string</entry>
 720         <entry>Fixed: "ATT"</entry>
 721 </row>
 722 <row>
 723         <entry>tag</entry>
 724         <entry>Yes</entry>
 725         <entry>string</entry>
 726         <entry>Type tag associated with this GPS sentence; from an NMEA
 727         device this is just the NMEA sentence type..</entry>
 728 </row>
 729 <row>
 730         <entry>device</entry>
 731         <entry>Yes</entry>
 732         <entry>string</entry>
 733         <entry>Name of originating device</entry>
 734 </row>
 735 <row>
 736         <entry>time</entry>
 737         <entry>Yes</entry>
 738         <entry>numeric</entry>
 739         <entry>Seconds since the Unix epoch, UTC. May have a
 740         fractional part of up to .01sec precision.</entry>
 741 </row>
 742 <row>
 743         <entry>heading</entry>
 744         <entry>No</entry>
 745         <entry>numeric</entry>
 746         <entry>Heading, degrees from true north.</entry>
 747 </row>
 748 <row>
 749         <entry>mag_st</entry>
 750         <entry>No</entry>
 751         <entry>string</entry>
 752         <entry>Magnetometer status.</entry>
 753 </row>
 754 <row>
 755         <entry>pitch</entry>
 756         <entry>No</entry>
 757         <entry>numeric</entry>
 758         <entry>Pitch in degrees.</entry>
 759 </row>
 760 <row>
 761         <entry>pitch_st</entry>
 762         <entry>No</entry>
 763         <entry>string</entry>
 764         <entry>Pitch sensor status.</entry>
 765 </row>
 766 <row>
 767         <entry>yaw</entry>
 768         <entry>No</entry>
 769         <entry>numeric</entry>
 770         <entry>Yaw in degrees</entry>
 771 </row>
 772 <row>
 773         <entry>yaw_st</entry>
 774         <entry>No</entry>
 775         <entry>string</entry>
 776         <entry>Yaw sensor status.</entry>
 777 </row>
 778 <row>
 779         <entry>roll</entry>
 780         <entry>No</entry>
 781         <entry>numeric</entry>
 782         <entry>Roll in degrees.</entry>
 783 </row>
 784 <row>
 785         <entry>roll_st</entry>
 786         <entry>No</entry>
 787         <entry>string</entry>
 788         <entry>Roll sensor status.</entry>
 789 </row>
 790 <row>
 791         <entry>dip</entry>
 792         <entry>No</entry>
 793         <entry>numeric</entry>
 794         <entry>Roll in degrees.</entry>
 795 </row>
 796 <row>
 797         <entry>mag_len</entry>
 798         <entry>No</entry>
 799         <entry>numeric</entry>
 800         <entry>Scalar magnetic field strength.</entry>
 801 </row>
 802 <row>
 803         <entry>mag_x</entry>
 804         <entry>No</entry>
 805         <entry>numeric</entry>
 806         <entry>X component of magnetic field strength.</entry>
 807 </row>
 808 <row>
 809         <entry>mag_y</entry>
 810         <entry>No</entry>
 811         <entry>numeric</entry>
 812         <entry>Y component of magnetic field strength..</entry>
 813 </row>
 814 <row>
 815         <entry>mag_z</entry>
 816         <entry>No</entry>
 817         <entry>numeric</entry>
 818         <entry>Z component of magnetic field strength..</entry>
 819 </row>
 820 <row>
 821         <entry>mag_len</entry>
 822         <entry>No</entry>
 823         <entry>numeric</entry>
 824         <entry>Scalar acceleration.</entry>
 825 </row>
 826 <row>
 827         <entry>acc_x</entry>
 828         <entry>No</entry>
 829         <entry>numeric</entry>
 830         <entry>X component of acceleration.</entry>
 831 </row>
 832 <row>
 833         <entry>acc_y</entry>
 834         <entry>No</entry>
 835         <entry>numeric</entry>
 836         <entry>Y component of acceleration.</entry>
 837 </row>
 838 <row>
 839         <entry>acc_z</entry>
 840         <entry>No</entry>
 841         <entry>numeric</entry>
 842         <entry>Z component of acceleration..</entry>
 843 </row>
 844 <row>
 845         <entry>gyro_x</entry>
 846         <entry>No</entry>
 847         <entry>numeric</entry>
 848         <entry>X component of acceleration.</entry>
 849 </row>
 850 <row>
 851         <entry>gyro_y</entry>
 852         <entry>No</entry>
 853         <entry>numeric</entry>
 854         <entry>Y component of acceleration.</entry>
 855 </row>
 856 <row>
 857         <entry>depth</entry>
 858         <entry>No</entry>
 859         <entry>numeric</entry>
 860         <entry>Water depth in meters.</entry>
 861 </row>
 862 <row>
 863         <entry>temperature</entry>
 864         <entry>No</entry>
 865         <entry>numeric</entry>
 866         <entry>Temperature at sensir, degrees centigrade.</entry>
 867 </row>
 868
 869
 870 </tbody>
 871 </tgroup>
 872 </table>
 873
 874 <para>The heading, pitch, and roll status codes (if present) vary by device.
 875 For the TNT Revolution digital compasses, they are coded as follows: </para>
 876
 877 <table frame="all" pgwide="0"><title>Device flags</title>
 878 <tgroup cols="2" align="left" colsep="1" rowsep="1">
 879 <thead>
 880 <row>
 881         <entry>Code</entry>
 882         <entry>Description</entry>
 883 </row>
 884 </thead>
 885 <tbody>
 886 <row>
 887         <entry>C</entry>
 888         <entry>magnetometer calibration alarm</entry>
 889 </row>
 890 <row>
 891         <entry>L</entry>
 892         <entry>low alarm</entry>
 893 </row>
 894 <row>
 895         <entry>M</entry>
 896         <entry>low warning</entry>
 897 </row>
 898 <row>
 899         <entry>N</entry>
 900         <entry>normal</entry>
 901 </row>
 902 <row>
 903         <entry>O</entry>
 904         <entry>high warning</entry>
 905 </row>
 906 <row>
 907         <entry>P</entry>
 908         <entry>high alarm</entry>
 909 </row>
 910 <row>
 911         <entry>V</entry>
 912         <entry>magnetometer voltage level alarm</entry>
 913 </row>
 914 </tbody>
 915 </tgroup>
 916 </table>
 917
 918
 919 <para>When the C client library parses a response of this kind, it
 920 will assert ATT_IS.</para>
 921
 922 <para>Here's an example:</para>
 923
 924 <programlisting>
 925 {"class":"ATT","tag":"PTNTHTM","time":1270938096.843,
 926     "heading":14223.00,"mag_st":"N",
 927     "pitch":169.00,"pitch_st":"N", "roll":-43.00,"roll_st":"N",
 928     "dip":13641.000,"mag_x":2454.000,"temperature":0.000,"depth":0.000}
 929 </programlisting>
 930 </listitem>
 931 </varlistentry>
 932
 933 </variablelist>
 934
 935 <para>And here are the commands:</para>
 936
 937 <variablelist>
 938
 939 <varlistentry>
 940 <term>?VERSION;</term>
 941 <listitem><para>Returns an object with the following attributes:</para>
 942
 943 <table frame="all" pgwide="0"><title>VERSION object</title>
 944 <tgroup cols="4" align="left" colsep="1" rowsep="1">
 945 <thead>
 946 <row>
 947         <entry>Name</entry>
 948         <entry>Always?</entry>
 949         <entry>Type</entry>
 950         <entry>Description</entry>
 951 </row>
 952 </thead>
 953 <tbody>
 954 <row>
 955         <entry>class</entry>
 956         <entry>Yes</entry>
 957         <entry>string</entry>
 958         <entry>Fixed: "VERSION"</entry>
 959 </row>
 960 <row>
 961         <entry>release</entry>
 962         <entry>Yes</entry>
 963         <entry>string</entry>
 964         <entry>Public release level</entry>
 965 </row>
 966 <row>
 967         <entry>rev</entry>
 968         <entry>Yes</entry>
 969         <entry>string</entry>
 970         <entry>Internal revision-control level.</entry>
 971 </row>
 972 <row>
 973         <entry>proto_major</entry>
 974         <entry>Yes</entry>
 975         <entry>numeric</entry>
 976         <entry>API major revision level..</entry>
 977 </row>
 978 <row>
 979         <entry>proto_minor</entry>
 980         <entry>Yes</entry>
 981         <entry>numeric</entry>
 982         <entry>API minor revision level..</entry>
 983 </row>
 984 </tbody>
 985 </tgroup>
 986 </table>
 987
 988 <para>The daemon ships a VERSION response to each client when the
 989 client first connects to it.</para>
 990
 991 <para>When the C client library parses a response of this kind, it
 992 will assert the VERSION_SET bit in the top-level set member.</para>
 993
 994 <para>Here's an example:</para>
 995
 996 <programlisting>
 997 {"class":"VERSION","version":"2.40dev","rev":"06f62e14eae9886cde907dae61c124c53eb1101f","proto_major":3,"proto_minor":1}
 998 </programlisting>
 999
1000
1001 </listitem>
1002 </varlistentry>
1003
1004 <varlistentry>
1005 <term>?DEVICES;</term>
1006 <listitem><para>Returns a device list object with the
1007 following elements:</para>
1008
1009 <table frame="all" pgwide="0"><title>DEVICES object</title>
1010 <tgroup cols="3" align="left" colsep="1" rowsep="1">
1011 <thead>
1012 <row>
1013         <entry>Name</entry>
1014         <entry>Always?</entry>
1015         <entry>Type</entry>
1016         <entry>Description</entry>
1017 </row>
1018 </thead>
1019 <tbody>
1020 <row>
1021         <entry>class</entry>
1022         <entry>Yes</entry>
1023         <entry>string</entry>
1024         <entry>Fixed: "DEVICES"</entry>
1025 </row>
1026 <row>
1027         <entry>devices</entry>
1028         <entry>Yes</entry>
1029         <entry>list</entry>
1030         <entry>List of device descriptions</entry>
1031 </row>
1032 </tbody>
1033 </tgroup>
1034 </table>
1035
1036 <para>When the C client library parses a response of this kind, it
1037 will assert the DEVICELIST_SET bit in the top-level set member.</para>
1038
1039 <para>Here's an example:</para>
1040
1041 <programlisting>
1042 {"class"="DEVICES","devices":[
1043     {"class":"DEVICE","path":"/dev/pts/1","flags":1,"driver":"SiRF binary"},
1044     {"class":"DEVICE","path":"/dev/pts/3","flags":4,"driver":"AIVDM"}]}
1045 </programlisting>
1046
1047 <para>The daemon occasionally ships a bare DEVICE object to the client
1048 (that is, one not inside a DEVICES wrapper). The data content of these
1049 objects will be described later in the section covering
1050 notifications.</para>
1051
1052 </listitem>
1053 </varlistentry>
1054
1055 <varlistentry>
1056 <term>?WATCH;</term>
1057 <listitem>
1058
1059 <para>This command sets watcher mode. It also sets or elicits a report
1060 of per-subscriber policy and the raw bit.  An argument WATCH object
1061 changes the subscriber's policy. The responce describes the
1062 subscriber's policy. The response will also include a DEVICES
1063 object.</para>
1064
1065 <para>A WATCH object has the following elements:</para>
1066
1067 <table frame="all" pgwide="0"><title>WATCH object</title>
1068 <tgroup cols="4" align="left" colsep="1" rowsep="1">
1069 <thead>
1070 <row>
1071         <entry>Name</entry>
1072         <entry>Always?</entry>
1073         <entry>Type</entry>
1074         <entry>Description</entry>
1075 </row>
1076 </thead>
1077 <tbody>
1078 <row>
1079         <entry>class</entry>
1080         <entry>Yes</entry>
1081         <entry>string</entry>
1082         <entry>Fixed: "WATCH"</entry>
1083 </row>
1084 <row>
1085         <entry>enable</entry>
1086         <entry>No</entry>
1087         <entry>boolean</entry>
1088         <entry>Enable (true) or disable (false) watcher mode. Default
1089         is true.</entry>
1090 </row>
1091 <row>
1092         <entry>json</entry>
1093         <entry>No</entry>
1094         <entry>boolean</entry>
1095         <entry>Enable (true) or disable (false) dumping of JSON reports.
1096         Default is false.</entry>
1097 </row>
1098 <row>
1099         <entry>nmea</entry>
1100         <entry>No</entry>
1101         <entry>boolean</entry>
1102         <entry>Enable (true) or disable (false) dumping of binary
1103         packets as pseudo-NMEA. Default
1104         is false.</entry>
1105 </row>
1106 <row>
1107         <entry>raw</entry>
1108         <entry>No</entry>
1109         <entry>integer</entry>
1110
1111         <entry>Controls 'raw' mode. When this attribute is set to 1
1112         for a channel, <application>gpsd</application> reports the
1113         unprocessed NMEA or AIVDM data stream from whatever device is attached.
1114         Binary GPS packets are hex-dumped.  RTCM2 and RTCM3
1115         packets are not dumped in raw mode.</entry>
1116 </row>
1117 <row>
1118         <entry>scaled</entry>
1119         <entry>No</entry>
1120         <entry>boolean</entry>
1121         <entry>If true, apply scaling divisors to output before
1122         dumping; default is false. Applies only to AIS reports.</entry>
1123 </row>
1124 <row>
1125         <entry>device</entry>
1126         <entry>No</entry>
1127         <entry>string</entry>
1128         <entry>If present, enable watching only of the specified device
1129         rather than all devices.  Useful with raw and NMEA modes
1130         in which device responses aren't tagged. Has no effect when
1131         used with enable:false.</entry>
1132 </row>
1133 </tbody>
1134 </tgroup>
1135 </table>
1136
1137 <para>There is an additional boolean "timing" attribute which is
1138 undocumented because that portion of the interface is considered
1139 unstable and for developer use only.</para>
1140
1141 <para>In watcher mode, GPS reports are dumped as TPV and SKY
1142 responses. AIS and RTCM reporting is described in the next section.</para>
1143
1144 <para>When the C client library parses a response of this kind, it
1145 will assert the POLICY_SET bit in the top-level set member.</para>
1146
1147 <para>Here's an example:</para>
1148
1149 <programlisting>
1150 {"class":"WATCH", "raw":1,"scaled":true}
1151 </programlisting>
1152
1153 </listitem>
1154 </varlistentry>
1155
1156 <varlistentry>
1157 <term>?POLL;</term>
1158 <listitem>
1159
1160 <para>The POLL command requests data from the last-seen fixes on all
1161 active GPS devices.  Devices must previously have been activated by
1162 ?WATCH to be pollable, or have been specified on the GPSD command line
1163 together with an <option>-n</option> option.</para>
1164
1165 <para>Polling can lead to possibly surprising results when it is used
1166 on a device such as an NMEA GPS for which a complete fix has to be
1167 accumulated from several sentences. If you poll while those sentences
1168 are being emitted, the response will contain the last complete fix
1169 data and may be as much as one cycle time (typically 1 second)
1170 stale.</para>
1171
1172 <para>The POLL response will contain a timestamped list of TPV objects
1173 describing cached data, and a timestamped list of SKY objects
1174 describing satellite configuration. If a device has not seen fixes, it
1175 will be reported with a mode field of zero.</para>
1176
1177 <table frame="all" pgwide="0"><title>POLL object</title>
1178 <tgroup cols="3" align="left" colsep="1" rowsep="1">
1179 <thead>
1180 <row>
1181         <entry>Name</entry>
1182         <entry>Always?</entry>
1183         <entry>Type</entry>
1184         <entry>Description</entry>
1185 </row>
1186 </thead>
1187 <tbody>
1188 <row>
1189         <entry>class</entry>
1190         <entry>Yes</entry>
1191         <entry>string</entry>
1192         <entry>Fixed: "POLL"</entry>
1193 </row>
1194 <row>
1195         <entry>time</entry>
1196         <entry>Yes</entry>
1197         <entry>Numeric</entry>
1198         <entry>Seconds since the Unix epoch, UTC. May have a
1199         fractional part of up to .001sec precision.</entry>
1200 </row>
1201 <row>
1202         <entry>active</entry>
1203         <entry>Yes</entry>
1204         <entry>Numeric</entry>
1205         <entry>Count of active devices.</entry>
1206 </row>
1207 <row>
1208         <entry>fixes</entry>
1209         <entry>Yes</entry>
1210         <entry>JSON array</entry>
1211         <entry>Comma-separated list of TPV objects.</entry>
1212 </row>
1213 <row>
1214         <entry>skyviews</entry>
1215         <entry>Yes</entry>
1216         <entry>JSON array</entry>
1217         <entry>Comma-separated list of SKY objects.</entry>
1218 </row>
1219 </tbody>
1220 </tgroup>
1221 </table>
1222
1223 <para>Here's an example of a POLL response:</para>
1224
1225 <programlisting>
1226 {"class":"POLL","timestamp":1270517274.846,"active":1,
1227     "fixes":[{"class":"TPV","tag":"MID41","device":"/dev/ttyUSB0",
1228               "time":1270517264.240,"ept":0.005,"lat":40.035093060,
1229               "lon":-75.519748733,"track":99.4319,"speed":0.123,"mode":2}],
1230     "skyviews":[{"class":"SKY","tag":"MID41","device":"/dev/ttyUSB0",
1231                  "time":1270517264.240,"hdop":9.20,
1232                  "satellites":[{"PRN":16,"el":55,"az":42,"ss":36,"used":true},
1233                                {"PRN":19,"el":25,"az":177,"ss":0,"used":false},
1234                                {"PRN":7,"el":13,"az":295,"ss":0,"used":false},
1235                                {"PRN":6,"el":56,"az":135,"ss":32,"used":true},
1236                                {"PRN":13,"el":47,"az":304,"ss":0,"used":false},
1237                                {"PRN":23,"el":66,"az":259,"ss":0,"used":false},
1238                                {"PRN":20,"el":7,"az":226,"ss":0,"used":false},
1239                                {"PRN":3,"el":52,"az":163,"ss":32,"used":true},
1240                                {"PRN":31,"el":16,"az":102,"ss":0,"used":false}
1241 ]}]}
1242 </programlisting>
1243
1244 <note>
1245 <para>Client software should not assime the field inventory of the
1246 POLL response is fixed for all time.  As
1247 <application>gpsd</application> collects and caches more data from
1248 more sensor types, those data are likely to find their way
1249 into this response.</para>
1250 </note>
1251
1252 </listitem>
1253 </varlistentry>
1254
1255 <varlistentry>
1256 <term>?DEVICE</term>
1257 <listitem>
1258
1259 <para>This command reports (when followed by ';') the state of a
1260 device, or sets (when followed by '=' and a DEVICE object)
1261 device-specific control bits, notably the device's speed and serial
1262 mode and the native-mode bit.  The parameter-setting form will be rejected if
1263 more than one client is attached to the channel.</para>
1264
1265 <para>Pay attention to the response, because it is
1266 possible for this command to fail if the GPS does not support a
1267 speed-switching command or only supports some combinations of
1268 serial modes.  In case of failure, the daemon and GPS will
1269 continue to communicate at the old speed.</para>
1270
1271 <para>Use the parameter-setting form with caution.  On USB and
1272 Bluetooth GPSes it is also possible for serial mode setting to fail
1273 either because the serial adaptor chip does not support non-8N1 modes
1274 or because the device firmware does not properly synchronize the
1275 serial adaptor chip with the UART on the GPS chipset whjen the speed
1276 changes. These failures can hang your device, possibly requiring a GPS
1277 power cycle or (in extreme cases) physically disconnecting the NVRAM
1278 backup battery.</para>
1279
1280 <para>A DEVICE object has the following elements:</para>
1281
1282 <table frame="all" pgwide="0"><title>CONFIGCHAN object</title>
1283 <tgroup cols="4" align="left" colsep="1" rowsep="1">
1284 <thead>
1285 <row>
1286         <entry>Name</entry>
1287         <entry>Always?</entry>
1288         <entry>Type</entry>
1289         <entry>Description</entry>
1290 </row>
1291 </thead>
1292 <tbody>
1293 <row>
1294         <entry>class</entry>
1295         <entry>Yes</entry>
1296         <entry>string</entry>
1297         <entry>Fixed: "DEVICE"</entry>
1298 </row>
1299 <row>
1300         <entry>path</entry>
1301         <entry>No</entry>
1302         <entry>string</entry>
1303         <entry>Name the device for which the control bits are
1304         being reported, or for which they are to be applied. This
1305         attribute may be omitted only when there is exactly one
1306         subscribed channel.</entry>
1307 </row>
1308 <row>
1309         <entry>activated</entry>
1310         <entry>At device activation and device close time.</entry>
1311         <entry>numeric</entry>
1312         <entry>Time the device was activated,
1313         or 0 if it is being closed.</entry>
1314 </row>
1315 <row>
1316         <entry>flags</entry>
1317         <entry>No</entry>
1318         <entry>integer</entry>
1319         <entry>Bit vector of property flags.  Currently defined flags are:
1320         describe packet types seen so far (GPS, RTCM2, RTCM3,
1321         AIS). Won't be reported if empty, e.g. before
1322         <application>gpsd</application> has seen identifiable packets
1323         from the device.</entry>
1324 </row>
1325 <row>
1326         <entry>driver</entry>
1327         <entry>No</entry>
1328         <entry>string</entry>
1329         <entry>GPSD's name for the device driver type. Won't be reported before
1330         <application>gpsd</application> has seen identifiable packets
1331         from the device.</entry>
1332 </row>
1333 <row>
1334         <entry>subtype</entry>
1335         <entry>When the daemon sees a delayed response to a probe for
1336         subtype or firmware-version information.</entry>
1337         <entry>string</entry>
1338         <entry>Whatever version information the device returned.</entry>
1339 </row>
1340 <row>
1341         <entry>bps</entry>
1342         <entry>No</entry>
1343         <entry>integer</entry>
1344         <entry>Device speed in bits per second.</entry>
1345 </row>
1346 <row>
1347         <entry>parity</entry>
1348         <entry>Yes</entry>
1349         <entry>string</entry>
1350         <entry><para>N, O or E for no parity, odd, or even.</para></entry>
1351 </row>
1352 <row>
1353         <entry>stopbits</entry>
1354         <entry>Yes</entry>
1355         <entry>string</entry>
1356         <entry><para>Stop bits (1 or 2).</para></entry>
1357 </row>
1358 <row>
1359         <entry>native</entry>
1360         <entry>No</entry>
1361         <entry>integer</entry>
1362         <entry>0 means NMEA mode and 1 means
1363         alternate mode (binary if it has one, for SiRF and Evermore chipsets
1364         in particular). Attempting to set this mode on a non-GPS
1365         device will yield an error.</entry>
1366 </row>
1367 <row>
1368         <entry>cycle</entry>
1369         <entry>No</entry>
1370         <entry>real</entry>
1371         <entry>Device cycle time in seconds.</entry>
1372 </row>
1373 <row>
1374         <entry>mincycle</entry>
1375         <entry>No</entry>
1376         <entry>real</entry>
1377         <entry>Device minimum cycle time in seconds. Reported from
1378         ?CONFIGDEV when (and only when) the rate is switchable. It is
1379         read-only and not settable.</entry>
1380 </row>
1381 </tbody>
1382 </tgroup>
1383 </table>
1384
1385 <para>The serial parameters will be omitted in a response describing a
1386 TCP/IP source such as an Ntrip, DGPSIP, or AIS feed.</para>
1387
1388 <para>The contents of the flags field should be interpreted as follows:</para>
1389
1390 <table frame="all" pgwide="0"><title>Device flags</title>
1391 <tgroup cols="3" align="left" colsep="1" rowsep="1">
1392 <thead>
1393 <row>
1394         <entry>C #define</entry>
1395         <entry>Value</entry>
1396         <entry>Description</entry>
1397 </row>
1398 </thead>
1399 <tbody>
1400 <row>
1401         <entry>SEEN_GPS</entry>
1402         <entry>0x01</entry>
1403         <entry>GPS data has been seen on this device</entry>
1404 </row>
1405 <row>
1406         <entry>SEEN_RTCM2</entry>
1407         <entry>0x02</entry>
1408         <entry>RTCM2 data has been seen on this device</entry>
1409 </row>
1410 <row>
1411         <entry>SEEN_RTCM3</entry>
1412         <entry>0x04</entry>
1413         <entry>RTCM3 data has been seen on this device</entry>
1414 </row>
1415 <row>
1416         <entry>SEEN_AIS</entry>
1417         <entry>0x08</entry>
1418         <entry>AIS data has been seen on this device</entry>
1419 </row>
1420 </tbody>
1421 </tgroup>
1422 </table>
1423
1424 <!--
1425 <para>The mincycle member may be 0, indicating no hard lower limit on the
1426 cycle time. On an NMEA device of this kind it is possible to try to
1427 push more characters through per cycle than the time to transmit will
1428 allow. You must set the time high enough to let all sentences come
1429 through.  Here are the maxima to use for computation:</para>
1430
1431 <table frame='all'>
1432 <tgroup cols='2'>
1433 <tbody>
1434 <row><entry>ZDA       </entry><entry>36</entry></row>
1435 <row><entry>GLL       </entry><entry>47</entry></row>
1436 <row><entry>GGA       </entry><entry>82</entry></row>
1437 <row><entry>VTG       </entry><entry>46</entry></row>
1438 <row><entry>RMC       </entry><entry>77</entry></row>
1439 <row><entry>GSA       </entry><entry>67</entry></row>
1440 <row><entry>GSV       </entry><entry>60 (per line, thus 180 for a set of 3)</entry> </row>
1441 </tbody>
1442 </tgroup>
1443 </table>
1444
1445 <para>The transmit time for a cycle (which must be less than 1 second)
1446 is the total character count multiplied by 10 and divided by the baud
1447 rate. A typical budget is GGA, RMC, GSA, 3*GSV = 82+75+67+(3*60) =
1448 404.</para>
1449 -->
1450
1451 <para>When the C client library parses a response of this kind, it
1452 will assert the DEVICE_SET bit in the top-level set member.</para>
1453
1454 <para>Here's an example:</para>
1455
1456 <programlisting>
1457 {"class":"DEVICE", "speed":4800,"serialmode":"8N1","native":0}
1458 </programlisting>
1459
1460 </listitem>
1461 </varlistentry>
1462
1463 </variablelist>
1464
1465 <para>When a client is in watcher mode, the daemon will ship it DEVICE
1466 notifications when a device is added to the pool or
1467 deactivated.</para>
1468
1469 <para>When the C client library parses a response of this kind, it
1470 will assert the DEVICE_SET bit in the top-level set member.</para>
1471
1472 <para>Here's an example:</para>
1473
1474 <programlisting>
1475 {"class":"DEVICE","path":"/dev/pts1","activated":0}
1476 </programlisting>
1477
1478 <para>The daemon may ship an error object in response to a
1479 syntactically invalid command line or unknown command. It has
1480 the following elements:</para>
1481
1482 <table frame="all" pgwide="0"><title>ERROR notification object</title>
1483 <tgroup cols="4" align="left" colsep="1" rowsep="1">
1484 <thead>
1485 <row>
1486         <entry>Name</entry>
1487         <entry>Always?</entry>
1488         <entry>Type</entry>
1489         <entry>Description</entry>
1490 </row>
1491 </thead>
1492 <tbody>
1493 <row>
1494         <entry>class</entry>
1495         <entry>Yes</entry>
1496         <entry>string</entry>
1497         <entry>Fixed: "ERROR"</entry>
1498 </row>
1499 <row>
1500         <entry>message</entry>
1501         <entry>Yes</entry>
1502         <entry>string</entry>
1503         <entry>Textual error message</entry>
1504 </row>
1505 </tbody>
1506 </tgroup>
1507 </table>
1508
1509 <para>Here's an example:</para>
1510
1511 <programlisting>
1512 {"class":"ERROR","message":"Unrecognized request '?FOO'"}
1513 </programlisting>
1514
1515 <para>When the C client library parses a response of this kind, it
1516 will assert the ERR_SET bit in the top-level set member.</para>
1517
1518 </refsect1>
1519 <refsect1 id='ais-rtcm'><title>AIS AND RTCM DUMP FORMATS</title>
1520
1521 <para>AIS support is an extension.  It may not be present if your
1522 instance of <application>gpsd</application> has been built with
1523 a restricted feature set.</para>
1524
1525 <para>AIS packets are dumped as JSON objects with class "AIS".  Each
1526 AIS report object contains a "type" field giving the AIS message type
1527 and a "scaled" field telling whether the remainder of the fields are
1528 dumped in scaled or unscaled form. Other fields have names and types
1529 as specified in the <ulink
1530 url="http://gpsd.berlios.de/AIVDM.html">AIVDM/AIVDO Protocol
1531 Decoding</ulink> document; each message field table may be directly
1532 interpreted as a specification for the members of the corresponding
1533 JSON object type.</para>
1534
1535 <para>RTCM2 corrections are dumped in the JSON format described in
1536 <citerefentry><refentrytitle>rtcm104</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
1537
1538 </refsect1>
1539 <refsect1 id='devices'><title>GPS DEVICE MANAGEMENT</title>
1540
1541 <para><application>gpsd</application> maintains an internal list of
1542 GPS devices (the "device pool").  If you specify devices on the
1543 command line, the list is initialized with those pathnames; otherwise
1544 the list starts empty.  Commands to add and remove GPS device paths
1545 from the daemon's device list must be written to a local Unix-domain
1546 socket which will be accessible only to programs running as root.
1547 This control socket will be located wherever the -F option specifies
1548 it.</para>
1549
1550 <para>A device may will also be dropped from the pool if GPSD gets a zero
1551 length read from it. This  end-of-file condition indicates that the'
1552 device has been disconnected.</para>
1553
1554 <para>When <application>gpsd</application> is properly installed along
1555 with hotplug notifier scripts feeding it device-add commands over the
1556 control socket, <application>gpsd</application> should require no
1557 configuration or user action to find devices.</para>
1558
1559 <para>Sending SIGHUP to a running <application>gpsd</application>
1560 forces it to close all GPSes and all client connections.  It will then
1561 attempt to reconnect to any GPSes on its device list and resume
1562 listening for client connections.  This may be useful if your GPS
1563 enters a wedged or confused state but can be soft-reset by pulling
1564 down DTR.</para>
1565
1566 <para>To point <application>gpsd</application> at a device that may be
1567 a GPS, write to the control socket a plus sign ('+') followed by the
1568 device name followed by LF or CR-LF.  Thus, to point the daemon at
1569 <filename>/dev/foo</filename>. send "+/dev/foo\n".  To tell the daemon
1570 that a device has been disconnected and is no longer available, send a
1571 minus sign ('-') followed by the device name followed by LF or
1572 CR-LF. Thus, to remove <filename>/dev/foo</filename> from the search
1573 list. send "-/dev/foo\n".</para>
1574
1575 <para>To send a control string to a specified device, write to the
1576 control socket a '!', followed by the device name, followed by '=',
1577 followed by the control string.</para>
1578
1579 <para>To send a binary control string to a specified device, write to the
1580 control socket a '&amp;', followed by the device name, followed by '=',
1581 followed by the control string in paired hex digits.</para>
1582
1583 <para>Your client may await a response, which will be a line beginning
1584 with either "OK" or "ERROR".  An ERROR reponse to an add command means
1585 the device did not emit data recognizable as GPS packets; an ERROR
1586 response to a remove command means the specified device was not in
1587 <application>gpsd</application>'s device pool. An ERROR response to a
1588 ! command means the daemon did not recognize the devicename
1589 specified.</para>
1590
1591 <para>The control socket is intended for use by hotplug scripts and
1592 other device-discovery services.  This control channel is separate
1593 from the public <application>gpsd</application> service port, and only
1594 locally accessible, in order to prevent remote denial-of-service and
1595 spoofing attacks.</para>
1596
1597 </refsect1>
1598 <refsect1 id='accuracy'><title>ACCURACY</title>
1599
1600 <para>The base User Estimated Range Error (UERE) of GPSes is 8 meters
1601 or less at 66% confidence, 15 meters or less at 95% confidence. Actual
1602 horizontal error will be UERE times a dilution factor dependent on current
1603 satellite position.  Altitude determination is more sensitive to
1604 variability in ionospheric signal lag than latitude/longitude is, and is
1605 also subject to errors in the estimation of local mean sea level; base
1606 error is 12 meters at 66% confidence, 23 meters at 95% confidence.
1607 Again, this will be multiplied by a vertical dilution of precision
1608 (VDOP) dependent on satellite geometry, and VDOP is typically larger
1609 than HDOP.  Users should <emphasis>not</emphasis> rely on GPS altitude for
1610 life-critical tasks such as landing an airplane.</para>
1611
1612 <para>These errors are intrinsic to the design and physics of the GPS
1613 system.  <application>gpsd</application> does its internal
1614 computations at sufficient accuracy that it will add no measurable
1615 position error of its own.</para>
1616
1617 <para>DGPS correction will reduce UERE by a factor of 4, provided you
1618 are within about 100mi (160km) of a DGPS ground station from which you
1619 are receiving corrections.</para>
1620
1621 <para>On a 4800bps connection, the time latency of fixes provided by
1622 <application>gpsd</application> will be one second or less 95% of the
1623 time.  Most of this lag is due to the fact that GPSes normally emit
1624 fixes once per second, thus expected latency is 0.5sec.  On the
1625 personal-computer hardware available in 2005, computation lag induced
1626 by <application>gpsd</application> will be negligible, on the order of
1627 a millisecond.  Nevertheless, latency can introduce significant errors
1628 for vehicles in motion; at 50km/h (31mi/h) of speed over ground, 1
1629 second of lag corresponds to 13.8 meters change in position between
1630 updates.</para>
1631
1632 <para>The time reporting of the GPS system itself has an intrinsic
1633 accuracy limit of 0.000,000,340 =
1634 3.4&times;10<superscript>-7</superscript> seconds.  A more important
1635 limit is the GPS tick rate.  While the one-per-second PPS pulses
1636 emitted by serial GPS units are timed to the GPS system's intrinsic
1637 accuracy limit,the satellites only emit navigation messages at
1638 0.01-second intervals, and the timestamps in them only carry
1639 0.01-second precision. Thus, the timestamps that
1640 <application>gpsd</application> reports in time/position/velocity
1641 messages are normally accurate only to 1/100th of a second.</para>
1642
1643 </refsect1>
1644 <refsect1 id='ntp'><title>USE WITH NTP</title>
1645
1646 <para>gpsd can provide reference clock information to
1647 <application>ntpd</application>, to keep the system clock synchronized
1648 to the time provided by the GPS receiver.  This facility is
1649 only available when the daemon is started from root.  If you're going
1650 to use <application>gpsd</application> you probably want to run it
1651 <option>-n</option> mode so the clock will be updated even when no
1652 clients are active.</para>
1653
1654 <para>Note that deriving time from messages received from the GPS is
1655 not as accurate as you might expect.  Messages are often delayed in
1656 the receiver and on the link by several hundred milliseconds, and this
1657 delay is not constant.  On Linux, <application>gpsd</application>
1658 includes support for interpreting the PPS pulses emitted at the start
1659 of every clock second on the carrier-detect lines of some serial
1660 GPSes; this pulse can be used to update NTP at much higher accuracy
1661 than message time provides.  You can determine whether your GPS emits
1662 this pulse by running at -D 5 and watching for carrier-detect state
1663 change messages in the logfile.</para>
1664
1665 <para>When <application>gpsd</application> receives a sentence with a
1666 timestamp, it packages the received timestamp with current local time
1667 and sends it to a shared-memory segment with an ID known to
1668 <application>ntpd</application>, the network time synchronization
1669 daemon.  If <application>ntpd</application> has been properly
1670 configured to receive this message, it will be used to correct the
1671 system clock.</para>
1672
1673 <para>Here is a sample <filename>ntp.conf</filename> configuration
1674 stanza telling <application>ntpd</application> how to read the GPS
1675 notfications:</para>
1676
1677 <programlisting>
1678 server 127.127.28.0 minpoll 4 maxpoll 4
1679 fudge 127.127.28.0 time1 0.420 refid GPS
1680
1681 server 127.127.28.1 minpoll 4 maxpoll 4 prefer
1682 fudge 127.127.28.1 refid GPS1
1683 </programlisting>
1684
1685 <para>The magic pseudo-IP address 127.127.28.0 identifies unit 0 of
1686 the <application>ntpd</application> shared-memory driver; 127.127.28.1
1687 identifies unit 1.  Unit 0 is used for message-decoded time and unit 1
1688 for the (more accurate, when available) time derived from the PPS
1689 synchronization pulse.  Splitting these notifications allows
1690 <application>ntpd</application> to use its normal heuristics to weight
1691 them.</para>
1692
1693 <para>With this configuration, <application>ntpd</application> will
1694 read the timestamp posted by <application>gpsd</application> every 16
1695 seconds and send it to unit 0.  The number after the parameter time1
1696 is an offset in seconds.  You can use it to adjust out some of the
1697 fixed delays in the system.  0.035 is a good starting value for the
1698 Garmin GPS-18/USB, 0.420 for the Garmin GPS-18/LVC.</para>
1699
1700 <para>After restarting ntpd, a line similar to the one below should
1701 appear in the output of the command "ntpq -p" (after allowing a couple
1702 of minutes):</para>
1703
1704 <screen>
1705 remote     refid      st t when poll reach  delay    offset  jitter
1706 =========================================================================
1707 +SHM(0)   .GPS.      0 l   13   16  377    0.000    0.885   0.882
1708 </screen>
1709
1710 <para>If you are running PPS then it will look like this:</para>
1711
1712 <screen>
1713 remote     refid      st t when poll reach  delay    offset  jitter
1714 =========================================================================
1715 -SHM(0)   .GPS.      0 l   13   16  377    0.000    0.885   0.882
1716 *SHM(1)   .GPS1.     0 l   11   16  377    0.000   -0.059   0.006
1717 </screen>
1718
1719 <para>When the value under "reach" remains zero, check that gpsd is
1720 running; and some application is connected to it or the '-n' option was
1721 used.  Make sure the receiver is locked on to at least one satellite,
1722 and the receiver is in SiRF binary, Garmin binary or NMEA/PPS mode.  Plain
1723 NMEA will also drive ntpd, but the accuracy as bad as one second.  When
1724 the SHM(0) line does not appear at all, check the system logs for error
1725 messages from ntpd.</para>
1726
1727 <para>When no other reference clocks appear in the NTP configuration,
1728 the system clock will lock onto the GPS clock.  When you have previously
1729 used <application>ntpd</application>, and other reference clocks appear
1730 in your configuration, there may be a fixed offset between the GPS clock
1731 and other clocks.  The <application>gpsd</application> developers would
1732 like to receive information about the offsets observed by users for each
1733 type of receiver.  Please send us the output of the "ntpq -p" command
1734 and the make and type of receiver.</para>
1735
1736 </refsect1>
1737 <refsect1 id='dbus'><title>USE WITH D-BUS</title>
1738
1739 <para>On operating systems that support D-BUS,
1740 <application>gpsd</application> can be built to broadcast GPS fixes to
1741 D-BUS-aware applications.  As D-BUS is still at a pre-1.0 stage, we
1742 will not attempt to document this interface here.  Read the
1743 <application>gpsd</application> source code to learn more.</para>
1744
1745 </refsect1>
1746 <refsect1 id='security'><title>SECURITY AND PERMISSIONS ISSUES</title>
1747
1748 <para><application>gpsd</application>, if given the -G flag, will
1749 listen for connections from any reachable host, and then disclose the
1750 current position.  Before using the -G flag, consider whether you
1751 consider your computer's location to be sensitive data to be kept
1752 private or something that you wish to publish.</para>
1753
1754 <para><application>gpsd</application> must start up as root in order
1755 to open the NTPD shared-memory segment, open its logfile, and create
1756 its local control socket.  Before doing any processing of GPS data, it
1757 tries to drop root privileges by setting its UID to "nobody" (or another
1758 userid as set by configure) and its group ID to the group of the initial
1759 GPS passed on the command line &mdash; or, if that device doesn't exist,
1760 to the group of <filename>/dev/ttyS0</filename>.</para>
1761
1762 <para>Privilege-dropping is a hedge against the possibility that
1763 carefully crafted data, either presented from a client socket or from
1764 a subverted serial device posing as a GPS, could be used to induce
1765 misbehavior in the internals of <application>gpsd</application>.
1766 It ensures that any such compromises cannot be used for privilege
1767 elevation to root.</para>
1768
1769 <para>The assumption behind <application>gpsd</application>'s
1770 particular behavior is that all the tty devices to which a GPS might
1771 be connected are owned by the same non-root group and allow group
1772 read/write, though the group may vary because of distribution-specific
1773 or local administrative practice.  If this assumption is false,
1774 <application>gpsd</application> may not be able to open GPS devices in
1775 order to read them (such failures will be logged).</para>
1776
1777 <para>In order to fend off inadvertent denial-of-service attacks by
1778 port scanners (not to mention deliberate ones),
1779 <application>gpsd</application> will time out inactive client
1780 connections.  Before the client has issued a command that requests a
1781 channel assignment, a short timeout (60 seconds) applies.  There is no
1782 timeout for clients in watcher or raw modes; rather,
1783 <application>gpsd</application> drops these clients if they fail to
1784 read data long enough for the outbound socket write buffer to fill.
1785 Clients with an assigned device in polling mode are subject to a
1786 longer timeout (15 minutes).</para>
1787
1788 </refsect1>
1789 <refsect1 id='limitations'><title>LIMITATIONS</title>
1790
1791 <para>If multiple NMEA talkers are feeding RMC, GLL, and GGA sentences
1792 to the same serial device (possible with an RS422 adapter hooked up to
1793 some marine-navigation systems), a 'TPV' response may mix an altitude
1794 from one device's GGA with latitude/longitude from another's RMC/GLL
1795 after the second sentence has arrived.</para>
1796
1797 <para><application>gpsd</application> may change control settings on
1798 your GPS (such as the emission frequency of various sentences or
1799 packets) and not restore the original settings on exit.  This is a
1800 result of inadequacies in NMEA and the vendor binary GPS protocols,
1801 which often do not give clients any way to query the values of control
1802 settings in order to be able to restore them later.</para>
1803
1804 <para>If your GPS uses a SiRF chipset at firmware level 231, reported
1805 UTC time may be off by the difference between 13 seconds and whatever
1806 leap-second correction is currently applicable, from startup until
1807 complete subframe information is received (normally about six
1808 seconds).  Firmware levels 232 and up don't have this problem.  You
1809 may run <application>gpsd</application> at debug level 4 to see the
1810 chipset type and firmware revision level.</para>
1811
1812 <para>When using SiRF chips, the VDOP/TDOP/GDOP figures and associated
1813 error estimates are computed by <application>gpsd</application> rather
1814 than reported by the chip.  The computation does not exactly match
1815 what SiRF chips do internally, which includes some satellite weighting
1816 using parameters <application>gpsd</application> cannot see.</para>
1817
1818 <para>Autobauding on the Trimble GPSes can take as long as 5 seconds
1819 if the device speed is not matched to the GPS speed.</para>
1820
1821 <para>If you are using an NMEA-only GPS (that is, not using SiRF or
1822 Garmin or Zodiac binary mode) and the GPS does not emit GPZDA at the
1823 start of its update cycle (which most consumer-grade NMEA GPSes do
1824 not) and it is after 2099, then the century part of the dates
1825 <application>gpsd</application> delivers will be wrong.</para>
1826
1827 <para>Generation of position error estimates (eph, epv, epd, eps, epc)
1828 from the incomplete data handed back by GPS reporting protocols
1829 involves both a lot of mathematical black art and fragile
1830 device-dependent assumptions.  This code has been bug-prone in tbe
1831 past and problems may still lurk there.</para>
1832
1833 </refsect1>
1834 <refsect1 id='files'><title>FILES</title>
1835
1836 <variablelist>
1837 <varlistentry>
1838 <term><filename>/dev/ttyS0</filename></term>
1839 <listitem>
1840 <para>Prototype TTY device. After startup,
1841 <application>gpsd</application> sets its group ID to the owner of this
1842 device if no GPS device was specified on the command line does not
1843 exist.</para>
1844 </listitem>
1845 </varlistentry>
1846 <!--
1847 <varlistentry>
1848 <term><filename>/usr/share/gpsd/dgpsip-servers</filename></term>
1849 <listitem>
1850 <para>A text file listing DGPSIP servers worldwide.  If no DGPSIP
1851 server is specified at startup (via the -d option)
1852 <application>gpsd</application> will look here to find the
1853 nearest one.  Each line has three space-separated fields:
1854 latitude (decimal degrees), longitude (decimal degrees) and
1855 a server name (optionally followed by a colon and a port number).
1856 Text following # on a line is ignored.  Blank lines are ignored.</para>
1857 </listitem>
1858 </varlistentry>
1859 -->
1860 </variablelist>
1861
1862 </refsect1>
1863 <refsect1 id='standards'><title>APPLICABLE STANDARDS</title>
1864
1865 <para>The official NMEA protocol standard is available on paper from
1866 the <ulink url='http://www.nmea.org/pub/0183/'>National Marine
1867 Electronics Association</ulink>, but is proprietary and expensive; the
1868 maintainers of <application>gpsd</application> have made a point of
1869 not looking at it.  The <ulink url="http://gpsd.berlios.de/">GPSD
1870 website</ulink> links to several documents that collect publicly
1871 disclosed information about the protocol.</para>
1872
1873 <para><application>gpsd</application> parses the following NMEA
1874 sentences: RMC, GGA, GLL, GSA, GSV, VTG, ZDA.  It recognizes these
1875 with either the normal GP talker-ID prefix, or with the GN prefix used
1876 by GLONASS, or with the II prefix emitted by Seahawk Autohelm marine
1877 navigation systems, or with the IN prefix emitted by some Garmin
1878 units.  It recognizes some vendor extensions: the PGRME emitted by some
1879 Garmin GPS models, the OHPR emitted by Oceanserver digital compasses,
1880 the PTNTHTM emitted by True North digital compasses, and the PASHR
1881 sentences emitted by some Ashtech GPSes.</para>
1882
1883 <para>Note that <application>gpsd</application> JSON returns pure decimal
1884 degrees, not the hybrid degree/minute format described in the NMEA
1885 standard.</para>
1886
1887 <para>Differential-GPS corrections are conveyed by the RTCM-104
1888 proocol. The applicable standard for RTCM-104 V2 is <citetitle>RTCM
1889 Recommended Standards for Differential NAVSTAR GPS Service</citetitle>
1890 RTCM Paper 194-93/SC 104-STD.  The applicable standard for RTCM-104 V3
1891 is <citetitle>RTCM Standard 10403.1 for Differential GNSS Services -
1892 Version 3</citetitle> RTCM Paper 177-2006-SC104-STD.</para>
1893
1894 <para>AIS is defined by ITU Recommendation M.1371,
1895 <citetitle>Technical Characteristics for a Universal Shipborne
1896 Automatic Identification System Using Time Division Multiple
1897 Access</citetitle>. The AIVDM/AIVDO format understood by this progeam
1898 is defined by IEC-PAS 61162-100, <citetitle>Maritime navigation and
1899 radiocommunication equipment and systems</citetitle></para>
1900
1901 </refsect1>
1902 <refsect1 id='see_also'><title>SEE ALSO</title>
1903 <para>
1904 <citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1905 <citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
1906 <citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
1907 <citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1908 <citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1909 <citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1910 <citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1911 <citerefentry><refentrytitle>rtcm-104</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
1912 </para>
1913 </refsect1>
1914
1915 <refsect1 id='maintainer'><title>AUTHORS</title>
1916
1917 <para>Remco Treffcorn, Derrick Brashear, Russ Nelson, Eric S. Raymond,
1918 Chris Kuethe.  This manual page by Eric S. Raymond
1919 <email>esr@thyrsus.com</email>.  There is a <ulink
1920 url="http://gpsd.berlios.de/">project site</ulink>.</para>
1921 </refsect1>
1922
1923 </refentry>