summaryrefslogtreecommitdiff
path: root/gpsd.xml
blob: e03d286ca8b786d18a8b39f768c01f6f50ea6b7d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC 
   "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "docbook/docbookx.dtd" [
<!ENTITY gpsdsock         "/var/run/gpsd.sock">
]>
<refentry id='gpsd.8'>
<refmeta>
<refentrytitle>gpsd</refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo class='date'>9 Aug 2004</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>gpsd</refname>
<refpurpose>interface daemon for GPS receivers</refpurpose>
</refnamediv>
<refsynopsisdiv id='synopsis'>

<cmdsynopsis>
  <command>gpsd</command>  
      <arg choice='opt'>-f <replaceable>GPS-devicename</replaceable></arg>
      <arg choice='opt'>-S <replaceable>listener-port</replaceable></arg>
      <arg choice='opt'>-d <replaceable>DGPS-server</replaceable></arg>
      <arg choice='opt'>-n </arg>      
      <arg choice='opt'>-N </arg>      
      <arg choice='opt'>-h </arg>
      <arg choice='opt'>-P <replaceable>pidfile</replaceable></arg>
      <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg>
      <arg choice='opt'>-v </arg>
</cmdsynopsis>
</refsynopsisdiv>

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

<para><application>gpsd</application> is a monitor daemon that watches
a TCP/IP port (2947 by default), waiting for applications to request
location information from GPS devices attached to the host machine.
Each GPS is expected to be direct-connected to the host via a USB or
RS232C serial port.  The port may be specified to gpsd at startup, or
it may be set via a command shipped down the client socket (e.g. by a
USB hotplug script). Given a GPS device by either means,
<application>gpsd</application> discovers the correct port speed and
protocol for it.</para>

<para><application>gpsd</application> should be able to query any GPS
that speaks either the standard textual NMEA 0183 protocol, or the
binary Rockwell protocol used by EarthMate and some other GPSes, or
the binary SiRF protocol used by SiRf-II and SiRF-Star chipsets, or
the Garmin binary protocol used by the USB version of the Garmin 18
and other Garmin USB GPSes. <application>gpsd</application>
effectively hides the differences among these.</para>

<para>Optionally, <application>gpsd</application> may get
differential-GPS corrections from a ground station running a RTCM-S104
server; this will improve user error by roughly a factor of four.
See <xref linkend='accuracy'/> for discussion.</para>

<para>The program accepts the following options:</para>
<variablelist remap='TP'>
<varlistentry>
<term>-f</term>
<listitem>
<para>Set a GPS device name (default is <filename>/dev/gps</filename>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-S</term>
<listitem><para>Set TCP/IP port (default is 2947).</para></listitem>
</varlistentry>
<varlistentry>
<term>-d</term>
<listitem>
<para>Query a differential-GPS (DGPS) server.  If a suffix of the
server name begins with ":" it is interpreted as a port number,
overriding the default IANA-assigned port of 2101.
For DGPS servers available for use with this option, see
<ulink url='http://www.wsrcc.com/wolfgang/gps/dgps-ip.html'>
DGPS corrections over the Internet</ulink>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-n</term>
<listitem><para>Don't wait for a client to connect before polling
the GPS.  The wait is a feature; many serial GPSes go to a standby
mode (not drawing power) before the host machine asserts DTR, so
waiting for the first actual request can save valuable battery power
on portable equipment.  This option combines well with -D2 to enable
monitoring of the GPS data stream.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-N</term>
<listitem><para>Don't daemonize; run in foreground. Mainly useful
for debugging.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-h</term>
<listitem><para>Display help message and terminate.</para></listitem>
</varlistentry>
<varlistentry>
<term>-P</term>
<listitem>
<para>Specify the name and path to record the daemon's process ID.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-D</term>
<listitem>
<para>Set debug level. At debug levels 2 and above,
<application>gpsd</application> reports incoming sentence and actions
to standard error.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-v</term>
<listitem>
<para>Dump version and exit.</para>
</listitem>
</varlistentry>
</variablelist>

<para>At any given time, each client will be listening to only one of
the GPSes known to the daemon.  By default, a client's device is the
one most recently on-line at the time the client connects.  A client
may use the 'F' command to specify a device to listen to.</para>

<para>The 'F' command fails if the specified device name is not on the
daemon's internal search list.  This search list is initialized with
<filename>/dev/gps</filename> or the path given in the -f command-line
option if that was specified.  For security reasons, ordinary clients
cannot change this search list; instead, this must be done via the
daemon's local control socket.</para>

<para>The request protocol for <application>gpsd</application> clients
is very simple.  Each request normally consists of a single ASCII
character followed by a newline.  Case of the request character is
ignored, Each request returns a line of response text ended by a
CR/LF.  Requests and responses are as follows, with %f standing for a
decimal float numeral and %d for decimal integer numeral:</para>

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

<varlistentry>
<term>b</term>

<listitem><para>The B command with no argument returns four fields
giving the parameters of the serial link to the GPS as "B=%d %d %c
%d"; baud rate, byte size, parity, (currently always N) and stop bits
(1 or 2).  The command "B=%d" sets the baud rate, not changing parity
or stop bits; watch the response, because it is possible for this to
fail if the GPS does not support a speed-switching command.  In case
of failure, the daemon and GPS will continue to communicate at the
old speed.</para></listitem>
</varlistentry>

<varlistentry>
<term>c</term>
<listitem><para>Returns, as "C=%d", the cycle time of updates
in seconds.</para></listitem>
</varlistentry>

<varlistentry>
<term>d</term>
<listitem><para>Returns the UTC time in the ISO 8601 format,
"D=yyyy-mm-ddThh:nmm:ss.ssZ". Digits of precision in the fractional-seconds
part will vary and may be zero.</para></listitem>
</varlistentry>

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

<varlistentry>
<term>f</term> 
<listitem><para>Gets or sets the active GPS device name. The bare
command 'f' requests a response containing 'f=' followed by the name
of the active GPS device.  The command may be followed by an '=', in
which case all following printable characters up to but not including
the next CR/LF are interpreted as the name of a trial GPS device. If
the trial device is in <application>gpsd</application>'s device list,
it is opened and read to see if a GPS can be found there.  If it can,
the trial device becomes the active device for this client.  The
response to this form of the command is to list the name of the active
device.</para>

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

<varlistentry>
<term>i</term>
<listitem><para>Returns a text string identifying the GPS.  The string
may contain spaces and is terminated by CR-LF.</para></listitem>
</varlistentry>

<varlistentry>
<term>k</term>
<listitem><para>Returns a line consisting of "K=" followed by a
space-separated list of all GPS devices known to
<application>gpsd</application> (that is, devices it has been pointed
at by the command-line -f argument or an F command and has
successfully recognized as GPSes).  Note that the fact that a
devicename appears in this list does not guarantee that a GPS is
connected to it and active.</para>

<para>(At protocol level 1, there was no K command.)</para> 
</listitem>
</varlistentry>

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

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

<varlistentry>
<term>n</term>
<listitem><para>Get or set the the GPS driver mode.  Without argument,
reports the mode as "N=%d"; N=0 means NMEA mode and N=1
means alternate mode (binary if it has one, for SiRF chipsets in
particular).  With argument, set the mode if possible; the new mode
will be reported in the response.
</para></listitem>
</varlistentry>

<varlistentry>
<term>o</term>
<listitem>
<para>Attempts to return a complete time/position/velocity report as a
unit.  Any field for which data is not available being reported as ?.
If there is no fix, the response is simply "O=?", otherwise a tag and
timestamp are always reported.  Fields are as follows, in order:</para>

<variablelist>
<varlistentry>
<term>tag</term> <listitem><para>A tag identifying the last sentence
received.  For NMEA devices this is just the NMEA sentence name; the
talker-ID portion may be useful for distinguishing among results
produced by different NMEA talkers in the same wire.</para></listitem>
</varlistentry>

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

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

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

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

<varlistentry>
<term>altitude</term>
<listitem><para>Altitude as in the A report (%f, meters).</para></listitem>
</varlistentry>

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

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

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

<varlistentry>
<term>speed over ground</term>
<listitem><para>Speed as in the V report (%f, knots).</para></listitem>
</varlistentry>

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

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

<varlistentry>
<term>estimated error in speed over ground</term>
<listitem><para>Error estimate for speed (%f, knots).</para></listitem>
</varlistentry>

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

</variablelist>

<para>Note: this command is experimental and still under development.</para>
</listitem>
</varlistentry>

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

<varlistentry>
<term>q</term>
<listitem>
<para>Returns "Q=%d %f %f %f": a count of satellites used in the last
fix, and three dimensionless dilution-of-precision (DOP) numbers
&mdash; total, horizontal, and vertical.  These are computed from the
satellite geometry; they are factors by which to multiply the
estimated UERE (user error in meters at specified confidence level due
to ionospheric delay, multipath reception, etc.) to get actual
circular error ranges in meters at the same confidence level. See also
the 'e' command.  Note: Some GPSes may fail to report these, or report
only one of them (often HDOP); a value of 0.0 should be taken
as an indication that the data is not available.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>r</term>
<listitem><para>Sets or toggles 'raw' mode. Return "R=0" or "R=1". In
raw mode you read the NMEA data stream from the GPS. (Non-NMEA GPSes
get their communication format translated to NMEA on the fly.)  The
command 'r' immediately followed by the digit '1' or the plus sign '+'
sets raw mode.  The command 'r' followed by the digit '0' or the minus
sign '-' clears raw mode.  The command 'r' with neither suffix toggles
raw mode.</para></listitem>
</varlistentry>

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

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

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

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

<varlistentry>
<term>w</term>
<listitem><para>Sets or toggles 'watcher' mode (see the descroiption
below). Return "W=0" or "W=1".The command 'w' immediately followed by
the digit '1' or the plus sign '+' sets watcher mode.  The command 'w'
followed by the digit '0' or the minus sign '-' clears watcher mode.
The command 'w' with neither suffix toggles watcher
mode.</para></listitem>
</varlistentry>

<varlistentry>
<term>x</term>
<listitem><para>Returns "X=0" if the GPS is offline, "X=%f" if 
online; in the latter case, %f is a timestamp from when the 
last sentence was received.</para>

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

<varlistentry>
<term>y</term> 
<listitem>
<para>Returns Y= followed by a timestamp (seconds since the Unix
epoch, UTC) and a count not more than 12, followed by that many
quintuples of satellite PRNs, elevation/azimuth pairs (elevation an
integer formatted as %d in range 0-90, azimuth an integer formatted as
%d in range 0-359), signal strengths in decibels, and 1 or 0 according
as the satellite was or was not used in the last fix. Each number is
followed by one space.</para>

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

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

</variablelist>

<para>Note that a response consisting of just ? following the =
means that there is no valid data available.</para>

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

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

<screen>
      query:       "p\n"
      reply:       "GPSD,P=36.000000 123.000000\r\n"

      query:       "d\n"
      reply:       "GPSD,D=2002-11-16T02:45:05.12Z\r\n"

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

<para>When clients are active but the GPS is not responding,
<application>gpsd</application> will spin trying to open the GPS
device once per second.  Thus, it can be left running in background
and survive having a GPS repeatedly unplugged and plugged back
in.  When it is properly installed along with hotplug notifier
scripts feeding it device-add commands, <application>gpsd</application> 
should require no configuration or user action to find devices.</para>

<para>The commands to add and remove GPS device paths from the
daemon's internal search list cannot be sent over the socket from a
client.  Instead, they must be written to a local Unix-domain socket
which will be accessible only to programs running as root.  This
control socket will be located at <filename>&gpsdsock;</filename>.</para>

<para>To point <application>gpsd</application> at a device that may be
a GPS, write to the control socket a plus sign ('+') followed by the
device name followed by LF or CR-LF.  Thus, to point the daemon at
<filename>/dev/foo</filename>. send "+/dev/foo\n".  To tell the daemon
that a device has been disconnected and is no longer available, send a
minus sign ('-') followed by the device name followed by LF or
CR-LF. Thus, to remove <filename>/dev/foo</filename> from the search
list. send "-/dev/foo\n".</para>

<para>The recommended mode for clients is watcher mode.  In watcher
mode <application>gpsd</application> ships a line of data to the
client each time the GPS gets either a fix update or a satellite
picture, but rather than being raw NMEA the line is a gpsd 'o' or 'y'
response.  Additionally, watching clients get notifications in the
form X=0 or X=%f when the online/offline status of the GPS
changes.</para>

<para>Sending SIGHUP to a running <application>gpsd</application>
forces it to close the GPS and all client connections.  It will then
attempt to reconnect to the GPS and resume listening for client
connections.  This may be useful if your GPS enters a wedged or
confused state but can be soft-reset by pulling down DTR.</para>

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

<para>The base user error (UERE) of GPSes is 8 meters or less at 66%
confidence, 15 meters or less at 95% confidence.  Actual horizontal
error will be UERE times a dilution factor dependent on current
satellite position.  Altitude determination is more sensitive to
variability to atmospheric signal lag than latitude/longitude, and is
also subject to errors in the estimation of local mean sea level; base
error is 12 meters at 66% confidence, 23 meters at 95% confidence.
Again, this will be multiplied by a vertical dilution of precision
(VDOP) dependent on satellite geometry, and VDOP is typically larger
than HDOP.  Users should <emphasis>not</emphasis> rely on GPS altitude for
life-critical tasks such as landing an airplane.</para>

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

<para>DGPS correction will reduce UERE from roughly 8 meters to
roughly 2 meters, provided you are within 1000 kilometers or so of the
DGPS ground station.</para>

<para>On a 4800bps connection, the time latency of fixes provided by
<application>gpsd</application> will be one second or less 95% of the
time.  Most of this lag is due to the fact that GPSes normally emit
fixes once per second, thus expected latency is 0.5sec.  On the
personal-computer hardware available in 2005, computation lag induced
by <application>gpsd</application> will be negligible, on the order of
a millisecond.  Nevertheless, latency can introduce significant errors
for vehicles in motion; at 50km/h (31mi/h) of speed over ground, 1
second of lag corresponds to 13.8 meters change in position between
updates.</para>

<para>The driver for SiRF-II binary mode only has leap-second correction
for its timestamps as of 2005. It will not include any leap-second
corrections introduced after 1 Jan 2006.</para>

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

<para>gpsd can provide reference clock information to ntpd, to keep the system
clock synchronized to the time provided by the GPS receiver.  This is an
experimental feature, currently only working with SiRF-II and Garmin binary 
mode.  Making it work with other GPSes that report subsecond time resolution
may come later.</para>

<para>To use the time information, you first need to install and
configure ntp as usual.  The package manager and system
administration tools of the distribution you use may provide some
assistance with this.</para>

<para>When <application>gpsd</application> receives a sentence with a
timestamp, it packages the received timestamp with current local time
and sends it to a shared-memory segment with an ID known to
<application>ntpd</application>, the network time synchronization
daemon.  If <application>ntpd</application> has been properly
configured to receive this message, it will be used to correct the
system clock.</para>

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

<programlisting>
server 127.127.28.0 minpoll 4 maxpoll 4
fudge 127.127.28.0 time1 0.035 refid GPS
</programlisting>

<para>The magic pseudo-IP address 127.127.28.0 identifies unit 0 of
the <application>ntpd</application> shared-memory driver, which is
what <application>gpsd</application> writes to.  With this
configuration, <application>ntpd</application> will read the timestamp
posted by <application>gpsd</application> every 16 seconds.  The number
after the parameter time1 is an offset in seconds.  You can use it to
adjust out some of the fixed delays in the system.  0.035 is a good starting
value for the Garmin.</para>

<para>After restarting ntpd, a line similar to the one below should
appear in the output of the command "ntpq -p" (after allowing a couple
of minutes):</para>

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

<para>When the value under "reach" remains zero, check that gpsd is running and
some application is connected to it.  Make sure the receiver is locked on
to at least one satellite, and the receiver is in SiRF-II or Garmin binary 
mode.  When the SHM(0) line does not appear at all, check the system logs for 
error messages from ntpd.</para>
 
<para>When no other reference clocks appear in the NTP configuration,
the system clock will lock onto the GPS clock.  Because GPS clocks
only return 0.01sec resolution, <application>ntpd</application> is
unlikely to use this cue unless your system is off-net. When you have
previously used <application>ntpd</application>, and other reference
clocks appear in your configuration, there may be a fixed offset
between the GPS clock and other clocks.  The
<application>gpsd</application> developers would like to receive
information about the offsets observed by users for each type of
receiver.  Please send us the output of the "ntpq -p" command and the
make and type of receiver.</para>

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

<para>If multiple NMEA talkers are feeding RMC, GLL, and GGA sentences
to the same serial device (possible with an RS422 adapter hooked up to
some marine-navigation systems), an 'O' response may mix an altitude
from one device's GGA with latitude/longitude from another's RMC/GLL
after the second sentence has arrived.</para>

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

<variablelist>
<varlistentry>
<term><filename>/dev/gps</filename></term>
<listitem>
<para>Default path to a GPS device.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>&gpsdsock;</filename></term>
<listitem>
<para>Location of the control socket for device add/remove commands.</para>
</listitem>
</varlistentry>
</variablelist>

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

<para>The official NMEA protocol standard is available on paper from
the <ulink url='http://www.nmea.org/pub/0183/'>National Marine
Electronics Association</ulink>, but is proprietary and expensive; the
maintainers of <application>gpsd</application> have made a point of
not looking at it.  The <ulink url="http://gpsd.berlios.de/">GPSD
website</ulink> links to several documents that collect publicly
disclosed information about the protocol.</para>

<para><application>gpsd</application> parses the following NMEA
sentences: RMC, GLL, GGA, GSA, GSV, ZDA.  It recognizes these with
either the normal GP talker-ID prefix, or with the II prefix emitted
by Seahawk Autohelm marine navigation systems, or with the IN prefix
emitted by some Garmin units.  It recognizes one vendor extension,
PGRME.  Note that <application>gpsd</application> returns pure decimal
degrees, not the hybrid degree/minute format described in the NMEA
standard.</para>

</refsect1>
<refsect1 id='see_also'><title>SEE ALSO</title>
<para>
<citerefentry><refentrytitle>xgps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>
</refsect1>

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

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

</refentry>