1GPSD(8) GPSD Documentation GPSD(8)
2
6 gpsd - interface daemon for GPS receivers
7
9 gpsd [-F control-socket] [-S listener-port] [-b] [-l] [-G] [-n] [-N]
10 [-h] [-P pidfile] [-D debuglevel] [-V] [[source-name]...]
11
13 If you have a GPS attached on the lowest-numbered USB port of a Linux
14 system, and want to read reports from it on TCP/IP port 2947, it will
15 normally suffice to do this:
16 gpsd /dev/ttyUSB0
18 For the lowest-numbered serial port:
20 gpsd /dev/ttyS0
22 Change the device number as appropriate if you need to use a different
24 port. Command-line flags enable verbose logging, a control port, and
25 other optional extras but should not be needed for basic operation; the
26 one exception, on very badly designed hardware, might be -b (which
27 see).
28 On Linux systems supporting udev, gpsd is normally started
30 automatically when a USB plugin event fires (if it is not already
31 running) and is handed the name of the newly active device. In that
32 case no invocation is required at all.
33 For your initial tests set your GPS hardware to speak NMEA, as gpsd is
35 guaranteed to be able to process that. If your GPS has a native or
36 binary mode with better perfornance that gpsd knows how to speak, gpsd
37 will autoconfigure that mode.
38 You can verify correct operation by first starting gpsd and then xgps,
40 the X windows test client.
41 If you have problems, the GPSD project maintains a FAQ[1] to assist
43 troubleshooting.
44
46 gpsd is a monitor daemon that collects information from GPSes,
47 differential-GPS radios, or AIS receivers attached to the host machine.
48 Each GPS, DGPS radio, or AIS receiver is expected to be
49 direct-connected to the host via a USB or RS232C serial device. The
50 serial device may be specified to gpsd at startup, or it may be set via
51 a command shipped down a local control socket (e.g. by a USB hotplug
52 script). Given a GPS device by either means, gpsd discovers the correct
53 port speed and protocol for it.
54 gpsd should be able to query any GPS that speaks either the standard
56 textual NMEA 0183 protocol, or the (differing) extended NMEA dialects
57 used by MKT-3301, iTrax, Motorola OnCore, Sony CXD2951, and
58 Ashtech/Thales devices. It can also interpret the binary protocols used
59 by EverMore, Garmin, Navcom, Rockwell/Zodiac, SiRF, Trimble, and uBlox
60 ANTARIS devices. It can read heading and attitude information from the
61 Oceanserver 5000 orv TNT Revolution digital compasses.
62 The GPS reporting formats supported by your instance of gpsd may differ
64 depending on how it was compiled; general-purpose versions support
65 many, but it can be built with protocol subsets down to a singleton for
66 use in constrained environments. For a list of the GPS protocols
67 supported by your instance, see the output of gpsd -l
68 gpsd effectively hides the differences among the GPS types it supports.
70 It also knows about and uses commands that tune these GPSes for lower
71 latency. By using gpsd as an intermediary applications avoid contention
72 for serial devices.
73 gpsd can use differential-GPS corrections from a DGPS radio or over the
75 net, from a ground station running a DGPSIP server or a Ntrip
76 broadcaster that reports RTCM-104 data; this will shrink position
77 errors by roughly a factor of four. When gpsd opens a serial device
78 emitting RTCM-104, it automatically recognizes this and uses the device
79 as a correction source for all connected GPSes that accept RTCM
80 corrections (this is dependent on the type of the GPS; not all GPSes
81 have the firmware capability to accept RTCM correction packets). See
82 the section called “ACCURACY” and the section called “FILES” for
83 discussion.
84 Client applications will communicate with gpsd via a TCP/IP port, 2947
86 by default). Both IPv4 and IPv6 connections are supported and a client
87 may connect via either.
88 The program accepts the following options:
90 -F
92 Create a control socket for device addition and removal commands.
93 You must specify a valid pathname on your local filesystem; this
94 will be created as a Unix-domain socket to which you can write
95 commands that edit the daemon's internal device list.
96 -S
98 Set TCP/IP port on which to listen for GPSD clients (default is
99 2947).
100 -b
102 Broken-device-safety mode, otherwise known as read-only mode. Some
103 popular bluetooth and USB receivers lock up or become totally
104 inaccessible when probed or reconfigured. This switch prevents gpsd
105 from writing to a receiver. This means that gpsd cannot configure
106 the receiver for optimal performance, but it also means that gpsd
107 cannot break the receiver. A better solution would be for Bluetooth
108 to not be so fragile. A platform independent method to identify
109 serial-over-Bluetooth devices would also be nice.
110 -G
112 This flag causes gpsd to listen on all addresses (INADDR_ANY)
113 rather than just the loopback (INADDR_LOOPBACK) address. For the
114 sake of privacy and security, TPV information is now private to the
115 local machine until the user makes an effort to expose this to the
116 world.
117 -l
119 List all drivers compiled into this gpsd instance. The letters to
120 the left of each driver name are the gpsd control commands
121 supported by that driver.
122 -n
124 Don't wait for a client to connect before polling whatever GPS is
125 associated with it. Many GPSes go to a standby mode (drawing less
126 power) before the host machine asserts DTR, so waiting for the
127 first actual request saves battery power.
128 -N
130 Don't daemonize; run in foreground. Also suppresses
131 privilege-dropping. This switch is mainly useful for debugging.
132 -h
134 Display help message and terminate.
135 -P
137 Specify the name and path to record the daemon's process ID.
138 -D
140 Set debug level. At debug levels 2 and above, gpsd reports incoming
141 sentence and actions to standard error if gpsd is in the foreground
142 (-N) or to syslog if in the background.
143 -V
145 Dump version and exit.
146 Arguments are interpreted as the names of data sources. Normally, a
148 data source is the device pathname of a local device from which the
149 daemon may expect GPS data. But there are three other special source
150 types recognized, for a total of four:
151 Local serial or USB device
153 A normal Unix device name of a serial or USB device to which a
154 sensor is attached. Example: /dev/ttyUSB0.
155 TCP feed
157 A URI with the prefix "tcp://", followed by a hostname, a colon,
158 and a port number. The daemon will open a socket to the indicated
159 address and port and read data packets from it, which will be
160 interpreted as though they had been issued by a serial device.
161 Example: tcp://data.aishub.net:4006.
162 UDP feed
164 A URI with the prefix "udp://", followed by a hostname, a colon,
165 and a port number. The daemon will open a socket listening for UDP
166 datagrams arriving on the indicated address and port, which will be
167 interpreted as though they had been issued by a serial device.
168 Example: udp://127.0.0.1:5000.
169 Ntrip caster
171 A URI with the prefix "ntrip://" followed by the name of an Ntrip
172 caster (Ntrip is a protocol for broadcasting differential-GPS fixes
173 over the net). For Ntrip services that require authentication, a
174 prefix of the form "username:password@" can be added before the
175 name of the Ntrip broadcaster. For Ntrip service, you must specify
176 which stream to use; the stream is given in the form "/streamname".
177 An example DGPSIP URI could be "dgpsip://dgpsip.example.com" and a
178 Ntrip URI could be
179 "ntrip://foo:bar@ntrip.example.com:80/example-stream". Corrections
180 from the caster will be send to each attached GPS with the
181 capability to accept them.
182 DGPSIP server
184 A URI with the prefix "dgpsip://" followed by a hostname, a colon,
185 and an optional colon-separated port number (defaulting to 2101).
186 The daemon will handshake with the DGPSIP server and read RTCM2
187 correction data from it. Corrections from the server will be set to
188 each attached GPS with the capability to accept them.Example:
189 dgpsip://dgps.wsrcc.com:2101.
190 (The "ais:://" source type supported in some older versions of the
192 daemon has been retired in favor of the more general "tcp://".)
193 Internally, the daemon maintains a device pool holding the pathnames of
195 devices and remote servers known to the daemon. Initially, this list is
196 the list of device-name arguments specified on the command line. That
197 list may be empty, in which case the daemon will have no devices on its
198 search list until they are added by a control-socket command (see the
199 section called “GPS DEVICE MANAGEMENT” for details on this). Daemon
200 startup will abort with an error if neither any devices nor a control
201 socket are specified.
202 Clients communicate with the daemon via textual request and responses.
204 It is a bad idea for applications to speak the protocol directly:
205 rather, they should use the libgps client library and take appropriate
206 care to conditionalize their code on the major and minor protocol
207 version symbols.
208
210 The GPSD protocol is built on top of JSON, JaveScript Object Notation.
211 Use of this metaprotocol to pass structured data between daemon and
212 client avoids the non-extensibility problems of the old protocol, and
213 permits a richer set of record types to be passed up to clients.
214 A request line is introduced by "?" and may include multiple commands.
216 Commands begin with a command identifier, followed either by a
217 terminating ';' or by an equal sign "=" and a JSON object treated as an
218 argument. Any ';' or newline indication (either LF or CR-LF) after the
219 end of a command is ignored. All request lines must be composed of
220 US-ASCII characters and may be no more than 80 characters in length,
221 exclusive of the trailing newline.
222 Responses are JSON objects all of which have a "class" attribute the
224 value of which is either the name of the invoking command or one of the
225 strings "DEVICE" or "ERROR". Their length limit is 1024 characters,
226 including trailing newline.
227 The remainder of this section documents the core GPSD protocol.
229 Extensions are docomented in the following sections. The extensions may
230 not be supported in your gpsd instance if it has been compiled with a
231 restricted feature set.
232 Here are the core-protocol responses:
234 TPV
236 A TPV object is a time-position-velocity report. The "class" and
237 "mode" fields will reliably be present. Others may be reported or
238 not depending on the fix quality.
239 Table 1. TPV object
241 ┌───────┬─────────┬─────────┬──────────────────┐
242 │Name │ Always? │ Type │ Description │
243 ├───────┼─────────┼─────────┼──────────────────┤
244 │class │ Yes │ string │ Fixed: "TPV" │
245 ├───────┼─────────┼─────────┼──────────────────┤
246 │tag │ No │ string │ Type tag │
247 │ │ │ │ associated with │
248 │ │ │ │ this GPS │
249 │ │ │ │ sentence; from │
250 │ │ │ │ an NMEA │
251 │ │ │ │ device this │
252 │ │ │ │ is just the NMEA │
253 │ │ │ │ sentence type.. │
254 ├───────┼─────────┼─────────┼──────────────────┤
255 │device │ No │ string │ Name of │
256 │ │ │ │ originating │
257 │ │ │ │ device │
258 ├───────┼─────────┼─────────┼──────────────────┤
259 │time │ No │ numeric │ Seconds since │
260 │ │ │ │ the Unix epoch, │
261 │ │ │ │ UTC. May have a │
262 │ │ │ │ fractional │
263 │ │ │ │ part of up to │
264 │ │ │ │ .01sec │
265 │ │ │ │ precision. │
266 ├───────┼─────────┼─────────┼──────────────────┤
267 │ept │ No │ numeric │ Estimated │
268 │ │ │ │ timestamp error │
269 │ │ │ │ (%f, seconds, │
270 │ │ │ │ 95% confidence). │
271 ├───────┼─────────┼─────────┼──────────────────┤
272 │lat │ No │ numeric │ Latitude in │
273 │ │ │ │ degrees: +/- │
274 │ │ │ │ signifies │
275 │ │ │ │ West/East │
276 ├───────┼─────────┼─────────┼──────────────────┤
277 │lon │ No │ numeric │ Longitude in │
278 │ │ │ │ degrees: +/- │
279 │ │ │ │ signifies │
280 │ │ │ │ North/South. │
281 ├───────┼─────────┼─────────┼──────────────────┤
282 │alt │ No │ numeric │ Altitude in │
283 │ │ │ │ meters. │
284 ├───────┼─────────┼─────────┼──────────────────┤
285 │epx │ No │ numeric │ Longitude error │
286 │ │ │ │ estimate in │
287 │ │ │ │ meters, 95% │
288 │ │ │ │ confidence. │
289 ├───────┼─────────┼─────────┼──────────────────┤
290 │epy │ No │ numeric │ Latitude error │
291 │ │ │ │ estimate in │
292 │ │ │ │ meters, 95% │
293 │ │ │ │ confidence. │
294 ├───────┼─────────┼─────────┼──────────────────┤
295 │epv │ No │ numeric │ Estimated │
296 │ │ │ │ vertical error │
297 │ │ │ │ in meters, 95% │
298 │ │ │ │ confidence. │
299 ├───────┼─────────┼─────────┼──────────────────┤
300 │track │ No │ numeric │ Course over │
301 │ │ │ │ ground, degrees │
302 │ │ │ │ from true north. │
303 ├───────┼─────────┼─────────┼──────────────────┤
304 │speed │ No │ numeric │ Speed over │
305 │ │ │ │ ground, meters │
306 │ │ │ │ per second. │
307 ├───────┼─────────┼─────────┼──────────────────┤
308 │climb │ No │ numeric │ Climb (positive) │
309 │ │ │ │ or sink │
310 │ │ │ │ (negative) rate, │
311 │ │ │ │ meters per │
312 │ │ │ │ second. │
313 ├───────┼─────────┼─────────┼──────────────────┤
314 │epd │ No │ numeric │ Direction error │
315 │ │ │ │ estimate in │
316 │ │ │ │ degrees, 95% │
317 │ │ │ │ confifdence. │
318 ├───────┼─────────┼─────────┼──────────────────┤
319 │eps │ No │ numeric │ Speed error │
320 │ │ │ │ estinmate in │
321 │ │ │ │ meters/sec, 95% │
322 │ │ │ │ confifdence. │
323 ├───────┼─────────┼─────────┼──────────────────┤
324 │epc │ No │ numeric │ Climb/sink error │
325 │ │ │ │ estinmate in │
326 │ │ │ │ meters/sec, 95% │
327 │ │ │ │ confifdence. │
328 ├───────┼─────────┼─────────┼──────────────────┤
329 │mode │ Yes │ numeric │ NMEA mode: %d, │
330 │ │ │ │ 0=no mode value │
331 │ │ │ │ yet seen, 1=no │
332 │ │ │ │ fix, 2=2D, 3=3D. │
333 └───────┴─────────┴─────────┴──────────────────┘
334 When the C client library parses a response of this kind, it will
335 assert validity bits in the top-level set member for each field
336 actually received; see gps.h for bitmask names and values.
337 Here's an example:
339 {"class":"TPV","tag":"MID2","device":"/dev/pts/1",
341 "time":1118327688.280,"ept":0.005,
342 "lat":46.498293369,"lon":7.567411672,"alt":1343.127,
343 "eph":36.000,"epv":32.321,
344 "track":10.3788,"speed":0.091,"climb":-0.085,"mode":3}
345 SKY
347 A SKY object reports a sky view of the GPS satellite positions. If
348 there is no GPS device available, or no skyview has been reported
349 yet, only the "class" field will reliably be present.
350 Table 2. SKY object
352 ┌───────────┬─────────┬─────────┬──────────────────┐
353 │Name │ Always? │ Type │ Description │
354 ├───────────┼─────────┼─────────┼──────────────────┤
355 │class │ Yes │ string │ Fixed: "SKY" │
356 ├───────────┼─────────┼─────────┼──────────────────┤
357 │tag │ No │ string │ Type tag │
358 │ │ │ │ associated with │
359 │ │ │ │ this GPS │
360 │ │ │ │ sentence; from │
361 │ │ │ │ an NMEA │
362 │ │ │ │ device this │
363 │ │ │ │ is just the NMEA │
364 │ │ │ │ sentence type.. │
365 ├───────────┼─────────┼─────────┼──────────────────┤
366 │device │ No │ string │ Name of │
367 │ │ │ │ originating │
368 │ │ │ │ device │
369 ├───────────┼─────────┼─────────┼──────────────────┤
370 │time │ No │ numeric │ Seconds since │
371 │ │ │ │ the Unix epoch, │
372 │ │ │ │ UTC. May have a │
373 │ │ │ │ fractional │
374 │ │ │ │ part of up to │
375 │ │ │ │ .01sec │
376 │ │ │ │ precision. │
377 ├───────────┼─────────┼─────────┼──────────────────┤
378 │xdop │ No │ numeric │ Longitudinal │
379 │ │ │ │ dilution of │
380 │ │ │ │ precision, a │
381 │ │ │ │ dimensionsless │
382 │ │ │ │ factor │
383 │ │ │ │ which should be │
384 │ │ │ │ multiplied by a │
385 │ │ │ │ base UERE to get │
386 │ │ │ │ an error │
387 │ │ │ │ estimate. │
388 ├───────────┼─────────┼─────────┼──────────────────┤
389 │ydop │ No │ numeric │ Latitudinal │
390 │ │ │ │ dilution of │
391 │ │ │ │ precision, a │
392 │ │ │ │ dimensionsless │
393 │ │ │ │ factor │
394 │ │ │ │ which should be │
395 │ │ │ │ multiplied by a │
396 │ │ │ │ base UERE to get │
397 │ │ │ │ an error │
398 │ │ │ │ estimate. │
399 ├───────────┼─────────┼─────────┼──────────────────┤
400 │vdop │ No │ numeric │ Altitude │
401 │ │ │ │ dilution of │
402 │ │ │ │ precision, a │
403 │ │ │ │ dimensionsless │
404 │ │ │ │ factor │
405 │ │ │ │ which should be │
406 │ │ │ │ multiplied by a │
407 │ │ │ │ base UERE to get │
408 │ │ │ │ an error │
409 │ │ │ │ estimate. │
410 ├───────────┼─────────┼─────────┼──────────────────┤
411 │tdop │ No │ numeric │ Time dilution of │
412 │ │ │ │ precision, a │
413 │ │ │ │ dimensionsless │
414 │ │ │ │ factor │
415 │ │ │ │ which should be │
416 │ │ │ │ multiplied by a │
417 │ │ │ │ base UERE to get │
418 │ │ │ │ an error │
419 │ │ │ │ estimate. │
420 ├───────────┼─────────┼─────────┼──────────────────┤
421 │hdop │ No │ numeric │ Horizontal │
422 │ │ │ │ dilution of │
423 │ │ │ │ precision, a │
424 │ │ │ │ dimensionsless │
425 │ │ │ │ factor │
426 │ │ │ │ which should be │
427 │ │ │ │ multiplied by a │
428 │ │ │ │ base UERE to get │
429 │ │ │ │ a circular │
430 │ │ │ │ error estimate. │
431 ├───────────┼─────────┼─────────┼──────────────────┤
432 │pdop │ No │ numeric │ Spherical │
433 │ │ │ │ dilution of │
434 │ │ │ │ precision, a │
435 │ │ │ │ dimensionsless │
436 │ │ │ │ factor │
437 │ │ │ │ which should be │
438 │ │ │ │ multiplied by a │
439 │ │ │ │ base UERE to get │
440 │ │ │ │ an error │
441 │ │ │ │ estimate. │
442 ├───────────┼─────────┼─────────┼──────────────────┤
443 │gdop │ No │ numeric │ Hyperspherical │
444 │ │ │ │ dilution of │
445 │ │ │ │ precision, a │
446 │ │ │ │ dimensionsless │
447 │ │ │ │ factor │
448 │ │ │ │ which should be │
449 │ │ │ │ multiplied by a │
450 │ │ │ │ base UERE to get │
451 │ │ │ │ an error │
452 │ │ │ │ estimate. │
453 ├───────────┼─────────┼─────────┼──────────────────┤
454 │xdop │ No │ numeric │ Longitudinal │
455 │ │ │ │ dilution of │
456 │ │ │ │ precision, a │
457 │ │ │ │ dimensionsless │
458 │ │ │ │ factor │
459 │ │ │ │ which should be │
460 │ │ │ │ multiplied by a │
461 │ │ │ │ base UERE to get │
462 │ │ │ │ an error │
463 │ │ │ │ estimate. │
464 ├───────────┼─────────┼─────────┼──────────────────┤
465 │satellites │ Yes │ list │ List of │
466 │ │ │ │ satellite │
467 │ │ │ │ objects in │
468 │ │ │ │ skyview │
469 └───────────┴─────────┴─────────┴──────────────────┘
470 Many devices compute dilution of precision factors but do nit
471 include them in their reports. Many that do report DOPs report only
472 HDOP, two-dimensial circular error. gpsd always passes through
473 whatever the device actually reports, then attempts to fill in
474 other DOPs by calculating the appropriate determinants in a
475 covariance matrix based on the satellite view. DOPs may be missing
476 if some of these determinants are singular. It can even happen that
477 the device reports an error estimate in meters when the
478 correspoding DOP is unavailable; some devices use more
479 sophisticated error modeling than the covariance calculation.
480 The satellite list objects have the following elements:
482 Table 3. Satellite object
484 ┌─────┬─────────┬─────────┬──────────────────┐
485 │Name │ Always? │ Type │ Description │
486 ├─────┼─────────┼─────────┼──────────────────┤
487 │PRN │ Yes │ numeric │ PRN ID of the │
488 │ │ │ │ satellite │
489 ├─────┼─────────┼─────────┼──────────────────┤
490 │az │ Yes │ numeric │ Azimuth, degrees │
491 │ │ │ │ from true north. │
492 ├─────┼─────────┼─────────┼──────────────────┤
493 │el │ Yes │ numeric │ Elevation in │
494 │ │ │ │ degrees. │
495 ├─────┼─────────┼─────────┼──────────────────┤
496 │ss │ Yes │ numeric │ Signal strength │
497 │ │ │ │ in dB. │
498 ├─────┼─────────┼─────────┼──────────────────┤
499 │used │ Yes │ boolean │ Used in current │
500 │ │ │ │ solution? │
501 └─────┴─────────┴─────────┴──────────────────┘
502 Note that satellite objects do not have a "class" field.., as they
503 are never shipped outside of a SKY object.
504 When the C client library parses a SKY response, it will assert the
506 SATELLITE_SET bit in the top-level set member.
507 Here's an example:
509 {"class":"SKY","tag":"MID2","device":"/dev/pts/1","time":1118327688.280
511 "xdop":1.55,"hdop":1.24,"pdop":1.99,
512 "satellites":[
513 {"PRN":23,"el":6,"az":84,"ss":0,"used":false},
514 {"PRN":28,"el":7,"az":160,"ss":0,"used":false},
515 {"PRN":8,"el":66,"az":189,"ss":44,"used":true},
516 {"PRN":29,"el":13,"az":273,"ss":0,"used":false},
517 {"PRN":10,"el":51,"az":304,"ss":29,"used":true},
518 {"PRN":4,"el":15,"az":199,"ss":36,"used":true},
519 {"PRN":2,"el":34,"az":241,"ss":43,"used":true},
520 {"PRN":27,"el":71,"az":76,"ss":43,"used":true}]}
521 ATT
523 An ATT object is a vehicle-attitude report. It is returned by
524 digital-compass and gyroscope sensors; depending on device, it may
525 include: heading, pitch, roll, yaw, gyroscope, and magnetic-field
526 readings. Because such sensors are often bundled as part of
527 marine-navigation systems, the ATT response may also include water
528 depth.
529 The "class", "mode", and "tag" fields will reliably be present.
531 Others may be reported or not depending on the specific device
532 type.
533 Table 4. ATT object
535 ┌────────────┬─────────┬─────────┬──────────────────┐
536 │Name │ Always? │ Type │ Description │
537 ├────────────┼─────────┼─────────┼──────────────────┤
538 │class │ Yes │ string │ Fixed: "ATT" │
539 ├────────────┼─────────┼─────────┼──────────────────┤
540 │tag │ Yes │ string │ Type tag │
541 │ │ │ │ associated with │
542 │ │ │ │ this GPS │
543 │ │ │ │ sentence; from │
544 │ │ │ │ an NMEA │
545 │ │ │ │ device this │
546 │ │ │ │ is just the NMEA │
547 │ │ │ │ sentence type.. │
548 ├────────────┼─────────┼─────────┼──────────────────┤
549 │device │ Yes │ string │ Name of │
550 │ │ │ │ originating │
551 │ │ │ │ device │
552 ├────────────┼─────────┼─────────┼──────────────────┤
553 │time │ Yes │ numeric │ Seconds since │
554 │ │ │ │ the Unix epoch, │
555 │ │ │ │ UTC. May have a │
556 │ │ │ │ fractional │
557 │ │ │ │ part of up to │
558 │ │ │ │ .01sec │
559 │ │ │ │ precision. │
560 ├────────────┼─────────┼─────────┼──────────────────┤
561 │heading │ No │ numeric │ Heading, degrees │
562 │ │ │ │ from true north. │
563 ├────────────┼─────────┼─────────┼──────────────────┤
564 │mag_st │ No │ string │ Magnetometer │
565 │ │ │ │ status. │
566 ├────────────┼─────────┼─────────┼──────────────────┤
567 │pitch │ No │ numeric │ Pitch in │
568 │ │ │ │ degrees. │
569 ├────────────┼─────────┼─────────┼──────────────────┤
570 │pitch_st │ No │ string │ Pitch sensor │
571 │ │ │ │ status. │
572 ├────────────┼─────────┼─────────┼──────────────────┤
573 │yaw │ No │ numeric │ Yaw in degrees │
574 ├────────────┼─────────┼─────────┼──────────────────┤
575 │yaw_st │ No │ string │ Yaw sensor │
576 │ │ │ │ status. │
577 ├────────────┼─────────┼─────────┼──────────────────┤
578 │roll │ No │ numeric │ Roll in degrees. │
579 ├────────────┼─────────┼─────────┼──────────────────┤
580 │roll_st │ No │ string │ Roll sensor │
581 │ │ │ │ status. │
582 ├────────────┼─────────┼─────────┼──────────────────┤
583 │dip │ No │ numeric │ Roll in degrees. │
584 ├────────────┼─────────┼─────────┼──────────────────┤
585 │mag_len │ No │ numeric │ Scalar magnetic │
586 │ │ │ │ field strength. │
587 ├────────────┼─────────┼─────────┼──────────────────┤
588 │mag_x │ No │ numeric │ X component of │
589 │ │ │ │ magnetic field │
590 │ │ │ │ strength. │
591 ├────────────┼─────────┼─────────┼──────────────────┤
592 │mag_y │ No │ numeric │ Y component of │
593 │ │ │ │ magnetic field │
594 │ │ │ │ strength.. │
595 ├────────────┼─────────┼─────────┼──────────────────┤
596 │mag_z │ No │ numeric │ Z component of │
597 │ │ │ │ magnetic field │
598 │ │ │ │ strength.. │
599 ├────────────┼─────────┼─────────┼──────────────────┤
600 │mag_len │ No │ numeric │ Scalar │
601 │ │ │ │ acceleration. │
602 ├────────────┼─────────┼─────────┼──────────────────┤
603 │acc_x │ No │ numeric │ X component of │
604 │ │ │ │ acceleration. │
605 ├────────────┼─────────┼─────────┼──────────────────┤
606 │acc_y │ No │ numeric │ Y component of │
607 │ │ │ │ acceleration. │
608 ├────────────┼─────────┼─────────┼──────────────────┤
609 │acc_z │ No │ numeric │ Z component of │
610 │ │ │ │ acceleration.. │
611 ├────────────┼─────────┼─────────┼──────────────────┤
612 │gyro_x │ No │ numeric │ X component of │
613 │ │ │ │ acceleration. │
614 ├────────────┼─────────┼─────────┼──────────────────┤
615 │gyro_y │ No │ numeric │ Y component of │
616 │ │ │ │ acceleration. │
617 ├────────────┼─────────┼─────────┼──────────────────┤
618 │depth │ No │ numeric │ Water depth in │
619 │ │ │ │ meters. │
620 ├────────────┼─────────┼─────────┼──────────────────┤
621 │temperature │ No │ numeric │ Temperature at │
622 │ │ │ │ sensir, degrees │
623 │ │ │ │ centigrade. │
624 └────────────┴─────────┴─────────┴──────────────────┘
625 The heading, pitch, and roll status codes (if present) vary by
626 device. For the TNT Revolution digital compasses, they are coded as
627 follows:
628 Table 5. Device flags
630 ┌─────┬────────────────────────────┐
631 │Code │ Description │
632 ├─────┼────────────────────────────┤
633 │C │ magnetometer calibration │
634 │ │ alarm │
635 ├─────┼────────────────────────────┤
636 │L │ low alarm │
637 ├─────┼────────────────────────────┤
638 │M │ low warning │
639 ├─────┼────────────────────────────┤
640 │N │ normal │
641 ├─────┼────────────────────────────┤
642 │O │ high warning │
643 ├─────┼────────────────────────────┤
644 │P │ high alarm │
645 ├─────┼────────────────────────────┤
646 │V │ magnetometer voltage level │
647 │ │ alarm │
648 └─────┴────────────────────────────┘
649 When the C client library parses a response of this kind, it will
650 assert ATT_IS.
651 Here's an example:
653 {"class":"ATT","tag":"PTNTHTM","time":1270938096.843,
655 "heading":14223.00,"mag_st":"N",
656 "pitch":169.00,"pitch_st":"N", "roll":-43.00,"roll_st":"N",
657 "dip":13641.000,"mag_x":2454.000,"temperature":0.000,"depth":0.000}
658 And here are the commands:
660 ?VERSION;
662 Returns an object with the following attributes:
663 Table 6. VERSION object
665 ┌────────────┬─────────┬─────────┬──────────────────┐
666 │Name │ Always? │ Type │ Description │
667 ├────────────┼─────────┼─────────┼──────────────────┤
668 │class │ Yes │ string │ Fixed: "VERSION" │
669 ├────────────┼─────────┼─────────┼──────────────────┤
670 │release │ Yes │ string │ Public release │
671 │ │ │ │ level │
672 ├────────────┼─────────┼─────────┼──────────────────┤
673 │rev │ Yes │ string │ Internal │
674 │ │ │ │ revision-control │
675 │ │ │ │ level. │
676 ├────────────┼─────────┼─────────┼──────────────────┤
677 │proto_major │ Yes │ numeric │ API major │
678 │ │ │ │ revision level.. │
679 ├────────────┼─────────┼─────────┼──────────────────┤
680 │proto_minor │ Yes │ numeric │ API minor │
681 │ │ │ │ revision level.. │
682 └────────────┴─────────┴─────────┴──────────────────┘
683 The daemon ships a VERSION response to each client when the client
684 first connects to it.
685 When the C client library parses a response of this kind, it will
687 assert the VERSION_SET bit in the top-level set member.
688 Here's an example:
690 {"class":"VERSION","version":"2.40dev","rev":"06f62e14eae9886cde907dae61c124c53eb1101f","proto_major":3,"proto_minor":1}
692 ?DEVICES;
694 Returns a device list object with the following elements:
695 Table 7. DEVICES object
697 ┌────────┬─────────┬────────┬──────────────────┐
698 │Name │ Always? │ Type │ Description │
699 ├────────┼─────────┼────────┼──────────────────┤
700 │class │ Yes │ string │ Fixed: "DEVICES" │
701 ├────────┼─────────┼────────┼──────────────────┤
702 │devices │ Yes │ list │ List of device │
703 │ │ │ │ descriptions │
704 └────────┴─────────┴────────┴──────────────────┘
705 When the C client library parses a response of this kind, it will
706 assert the DEVICELIST_SET bit in the top-level set member.
707 Here's an example:
709 {"class"="DEVICES","devices":[
711 {"class":"DEVICE","path":"/dev/pts/1","flags":1,"driver":"SiRF binary"},
712 {"class":"DEVICE","path":"/dev/pts/3","flags":4,"driver":"AIVDM"}]}
713 The daemon occasionally ships a bare DEVICE object to the client
715 (that is, one not inside a DEVICES wrapper). The data content of
716 these objects will be described later in the section covering
717 notifications.
718 ?WATCH;
720 This command sets watcher mode. It also sets or elicits a report of
721 per-subscriber policy and the raw bit. An argument WATCH object
722 changes the subscriber's policy. The responce describes the
723 subscriber's policy. The response will also include a DEVICES
724 object.
725 A WATCH object has the following elements:
727 Table 8. WATCH object
729 ┌───────┬─────────┬─────────┬──────────────────┐
730 │Name │ Always? │ Type │ Description │
731 ├───────┼─────────┼─────────┼──────────────────┤
732 │class │ Yes │ string │ Fixed: "WATCH" │
733 ├───────┼─────────┼─────────┼──────────────────┤
734 │enable │ No │ boolean │ Enable (true) or │
735 │ │ │ │ disable (false) │
736 │ │ │ │ watcher mode. │
737 │ │ │ │ Default is │
738 │ │ │ │ true. │
739 ├───────┼─────────┼─────────┼──────────────────┤
740 │json │ No │ boolean │ Enable (true) or │
741 │ │ │ │ disable (false) │
742 │ │ │ │ dumping of JSON │
743 │ │ │ │ reports. │
744 │ │ │ │ Default is │
745 │ │ │ │ false. │
746 ├───────┼─────────┼─────────┼──────────────────┤
747 │nmea │ No │ boolean │ Enable (true) or │
748 │ │ │ │ disable (false) │
749 │ │ │ │ dumping of │
750 │ │ │ │ binary │
751 │ │ │ │ packets as │
752 │ │ │ │ pseudo-NMEA. │
753 │ │ │ │ Default is │
754 │ │ │ │ false. │
755 ├───────┼─────────┼─────────┼──────────────────┤
756 │raw │ No │ integer │ Controls 'raw' │
757 │ │ │ │ mode. When this │
758 │ │ │ │ attribute is set │
759 │ │ │ │ to 1 for a │
760 │ │ │ │ channel, gpsd │
761 │ │ │ │ reports the │
762 │ │ │ │ unprocessed │
763 │ │ │ │ NMEA or AIVDM │
764 │ │ │ │ data stream from │
765 │ │ │ │ whatever device │
766 │ │ │ │ is attached. │
767 │ │ │ │ Binary GPS │
768 │ │ │ │ packets are │
769 │ │ │ │ hex-dumped. │
770 │ │ │ │ RTCM2 and RTCM3 │
771 │ │ │ │ packets │
772 │ │ │ │ are not dumped │
773 │ │ │ │ in raw mode. │
774 ├───────┼─────────┼─────────┼──────────────────┤
775 │scaled │ No │ boolean │ If true, apply │
776 │ │ │ │ scaling divisors │
777 │ │ │ │ to output before │
778 │ │ │ │ dumping; │
779 │ │ │ │ default is │
780 │ │ │ │ false. Applies │
781 │ │ │ │ only to AIS │
782 │ │ │ │ reports. │
783 ├───────┼─────────┼─────────┼──────────────────┤
784 │device │ No │ string │ If present, │
785 │ │ │ │ enable watching │
786 │ │ │ │ only of the │
787 │ │ │ │ specified device │
788 │ │ │ │ rather than │
789 │ │ │ │ all devices. │
790 │ │ │ │ Useful with raw │
791 │ │ │ │ and NMEA modes │
792 │ │ │ │ in which │
793 │ │ │ │ device responses │
794 │ │ │ │ aren't tagged. │
795 │ │ │ │ Has no effect │
796 │ │ │ │ when used │
797 │ │ │ │ with │
798 │ │ │ │ enable:false. │
799 └───────┴─────────┴─────────┴──────────────────┘
800 There is an additional boolean "timing" attribute which is
801 undocumented because that portion of the interface is considered
802 unstable and for developer use only.
803 In watcher mode, GPS reports are dumped as TPV and SKY responses.
805 AIS and RTCM reporting is described in the next section.
806 When the C client library parses a response of this kind, it will
808 assert the POLICY_SET bit in the top-level set member.
809 Here's an example:
811 {"class":"WATCH", "raw":1,"scaled":true}
813 ?POLL;
815 The POLL command requests data from the last-seen fixes on all
816 active GPS devices. Devices must previously have been activated by
817 ?WATCH to be pollable, or have been specified on the GPSD command
818 line together with an -n option.
819 Polling can lead to possibly surprising results when it is used on
821 a device such as an NMEA GPS for which a complete fix has to be
822 accumulated from several sentences. If you poll while those
823 sentences are being emitted, the response will contain the last
824 complete fix data and may be as much as one cycle time (typically 1
825 second) stale.
826 The POLL response will contain a timestamped list of TPV objects
828 describing cached data, and a timestamped list of SKY objects
829 describing satellite configuration. If a device has not seen fixes,
830 it will be reported with a mode field of zero.
831 Table 9. POLL object
833 ┌─────────┬─────────┬────────────┬─────────────────┐
834 │Name │ Always? │ Type │ Description │
835 ├─────────┼─────────┼────────────┼─────────────────┤
836 │class │ Yes │ string │ Fixed: "POLL" │
837 ├─────────┼─────────┼────────────┼─────────────────┤
838 │time │ Yes │ Numeric │ Seconds since │
839 │ │ │ │ the Unix epoch, │
840 │ │ │ │ UTC. May have a │
841 │ │ │ │ fractional │
842 │ │ │ │ part of up to │
843 │ │ │ │ .001sec │
844 │ │ │ │ precision. │
845 ├─────────┼─────────┼────────────┼─────────────────┤
846 │active │ Yes │ Numeric │ Count of active │
847 │ │ │ │ devices. │
848 ├─────────┼─────────┼────────────┼─────────────────┤
849 │fixes │ Yes │ JSON array │ Comma-separated │
850 │ │ │ │ list of TPV │
851 │ │ │ │ objects. │
852 ├─────────┼─────────┼────────────┼─────────────────┤
853 │skyviews │ Yes │ JSON array │ Comma-separated │
854 │ │ │ │ list of SKY │
855 │ │ │ │ objects. │
856 └─────────┴─────────┴────────────┴─────────────────┘
857 Here's an example of a POLL response:
858 {"class":"POLL","timestamp":1270517274.846,"active":1,
860 "fixes":[{"class":"TPV","tag":"MID41","device":"/dev/ttyUSB0",
861 "time":1270517264.240,"ept":0.005,"lat":40.035093060,
862 "lon":-75.519748733,"track":99.4319,"speed":0.123,"mode":2}],
863 "skyviews":[{"class":"SKY","tag":"MID41","device":"/dev/ttyUSB0",
864 "time":1270517264.240,"hdop":9.20,
865 "satellites":[{"PRN":16,"el":55,"az":42,"ss":36,"used":true},
866 {"PRN":19,"el":25,"az":177,"ss":0,"used":false},
867 {"PRN":7,"el":13,"az":295,"ss":0,"used":false},
868 {"PRN":6,"el":56,"az":135,"ss":32,"used":true},
869 {"PRN":13,"el":47,"az":304,"ss":0,"used":false},
870 {"PRN":23,"el":66,"az":259,"ss":0,"used":false},
871 {"PRN":20,"el":7,"az":226,"ss":0,"used":false},
872 {"PRN":3,"el":52,"az":163,"ss":32,"used":true},
873 {"PRN":31,"el":16,"az":102,"ss":0,"used":false}
874 ]}]}
875 Note
877 Client software should not assime the field inventory of the
878 POLL response is fixed for all time. As gpsd collects and
879 caches more data from more sensor types, those data are likely
880 to find their way into this response.
881 ?DEVICE
883 This command reports (when followed by ';') the state of a device,
884 or sets (when followed by '=' and a DEVICE object) device-specific
885 control bits, notably the device's speed and serial mode and the
886 native-mode bit. The parameter-setting form will be rejected if
887 more than one client is attached to the channel.
888 Pay attention to the response, because it is possible for this
890 command to fail if the GPS does not support a speed-switching
891 command or only supports some combinations of serial modes. In case
892 of failure, the daemon and GPS will continue to communicate at the
893 old speed.
894 Use the parameter-setting form with caution. On USB and Bluetooth
896 GPSes it is also possible for serial mode setting to fail either
897 because the serial adaptor chip does not support non-8N1 modes or
898 because the device firmware does not properly synchronize the
899 serial adaptor chip with the UART on the GPS chipset whjen the
900 speed changes. These failures can hang your device, possibly
901 requiring a GPS power cycle or (in extreme cases) physically
902 disconnecting the NVRAM backup battery.
903 A DEVICE object has the following elements:
905 Table 10. CONFIGCHAN object
907 ┌──────────┬──────────────────┬─────────┬────────────────────┐
908 │Name │ Always? │ Type │ Description │
909 ├──────────┼──────────────────┼─────────┼────────────────────┤
910 │class │ Yes │ string │ Fixed: "DEVICE" │
911 ├──────────┼──────────────────┼─────────┼────────────────────┤
912 │path │ No │ string │ Name the device │
913 │ │ │ │ for which the │
914 │ │ │ │ control bits are │
915 │ │ │ │ being │
916 │ │ │ │ reported, or for │
917 │ │ │ │ which they are │
918 │ │ │ │ to be applied. │
919 │ │ │ │ This │
920 │ │ │ │ attribute │
921 │ │ │ │ may be omitted │
922 │ │ │ │ only when there │
923 │ │ │ │ is exactly one │
924 │ │ │ │ subscribed │
925 │ │ │ │ channel. │
926 ├──────────┼──────────────────┼─────────┼────────────────────┤
927 │activated │ At device │ numeric │ Time the device │
928 │ │ activation and │ │ was activated, │
929 │ │ device close │ │ or 0 if it is │
930 │ │ time. │ │ being closed. │
931 ├──────────┼──────────────────┼─────────┼────────────────────┤
932 │flags │ No │ integer │ Bit vector of │
933 │ │ │ │ property flags. │
934 │ │ │ │ Currently defined │
935 │ │ │ │ flags are: │
936 │ │ │ │ describe │
937 │ │ │ │ packet types seen │
938 │ │ │ │ so far (GPS, │
939 │ │ │ │ RTCM2, RTCM3, │
940 │ │ │ │ AIS). Won't │
941 │ │ │ │ be reported if │
942 │ │ │ │ empty, e.g. before │
943 │ │ │ │ gpsd has seen │
944 │ │ │ │ identifiable │
945 │ │ │ │ packets from │
946 │ │ │ │ the device. │
947 ├──────────┼──────────────────┼─────────┼────────────────────┤
948 │driver │ No │ string │ GPSD's name for │
949 │ │ │ │ the device driver │
950 │ │ │ │ type. Won't be │
951 │ │ │ │ reported before │
952 │ │ │ │ gpsd has seen │
953 │ │ │ │ identifiable │
954 │ │ │ │ packets from │
955 │ │ │ │ the device. │
956 ├──────────┼──────────────────┼─────────┼────────────────────┤
957 │subtype │ When the daemon │ string │ Whatever version │
958 │ │ sees a delayed │ │ information the │
959 │ │ response to a │ │ device returned. │
960 │ │ probe for │ │ │
961 │ │ subtype or │ │ │
962 │ │ firmware-version │ │ │
963 │ │ information. │ │ │
964 ├──────────┼──────────────────┼─────────┼────────────────────┤
965 │bps │ No │ integer │ Device speed in │
966 │ │ │ │ bits per second. │
967 ├──────────┼──────────────────┼─────────┼────────────────────┤
968 │parity │ Yes │ string │ N, O or E for no │
969 │ │ │ │ parity, odd, or │
970 │ │ │ │ even. │
971 ├──────────┼──────────────────┼─────────┼────────────────────┤
972 │stopbits │ Yes │ string │ Stop bits (1 or │
973 │ │ │ │ 2). │
974 ├──────────┼──────────────────┼─────────┼────────────────────┤
975 │native │ No │ integer │ 0 means NMEA mode │
976 │ │ │ │ and 1 means │
977 │ │ │ │ alternate │
978 │ │ │ │ mode (binary if it │
979 │ │ │ │ has one, for SiRF │
980 │ │ │ │ and Evermore │
981 │ │ │ │ chipsets in │
982 │ │ │ │ particular). │
983 │ │ │ │ Attempting to set │
984 │ │ │ │ this mode on a │
985 │ │ │ │ non-GPS │
986 │ │ │ │ device will │
987 │ │ │ │ yield an error. │
988 ├──────────┼──────────────────┼─────────┼────────────────────┤
989 │cycle │ No │ real │ Device cycle time │
990 │ │ │ │ in seconds. │
991 ├──────────┼──────────────────┼─────────┼────────────────────┤
992 │mincycle │ No │ real │ Device minimum │
993 │ │ │ │ cycle time in │
994 │ │ │ │ seconds. Reported │
995 │ │ │ │ from │
996 │ │ │ │ ?CONFIGDEV │
997 │ │ │ │ when (and only │
998 │ │ │ │ when) the rate is │
999 │ │ │ │ switchable. It is │
1000 │ │ │ │ read-only and │
1001 │ │ │ │ not settable. │
1002 └──────────┴──────────────────┴─────────┴────────────────────┘
1003 The serial parameters will be omitted in a response describing a
1004 TCP/IP source such as an Ntrip, DGPSIP, or AIS feed.
1005 The contents of the flags field should be interpreted as follows:
1007 Table 11. Device flags
1009 ┌───────────┬───────┬─────────────────────┐
1010 │C #define │ Value │ Description │
1011 ├───────────┼───────┼─────────────────────┤
1012 │SEEN_GPS │ 0x01 │ GPS data has been │
1013 │ │ │ seen on this device │
1014 ├───────────┼───────┼─────────────────────┤
1015 │SEEN_RTCM2 │ 0x02 │ RTCM2 data has been │
1016 │ │ │ seen on this device │
1017 ├───────────┼───────┼─────────────────────┤
1018 │SEEN_RTCM3 │ 0x04 │ RTCM3 data has been │
1019 │ │ │ seen on this device │
1020 ├───────────┼───────┼─────────────────────┤
1021 │SEEN_AIS │ 0x08 │ AIS data has been │
1022 │ │ │ seen on this device │
1023 └───────────┴───────┴─────────────────────┘
1024 When the C client library parses a response of this kind, it will
1025 assert the DEVICE_SET bit in the top-level set member.
1026 Here's an example:
1028 {"class":"DEVICE", "speed":4800,"serialmode":"8N1","native":0}
1030 When a client is in watcher mode, the daemon will ship it DEVICE
1032 notifications when a device is added to the pool or deactivated.
1033 When the C client library parses a response of this kind, it will
1035 assert the DEVICE_SET bit in the top-level set member.
1036 Here's an example:
1038 {"class":"DEVICE","path":"/dev/pts1","activated":0}
1040 The daemon may ship an error object in response to a syntactically
1042 invalid command line or unknown command. It has the following elements:
1043 Table 12. ERROR notification object
1045 ┌────────┬─────────┬────────┬────────────────┐
1046 │Name │ Always? │ Type │ Description │
1047 ├────────┼─────────┼────────┼────────────────┤
1048 │class │ Yes │ string │ Fixed: "ERROR" │
1049 ├────────┼─────────┼────────┼────────────────┤
1050 │message │ Yes │ string │ Textual error │
1051 │ │ │ │ message │
1052 └────────┴─────────┴────────┴────────────────┘
1053 Here's an example:
1055 {"class":"ERROR","message":"Unrecognized request '?FOO'"}
1057 When the C client library parses a response of this kind, it will
1059 assert the ERR_SET bit in the top-level set member.
1060
1062 AIS support is an extension. It may not be present if your instance of
1063 gpsd has been built with a restricted feature set.
1064 AIS packets are dumped as JSON objects with class "AIS". Each AIS
1066 report object contains a "type" field giving the AIS message type and a
1067 "scaled" field telling whether the remainder of the fields are dumped
1068 in scaled or unscaled form. Other fields have names and types as
1069 specified in the AIVDM/AIVDO Protocol Decoding[2] document; each
1070 message field table may be directly interpreted as a specification for
1071 the members of the corresponding JSON object type.
1072 RTCM2 corrections are dumped in the JSON format described in
1074 rtcm104(5).
1075
1077 gpsd maintains an internal list of GPS devices (the "device pool"). If
1078 you specify devices on the command line, the list is initialized with
1079 those pathnames; otherwise the list starts empty. Commands to add and
1080 remove GPS device paths from the daemon's device list must be written
1081 to a local Unix-domain socket which will be accessible only to programs
1082 running as root. This control socket will be located wherever the -F
1083 option specifies it.
1084 A device may will also be dropped from the pool if GPSD gets a zero
1086 length read from it. This end-of-file condition indicates that the'
1087 device has been disconnected.
1088 When gpsd is properly installed along with hotplug notifier scripts
1090 feeding it device-add commands over the control socket, gpsd should
1091 require no configuration or user action to find devices.
1092 Sending SIGHUP to a running gpsd forces it to close all GPSes and all
1094 client connections. It will then attempt to reconnect to any GPSes on
1095 its device list and resume listening for client connections. This may
1096 be useful if your GPS enters a wedged or confused state but can be
1097 soft-reset by pulling down DTR.
1098 To point gpsd at a device that may be a GPS, write to the control
1100 socket a plus sign ('+') followed by the device name followed by LF or
1101 CR-LF. Thus, to point the daemon at /dev/foo. send "+/dev/foo\n". To
1102 tell the daemon that a device has been disconnected and is no longer
1103 available, send a minus sign ('-') followed by the device name followed
1104 by LF or CR-LF. Thus, to remove /dev/foo from the search list. send
1105 "-/dev/foo\n".
1106 To send a control string to a specified device, write to the control
1108 socket a '!', followed by the device name, followed by '=', followed by
1109 the control string.
1110 To send a binary control string to a specified device, write to the
1112 control socket a '&', followed by the device name, followed by '=',
1113 followed by the control string in paired hex digits.
1114 Your client may await a response, which will be a line beginning with
1116 either "OK" or "ERROR". An ERROR reponse to an add command means the
1117 device did not emit data recognizable as GPS packets; an ERROR response
1118 to a remove command means the specified device was not in gpsd's device
1119 pool. An ERROR response to a ! command means the daemon did not
1120 recognize the devicename specified.
1121 The control socket is intended for use by hotplug scripts and other
1123 device-discovery services. This control channel is separate from the
1124 public gpsd service port, and only locally accessible, in order to
1125 prevent remote denial-of-service and spoofing attacks.
1126
1128 The base User Estimated Range Error (UERE) of GPSes is 8 meters or less
1129 at 66% confidence, 15 meters or less at 95% confidence. Actual
1130 horizontal error will be UERE times a dilution factor dependent on
1131 current satellite position. Altitude determination is more sensitive to
1132 variability in ionospheric signal lag than latitude/longitude is, and
1133 is also subject to errors in the estimation of local mean sea level;
1134 base error is 12 meters at 66% confidence, 23 meters at 95% confidence.
1135 Again, this will be multiplied by a vertical dilution of precision
1136 (VDOP) dependent on satellite geometry, and VDOP is typically larger
1137 than HDOP. Users should not rely on GPS altitude for life-critical
1138 tasks such as landing an airplane.
1139 These errors are intrinsic to the design and physics of the GPS system.
1141 gpsd does its internal computations at sufficient accuracy that it will
1142 add no measurable position error of its own.
1143 DGPS correction will reduce UERE by a factor of 4, provided you are
1145 within about 100mi (160km) of a DGPS ground station from which you are
1146 receiving corrections.
1147 On a 4800bps connection, the time latency of fixes provided by gpsd
1149 will be one second or less 95% of the time. Most of this lag is due to
1150 the fact that GPSes normally emit fixes once per second, thus expected
1151 latency is 0.5sec. On the personal-computer hardware available in 2005,
1152 computation lag induced by gpsd will be negligible, on the order of a
1153 millisecond. Nevertheless, latency can introduce significant errors for
1154 vehicles in motion; at 50km/h (31mi/h) of speed over ground, 1 second
1155 of lag corresponds to 13.8 meters change in position between updates.
1156 The time reporting of the GPS system itself has an intrinsic accuracy
1158 limit of 0.000,000,340 = 3.4×10-7 seconds. A more important limit is
1159 the GPS tick rate. While the one-per-second PPS pulses emitted by
1160 serial GPS units are timed to the GPS system's intrinsic accuracy
1161 limit,the satellites only emit navigation messages at 0.01-second
1162 intervals, and the timestamps in them only carry 0.01-second precision.
1163 Thus, the timestamps that gpsd reports in time/position/velocity
1164 messages are normally accurate only to 1/100th of a second.
1165
1167 gpsd can provide reference clock information to ntpd, to keep the
1168 system clock synchronized to the time provided by the GPS receiver.
1169 This facility is only available when the daemon is started from root.
1170 If you're going to use gpsd you probably want to run it -n mode so the
1171 clock will be updated even when no clients are active.
1172 Note that deriving time from messages received from the GPS is not as
1174 accurate as you might expect. Messages are often delayed in the
1175 receiver and on the link by several hundred milliseconds, and this
1176 delay is not constant. On Linux, gpsd includes support for interpreting
1177 the PPS pulses emitted at the start of every clock second on the
1178 carrier-detect lines of some serial GPSes; this pulse can be used to
1179 update NTP at much higher accuracy than message time provides. You can
1180 determine whether your GPS emits this pulse by running at -D 5 and
1181 watching for carrier-detect state change messages in the logfile.
1182 When gpsd receives a sentence with a timestamp, it packages the
1184 received timestamp with current local time and sends it to a
1185 shared-memory segment with an ID known to ntpd, the network time
1186 synchronization daemon. If ntpd has been properly configured to receive
1187 this message, it will be used to correct the system clock.
1188 Here is a sample ntp.conf configuration stanza telling ntpd how to read
1190 the GPS notfications:
1191 server 127.127.28.0 minpoll 4 maxpoll 4
1193 fudge 127.127.28.0 time1 0.420 refid GPS
1194 server 127.127.28.1 minpoll 4 maxpoll 4 prefer
1196 fudge 127.127.28.1 refid GPS1
1197 The magic pseudo-IP address 127.127.28.0 identifies unit 0 of the ntpd
1199 shared-memory driver; 127.127.28.1 identifies unit 1. Unit 0 is used
1200 for message-decoded time and unit 1 for the (more accurate, when
1201 available) time derived from the PPS synchronization pulse. Splitting
1202 these notifications allows ntpd to use its normal heuristics to weight
1203 them.
1204 With this configuration, ntpd will read the timestamp posted by gpsd
1206 every 16 seconds and send it to unit 0. The number after the parameter
1207 time1 is an offset in seconds. You can use it to adjust out some of the
1208 fixed delays in the system. 0.035 is a good starting value for the
1209 Garmin GPS-18/USB, 0.420 for the Garmin GPS-18/LVC.
1210 After restarting ntpd, a line similar to the one below should appear in
1212 the output of the command "ntpq -p" (after allowing a couple of
1213 minutes):
1214 remote refid st t when poll reach delay offset jitter
1216 =========================================================================
1217 +SHM(0) .GPS. 0 l 13 16 377 0.000 0.885 0.882
1218 If you are running PPS then it will look like this:
1220 remote refid st t when poll reach delay offset jitter
1222 =========================================================================
1223 -SHM(0) .GPS. 0 l 13 16 377 0.000 0.885 0.882
1224 *SHM(1) .GPS1. 0 l 11 16 377 0.000 -0.059 0.006
1225 When the value under "reach" remains zero, check that gpsd is running;
1227 and some application is connected to it or the '-n' option was used.
1228 Make sure the receiver is locked on to at least one satellite, and the
1229 receiver is in SiRF binary, Garmin binary or NMEA/PPS mode. Plain NMEA
1230 will also drive ntpd, but the accuracy as bad as one second. When the
1231 SHM(0) line does not appear at all, check the system logs for error
1232 messages from ntpd.
1233 When no other reference clocks appear in the NTP configuration, the
1235 system clock will lock onto the GPS clock. When you have previously
1236 used ntpd, and other reference clocks appear in your configuration,
1237 there may be a fixed offset between the GPS clock and other clocks. The
1238 gpsd developers would like to receive information about the offsets
1239 observed by users for each type of receiver. Please send us the output
1240 of the "ntpq -p" command and the make and type of receiver.
1241
1243 On operating systems that support D-BUS, gpsd can be built to broadcast
1244 GPS fixes to D-BUS-aware applications. As D-BUS is still at a pre-1.0
1245 stage, we will not attempt to document this interface here. Read the
1246 gpsd source code to learn more.
1247
1249 gpsd, if given the -G flag, will listen for connections from any
1250 reachable host, and then disclose the current position. Before using
1251 the -G flag, consider whether you consider your computer's location to
1252 be sensitive data to be kept private or something that you wish to
1253 publish.
1254 gpsd must start up as root in order to open the NTPD shared-memory
1256 segment, open its logfile, and create its local control socket. Before
1257 doing any processing of GPS data, it tries to drop root privileges by
1258 setting its UID to "nobody" (or another userid as set by configure) and
1259 its group ID to the group of the initial GPS passed on the command line
1260 — or, if that device doesn't exist, to the group of /dev/ttyS0.
1261 Privilege-dropping is a hedge against the possibility that carefully
1263 crafted data, either presented from a client socket or from a subverted
1264 serial device posing as a GPS, could be used to induce misbehavior in
1265 the internals of gpsd. It ensures that any such compromises cannot be
1266 used for privilege elevation to root.
1267 The assumption behind gpsd's particular behavior is that all the tty
1269 devices to which a GPS might be connected are owned by the same
1270 non-root group and allow group read/write, though the group may vary
1271 because of distribution-specific or local administrative practice. If
1272 this assumption is false, gpsd may not be able to open GPS devices in
1273 order to read them (such failures will be logged).
1274 In order to fend off inadvertent denial-of-service attacks by port
1276 scanners (not to mention deliberate ones), gpsd will time out inactive
1277 client connections. Before the client has issued a command that
1278 requests a channel assignment, a short timeout (60 seconds) applies.
1279 There is no timeout for clients in watcher or raw modes; rather, gpsd
1280 drops these clients if they fail to read data long enough for the
1281 outbound socket write buffer to fill. Clients with an assigned device
1282 in polling mode are subject to a longer timeout (15 minutes).
1283
1285 If multiple NMEA talkers are feeding RMC, GLL, and GGA sentences to the
1286 same serial device (possible with an RS422 adapter hooked up to some
1287 marine-navigation systems), a 'TPV' response may mix an altitude from
1288 one device's GGA with latitude/longitude from another's RMC/GLL after
1289 the second sentence has arrived.
1290 gpsd may change control settings on your GPS (such as the emission
1292 frequency of various sentences or packets) and not restore the original
1293 settings on exit. This is a result of inadequacies in NMEA and the
1294 vendor binary GPS protocols, which often do not give clients any way to
1295 query the values of control settings in order to be able to restore
1296 them later.
1297 If your GPS uses a SiRF chipset at firmware level 231, reported UTC
1299 time may be off by the difference between 13 seconds and whatever
1300 leap-second correction is currently applicable, from startup until
1301 complete subframe information is received (normally about six seconds).
1302 Firmware levels 232 and up don't have this problem. You may run gpsd at
1303 debug level 4 to see the chipset type and firmware revision level.
1304 When using SiRF chips, the VDOP/TDOP/GDOP figures and associated error
1306 estimates are computed by gpsd rather than reported by the chip. The
1307 computation does not exactly match what SiRF chips do internally, which
1308 includes some satellite weighting using parameters gpsd cannot see.
1309 Autobauding on the Trimble GPSes can take as long as 5 seconds if the
1311 device speed is not matched to the GPS speed.
1312 If you are using an NMEA-only GPS (that is, not using SiRF or Garmin or
1314 Zodiac binary mode) and the GPS does not emit GPZDA at the start of its
1315 update cycle (which most consumer-grade NMEA GPSes do not) and it is
1316 after 2099, then the century part of the dates gpsd delivers will be
1317 wrong.
1318 Generation of position error estimates (eph, epv, epd, eps, epc) from
1320 the incomplete data handed back by GPS reporting protocols involves
1321 both a lot of mathematical black art and fragile device-dependent
1322 assumptions. This code has been bug-prone in tbe past and problems may
1323 still lurk there.
1324
1326 /dev/ttyS0
1327 Prototype TTY device. After startup, gpsd sets its group ID to the
1328 owner of this device if no GPS device was specified on the command
1329 line does not exist.
1330
1332 The official NMEA protocol standard is available on paper from the
1333 National Marine Electronics Association[3], but is proprietary and
1334 expensive; the maintainers of gpsd have made a point of not looking at
1335 it. The GPSD website[4] links to several documents that collect
1336 publicly disclosed information about the protocol.
1337 gpsd parses the following NMEA sentences: RMC, GGA, GLL, GSA, GSV, VTG,
1339 ZDA. It recognizes these with either the normal GP talker-ID prefix, or
1340 with the GN prefix used by GLONASS, or with the II prefix emitted by
1341 Seahawk Autohelm marine navigation systems, or with the IN prefix
1342 emitted by some Garmin units. It recognizes some vendor extensions: the
1343 PGRME emitted by some Garmin GPS models, the OHPR emitted by
1344 Oceanserver digital compasses, the PTNTHTM emitted by True North
1345 digital compasses, and the PASHR sentences emitted by some Ashtech
1346 GPSes.
1347 Note that gpsd JSON returns pure decimal degrees, not the hybrid
1349 degree/minute format described in the NMEA standard.
1350 Differential-GPS corrections are conveyed by the RTCM-104 proocol. The
1352 applicable standard for RTCM-104 V2 is RTCM Recommended Standards for
1353 Differential NAVSTAR GPS Service RTCM Paper 194-93/SC 104-STD. The
1354 applicable standard for RTCM-104 V3 is RTCM Standard 10403.1 for
1355 Differential GNSS Services - Version 3 RTCM Paper 177-2006-SC104-STD.
1356 AIS is defined by ITU Recommendation M.1371, Technical Characteristics
1358 for a Universal Shipborne Automatic Identification System Using Time
1359 Division Multiple Access. The AIVDM/AIVDO format understood by this
1360 progeam is defined by IEC-PAS 61162-100, Maritime navigation and
1361 radiocommunication equipment and systems
1362
1364 gps(1), libgps(3), libgpsd(3), gpsprof(1), gpsfake(1), gpsctl(1),
1365 gpscat(1), rtcm-104(5).
1366
1368 Remco Treffcorn, Derrick Brashear, Russ Nelson, Eric S. Raymond, Chris
1369 Kuethe. This manual page by Eric S. Raymond esr@thyrsus.com. There is a
1370 project site[4].
1371
1373 1. FAQ
1374 http://gpsd.berlios.de/faq.html
1375 2. AIVDM/AIVDO Protocol Decoding
1377 http://gpsd.berlios.de/AIVDM.html
1378 3. National Marine Electronics Association
1380 http://www.nmea.org/pub/0183/
1381 4. GPSD website
1383 http://gpsd.berlios.de/
1384The GPSD Project 9 Aug 2004 GPSD(8)