1GPSD(8) GPSD(8)
2
6 gpsd - interface daemon for GPS receivers
7
9 gpsd [-f GPS-devicename] [-F control-socket] [-S listener-port] [-b]
10 [-n] [-N] [-h] [-P pidfile] [-D debuglevel] [-V]
11 [[source-name]...]
12
15 gpsd is a monitor daemon that watches a TCP/IP port (2947 by default),
16 waiting for applications to request information from GPSes or differen‐
17 tial-GPS radios attached to the host machine. Each GPS or radio is ex‐
18 pected to be direct-connected to the host via a USB or RS232C serial
19 port. The port may be specified to gpsd at startup, or it may be set
20 via a command shipped down a local control socket (e.g. by a USB hot‐
21 plug script). Given a GPS device by either means, gpsd discovers the
22 correct port speed and protocol for it.
23 gpsd should be able to query any GPS that speaks either the standard
26 textual NMEA 0183 protocol, or the binary Rockwell protocol used by
27 EarthMate and some other GPSes, the TSIP binary protocol used by Trim‐
28 ble GPSes, or the binary SiRF protocol used by SiRFstar chipsets, or
29 the Garmin binary protocol used by the USB version of the Garmin 18 and
30 other Garmin USB GPSes, or the binary protocol used by Evermore
31 chipsets, or the extended NMEA used by iTrax. gpsd effectively hides
32 the differences among these. It also knows about and uses commands that
33 tune the GPS for lower latency, decreased bandwidth usage, or increased
34 accuracy on the San Jose Navigation FV18, the Sony CXD2951, the uBlox,
35 and the Motorola OnCore GT+. It can read heading and attitude informa‐
36 tion from the True North Technologies Revolution 2X Digital compass.
37 gpsd can use differential-GPS corrections from a DGPS radio or over the
40 net, from a ground station running a DGPSIP server or a Ntrip broad‐
41 caster that reports RTCM-S104 data; this will improve user error by
42 roughly a factor of four. When gpsd opens a serial device emitting
43 RTCM-104, it automatically recognizes this and uses the device as a
44 correction source for all connected GPSes. See [xref to refsect1] and
45 [xref to refsect1] for discussion.
46 The program accepts the following options:
49 -f Set a GPS device name. This option is deprecated and may be re‐
52 moved in a future version. Each command-line argument will be
53 treated as a device to be probed for the presence of a GPS;
54 that, rather than the -f option, is the preferred way of speci‐
55 fying GPS devices at startup.
56 -F Create a control socket for device addition and removal com‐
59 mands. You must specify a valid pathname on your local filesys‐
60 tem; this will be created as a Unix-domain socket to which you
61 can write commands that edit the daemon's internal device list.
62 -S Set TCP/IP port on which to listen for GPSD clients (default is
65 2947).
66 -d This is a deprecated option which takes a differential-GPS
69 source as argument. See the description of argument interpreta‐
70 tion below.
71 -b Broken-device-safety, otherwise known as read-only mode. Some
74 popular bluetooth and USB receivers lock up or become totally
75 inaccessible when probed or reconfigured. This switch prevents
76 gpsd from writing to a receiver. This means that gpsd cannot
77 configure the receiver for optimal performance, but it also
78 means that gpsd cannot break the receiver. A better solution
79 would be for bluetooth to not be so fragile. A platform indepen‐
80 dent method to identify serial-over-bluetooth devices would also
81 be nice.
82 -n Don't wait for a client to connect before polling whatever GPS
85 is associated with it. The wait is a feature; many serial GPSes
86 go to a standby mode (not drawing power) before the host machine
87 asserts DTR, so waiting for the first actual request can save
88 valuable battery power on portable equipment. This option com‐
89 bines well with -D2 to enable monitoring of the GPS data stream.
90 -N Don't daemonize; run in foreground. Also suppresses privi‐
93 lege-dropping. This switch is mainly useful for debugging. Its
94 meaning may change in future versions.
95 -h Display help message and terminate.
98 -P Specify the name and path to record the daemon's process ID.
101 -D Set debug level. At debug levels 2 and above, gpsd reports in‐
104 coming sentence and actions to standard error if gpsd is in the
105 foreground (-N) or to syslog if in the background.
106 -V Dump version and exit.
109 Arguments are interpreted as the names of data sources. Normally, a da‐
112 ta source is the name of a local serial device from which the daemon
113 may expect GPS data.
114 A data source name may also be a URL pointing to a specific differen‐
117 tial-GPS service (DGPSIP server or Ntrip broadcaster).If the URL starts
118 with "ntrip://" Ntrip will be used; if the URL starts with "dgpsip://",
119 DGPSIP will be used. Gpsd also defaults to DGPSIP if no protocol is de‐
120 fined. For Ntrip services that require authentication, a prefix of the
121 form "username:password@" can be added before the name of the Ntrip
122 broadcaster. If a suffix of the service name begins with ":" it is in‐
123 terpreted as a port number, overriding the default IANA-assigned port
124 of 2101. For Ntrip service you also need to specify which stream to
125 use; the stream is given in the form "/streamname". So, an example DGP‐
126 SIP URL could be "dgpsip://dgpsip.example.com" and a Ntrip URL could be
127 "ntrip://foo:bar@ntrip.example.com:80/example-stream".
128 Internally, the daemon maintains a device list holding the pathnames of
131 GPSes known to the daemon. Initially, this list is the list of de‐
132 vice-name arguments specified on the command line. That list may be
133 empty, in which case the daemon will have no devices on its search list
134 until they are added by a control-socket command (see [xref to ref‐
135 sect1] for details on this). Daemon startup will abort with an error if
136 neither any devices nor a control socket are specified.
137 At any given time, each client will be listening to only one of the
140 GPSes on the device list. By default, a client's device is the one that
141 most recently shipped information to the daemon at the time the client
142 first requests GPS information (that is, issues any command other than
143 F, K, W=0 or R=0).
144 The request protocol for gpsd clients is very simple. Each request nor‐
147 mally consists of a single ASCII character followed by a newline. Case
148 of the request character is ignored. Each request returns a line of re‐
149 sponse text ended by a CR/LF. Requests and responses are as follows,
150 with %f standing for a decimal float numeral and %d for decimal integer
151 numeral:
152 a The current altitude as "A=%f", meters above mean sea level.
155 b The B command with no argument returns four fields giving the
158 parameters of the serial link to the GPS as "B=%d %d %c %d";
159 baud rate, byte size, parity, (N, O or E for no parity, odd, or
160 even) and stop bits (1 or 2). The command "B=%d" sets the baud
161 rate, not changing parity or stop bits; watch the response, be‐
162 cause it is possible for this to fail if the GPS does not sup‐
163 port a speed-switching command. In case of failure, the daemon
164 and GPS will continue to communicate at the old speed. The B=
165 form is rejected if more than one client is attached to the
166 channel.
167 c C with no following = asks the daemon to return the cycle time
170 of the attached GPS, if any. If there is no attached device it
171 will return "C=?".
172 If the driver has the capability to change sampling rate the
174 command "C=%f" does so, setting a new cycle time in seconds. The
175 "C=" form is rejected if more than one client is attached to the
176 channel.
177 If the driver has the capability to change sampling rate, this
179 command always returns "C=%f %f" giving the current cycle time
180 in seconds and the minimum possible cycle time at the current
181 baud rate. If the driver does not have the capability to change
182 sampling rate, this returns, as "C=%f", the cycle time in sec‐
183 onds only.
184 Either number may be fractional, indicating a GPS cycle shorter
186 than a second; however, if >1 the cycle time must be a whole
187 number. Also note that relatively few GPSes have the ability to
188 set sub-second cycle times; consult your hardware protocol de‐
189 scription to make sure this works.
190 This command will return "C=?" at start of session, before the
192 first full packet has been received from the GPS, because the
193 GPS type is not yet known. To set up conditions for a real an‐
194 swer, issue it after some command that reads position/veloci‐
195 ty/time information from the device.
196 d Returns the UTC time in the ISO 8601 format,
199 "D=yyyy-mm-ddThh:nmm:ss.ssZ". Digits of precision in the frac‐
200 tional-seconds part will vary and may be absent.
201 e Returns "E=%f %f %f": three estimated position errors in meters
204 -- total, horizontal, and vertical (95% confidence level). Note:
205 many GPSes do not supply these numbers. When the GPS does not
206 supply them, gpsd computes them from satellite DOP using fixed
207 figures for expected non-DGPS and DGPS range errors in meters. A
208 value of '?' for any of these numbers should be taken to mean
209 that component of DOP is not available. See also the 'q' com‐
210 mand.
211 f Gets or sets the active GPS device name. The bare command 'f'
214 requests a response containing 'F=' followed by the name of the
215 active GPS device. The other form of the command is 'f=', in
216 which case all following printable characters up to but not in‐
217 cluding the next CR/LF are interpreted as the name of a trial
218 GPS device. If the trial device is in gpsd's device list, it is
219 opened and read to see if a GPS can be found there. If it can,
220 the trial device becomes the active device for this client.
221 The 'f=' command may fail if the specified device name is not on
223 the daemon's device list. This device list is initialized with
224 the paths given on the command line, if any were specified. For
225 security reasons, ordinary clients cannot change this device
226 list; instead, this must be done via the daemon's local control
227 socket declared with the -F option.
228 Once an 'f=' command succeeds, the client is tied to the speci‐
230 fied device until the client disconnects.
231 Whether the command is 'f' or 'f=' or not, and whether it suc‐
233 ceeds or not, the response always lists the name of the client's
234 device.
235 (At protocol level 1, the F command failed if more than one
237 client was attached, and multiple devices were not supported.)
238 g With =, accepts a single argument which may have either of the
241 values 'gps' or 'rtcm104', with case ignored. This specifies the
242 type of information the client wants and forces a device assign‐
243 ment. Without =, forces a device assignment but doesn't force
244 the type. This command is optional; if it is not given, the
245 client will be bound to whatever available device the daemon
246 finds first.
247 This command returns either '?' if no device of the specified
249 type(s) could be assigned, otherwise a string ('GPS' or
250 'RTCM104') identifying the kind of information the attached de‐
251 vice returns.
252 i Returns a text string identifying the GPS. The string may con‐
255 tain spaces and is terminated by CR-LF. This command will return
256 '?' at start of session, before the first full packet has been
257 received from the GPS, because its type is not yet known.
258 j Get or set buffering policy; this only matters for NMEA devices
261 which report fix data in several separate sentences during the
262 poll cycle (and in particular it doesn't matter for SiRF chips).
263 The default (j=0) is to clear all fix data at the start of each
264 poll cycle, so until the sentence that reports a given piece of
265 data arrives queries will report ?. Setting j=1 will disable
266 this, retaining data from the previous cycle. This is a per-us‐
267 er-channel bit, not a per-device one. The j=0 setting is hy‐
268 per-correct and never displays stale data, but may produce a
269 jittery display; the j=1 setting allows stale data but smooths
270 the display.
271 (At protocol level below 3, there was no J command. Note, this
273 command is experimental and its semantics are subject to
274 change.)
275 k Returns a line consisting of "K=" followed by an integer count
278 of of all GPS devices known to gpsd, followed by a space, fol‐
279 lowed by a space-separated list of the device names. This com‐
280 mand lists devices the daemon has been pointed at by the com‐
281 mand-line argument(s) or an add command via its control socket,
282 and has successfully recognized as GPSes. Because GPSes might be
283 unplugged at any time, the presence of a name in this list does
284 not guarantee that the device is available.
285 (At protocol level 1, there was no K command.)
287 l Returns three fields: a protocol revision number, the gpsd ver‐
290 sion, and a list of accepted request letters.
291 m The NMEA mode as "M=%d". 0=no mode value yet seen, 1=no fix,
294 2=2D (no altitude), 3=3D (with altitude).
295 n Get or set the GPS driver mode. Without argument, reports the
298 mode as "N=%d"; N=0 means NMEA mode and N=1 means alternate mode
299 (binary if it has one, for SiRF and Evermore chipsets in partic‐
300 ular). With argument, set the mode if possible; the new mode
301 will be reported in the response. The "N=" form is rejected if
302 more than one client is attached to the channel.
303 o Attempts to return a complete time/position/velocity report as a
306 unit. Any field for which data is not available being reported
307 as ?. If there is no fix, the response is simply "O=?", other‐
308 wise a tag and timestamp are always reported. Fields are as fol‐
309 lows, in order:
310 tag A tag identifying the last sentence received. For NMEA
314 devices this is just the NMEA sentence name; the talk‐
315 er-ID portion may be useful for distinguishing among re‐
316 sults produced by different NMEA talkers in the same
317 wire.
318 timestamp
321 Seconds since the Unix epoch, UTC. May have a fractional
322 part of up to .01sec precision.
323 time error
326 Estimated timestamp error (%f, seconds, 95% confidence).
327 latitude
330 Latitude as in the P report (%f, degrees).
331 longitude
334 Longitude as in the P report (%f, degrees).
335 altitude
338 Altitude as in the A report (%f, meters). If the mode
339 field is not 3 this is an estimate and should be treated
340 as unreliable.
341 horizontal error estimate
344 Horizontal error estimate as in the E report (%f, me‐
345 ters).
346 vertical error estimate
349 Vertical error estimate as in the E report (%f, meters).
350 course over ground
353 Track as in the T report (%f, degrees).
354 speed over ground
357 Speed (%f, meters/sec). Note: older versions of the O
358 command reported this field in knots.
359 climb/sink
362 Vertical velocity as in the U report (%f, meters/sec).
363 estimated error in course over ground
366 Error estimate for course (%f, degrees, 95% confidence).
367 estimated error in speed over ground
370 Error estimate for speed (%f, meters/sec, 95% confi‐
371 dence). Note: older experimental versions of the O com‐
372 mand reported this field in knots.
373 estimated error in climb/sink
376 Estimated error for climb/sink (%f, meters/sec, 95% con‐
377 fidence).
378 mode The NMEA mode (%d, ?=no mode value yet seen, 1=no fix,
381 2=2D, 3=3D). (This field was not reported at protocol
382 levels 2 and lower.)
383 p Returns the current position in the form "P=%f %f"; numbers are
386 in degrees, latitude first.
387 q Returns "Q=%d %f %f %f %f %f": a count of satellites used in the
390 last fix, and five dimensionless dilution-of-precision (DOP)
391 numbers -- spherical, horizontal, vertical, time, and total geo‐
392 metric. These are computed from the satellite geometry; they are
393 factors by which to multiply the estimated UERE (user error in
394 meters at specified confidence level due to ionospheric delay,
395 multipath reception, etc.) to get actual circular error ranges
396 in meters (or seconds) at the same confidence level. See also
397 the 'e' command. Note: Some GPSes may fail to report these, or
398 report only one of them (often HDOP); a value of 0.0 should be
399 taken as an indication that the data is not available.
400 Note: Older versions of gpsd reported only the first three DOP
402 numbers, omitting time DOP and total DOP.
403 r Sets or toggles 'raw' mode. Return "R=0" or "R=1" or "R=2". In
406 raw mode you read the NMEA data stream from each GPS. (Non-NMEA
407 GPSes get their communication format translated to NMEA on the
408 fly.) If the device is a source of RTCM-104 corrections, the
409 corrections are dumped in the textual format described in
410 rtcm104(5).
411 The command 'r' immediately followed by the digit '1' or the
413 plus sign '+' sets raw mode. The command 'r' immediately fol‐
414 lowed by the digit '2' sets super-raw mode; for non-NMEA (bina‐
415 ry) GPSes or RTCM-104 sources this dumps the raw binary packet.
416 The command 'r' followed by the digit '0' or the minus sign '-'
417 clears raw mode. The command 'r' with neither suffix toggles raw
418 mode.
419 Note: older versions of gpsd did not support super-raw mode.
421 s The NMEA status as "S=%d". 0=no fix, 1=fix, 2=DGPS-corrected
424 fix.
425 t Track made good; course "T=%f" in degrees from true north.
428 u Current rate of climb as "U=%f" in meters per second. Some GPSes
431 (not SiRF-based) do not report this, in that case gpsd computes
432 it using the altitude from the last fix (if available).
433 v The current speed over ground as "V=%f" in knots.
436 w Sets or toggles 'watcher' mode (see the description below). Re‐
439 turn "W=0" or "W=1".The command 'w' immediately followed by the
440 digit '1' or the plus sign '+' sets watcher mode. The command
441 'w' followed by the digit '0' or the minus sign '-' clears
442 watcher mode. The command 'w' with neither suffix toggles watch‐
443 er mode.
444 x Returns "X=0" if the GPS is offline, "X=%f" if online; in the
447 latter case, %f is a timestamp from when the last sentence was
448 received.
449 (At protocol level 1, the nonzero response was always 1.)
451 y Returns Y=, followed by a sentence tag, followed by a timestamp
454 (seconds since the Unix epoch, UTC) and a count not more than
455 12, followed by that many quintuples of satellite PRNs, eleva‐
456 tion/azimuth pairs (elevation an integer formatted as %d in
457 range 0-90, azimuth an integer formatted as %d in range 0-359),
458 signal strengths in decibels, and 1 or 0 according as the satel‐
459 lite was or was not used in the last fix. Each number is fol‐
460 lowed by one space.
461 (At protocol level 1, this response had no tag or timestamp.)
463 z The Z command returns daemon profiling information of interest
466 to gpsd developers. The format of this string is subject to
467 change without notice.
468 $ The $ command returns daemon profiling information of interest
471 to gpsd developers. The format of this string is subject to
472 change without notice.
473 Note that a response consisting of just ? following the = means that
476 there is no valid data available. This may mean either that the device
477 being queried is offline, or (for position/velocity/time queries) that
478 it is online but has no fix.
479 Requests can be concatenated and sent as a string; gpsd will then re‐
482 spond with a comma-separated list of replies.
483 Every gpsd reply will start with the string "GPSD" followed by the
486 replies. Examples:
487 query: "p\n"
490 reply: "GPSD,P=36.000000 123.000000\r\n"
491 query: "d\n"
493 reply: "GPSD,D=2002-11-16T02:45:05.12Z\r\n"
494 query: "va\n"
496 reply: "GPSD,V=0.000000,A=37.900000\r\n"
497 When clients are active but the GPS is not responding, gpsd will spin
500 trying to open the GPS device once per second. Thus, it can be left
501 running in background and survive having a GPS repeatedly unplugged and
502 plugged back in. When it is properly installed along with hotplug noti‐
503 fier scripts feeding it device-add commands, gpsd should require no
504 configuration or user action to find devices.
505 The recommended mode for clients is watcher mode. In watcher mode gpsd
508 ships a line of data to the client each time the GPS gets either a fix
509 update or a satellite picture, but rather than being raw NMEA the line
510 is a gpsd 'o' or 'y' response. Additionally, watching clients get noti‐
511 fications in the form X=0 or X=%f when the online/offline status of the
512 GPS changes, and an I response giving the device type when the user is
513 assigned a device.
514 Clients should be prepared for the possibility that additional fields
517 (such as heading or roll/pitch/yaw) may be added to the O command, and
518 not treat the occurrence of extra fields as an error. The protocol num‐
519 ber will be incremented if and when such fields are added.
520 Sending SIGHUP to a running gpsd forces it to close all GPSes and all
523 client connections. It will then attempt to reconnect to any GPSes on
524 its device list and resume listening for client connections. This may
525 be useful if your GPS enters a wedged or confused state but can be
526 soft-reset by pulling down DTR.
527
530 gpsd maintains an internal list of GPS devices. If you specify devices
531 on the command line, the list is initialized with those pathnames; oth‐
532 erwise the list starts empty. Commands to add and remove GPS device
533 paths from the daemon's device list must be written to a local Unix-do‐
534 main socket which will be accessible only to programs running as root.
535 This control socket will be located wherever the -F option specifies
536 it.
537 To point gpsd at a device that may be a GPS, write to the control sock‐
540 et a plus sign ('+') followed by the device name followed by LF or
541 CR-LF. Thus, to point the daemon at /dev/foo. send "+/dev/foo\n". To
542 tell the daemon that a device has been disconnected and is no longer
543 available, send a minus sign ('-') followed by the device name followed
544 by LF or CR-LF. Thus, to remove /dev/foo from the search list. send
545 "-/dev/foo\n".
546 To send a control string to a specified device, write to the control
549 socket a '!', followed by the device name, followed by '=', followed by
550 the control string.
551 Your client may await a response, which will be a line beginning with
554 either "OK" or "ERROR". An ERROR reponse to an add command means the
555 device did not emit data recognizable as GPS packets; an ERROR response
556 to a remove command means the specified device was not in gpsd's device
557 list. An ERROR response to a ! command means the daemon did not recog‐
558 nize the devicename specified.
559 The control socket is intended for use by hotplug scripts and other de‐
562 vice-discovery services. This control channel is separate from the pub‐
563 lic gpsd service port, and only locally accessible, in order to prevent
564 remote denial-of-service and spoofing attacks.
565
568 The base user error (UERE) of GPSes is 8 meters or less at 66% confi‐
569 dence, 15 meters or less at 95% confidence. Actual horizontal error
570 will be UERE times a dilution factor dependent on current satellite po‐
571 sition. Altitude determination is more sensitive to variability to at‐
572 mospheric signal lag than latitude/longitude, and is also subject to
573 errors in the estimation of local mean sea level; base error is 12 me‐
574 ters at 66% confidence, 23 meters at 95% confidence. Again, this will
575 be multiplied by a vertical dilution of precision (VDOP) dependent on
576 satellite geometry, and VDOP is typically larger than HDOP. Users
577 should not rely on GPS altitude for life-critical tasks such as landing
578 an airplane.
579 These errors are intrinsic to the design and physics of the GPS system.
582 gpsd does its internal computations at sufficient accuracy that it will
583 add no measurable position error of its own.
584 DGPS correction will reduce UERE from roughly 8 meters to roughly 2 me‐
587 ters, provided you are within about 100mi (160km) of a DGPS ground sta‐
588 tion.
589 On a 4800bps connection, the time latency of fixes provided by gpsd
592 will be one second or less 95% of the time. Most of this lag is due to
593 the fact that GPSes normally emit fixes once per second, thus expected
594 latency is 0.5sec. On the personal-computer hardware available in 2005,
595 computation lag induced by gpsd will be negligible, on the order of a
596 millisecond. Nevertheless, latency can introduce significant errors for
597 vehicles in motion; at 50km/h (31mi/h) of speed over ground, 1 second
598 of lag corresponds to 13.8 meters change in position between updates.
599
602 gpsd can provide reference clock information to ntpd, to keep the sys‐
603 tem clock synchronized to the time provided by the GPS receiver. This
604 facility is only available when the daemon is started from root. If
605 you're going to use gpsd you probably want to run it -n mode so the
606 clock will be updated even when no clients are active.
607 Note that deriving time from messages received from the GPS is not as
610 accurate as you might expect. Messages are often delayed in the receiv‐
611 er and on the link by several hundred milliseconds, and this delay is
612 not constant. On Linux, gpsd includes support for interpreting the PPS
613 pulses emitted at the start of every clock second on the carrier-detect
614 lines of some serial GPSes; this pulse can be used to update NTP at
615 much higher accuracy than message time provides. You can determine
616 whether your GPS emits this pulse by running at -D 5 and watching for
617 carrier-detect state change messages in the logfile. On OpenBSD gpsd
618 makes use of the nmea(4) line discipline and the tty(4) timestamping
619 facilities to export PPS time via the sensors framework. OpenBSD's ntpd
620 uses these sensors to adjust the hardware clock and frequency. To make
621 use of this feature, gpsd must be started as root so it can activate
622 the timestamping and line discipline; after attempting to set up PPS,
623 it will relinquish root privileges.
624 When gpsd receives a sentence with a timestamp, it packages the re‐
627 ceived timestamp with current local time and sends it to a shared-memo‐
628 ry segment with an ID known to ntpd, the network time synchronization
629 daemon. If ntpd has been properly configured to receive this message,
630 it will be used to correct the system clock.
631 Here is a sample ntp.conf configuration stanza telling ntpd how to read
634 the GPS notfications:
635 server 127.127.28.0 minpoll 4 maxpoll 4
638 fudge 127.127.28.0 time1 0.420 refid GPS
639 server 127.127.28.1 minpoll 4 maxpoll 4 prefer
641 fudge 127.127.28.1 refid GPS1
642 The magic pseudo-IP address 127.127.28.0 identifies unit 0 of the ntpd
646 shared-memory driver; 127.127.28.1 identifies unit 1. Unit 0 is used
647 for message-decoded time and unit 1 for the (more accurate, when avail‐
648 able) time derived from the PPS synchronization pulse. Splitting these
649 notifications allows ntpd to use its normal heuristics to weight them.
650 With this configuration, ntpd will read the timestamp posted by gpsd
653 every 16 seconds and send it to unit 0. The number after the parameter
654 time1 is an offset in seconds. You can use it to adjust out some of the
655 fixed delays in the system. 0.035 is a good starting value for the
656 Garmin GPS-18/USB, 0.420 for the Garmin GPS-18/LVC.
657 After restarting ntpd, a line similar to the one below should appear in
660 the output of the command "ntpq -p" (after allowing a couple of min‐
661 utes):
662 remote refid st t when poll reach delay off‐
665 set jitter
666 =========================================================================
667 +SHM(0) .GPS. 0 l 13 16 377 0.000 0.885
668 0.882
669 If you are running PPS then it will look like this:
672 remote refid st t when poll reach delay off‐
675 set jitter
676 =========================================================================
677 -SHM(0) .GPS. 0 l 13 16 377 0.000 0.885
678 0.882 *SHM(1) .GPS1. 0 l 11 16 377 0.000
679 -0.059 0.006
680 When the value under "reach" remains zero, check that gpsd is running;
683 and some application is connected to it or the '-n' option was used.
684 Make sure the receiver is locked on to at least one satellite, and the
685 receiver is in SiRF binary, Garmin binary or NMEA/PPS mode. Plain NMEA
686 will also drive ntpd, but the accuracy as bad as one second. When the
687 SHM(0) line does not appear at all, check the system logs for error
688 messages from ntpd.
689 When no other reference clocks appear in the NTP configuration, the
692 system clock will lock onto the GPS clock. When you have previously
693 used ntpd, and other reference clocks appear in your configuration,
694 there may be a fixed offset between the GPS clock and other clocks. The
695 gpsd developers would like to receive information about the offsets ob‐
696 served by users for each type of receiver. Please send us the output of
697 the "ntpq -p" command and the make and type of receiver.
698
701 On operating systems that support D-BUS, gpsd can be built to broadcast
702 GPS fixes to D-BUS-aware applications. As D-BUS is still at a pre-1.0
703 stage, we will not attempt to document this interface here. Read the
704 gpsd source code to learn more.
705
708 gpsd must start up as root in order to open the NTPD shared-memory seg‐
709 ment, open its logfile, and create its local control socket. Before do‐
710 ing any processing of GPS data, it tries to drop root privileges by
711 setting its UID to "nobody" (or another userid as set by configure) and
712 its group ID to the group of the initial GPS passed on the command line
713 -- or, if that device doesn't exist, to the group of /dev/ttyS0.
714 Privilege-dropping is a hedge against the possibility that carefully
717 crafted data, either presented from a client socket or from a subverted
718 serial device posing as a GPS, could be used to induce misbehavior in
719 the internals of gpsd. It ensures that any such compromises cannot be
720 used for privilege elevation to root.
721 The assumption behind gpsd's particular behavior is that all the tty
724 devices to which a GPS might be connected are owned by the same
725 non-root group and allow group read/write, though the group may vary
726 because of distribution-specific or local administrative practice. If
727 this assumption is false, gpsd may not be able to open GPS devices in
728 order to read them (such failures will be logged).
729 In order to fend off inadvertent denial-of-service attacks by port
732 scanners (not to mention deliberate ones), gpsd will time out inactive
733 client connections. Before the client has issued a command that re‐
734 quests a channel assignment, a short timeout (60 seconds) applies.
735 There is no timeout for clients in watcher or raw modes; rather, gpsd
736 drops these clients if they fail to read data long enough for the out‐
737 bound socket write buffer to fill. Clients with an assigned device in
738 polling mode are subject to a longer timeout (15 minutes).
739
742 If multiple NMEA talkers are feeding RMC, GLL, and GGA sentences to the
743 same serial device (possible with an RS422 adapter hooked up to some
744 marine-navigation systems), an 'O' response may mix an altitude from
745 one device's GGA with latitude/longitude from another's RMC/GLL after
746 the second sentence has arrived.
747 gpsd may change control settings on your GPS (such as the emission fre‐
750 quency of various sentences or packets) and not restore the original
751 settings on exit. This is a result of inadequacies in NMEA and the ven‐
752 dor binary GPS protocols, which often do not give clients any way to
753 query the values of control settings in order to be able to restore
754 them later.
755 If your GPS uses a SiRF chipset at firmware level 231, and it is after
758 31 May 2007, reported UTC time may be off by the difference between 13
759 seconds and whatever leap-second correction is currently applicable,
760 from startup until complete subframe information is received (normally
761 about six seconds). Firmware levels 232 and up don't have this problem.
762 You may run gpsd at debug level 4 to see the chipset type and firmware
763 revision level.
764 When using SiRF chips, the VDOP/TDOP/GDOP figures and associated error
767 estimates are computed by gpsd rather than reported by the chip. The
768 computation does not exactly match what SiRF chips do internally, which
769 includes some satellite weighting using parameters gpsd cannot see.
770 Autobauding on the Trimble GPSes can take as long as 5 seconds if the
773 device speed is not matched to the GPS speed.
774 If you are using an NMEA-only GPS (that is, not using SiRF or Garmin or
777 Zodiac binary mode) and the GPS does not emit GPZDA at the start of its
778 update cycle (which most consumer-grade NMEA GPSes do not) and it is
779 after 2099, then the century part of the dates gpsd delivers will be
780 wrong.
781
784 /dev/ttyS0
785 Prototype TTY device. After startup, gpsd sets its group ID to
786 the owner of this device if no GPS device was specified on the
787 command line does not exist.
788
791 The official NMEA protocol standard is available on paper from the Na‐
792 tional Marine Electronics Association: http://www.nmea.org/pub/0183/,
793 but is proprietary and expensive; the maintainers of gpsd have made a
794 point of not looking at it. The GPSD website: http://gpsd.berlios.de/
795 links to several documents that collect publicly disclosed information
796 about the protocol.
797 gpsd parses the following NMEA sentences: RMC, GGA, GLL, GSA, GSV, VTG,
800 ZDA. It recognizes these with either the normal GP talker-ID prefix, or
801 with the II prefix emitted by Seahawk Autohelm marine navigation sys‐
802 tems, or with the IN prefix emitted by some Garmin units. It recognizes
803 one vendor extension, the PGRME emitted by some Garmin GPS models.
804 Note that gpsd returns pure decimal degrees, not the hybrid de‐
807 gree/minute format described in the NMEA standard.
808
811 gps(1), libgps(3), libgpsd(3), gpsprof(1), gpsfake(1), gpsctl(1), gp‐
812 scat(1), rtcm-104(5).
813
816 Remco Treffcorn, Derrick Brashear, Russ Nelson, Eric S. Raymond, Chris
817 Kuethe. This manual page by Eric S. Raymond <esr@thyrsus.com>. There is
818 a project site at here: http://gpsd.berlios.de/.
819 GPSD(8)