1 <?xml version="1.0" encoding="ISO-8859-1"?>
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.
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">
11 <refentry id='gpsd.8'>
12 <refentryinfo><date>9 Aug 2004</date></refentryinfo>
14 <refentrytitle>gpsd</refentrytitle>
15 <manvolnum>8</manvolnum>
16 <refmiscinfo class="source">The GPSD Project</refmiscinfo>
17 <refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
19 <refnamediv id='name'>
20 <refname>gpsd</refname>
21 <refpurpose>interface daemon for GPS receivers</refpurpose>
24 <refsynopsisdiv id='synopsis'>
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>
42 <group><replaceable>source-name</replaceable></group>
47 <refsect1 id='quickstart'><title>QUICK START</title>
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>
57 <para>For the lowest-numbered serial port:</para>
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>
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>
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>
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>
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>
89 <refsect1 id='description'><title>DESCRIPTION</title>
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>
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>
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>
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>
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>
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>
139 <para>The program accepts the following options:</para>
140 <variablelist remap='TP'>
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>
152 <listitem><para>Set TCP/IP port on which to listen for GPSD clients
153 (default is 2947).</para></listitem>
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>
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>
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>
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>
195 <listitem><para>Don't daemonize; run in foreground. Also suppresses
196 privilege-dropping. This switch is mainly useful for debugging.</para>
201 <listitem><para>Display help message and terminate.</para></listitem>
206 <para>Specify the name and path to record the daemon's process ID.</para>
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>
221 <para>Dump version and exit.</para>
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>
233 <term>Local serial or USB device</term>
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>
241 <term>TCP feed</term>
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>
251 <term>UDP feed</term>
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>
261 <term>Ntrip caster</term>
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
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>
277 <term>DGPSIP server</term>
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>
290 <para>(The "ais:://" source type supported in some older versions of
291 the daemon has been retired in favor of the more general
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>
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>
311 <refsect1 id='protocol'><title>REQUEST/RESPONSE PROTOCOL</title>
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>
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>
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>
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>
337 <para>Here are the core-protocol responses:</para>
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>
347 <table frame="all" pgwide="0"><title>TPV object</title>
348 <tgroup cols="3" align="left" colsep="1" rowsep="1">
352 <entry>Always?</entry>
354 <entry>Description</entry>
361 <entry>string</entry>
362 <entry>Fixed: "TPV"</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>
372 <entry>device</entry>
374 <entry>string</entry>
375 <entry>Name of originating device</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>
387 <entry>numeric</entry>
388 <entry>Estimated timestamp error (%f, seconds, 95% confidence).</entry>
393 <entry>numeric</entry>
394 <entry>Latitude in degrees: +/- signifies West/East</entry>
399 <entry>numeric</entry>
400 <entry>Longitude in degrees: +/- signifies North/South.</entry>
405 <entry>numeric</entry>
406 <entry>Altitude in meters.</entry>
411 <entry>numeric</entry>
412 <entry>Longitude error estimate in meters, 95% confidence.</entry>
417 <entry>numeric</entry>
418 <entry>Latitude error estimate in meters, 95% confidence.</entry>
423 <entry>numeric</entry>
424 <entry>Estimated vertical error in meters, 95% confidence.</entry>
429 <entry>numeric</entry>
430 <entry>Course over ground, degrees from true north.</entry>
435 <entry>numeric</entry>
436 <entry>Speed over ground, meters per second.</entry>
441 <entry>numeric</entry>
442 <entry>Climb (positive) or sink (negative) rate, meters per
448 <entry>numeric</entry>
449 <entry>Direction error estimate in degrees, 95% confifdence.</entry>
454 <entry>numeric</entry>
455 <entry>Speed error estinmate in meters/sec, 95% confifdence.</entry>
460 <entry>numeric</entry>
461 <entry>Climb/sink error estinmate in meters/sec, 95% confifdence.</entry>
466 <entry>numeric</entry>
467 <entry>NMEA mode: %d, 0=no mode value yet seen, 1=no fix, 2=2D, 3=3D.</entry>
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>
478 <para>Here's an example:</para>
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}
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>
497 <table frame="all" pgwide="0"><title>SKY object</title>
498 <tgroup cols="3" align="left" colsep="1" rowsep="1">
502 <entry>Always?</entry>
504 <entry>Description</entry>
511 <entry>string</entry>
512 <entry>Fixed: "SKY"</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>
522 <entry>device</entry>
524 <entry>string</entry>
525 <entry>Name of originating device</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>
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>
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>
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>
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>
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>
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>
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>
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>
599 <entry>satellites</entry>
602 <entry>List of satellite objects in skyview</entry>
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>
620 <para>The satellite list objects have the following elements:</para>
622 <table frame="all" pgwide="0"><title>Satellite object</title>
623 <tgroup cols="3" align="left" colsep="1" rowsep="1">
627 <entry>Always?</entry>
629 <entry>Description</entry>
636 <entry>numeric</entry>
637 <entry>PRN ID of the satellite</entry>
642 <entry>numeric</entry>
643 <entry>Azimuth, degrees from true north.</entry>
648 <entry>numeric</entry>
649 <entry>Elevation in degrees.</entry>
654 <entry>numeric</entry>
655 <entry>Signal strength in dB.</entry>
660 <entry>boolean</entry>
661 <entry>Used in current solution?</entry>
667 <para>Note that satellite objects do not have a "class" field.., as
668 they are never shipped outside of a SKY object.</para>
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>
673 <para>Here's an example:</para>
676 {"class":"SKY","tag":"MID2","device":"/dev/pts/1","time":1118327688.280
677 "xdop":1.55,"hdop":1.24,"pdop":1.99,
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}]}
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
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>
705 <table frame="all" pgwide="0"><title>ATT object</title>
706 <tgroup cols="3" align="left" colsep="1" rowsep="1">
710 <entry>Always?</entry>
712 <entry>Description</entry>
719 <entry>string</entry>
720 <entry>Fixed: "ATT"</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>
730 <entry>device</entry>
732 <entry>string</entry>
733 <entry>Name of originating device</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>
743 <entry>heading</entry>
745 <entry>numeric</entry>
746 <entry>Heading, degrees from true north.</entry>
749 <entry>mag_st</entry>
751 <entry>string</entry>
752 <entry>Magnetometer status.</entry>
757 <entry>numeric</entry>
758 <entry>Pitch in degrees.</entry>
761 <entry>pitch_st</entry>
763 <entry>string</entry>
764 <entry>Pitch sensor status.</entry>
769 <entry>numeric</entry>
770 <entry>Yaw in degrees</entry>
773 <entry>yaw_st</entry>
775 <entry>string</entry>
776 <entry>Yaw sensor status.</entry>
781 <entry>numeric</entry>
782 <entry>Roll in degrees.</entry>
785 <entry>roll_st</entry>
787 <entry>string</entry>
788 <entry>Roll sensor status.</entry>
793 <entry>numeric</entry>
794 <entry>Roll in degrees.</entry>
797 <entry>mag_len</entry>
799 <entry>numeric</entry>
800 <entry>Scalar magnetic field strength.</entry>
805 <entry>numeric</entry>
806 <entry>X component of magnetic field strength.</entry>
811 <entry>numeric</entry>
812 <entry>Y component of magnetic field strength..</entry>
817 <entry>numeric</entry>
818 <entry>Z component of magnetic field strength..</entry>
821 <entry>mag_len</entry>
823 <entry>numeric</entry>
824 <entry>Scalar acceleration.</entry>
829 <entry>numeric</entry>
830 <entry>X component of acceleration.</entry>
835 <entry>numeric</entry>
836 <entry>Y component of acceleration.</entry>
841 <entry>numeric</entry>
842 <entry>Z component of acceleration..</entry>
845 <entry>gyro_x</entry>
847 <entry>numeric</entry>
848 <entry>X component of acceleration.</entry>
851 <entry>gyro_y</entry>
853 <entry>numeric</entry>
854 <entry>Y component of acceleration.</entry>
859 <entry>numeric</entry>
860 <entry>Water depth in meters.</entry>
863 <entry>temperature</entry>
865 <entry>numeric</entry>
866 <entry>Temperature at sensir, degrees centigrade.</entry>
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>
877 <table frame="all" pgwide="0"><title>Device flags</title>
878 <tgroup cols="2" align="left" colsep="1" rowsep="1">
882 <entry>Description</entry>
888 <entry>magnetometer calibration alarm</entry>
892 <entry>low alarm</entry>
896 <entry>low warning</entry>
900 <entry>normal</entry>
904 <entry>high warning</entry>
908 <entry>high alarm</entry>
912 <entry>magnetometer voltage level alarm</entry>
919 <para>When the C client library parses a response of this kind, it
920 will assert ATT_IS.</para>
922 <para>Here's an example:</para>
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}
935 <para>And here are the commands:</para>
940 <term>?VERSION;</term>
941 <listitem><para>Returns an object with the following attributes:</para>
943 <table frame="all" pgwide="0"><title>VERSION object</title>
944 <tgroup cols="4" align="left" colsep="1" rowsep="1">
948 <entry>Always?</entry>
950 <entry>Description</entry>
957 <entry>string</entry>
958 <entry>Fixed: "VERSION"</entry>
961 <entry>release</entry>
963 <entry>string</entry>
964 <entry>Public release level</entry>
969 <entry>string</entry>
970 <entry>Internal revision-control level.</entry>
973 <entry>proto_major</entry>
975 <entry>numeric</entry>
976 <entry>API major revision level..</entry>
979 <entry>proto_minor</entry>
981 <entry>numeric</entry>
982 <entry>API minor revision level..</entry>
988 <para>The daemon ships a VERSION response to each client when the
989 client first connects to it.</para>
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>
994 <para>Here's an example:</para>
997 {"class":"VERSION","version":"2.40dev","rev":"06f62e14eae9886cde907dae61c124c53eb1101f","proto_major":3,"proto_minor":1}
1005 <term>?DEVICES;</term>
1006 <listitem><para>Returns a device list object with the
1007 following elements:</para>
1009 <table frame="all" pgwide="0"><title>DEVICES object</title>
1010 <tgroup cols="3" align="left" colsep="1" rowsep="1">
1014 <entry>Always?</entry>
1016 <entry>Description</entry>
1021 <entry>class</entry>
1023 <entry>string</entry>
1024 <entry>Fixed: "DEVICES"</entry>
1027 <entry>devices</entry>
1030 <entry>List of device descriptions</entry>
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>
1039 <para>Here's an example:</para>
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"}]}
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>
1056 <term>?WATCH;</term>
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
1065 <para>A WATCH object has the following elements:</para>
1067 <table frame="all" pgwide="0"><title>WATCH object</title>
1068 <tgroup cols="4" align="left" colsep="1" rowsep="1">
1072 <entry>Always?</entry>
1074 <entry>Description</entry>
1079 <entry>class</entry>
1081 <entry>string</entry>
1082 <entry>Fixed: "WATCH"</entry>
1085 <entry>enable</entry>
1087 <entry>boolean</entry>
1088 <entry>Enable (true) or disable (false) watcher mode. Default
1094 <entry>boolean</entry>
1095 <entry>Enable (true) or disable (false) dumping of JSON reports.
1096 Default is false.</entry>
1101 <entry>boolean</entry>
1102 <entry>Enable (true) or disable (false) dumping of binary
1103 packets as pseudo-NMEA. Default
1109 <entry>integer</entry>
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>
1118 <entry>scaled</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>
1125 <entry>device</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>
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>
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>
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>
1147 <para>Here's an example:</para>
1150 {"class":"WATCH", "raw":1,"scaled":true}
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>
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)
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>
1177 <table frame="all" pgwide="0"><title>POLL object</title>
1178 <tgroup cols="3" align="left" colsep="1" rowsep="1">
1182 <entry>Always?</entry>
1184 <entry>Description</entry>
1189 <entry>class</entry>
1191 <entry>string</entry>
1192 <entry>Fixed: "POLL"</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>
1202 <entry>active</entry>
1204 <entry>Numeric</entry>
1205 <entry>Count of active devices.</entry>
1208 <entry>fixes</entry>
1210 <entry>JSON array</entry>
1211 <entry>Comma-separated list of TPV objects.</entry>
1214 <entry>skyviews</entry>
1216 <entry>JSON array</entry>
1217 <entry>Comma-separated list of SKY objects.</entry>
1223 <para>Here's an example of a POLL response:</para>
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}
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>
1256 <term>?DEVICE</term>
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>
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>
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>
1280 <para>A DEVICE object has the following elements:</para>
1282 <table frame="all" pgwide="0"><title>CONFIGCHAN object</title>
1283 <tgroup cols="4" align="left" colsep="1" rowsep="1">
1287 <entry>Always?</entry>
1289 <entry>Description</entry>
1294 <entry>class</entry>
1296 <entry>string</entry>
1297 <entry>Fixed: "DEVICE"</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>
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>
1316 <entry>flags</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>
1326 <entry>driver</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>
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>
1343 <entry>integer</entry>
1344 <entry>Device speed in bits per second.</entry>
1347 <entry>parity</entry>
1349 <entry>string</entry>
1350 <entry><para>N, O or E for no parity, odd, or even.</para></entry>
1353 <entry>stopbits</entry>
1355 <entry>string</entry>
1356 <entry><para>Stop bits (1 or 2).</para></entry>
1359 <entry>native</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>
1368 <entry>cycle</entry>
1371 <entry>Device cycle time in seconds.</entry>
1374 <entry>mincycle</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>
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>
1388 <para>The contents of the flags field should be interpreted as follows:</para>
1390 <table frame="all" pgwide="0"><title>Device flags</title>
1391 <tgroup cols="3" align="left" colsep="1" rowsep="1">
1394 <entry>C #define</entry>
1395 <entry>Value</entry>
1396 <entry>Description</entry>
1401 <entry>SEEN_GPS</entry>
1403 <entry>GPS data has been seen on this device</entry>
1406 <entry>SEEN_RTCM2</entry>
1408 <entry>RTCM2 data has been seen on this device</entry>
1411 <entry>SEEN_RTCM3</entry>
1413 <entry>RTCM3 data has been seen on this device</entry>
1416 <entry>SEEN_AIS</entry>
1418 <entry>AIS data has been seen on this device</entry>
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>
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>
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) =
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>
1454 <para>Here's an example:</para>
1457 {"class":"DEVICE", "speed":4800,"serialmode":"8N1","native":0}
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
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>
1472 <para>Here's an example:</para>
1475 {"class":"DEVICE","path":"/dev/pts1","activated":0}
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>
1482 <table frame="all" pgwide="0"><title>ERROR notification object</title>
1483 <tgroup cols="4" align="left" colsep="1" rowsep="1">
1487 <entry>Always?</entry>
1489 <entry>Description</entry>
1494 <entry>class</entry>
1496 <entry>string</entry>
1497 <entry>Fixed: "ERROR"</entry>
1500 <entry>message</entry>
1502 <entry>string</entry>
1503 <entry>Textual error message</entry>
1509 <para>Here's an example:</para>
1512 {"class":"ERROR","message":"Unrecognized request '?FOO'"}
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>
1519 <refsect1 id='ais-rtcm'><title>AIS AND RTCM DUMP FORMATS</title>
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>
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>
1535 <para>RTCM2 corrections are dumped in the JSON format described in
1536 <citerefentry><refentrytitle>rtcm104</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
1539 <refsect1 id='devices'><title>GPS DEVICE MANAGEMENT</title>
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
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>
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>
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
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>
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>
1579 <para>To send a binary control string to a specified device, write to the
1580 control socket a '&', followed by the device name, followed by '=',
1581 followed by the control string in paired hex digits.</para>
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
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>
1598 <refsect1 id='accuracy'><title>ACCURACY</title>
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>
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>
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>
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
1632 <para>The time reporting of the GPS system itself has an intrinsic
1633 accuracy limit of 0.000,000,340 =
1634 3.4×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>
1644 <refsect1 id='ntp'><title>USE WITH NTP</title>
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>
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>
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>
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>
1678 server 127.127.28.0 minpoll 4 maxpoll 4
1679 fudge 127.127.28.0 time1 0.420 refid GPS
1681 server 127.127.28.1 minpoll 4 maxpoll 4 prefer
1682 fudge 127.127.28.1 refid GPS1
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
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>
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
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
1710 <para>If you are running PPS then it will look like this:</para>
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
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>
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>
1737 <refsect1 id='dbus'><title>USE WITH D-BUS</title>
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>
1746 <refsect1 id='security'><title>SECURITY AND PERMISSIONS ISSUES</title>
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>
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 — or, if that device doesn't exist,
1760 to the group of <filename>/dev/ttyS0</filename>.</para>
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>
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>
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>
1789 <refsect1 id='limitations'><title>LIMITATIONS</title>
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>
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>
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>
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>
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>
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>
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>
1834 <refsect1 id='files'><title>FILES</title>
1838 <term><filename>/dev/ttyS0</filename></term>
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
1848 <term><filename>/usr/share/gpsd/dgpsip-servers</filename></term>
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>
1863 <refsect1 id='standards'><title>APPLICABLE STANDARDS</title>
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>
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>
1883 <para>Note that <application>gpsd</application> JSON returns pure decimal
1884 degrees, not the hybrid degree/minute format described in the NMEA
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>
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>
1902 <refsect1 id='see_also'><title>SEE ALSO</title>
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>.
1915 <refsect1 id='maintainer'><title>AUTHORS</title>
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>