1GPSD_JSON(5) GPSD Documentation GPSD_JSON(5)
2
6 gpsd_json - gpsd request/response protocol
7
9 gpsd is a service daemon that can be used to monitor GPSes, DGPS
10 receivers, Marine AIS broadcasts, and various other location-related
11 and kinematic sensors.
12 Clients may communicate with gpsd via textual requests and responses
14 over a socket. It is a bad idea for applications to speak the protocol
15 directly: rather, they should use the libgps client library (for C;
16 bindings also exist for other languages) and take appropriate care to
17 conditionalize their code on the major and minor protocol version
18 symbols.
19 The GPSD protocol is built on top of JSON, JavaScript Object Notation,
21 as specified in RFC 7159: The JavaScript Object Notation (JSON) Data
22 Interchange Format. GPSD's use of JSON is restricted in some ways that
23 make parsing it in fixed-extent languages (such as C) easier.
24 A request line is introduced by "?" and may include multiple commands.
26 Commands begin with a command identifier, followed either by a
27 terminating ';' or by an equal sign "=" and a JSON object treated as an
28 argument. Any ';' or newline indication (either LF or CR-LF) after the
29 end of a command is ignored. All request lines must be composed of
30 US-ASCII characters and may be no more than 80 characters in length,
31 exclusive of the trailing newline.
32 Responses are JSON objects all of which have a "class" attribute the
34 value of which is either the name of the invoking command. There are
35 reports (including but not limited to as "TPV", "SKY", "DEVICE", and
36 "ERROR") which are not direct responses to commands.
37 The order of JSON attributes within a response object is never
39 significant, and you may specify command attributes in any order.
40 Responses never contain the special JSON value null; instead,
41 attributes with empty or undefined values are omitted. The length limit
42 for responses and reports is 1536 characters, including a trailing
43 newline; longer responses will be truncated, so client code must be
44 prepared for the possibility of invalid JSON fragments.
45 In JSON reports, if an attribute is present only if the parent
47 attribute is present or has a particular range, then the parent
48 attribute is emitted first.
49 There is one constraint on the order in which attributes will be
51 omitted. If an optional attribute is present only when a parent
52 attribute has a specified value or range of values, the parent
53 attribute will be emitted first to make parsing easier.
54 The next subsection section documents the core GPSD protocol.
56 Extensions are documented in the following subsections. The extensions
57 may not be supported in your gpsd instance if it has been compiled with
58 a restricted feature set.
59
61 Here are the core-protocol responses:
62 TPV
64 A TPV object is a time-position-velocity report. The "class" and
65 "mode" fields will reliably be present. The "mode" field will be
66 emitted before optional fields that may be absent when there is no
67 fix. Error estimates will be emitted after the fix components
68 they're associated with. Others may be reported or not depending on
69 the fix quality.
70 All error estimates (epc, epd, epe, eph, ept, epv, epx, epy) are
72 guessed to be 95% confidence, may also be 50%, one sigma, or two
73 sigma confidence. Many GNSS receivers do not specify a confidence
74 level. None specify how the value is calculated. Use error
75 estimates with caution, and only as relative "goodness" indicators.
76 If the GPS reports a value to gpsd, then gpsd will report that
77 value. Otherwise gpsd will try to compute the value from the
78 skyview.
79 Table 1. TPV object
81 ┌────────────┬─────────┬─────────┬──────────────────┐
82 │Name │ Always? │ Type │ Description │
83 ├────────────┼─────────┼─────────┼──────────────────┤
84 │class │ Yes │ string │ Fixed: "TPV" │
85 ├────────────┼─────────┼─────────┼──────────────────┤
86 │device │ No │ string │ Name of the │
87 │ │ │ │ originating │
88 │ │ │ │ device. │
89 ├────────────┼─────────┼─────────┼──────────────────┤
90 │status │ No │ numeric │ GPS fix status: │
91 │ │ │ │ %d, 2=DGPS fix, │
92 │ │ │ │ 3=RTK Fixed │
93 │ │ │ │ point, 4=RTK │
94 │ │ │ │ Floating point, │
95 │ │ │ │ 5=DR fix, │
96 │ │ │ │ 6=GNSSDR fix, │
97 │ │ │ │ 7=Time │
98 │ │ │ │ (surveyed) fix, │
99 │ │ │ │ 8=Simulated, │
100 │ │ │ │ 9=P(Y) fix, │
101 │ │ │ │ otherwise not │
102 │ │ │ │ present. Similar │
103 │ │ │ │ to FAA Quality │
104 │ │ │ │ Indicator in │
105 │ │ │ │ NMEA. │
106 ├────────────┼─────────┼─────────┼──────────────────┤
107 │mode │ Yes │ numeric │ NMEA mode: %d, │
108 │ │ │ │ 0=no mode value │
109 │ │ │ │ yet seen, 1=no │
110 │ │ │ │ fix, 2=2D, 3=3D. │
111 ├────────────┼─────────┼─────────┼──────────────────┤
112 │time │ No │ string │ Time/date stamp │
113 │ │ │ │ in ISO8601 │
114 │ │ │ │ format, UTC. May │
115 │ │ │ │ have a │
116 │ │ │ │ fractional part │
117 │ │ │ │ of up to .001sec │
118 │ │ │ │ precision. May │
119 │ │ │ │ be absent if the │
120 │ │ │ │ mode is not 2D │
121 │ │ │ │ or 3D. │
122 ├────────────┼─────────┼─────────┼──────────────────┤
123 │altHAE │ No │ numeric │ Altitude, height │
124 │ │ │ │ above allipsoid, │
125 │ │ │ │ in meters. │
126 │ │ │ │ Probably WGS84. │
127 ├────────────┼─────────┼─────────┼──────────────────┤
128 │altMSL │ No │ numeric │ MSL Altitude in │
129 │ │ │ │ meters. The │
130 │ │ │ │ geoid used is │
131 │ │ │ │ rarely specified │
132 │ │ │ │ and is often │
133 │ │ │ │ inaccurate. See │
134 │ │ │ │ the comments │
135 │ │ │ │ below on │
136 │ │ │ │ geoidSep. │
137 │ │ │ │ altMSL is altHAE │
138 │ │ │ │ minus geoidSep. │
139 ├────────────┼─────────┼─────────┼──────────────────┤
140 │alt │ No │ numeric │ Deprecated. │
141 │ │ │ │ Undefined. Use │
142 │ │ │ │ altHAE or │
143 │ │ │ │ altMSL. │
144 ├────────────┼─────────┼─────────┼──────────────────┤
145 │climb │ No │ numeric │ Climb (positive) │
146 │ │ │ │ or sink │
147 │ │ │ │ (negative) rate, │
148 │ │ │ │ meters per │
149 │ │ │ │ second. │
150 ├────────────┼─────────┼─────────┼──────────────────┤
151 │datum │ No │ string │ Current datum. │
152 │ │ │ │ Hopefully WGS84. │
153 ├────────────┼─────────┼─────────┼──────────────────┤
154 │depth │ No │ numeric │ Depth in meters. │
155 │ │ │ │ Probably depth │
156 │ │ │ │ below the │
157 │ │ │ │ keel... │
158 ├────────────┼─────────┼─────────┼──────────────────┤
159 │dgpsAge │ No │ numeric │ Age of DGPS │
160 │ │ │ │ data. In seconds │
161 ├────────────┼─────────┼─────────┼──────────────────┤
162 │dgpsSta │ No │ numeric │ Station of DGPS │
163 │ │ │ │ data. │
164 ├────────────┼─────────┼─────────┼──────────────────┤
165 │epc │ No │ numeric │ Estimated climb │
166 │ │ │ │ error in meters │
167 │ │ │ │ per second. │
168 │ │ │ │ Certainty │
169 │ │ │ │ unknown. │
170 ├────────────┼─────────┼─────────┼──────────────────┤
171 │epd │ No │ numeric │ Estimated track │
172 │ │ │ │ (direction) │
173 │ │ │ │ error in │
174 │ │ │ │ degrees. │
175 │ │ │ │ Certainty │
176 │ │ │ │ unknown. │
177 ├────────────┼─────────┼─────────┼──────────────────┤
178 │eph │ No │ numeric │ Estimated │
179 │ │ │ │ horizontal │
180 │ │ │ │ Position (2D) │
181 │ │ │ │ Error in meters. │
182 │ │ │ │ Also known as │
183 │ │ │ │ Estimated │
184 │ │ │ │ Position Error │
185 │ │ │ │ (epe). │
186 │ │ │ │ Certainty │
187 │ │ │ │ unknown. │
188 ├────────────┼─────────┼─────────┼──────────────────┤
189 │eps │ No │ numeric │ Estimated speed │
190 │ │ │ │ error in meters │
191 │ │ │ │ per second. │
192 │ │ │ │ Certainty │
193 │ │ │ │ unknown. │
194 ├────────────┼─────────┼─────────┼──────────────────┤
195 │ept │ No │ numeric │ Estimated │
196 │ │ │ │ timestamp error │
197 │ │ │ │ in seconds. │
198 │ │ │ │ Certainty │
199 │ │ │ │ unknown. │
200 ├────────────┼─────────┼─────────┼──────────────────┤
201 │epx │ No │ numeric │ Longitude error │
202 │ │ │ │ estimate in │
203 │ │ │ │ meters. │
204 │ │ │ │ Certainty │
205 │ │ │ │ unknown. │
206 ├────────────┼─────────┼─────────┼──────────────────┤
207 │epy │ No │ numeric │ Latitude error │
208 │ │ │ │ estimate in │
209 │ │ │ │ meters. │
210 │ │ │ │ Certainty │
211 │ │ │ │ unknown. │
212 ├────────────┼─────────┼─────────┼──────────────────┤
213 │epv │ No │ numeric │ Estimated │
214 │ │ │ │ vertical error │
215 │ │ │ │ in meters. │
216 │ │ │ │ Certainty │
217 │ │ │ │ unknown. │
218 ├────────────┼─────────┼─────────┼──────────────────┤
219 │geoidSep │ No │ numeric │ Geoid separation │
220 │ │ │ │ is the │
221 │ │ │ │ difference │
222 │ │ │ │ between the │
223 │ │ │ │ WGS84 reference │
224 │ │ │ │ ellipsoid and │
225 │ │ │ │ the geoid (Mean │
226 │ │ │ │ Sea Level) in │
227 │ │ │ │ meters. Almost │
228 │ │ │ │ no GNSS receiver │
229 │ │ │ │ specifies how │
230 │ │ │ │ they compute │
231 │ │ │ │ their geoid. │
232 │ │ │ │ gpsd │
233 │ │ │ │ interpolates the │
234 │ │ │ │ geoid from a 5x5 │
235 │ │ │ │ degree table of │
236 │ │ │ │ EGM2008 values │
237 │ │ │ │ when the │
238 │ │ │ │ receiver does │
239 │ │ │ │ not supply a │
240 │ │ │ │ geoid │
241 │ │ │ │ separation. The │
242 │ │ │ │ gpsd computed │
243 │ │ │ │ geoidSep is │
244 │ │ │ │ usually within │
245 │ │ │ │ one meter of the │
246 │ │ │ │ "true" value, │
247 │ │ │ │ but can be off │
248 │ │ │ │ as much as 12 │
249 │ │ │ │ meters. │
250 ├────────────┼─────────┼─────────┼──────────────────┤
251 │lat │ No │ numeric │ Latitude in │
252 │ │ │ │ degrees: +/- │
253 │ │ │ │ signifies │
254 │ │ │ │ North/South. │
255 ├────────────┼─────────┼─────────┼──────────────────┤
256 │leapseconds │ No │ integer │ Current leap │
257 │ │ │ │ seconds. │
258 ├────────────┼─────────┼─────────┼──────────────────┤
259 │lon │ No │ numeric │ Longitude in │
260 │ │ │ │ degrees: +/- │
261 │ │ │ │ signifies │
262 │ │ │ │ East/West. │
263 ├────────────┼─────────┼─────────┼──────────────────┤
264 │track │ No │ numeric │ Course over │
265 │ │ │ │ ground, degrees │
266 │ │ │ │ from true north. │
267 ├────────────┼─────────┼─────────┼──────────────────┤
268 │magtrack │ No │ numeric │ Course over │
269 │ │ │ │ ground, degrees │
270 │ │ │ │ magnetic. │
271 ├────────────┼─────────┼─────────┼──────────────────┤
272 │magvar │ No │ numeric │ Magnetic │
273 │ │ │ │ variation, │
274 │ │ │ │ degrees. Also │
275 │ │ │ │ known as the │
276 │ │ │ │ magnetic │
277 │ │ │ │ declination (the │
278 │ │ │ │ direction of the │
279 │ │ │ │ horizontal │
280 │ │ │ │ component of the │
281 │ │ │ │ magnetic field │
282 │ │ │ │ measured │
283 │ │ │ │ clockwise from │
284 │ │ │ │ north) in │
285 │ │ │ │ degrees, │
286 │ │ │ │ Positive is West │
287 │ │ │ │ variation. │
288 │ │ │ │ Negative is East │
289 │ │ │ │ variation. │
290 ├────────────┼─────────┼─────────┼──────────────────┤
291 │speed │ No │ numeric │ Speed over │
292 │ │ │ │ ground, meters │
293 │ │ │ │ per second. │
294 ├────────────┼─────────┼─────────┼──────────────────┤
295 │ecefx │ No │ numeric │ ECEF X position │
296 │ │ │ │ in meters. │
297 ├────────────┼─────────┼─────────┼──────────────────┤
298 │ecefy │ No │ numeric │ ECEF Y position │
299 │ │ │ │ in meters. │
300 ├────────────┼─────────┼─────────┼──────────────────┤
301 │ecefz │ No │ numeric │ ECEF Z position │
302 │ │ │ │ in meters. │
303 ├────────────┼─────────┼─────────┼──────────────────┤
304 │ecefpAcc │ No │ numeric │ ECEF position │
305 │ │ │ │ error in meters. │
306 │ │ │ │ Certainty │
307 │ │ │ │ unknown. │
308 ├────────────┼─────────┼─────────┼──────────────────┤
309 │ecefvx │ No │ numeric │ ECEF X velocity │
310 │ │ │ │ in meters per │
311 │ │ │ │ second. │
312 ├────────────┼─────────┼─────────┼──────────────────┤
313 │ecefvy │ No │ numeric │ ECEF Y velocity │
314 │ │ │ │ in meters per │
315 │ │ │ │ second. │
316 ├────────────┼─────────┼─────────┼──────────────────┤
317 │ecefvz │ No │ numeric │ ECEF Z velocity │
318 │ │ │ │ in meters per │
319 │ │ │ │ second. │
320 ├────────────┼─────────┼─────────┼──────────────────┤
321 │ecefvAcc │ No │ numeric │ ECEF velocity │
322 │ │ │ │ error in meters │
323 │ │ │ │ per second. │
324 │ │ │ │ Certainty │
325 │ │ │ │ unknown. │
326 ├────────────┼─────────┼─────────┼──────────────────┤
327 │sep │ No │ numeric │ Estimated │
328 │ │ │ │ Spherical (3D) │
329 │ │ │ │ Position Error │
330 │ │ │ │ in meters. │
331 │ │ │ │ Guessed to be │
332 │ │ │ │ 95% confidence, │
333 │ │ │ │ but many GNSS │
334 │ │ │ │ receivers do not │
335 │ │ │ │ specify, so │
336 │ │ │ │ certainty │
337 │ │ │ │ unknown. │
338 ├────────────┼─────────┼─────────┼──────────────────┤
339 │relD │ No │ numeric │ Down component │
340 │ │ │ │ of relative │
341 │ │ │ │ position vector │
342 │ │ │ │ in meters. │
343 ├────────────┼─────────┼─────────┼──────────────────┤
344 │relE │ No │ numeric │ East component │
345 │ │ │ │ of relative │
346 │ │ │ │ position vector │
347 │ │ │ │ in meters. │
348 ├────────────┼─────────┼─────────┼──────────────────┤
349 │relN │ No │ numeric │ North component │
350 │ │ │ │ of relative │
351 │ │ │ │ position vector │
352 │ │ │ │ in meters. │
353 ├────────────┼─────────┼─────────┼──────────────────┤
354 │velD │ No │ numeric │ Down velocity │
355 │ │ │ │ component in │
356 │ │ │ │ meters. │
357 ├────────────┼─────────┼─────────┼──────────────────┤
358 │velE │ No │ numeric │ wEast velocity │
359 │ │ │ │ component in │
360 │ │ │ │ meters. │
361 ├────────────┼─────────┼─────────┼──────────────────┤
362 │velN │ No │ numeric │ North velocity │
363 │ │ │ │ component in │
364 │ │ │ │ meters. │
365 ├────────────┼─────────┼─────────┼──────────────────┤
366 │wanglem │ No │ numeric │ Wind angle │
367 │ │ │ │ magnetic in │
368 │ │ │ │ degrees. │
369 ├────────────┼─────────┼─────────┼──────────────────┤
370 │wangler │ No │ numeric │ Wind angle │
371 │ │ │ │ relative in │
372 │ │ │ │ degrees. │
373 ├────────────┼─────────┼─────────┼──────────────────┤
374 │wanglet │ No │ numeric │ Wind angle true │
375 │ │ │ │ in degrees. │
376 ├────────────┼─────────┼─────────┼──────────────────┤
377 │wspeedr │ No │ numeric │ Wind speed │
378 │ │ │ │ relative in │
379 │ │ │ │ meters per │
380 │ │ │ │ second. │
381 ├────────────┼─────────┼─────────┼──────────────────┤
382 │wspeedt │ No │ numeric │ Wind speed true │
383 │ │ │ │ in meters per │
384 │ │ │ │ second. │
385 └────────────┴─────────┴─────────┴──────────────────┘
386 When the C client library parses a response of this kind, it will
387 assert validity bits in the top-level set member for each field
388 received; see gps.h for bitmask names and values.
389 Invalid or unknown floating-point values will be set to NAN. Always
391 check floating points with isfinite() before use.
392 Here's an example:
394 {"class":"TPV","device":"/dev/pts/1",
396 "time":"2005-06-08T10:34:48.283Z","ept":0.005,
397 "lat":46.498293369,"lon":7.567411672,"alt":1343.127,
398 "eph":36.000,"epv":32.321,
399 "track":10.3788,"speed":0.091,"climb":-0.085,"mode":3}
400 SKY
402 A SKY object reports a sky view of the GPS satellite positions. If
403 there is no GPS device available, or no skyview has been reported
404 yet, only the "class" field will reliably be present.
405 Table 2. SKY object
407 ┌───────────┬─────────┬─────────┬──────────────────┐
408 │Name │ Always? │ Type │ Description │
409 ├───────────┼─────────┼─────────┼──────────────────┤
410 │class │ Yes │ string │ Fixed: "SKY" │
411 ├───────────┼─────────┼─────────┼──────────────────┤
412 │device │ No │ string │ Name of │
413 │ │ │ │ originating │
414 │ │ │ │ device │
415 ├───────────┼─────────┼─────────┼──────────────────┤
416 │time │ No │ string │ Time/date stamp │
417 │ │ │ │ in ISO8601 │
418 │ │ │ │ format, UTC. May │
419 │ │ │ │ have a │
420 │ │ │ │ fractional part │
421 │ │ │ │ of up to .001sec │
422 │ │ │ │ precision. │
423 ├───────────┼─────────┼─────────┼──────────────────┤
424 │gdop │ No │ numeric │ Geometric │
425 │ │ │ │ (hyperspherical) │
426 │ │ │ │ dilution of │
427 │ │ │ │ precision, a │
428 │ │ │ │ combination of │
429 │ │ │ │ PDOP and TDOP. │
430 │ │ │ │ A dimensionless │
431 │ │ │ │ factor which │
432 │ │ │ │ should be │
433 │ │ │ │ multiplied by a │
434 │ │ │ │ base UERE to get │
435 │ │ │ │ an error │
436 │ │ │ │ estimate. │
437 ├───────────┼─────────┼─────────┼──────────────────┤
438 │hdop │ No │ numeric │ Horizontal │
439 │ │ │ │ dilution of │
440 │ │ │ │ precision, a │
441 │ │ │ │ dimensionless │
442 │ │ │ │ factor which │
443 │ │ │ │ should be │
444 │ │ │ │ multiplied by a │
445 │ │ │ │ base UERE to get │
446 │ │ │ │ a circular error │
447 │ │ │ │ estimate. │
448 ├───────────┼─────────┼─────────┼──────────────────┤
449 │pdop │ No │ numeric │ Position │
450 │ │ │ │ (spherical/3D) │
451 │ │ │ │ dilution of │
452 │ │ │ │ precision, a │
453 │ │ │ │ dimensionless │
454 │ │ │ │ factor which │
455 │ │ │ │ should be │
456 │ │ │ │ multiplied by a │
457 │ │ │ │ base UERE to get │
458 │ │ │ │ an error │
459 │ │ │ │ estimate. │
460 ├───────────┼─────────┼─────────┼──────────────────┤
461 │tdop │ No │ numeric │ Time dilution of │
462 │ │ │ │ precision, a │
463 │ │ │ │ dimensionless │
464 │ │ │ │ factor which │
465 │ │ │ │ should be │
466 │ │ │ │ multiplied by a │
467 │ │ │ │ base UERE to get │
468 │ │ │ │ an error │
469 │ │ │ │ estimate. │
470 ├───────────┼─────────┼─────────┼──────────────────┤
471 │vdop │ No │ numeric │ Vertical │
472 │ │ │ │ (altitude) │
473 │ │ │ │ dilution of │
474 │ │ │ │ precision, a │
475 │ │ │ │ dimensionless │
476 │ │ │ │ factor which │
477 │ │ │ │ should be │
478 │ │ │ │ multiplied by a │
479 │ │ │ │ base UERE to get │
480 │ │ │ │ an error │
481 │ │ │ │ estimate. │
482 ├───────────┼─────────┼─────────┼──────────────────┤
483 │xdop │ No │ numeric │ Longitudinal │
484 │ │ │ │ dilution of │
485 │ │ │ │ precision, a │
486 │ │ │ │ dimensionless │
487 │ │ │ │ factor which │
488 │ │ │ │ should be │
489 │ │ │ │ multiplied by a │
490 │ │ │ │ base UERE to get │
491 │ │ │ │ an error │
492 │ │ │ │ estimate. │
493 ├───────────┼─────────┼─────────┼──────────────────┤
494 │ydop │ No │ numeric │ Latitudinal │
495 │ │ │ │ dilution of │
496 │ │ │ │ precision, a │
497 │ │ │ │ dimensionless │
498 │ │ │ │ factor which │
499 │ │ │ │ should be │
500 │ │ │ │ multiplied by a │
501 │ │ │ │ base UERE to get │
502 │ │ │ │ an error │
503 │ │ │ │ estimate. │
504 ├───────────┼─────────┼─────────┼──────────────────┤
505 │nSat │ No │ numeric │ Number of │
506 │ │ │ │ satellite │
507 │ │ │ │ objects in │
508 │ │ │ │ "satellites" │
509 │ │ │ │ array. │
510 ├───────────┼─────────┼─────────┼──────────────────┤
511 │uSat │ No │ numeric │ Number of │
512 │ │ │ │ satellites used │
513 │ │ │ │ in navigation │
514 │ │ │ │ solution. │
515 ├───────────┼─────────┼─────────┼──────────────────┤
516 │satellites │ Yes │ list │ List of │
517 │ │ │ │ satellite │
518 │ │ │ │ objects in │
519 │ │ │ │ skyview │
520 └───────────┴─────────┴─────────┴──────────────────┘
521 Many devices compute dilution of precision factors but do not
522 include them in their reports. Many that do report DOPs report only
523 HDOP, two-dimensional circular error. gpsd always passes through
524 whatever the device reports, then attempts to fill in other DOPs by
525 calculating the appropriate determinants in a covariance matrix
526 based on the satellite view. DOPs may be missing if some of these
527 determinants are singular. It can even happen that the device
528 reports an error estimate in meters when the corresponding DOP is
529 unavailable; some devices use more sophisticated error modeling
530 than the covariance calculation.
531 The satellite list objects have the following elements:
533 Table 3. Satellite object
535 ┌───────┬─────────┬─────────┬──────────────────┐
536 │Name │ Always? │ Type │ Description │
537 ├───────┼─────────┼─────────┼──────────────────┤
538 │PRN │ Yes │ numeric │ PRN ID of the │
539 │ │ │ │ satellite. 1-63 │
540 │ │ │ │ are GNSS │
541 │ │ │ │ satellites, │
542 │ │ │ │ 64-96 are │
543 │ │ │ │ GLONASS │
544 │ │ │ │ satellites, │
545 │ │ │ │ 100-164 are SBAS │
546 │ │ │ │ satellites │
547 ├───────┼─────────┼─────────┼──────────────────┤
548 │az │ No │ numeric │ Azimuth, degrees │
549 │ │ │ │ from true north. │
550 ├───────┼─────────┼─────────┼──────────────────┤
551 │el │ No │ numeric │ Elevation in │
552 │ │ │ │ degrees. │
553 ├───────┼─────────┼─────────┼──────────────────┤
554 │ss │ No │ numeric │ Signal to Noise │
555 │ │ │ │ ratio in dBHz. │
556 ├───────┼─────────┼─────────┼──────────────────┤
557 │used │ Yes │ boolean │ Used in current │
558 │ │ │ │ solution? │
559 │ │ │ │ (SBAS/WAAS/EGNOS │
560 │ │ │ │ satellites may │
561 │ │ │ │ be flagged used │
562 │ │ │ │ if the solution │
563 │ │ │ │ has corrections │
564 │ │ │ │ from them, but │
565 │ │ │ │ not all drivers │
566 │ │ │ │ make this │
567 │ │ │ │ information │
568 │ │ │ │ available.) │
569 ├───────┼─────────┼─────────┼──────────────────┤
570 │gnssid │ No │ numeric │ The GNSS ID, as │
571 │ │ │ │ defined by │
572 │ │ │ │ u-blox, not │
573 │ │ │ │ NMEA. 0=GPS, │
574 │ │ │ │ 2=Galileo, │
575 │ │ │ │ 3=Beidou, │
576 │ │ │ │ 5=QZSS, │
577 │ │ │ │ 6-GLONASS. │
578 ├───────┼─────────┼─────────┼──────────────────┤
579 │svid │ No │ numeric │ The satellite ID │
580 │ │ │ │ within its │
581 │ │ │ │ constellation. │
582 │ │ │ │ As defined by │
583 │ │ │ │ u-blox, not │
584 │ │ │ │ NMEA). │
585 ├───────┼─────────┼─────────┼──────────────────┤
586 │sigid │ No │ numeric │ The signal ID of │
587 │ │ │ │ this signal. As │
588 │ │ │ │ defined by │
589 │ │ │ │ u-blox, not │
590 │ │ │ │ NMEA. See u-blox │
591 │ │ │ │ doc for details. │
592 ├───────┼─────────┼─────────┼──────────────────┤
593 │freqid │ No │ numeric │ For GLONASS │
594 │ │ │ │ satellites only: │
595 │ │ │ │ the frequency ID │
596 │ │ │ │ of the signal. │
597 │ │ │ │ As defined by │
598 │ │ │ │ u-blox, range 0 │
599 │ │ │ │ to 13. The │
600 │ │ │ │ freqid is the │
601 │ │ │ │ frequency slot │
602 │ │ │ │ plus 7. │
603 ├───────┼─────────┼─────────┼──────────────────┤
604 │health │ No │ numeric │ The health of │
605 │ │ │ │ this satellite. │
606 │ │ │ │ 0 is unknown, 1 │
607 │ │ │ │ is OK, and 2 is │
608 │ │ │ │ unhealthy. │
609 └───────┴─────────┴─────────┴──────────────────┘
610 Note that satellite objects do not have a "class" field, as they
611 are never shipped outside of a SKY object.
612 When the C client library parses a SKY response, it will assert the
614 SATELLITE_SET bit in the top-level set member.
615 Here's an example:
617 {"class":"SKY","device":"/dev/pts/1",
619 "time":"2005-07-08T11:28:07.114Z",
620 "xdop":1.55,"hdop":1.24,"pdop":1.99,
621 "satellites":[
622 {"PRN":23,"el":6,"az":84,"ss":0,"used":false},
623 {"PRN":28,"el":7,"az":160,"ss":0,"used":false},
624 {"PRN":8,"el":66,"az":189,"ss":44,"used":true},
625 {"PRN":29,"el":13,"az":273,"ss":0,"used":false},
626 {"PRN":10,"el":51,"az":304,"ss":29,"used":true},
627 {"PRN":4,"el":15,"az":199,"ss":36,"used":true},
628 {"PRN":2,"el":34,"az":241,"ss":43,"used":true},
629 {"PRN":27,"el":71,"az":76,"ss":43,"used":true}]}
630 GST
632 A GST object is a pseudorange noise report.
633 Table 4. GST object
635 ┌───────┬─────────┬─────────┬──────────────────┐
636 │Name │ Always? │ Type │ Description │
637 ├───────┼─────────┼─────────┼──────────────────┤
638 │class │ Yes │ string │ Fixed: "GST" │
639 ├───────┼─────────┼─────────┼──────────────────┤
640 │device │ No │ string │ Name of │
641 │ │ │ │ originating │
642 │ │ │ │ device │
643 ├───────┼─────────┼─────────┼──────────────────┤
644 │time │ No │ string │ Time/date stamp │
645 │ │ │ │ in ISO8601 │
646 │ │ │ │ format, UTC. May │
647 │ │ │ │ have a │
648 │ │ │ │ fractional part │
649 │ │ │ │ of up to .001sec │
650 │ │ │ │ precision. │
651 ├───────┼─────────┼─────────┼──────────────────┤
652 │rms │ No │ numeric │ Value of the │
653 │ │ │ │ standard │
654 │ │ │ │ deviation of the │
655 │ │ │ │ range inputs to │
656 │ │ │ │ the navigation │
657 │ │ │ │ process (range │
658 │ │ │ │ inputs include │
659 │ │ │ │ pseudoranges and │
660 │ │ │ │ DGPS │
661 │ │ │ │ corrections). │
662 ├───────┼─────────┼─────────┼──────────────────┤
663 │major │ No │ numeric │ Standard │
664 │ │ │ │ deviation of │
665 │ │ │ │ semi-major axis │
666 │ │ │ │ of error │
667 │ │ │ │ ellipse, in │
668 │ │ │ │ meters. │
669 ├───────┼─────────┼─────────┼──────────────────┤
670 │minor │ No │ numeric │ Standard │
671 │ │ │ │ deviation of │
672 │ │ │ │ semi-minor axis │
673 │ │ │ │ of error │
674 │ │ │ │ ellipse, in │
675 │ │ │ │ meters. │
676 ├───────┼─────────┼─────────┼──────────────────┤
677 │orient │ No │ numeric │ Orientation of │
678 │ │ │ │ semi-major axis │
679 │ │ │ │ of error │
680 │ │ │ │ ellipse, in │
681 │ │ │ │ degrees from │
682 │ │ │ │ true north. │
683 ├───────┼─────────┼─────────┼──────────────────┤
684 │lat │ No │ numeric │ Standard │
685 │ │ │ │ deviation of │
686 │ │ │ │ latitude error, │
687 │ │ │ │ in meters. │
688 ├───────┼─────────┼─────────┼──────────────────┤
689 │lon │ No │ numeric │ Standard │
690 │ │ │ │ deviation of │
691 │ │ │ │ longitude error, │
692 │ │ │ │ in meters. │
693 ├───────┼─────────┼─────────┼──────────────────┤
694 │alt │ No │ numeric │ Standard │
695 │ │ │ │ deviation of │
696 │ │ │ │ altitude error, │
697 │ │ │ │ in meters. │
698 └───────┴─────────┴─────────┴──────────────────┘
699 Here's an example:
700 {"class":"GST","device":"/dev/ttyUSB0",
702 "time":"2010-12-07T10:23:07.096Z","rms":2.440,
703 "major":1.660,"minor":1.120,"orient":68.989,
704 "lat":1.600,"lon":1.200,"alt":2.520}
705 ATT
707 An ATT object is a vehicle-attitude report. It is returned by
708 digital-compass and gyroscope sensors; depending on device, it may
709 include: heading, pitch, roll, yaw, gyroscope, and magnetic-field
710 readings. Because such sensors are often bundled as part of
711 marine-navigation systems, the ATT response may also include water
712 depth.
713 The "class" and "mode" fields will reliably be present. Others may
715 be reported or not depending on the specific device type.
716 Table 5. ATT object
718 ┌─────────┬─────────┬─────────┬──────────────────┐
719 │Name │ Always? │ Type │ Description │
720 ├─────────┼─────────┼─────────┼──────────────────┤
721 │class │ Yes │ string │ Fixed: "ATT" │
722 ├─────────┼─────────┼─────────┼──────────────────┤
723 │device │ Yes │ string │ Name of │
724 │ │ │ │ originating │
725 │ │ │ │ device │
726 ├─────────┼─────────┼─────────┼──────────────────┤
727 │time │ No │ string │ Time/date stamp │
728 │ │ │ │ in ISO8601 │
729 │ │ │ │ format, UTC. May │
730 │ │ │ │ have a │
731 │ │ │ │ fractional part │
732 │ │ │ │ of up to .001sec │
733 │ │ │ │ precision. │
734 ├─────────┼─────────┼─────────┼──────────────────┤
735 │heading │ No │ numeric │ Heading, degrees │
736 │ │ │ │ from true north. │
737 ├─────────┼─────────┼─────────┼──────────────────┤
738 │mag_st │ No │ string │ Magnetometer │
739 │ │ │ │ status. │
740 ├─────────┼─────────┼─────────┼──────────────────┤
741 │pitch │ No │ numeric │ Pitch in │
742 │ │ │ │ degrees. │
743 ├─────────┼─────────┼─────────┼──────────────────┤
744 │pitch_st │ No │ string │ Pitch sensor │
745 │ │ │ │ status. │
746 ├─────────┼─────────┼─────────┼──────────────────┤
747 │yaw │ No │ numeric │ Yaw in degrees │
748 ├─────────┼─────────┼─────────┼──────────────────┤
749 │yaw_st │ No │ string │ Yaw sensor │
750 │ │ │ │ status. │
751 ├─────────┼─────────┼─────────┼──────────────────┤
752 │roll │ No │ numeric │ Roll in degrees. │
753 ├─────────┼─────────┼─────────┼──────────────────┤
754 │roll_st │ No │ string │ Roll sensor │
755 │ │ │ │ status. │
756 ├─────────┼─────────┼─────────┼──────────────────┤
757 │dip │ No │ numeric │ Local magnetic │
758 │ │ │ │ inclination, │
759 │ │ │ │ degrees, │
760 │ │ │ │ positive when │
761 │ │ │ │ the magnetic │
762 │ │ │ │ field points │
763 │ │ │ │ downward (into │
764 │ │ │ │ the Earth). │
765 ├─────────┼─────────┼─────────┼──────────────────┤
766 │mag_len │ No │ numeric │ Scalar magnetic │
767 │ │ │ │ field strength. │
768 ├─────────┼─────────┼─────────┼──────────────────┤
769 │mag_x │ No │ numeric │ X component of │
770 │ │ │ │ magnetic field │
771 │ │ │ │ strength. │
772 ├─────────┼─────────┼─────────┼──────────────────┤
773 │mag_y │ No │ numeric │ Y component of │
774 │ │ │ │ magnetic field │
775 │ │ │ │ strength. │
776 ├─────────┼─────────┼─────────┼──────────────────┤
777 │mag_z │ No │ numeric │ Z component of │
778 │ │ │ │ magnetic field │
779 │ │ │ │ strength. │
780 ├─────────┼─────────┼─────────┼──────────────────┤
781 │acc_len │ No │ numeric │ Scalar │
782 │ │ │ │ acceleration. │
783 ├─────────┼─────────┼─────────┼──────────────────┤
784 │acc_x │ No │ numeric │ X component of │
785 │ │ │ │ acceleration. │
786 ├─────────┼─────────┼─────────┼──────────────────┤
787 │acc_y │ No │ numeric │ Y component of │
788 │ │ │ │ acceleration. │
789 ├─────────┼─────────┼─────────┼──────────────────┤
790 │acc_z │ No │ numeric │ Z component of │
791 │ │ │ │ acceleration. │
792 ├─────────┼─────────┼─────────┼──────────────────┤
793 │gyro_x │ No │ numeric │ X component of │
794 │ │ │ │ acceleration. │
795 ├─────────┼─────────┼─────────┼──────────────────┤
796 │gyro_y │ No │ numeric │ Y component of │
797 │ │ │ │ acceleration. │
798 ├─────────┼─────────┼─────────┼──────────────────┤
799 │depth │ No │ numeric │ Water depth in │
800 │ │ │ │ meters. │
801 ├─────────┼─────────┼─────────┼──────────────────┤
802 │temp │ No │ numeric │ Temperature at │
803 │ │ │ │ the sensor, │
804 │ │ │ │ degrees │
805 │ │ │ │ centigrade. │
806 └─────────┴─────────┴─────────┴──────────────────┘
807 The heading, pitch, and roll status codes (if present) vary by
808 device. For the TNT Revolution digital compasses, they are coded as
809 follows:
810 Table 6. Device flags
812 ┌─────┬────────────────────────────┐
813 │Code │ Description │
814 ├─────┼────────────────────────────┤
815 │C │ magnetometer calibration │
816 │ │ alarm │
817 ├─────┼────────────────────────────┤
818 │L │ low alarm │
819 ├─────┼────────────────────────────┤
820 │M │ low warning │
821 ├─────┼────────────────────────────┤
822 │N │ normal │
823 ├─────┼────────────────────────────┤
824 │O │ high warning │
825 ├─────┼────────────────────────────┤
826 │P │ high alarm │
827 ├─────┼────────────────────────────┤
828 │V │ magnetometer voltage level │
829 │ │ alarm │
830 └─────┴────────────────────────────┘
831 When the C client library parses a response of this kind, it will
832 assert ATT_IS.
833 Here's an example:
835 {"class":"ATT","time":1270938096.843,
837 "heading":14223.00,"mag_st":"N",
838 "pitch":169.00,"pitch_st":"N", "roll":-43.00,"roll_st":"N",
839 "dip":13641.000,"mag_x":2454.000}
840 And here are the commands:
842 ?VERSION;
844 Returns an object with the following attributes:
845 Table 7. VERSION object
847 ┌────────────┬─────────┬─────────┬──────────────────┐
848 │Name │ Always? │ Type │ Description │
849 ├────────────┼─────────┼─────────┼──────────────────┤
850 │class │ Yes │ string │ Fixed: "VERSION" │
851 ├────────────┼─────────┼─────────┼──────────────────┤
852 │release │ Yes │ string │ Public release │
853 │ │ │ │ level │
854 ├────────────┼─────────┼─────────┼──────────────────┤
855 │rev │ Yes │ string │ Internal │
856 │ │ │ │ revision-control │
857 │ │ │ │ level. │
858 ├────────────┼─────────┼─────────┼──────────────────┤
859 │proto_major │ Yes │ numeric │ API major │
860 │ │ │ │ revision level. │
861 ├────────────┼─────────┼─────────┼──────────────────┤
862 │proto_minor │ Yes │ numeric │ API minor │
863 │ │ │ │ revision level. │
864 ├────────────┼─────────┼─────────┼──────────────────┤
865 │remote │ No │ string │ URL of the │
866 │ │ │ │ remote daemon │
867 │ │ │ │ reporting this │
868 │ │ │ │ version. If │
869 │ │ │ │ empty, this is │
870 │ │ │ │ the version of │
871 │ │ │ │ the local │
872 │ │ │ │ daemon. │
873 └────────────┴─────────┴─────────┴──────────────────┘
874 The daemon ships a VERSION response to each client when the client
875 first connects to it.
876 When the C client library parses a response of this kind, it will
878 assert the VERSION_SET bit in the top-level set member.
879 Here's an example:
881 {"class":"VERSION","version":"2.40dev",
883 "rev":"06f62e14eae9886cde907dae61c124c53eb1101f",
884 "proto_major":3,"proto_minor":1
885 }
886 ?DEVICES;
888 Returns a device list object with the following elements:
889 Table 8. DEVICES object
891 ┌────────┬─────────┬────────┬──────────────────┐
892 │Name │ Always? │ Type │ Description │
893 ├────────┼─────────┼────────┼──────────────────┤
894 │class │ Yes │ string │ Fixed: "DEVICES" │
895 ├────────┼─────────┼────────┼──────────────────┤
896 │devices │ Yes │ list │ List of device │
897 │ │ │ │ descriptions │
898 ├────────┼─────────┼────────┼──────────────────┤
899 │remote │ No │ string │ URL of the │
900 │ │ │ │ remote daemon │
901 │ │ │ │ reporting the │
902 │ │ │ │ device set. If │
903 │ │ │ │ empty, this is a │
904 │ │ │ │ DEVICES response │
905 │ │ │ │ from the local │
906 │ │ │ │ daemon. │
907 └────────┴─────────┴────────┴──────────────────┘
908 When the C client library parses a response of this kind, it will
909 assert the DEVICELIST_SET bit in the top-level set member.
910 Here's an example:
912 {"class"="DEVICES","devices":[
914 {"class":"DEVICE","path":"/dev/pts/1","flags":1,"driver":"SiRF binary"},
915 {"class":"DEVICE","path":"/dev/pts/3","flags":4,"driver":"AIVDM"}]}
916 The daemon occasionally ships a bare DEVICE object to the client
918 (that is, one not inside a DEVICES wrapper). The data content of
919 these objects will be described later as a response to the ?DEVICE
920 command.
921 ?WATCH;
923 This command sets watcher mode. It also sets or elicits a report of
924 per-subscriber policy and the raw bit. An argument WATCH object
925 changes the subscriber's policy. The response describes the
926 subscriber's policy. The response will also include a DEVICES
927 object.
928 A WATCH object has the following elements:
930 Table 9. WATCH object
932 ┌────────┬─────────┬─────────┬──────────────────┐
933 │Name │ Always? │ Type │ Description │
934 ├────────┼─────────┼─────────┼──────────────────┤
935 │class │ Yes │ string │ Fixed: "WATCH" │
936 ├────────┼─────────┼─────────┼──────────────────┤
937 │enable │ No │ boolean │ Enable (true) or │
938 │ │ │ │ disable (false) │
939 │ │ │ │ watcher mode. │
940 │ │ │ │ Default is true. │
941 ├────────┼─────────┼─────────┼──────────────────┤
942 │json │ No │ boolean │ Enable (true) or │
943 │ │ │ │ disable (false) │
944 │ │ │ │ dumping of JSON │
945 │ │ │ │ reports. │
946 │ │ │ │ Default is │
947 │ │ │ │ false. │
948 ├────────┼─────────┼─────────┼──────────────────┤
949 │nmea │ No │ boolean │ Enable (true) or │
950 │ │ │ │ disable (false) │
951 │ │ │ │ dumping of │
952 │ │ │ │ binary packets │
953 │ │ │ │ as pseudo-NMEA. │
954 │ │ │ │ Default is │
955 │ │ │ │ false. │
956 ├────────┼─────────┼─────────┼──────────────────┤
957 │raw │ No │ integer │ Controls 'raw' │
958 │ │ │ │ mode. When this │
959 │ │ │ │ attribute is set │
960 │ │ │ │ to 1 for a │
961 │ │ │ │ channel, gpsd │
962 │ │ │ │ reports the │
963 │ │ │ │ unprocessed NMEA │
964 │ │ │ │ or AIVDM data │
965 │ │ │ │ stream from │
966 │ │ │ │ whatever device │
967 │ │ │ │ is attached. │
968 │ │ │ │ Binary GPS │
969 │ │ │ │ packets are │
970 │ │ │ │ hex-dumped. │
971 │ │ │ │ RTCM2 and RTCM3 │
972 │ │ │ │ packets are not │
973 │ │ │ │ dumped in raw │
974 │ │ │ │ mode. When this │
975 │ │ │ │ attribute is set │
976 │ │ │ │ to 2 for a │
977 │ │ │ │ channel that │
978 │ │ │ │ processes binary │
979 │ │ │ │ data, gpsd │
980 │ │ │ │ reports the │
981 │ │ │ │ received data │
982 │ │ │ │ verbatim without │
983 │ │ │ │ hex-dumping. │
984 ├────────┼─────────┼─────────┼──────────────────┤
985 │scaled │ No │ boolean │ If true, apply │
986 │ │ │ │ scaling divisors │
987 │ │ │ │ to output before │
988 │ │ │ │ dumping; default │
989 │ │ │ │ is false. │
990 ├────────┼─────────┼─────────┼──────────────────┤
991 │split24 │ No │ boolean │ If true, │
992 │ │ │ │ aggregate AIS │
993 │ │ │ │ type24 sentence │
994 │ │ │ │ parts. If │
995 │ │ │ │ false, report │
996 │ │ │ │ each part as a │
997 │ │ │ │ separate JSON │
998 │ │ │ │ object, leaving │
999 │ │ │ │ the client to │
1000 │ │ │ │ match MMSIs and │
1001 │ │ │ │ aggregate. │
1002 │ │ │ │ Default is │
1003 │ │ │ │ false. Applies │
1004 │ │ │ │ only to AIS │
1005 │ │ │ │ reports. │
1006 ├────────┼─────────┼─────────┼──────────────────┤
1007 │pps │ No │ boolean │ If true, emit │
1008 │ │ │ │ the TOFF JSON │
1009 │ │ │ │ message on each │
1010 │ │ │ │ cycle and a PPS │
1011 │ │ │ │ JSON message │
1012 │ │ │ │ when the device │
1013 │ │ │ │ issues 1PPS. │
1014 │ │ │ │ Default is │
1015 │ │ │ │ false. │
1016 ├────────┼─────────┼─────────┼──────────────────┤
1017 │device │ No │ string │ If present, │
1018 │ │ │ │ enable watching │
1019 │ │ │ │ only of the │
1020 │ │ │ │ specified device │
1021 │ │ │ │ rather than all │
1022 │ │ │ │ devices. Useful │
1023 │ │ │ │ with raw and │
1024 │ │ │ │ NMEA modes in │
1025 │ │ │ │ which device │
1026 │ │ │ │ responses aren't │
1027 │ │ │ │ tagged. Has no │
1028 │ │ │ │ effect when used │
1029 │ │ │ │ with │
1030 │ │ │ │ enable:false. │
1031 ├────────┼─────────┼─────────┼──────────────────┤
1032 │remote │ No │ string │ URL of the │
1033 │ │ │ │ remote daemon │
1034 │ │ │ │ reporting the │
1035 │ │ │ │ watch set. If │
1036 │ │ │ │ empty, this is a │
1037 │ │ │ │ WATCH response │
1038 │ │ │ │ from the local │
1039 │ │ │ │ daemon. │
1040 └────────┴─────────┴─────────┴──────────────────┘
1041 There is an additional boolean "timing" attribute which is
1042 undocumented because that portion of the interface is considered
1043 unstable and for developer use only.
1044 In watcher mode, GPS reports are dumped as TPV and SKY responses.
1046 AIS, Subframe and RTCM reporting is described in the next section.
1047 When the C client library parses a response of this kind, it will
1049 assert the POLICY_SET bit in the top-level set member.
1050 Here's an example:
1052 {"class":"WATCH", "raw":1,"scaled":true}
1054 ?POLL;
1056 The POLL command requests data from the last-seen fixes on all
1057 active GPS devices. Devices must previously have been activated by
1058 ?WATCH to be pollable.
1059 Polling can lead to possibly surprising results when it is used on
1061 a device such as an NMEA GPS for which a complete fix has to be
1062 accumulated from several sentences. If you poll while those
1063 sentences are being emitted, the response will contain the last
1064 complete fix data and may be as much as one cycle time (typically 1
1065 second) stale.
1066 The POLL response will contain a timestamped list of TPV objects
1068 describing cached data, and a timestamped list of SKY objects
1069 describing satellite configuration. If a device has not seen fixes,
1070 it will be reported with a mode field of zero.
1071 Table 10. POLL object
1073 ┌───────┬─────────┬────────────┬──────────────────┐
1074 │Name │ Always? │ Type │ Description │
1075 ├───────┼─────────┼────────────┼──────────────────┤
1076 │class │ Yes │ string │ Fixed: "POLL" │
1077 ├───────┼─────────┼────────────┼──────────────────┤
1078 │time │ Yes │ Numeric │ Timestamp in ISO │
1079 │ │ │ │ 8601 format. May │
1080 │ │ │ │ have a │
1081 │ │ │ │ fractional part │
1082 │ │ │ │ of up to .001sec │
1083 │ │ │ │ precision. │
1084 ├───────┼─────────┼────────────┼──────────────────┤
1085 │active │ Yes │ Numeric │ Count of active │
1086 │ │ │ │ devices. │
1087 ├───────┼─────────┼────────────┼──────────────────┤
1088 │tpv │ Yes │ JSON array │ Comma-separated │
1089 │ │ │ │ list of TPV │
1090 │ │ │ │ objects. │
1091 ├───────┼─────────┼────────────┼──────────────────┤
1092 │sky │ Yes │ JSON array │ Comma-separated │
1093 │ │ │ │ list of SKY │
1094 │ │ │ │ objects. │
1095 └───────┴─────────┴────────────┴──────────────────┘
1096 Here's an example of a POLL response:
1097 {"class":"POLL","time":"2010-06-04T10:31:00.289Z","active":1,
1099 "tpv":[{"class":"TPV","device":"/dev/ttyUSB0",
1100 "time":"2010-09-08T13:33:06.095Z",
1101 "ept":0.005,"lat":40.035093060,
1102 "lon":-75.519748733,"track":99.4319,"speed":0.123,"mode":2}],
1103 "sky":[{"class":"SKY","device":"/dev/ttyUSB0",
1104 "time":1270517264.240,"hdop":9.20,
1105 "satellites":[{"PRN":16,"el":55,"az":42,"ss":36,"used":true},
1106 {"PRN":19,"el":25,"az":177,"ss":0,"used":false},
1107 {"PRN":7,"el":13,"az":295,"ss":0,"used":false},
1108 {"PRN":6,"el":56,"az":135,"ss":32,"used":true},
1109 {"PRN":13,"el":47,"az":304,"ss":0,"used":false},
1110 {"PRN":23,"el":66,"az":259,"ss":0,"used":false},
1111 {"PRN":20,"el":7,"az":226,"ss":0,"used":false},
1112 {"PRN":3,"el":52,"az":163,"ss":32,"used":true},
1113 {"PRN":31,"el":16,"az":102,"ss":0,"used":false}
1114 ]}]}
1115 Note
1117 Client software should not assume the field inventory of the
1118 POLL response is fixed for all time. As gpsd collects and
1119 caches more data from more sensor types, those data are likely
1120 to find their way into this response.
1121 TOFF
1123 This message is emitted on each cycle and reports the offset
1124 between the host's clock time and the GPS time at top of the second
1125 (actually, when the first data for the reporting cycle is
1126 received).
1127 This message exactly mirrors the PPS message except for two
1129 details.
1130 TOFF emits no NTP precision, this is assumed to be -2. See the NTP
1132 documentation for their definition of precision.
1133 The TOFF message reports the GPS time as derived from the GPS
1135 serial data stream. The PPS message reports the GPS time as derived
1136 from the GPS PPS pulse.
1137 A TOFF object has the following elements:
1139 Table 11. TOFF object
1141 ┌───────────┬─────────┬─────────┬──────────────────┐
1142 │Name │ Always? │ Type │ Description │
1143 ├───────────┼─────────┼─────────┼──────────────────┤
1144 │class │ Yes │ string │ Fixed: "TOFF" │
1145 ├───────────┼─────────┼─────────┼──────────────────┤
1146 │device │ Yes │ string │ Name of the │
1147 │ │ │ │ originating │
1148 │ │ │ │ device │
1149 ├───────────┼─────────┼─────────┼──────────────────┤
1150 │real_sec │ Yes │ numeric │ seconds from the │
1151 │ │ │ │ GPS clock │
1152 ├───────────┼─────────┼─────────┼──────────────────┤
1153 │real_nsec │ Yes │ numeric │ nanoseconds from │
1154 │ │ │ │ the GPS clock │
1155 ├───────────┼─────────┼─────────┼──────────────────┤
1156 │clock_sec │ Yes │ numeric │ seconds from the │
1157 │ │ │ │ system clock │
1158 ├───────────┼─────────┼─────────┼──────────────────┤
1159 │clock_nsec │ Yes │ numeric │ nanoseconds from │
1160 │ │ │ │ the system clock │
1161 └───────────┴─────────┴─────────┴──────────────────┘
1162 This message is emitted once per second to watchers of a device and
1163 is intended to report the timestamps of the in-band report of the
1164 GPS and seconds as reported by the system clock (which may be
1165 NTP-corrected) when the first valid timestamp of the reporting
1166 cycle was seen.
1167 The message contains two second/nanosecond pairs: real_sec and
1169 real_nsec contain the time the GPS thinks it was at the start of
1170 the current cycle; clock_sec and clock_nsec contain the time the
1171 system clock thinks it was on receipt of the first timing message
1172 of the cycle. real_nsec is always to nanosecond precision.
1173 clock_nsec is nanosecond precision on most systems.
1174 Here's an example:
1176 {"class":"TOFF","device":"/dev/ttyUSB0",
1178 "real_sec":1330212592, "real_nsec":343182,
1179 "clock_sec":1330212592,"clock_nsec":343184,
1180 "precision":-2}
1181 PPS
1183 This message is emitted each time the daemon sees a valid PPS
1184 (Pulse Per Second) strobe from a device.
1185 This message exactly mirrors the TOFF message except for two
1187 details.
1188 PPS emits the NTP precision. See the NTP documentation for their
1190 definition of precision.
1191 The TOFF message reports the GPS time as derived from the GPS
1193 serial data stream. The PPS message reports the GPS time as derived
1194 from the GPS PPS pulse.
1195 There are various sources of error in the reported clock times. The
1197 speed of the serial connection between the GPS and the system adds
1198 a delay to the start of cycle detection. An even bigger error is
1199 added by the variable computation time inside the GPS. Taken
1200 together the time derived from the start of the GPS cycle can have
1201 offsets of 10 milliseconds to 700 milliseconds and combined jitter
1202 and wander of 100 to 300 milliseconds.
1203 A PPS object has the following elements:
1205 Table 12. PPS object
1207 ┌───────────┬─────────┬─────────┬──────────────────┐
1208 │Name │ Always? │ Type │ Description │
1209 ├───────────┼─────────┼─────────┼──────────────────┤
1210 │class │ Yes │ string │ Fixed: "PPS" │
1211 ├───────────┼─────────┼─────────┼──────────────────┤
1212 │device │ Yes │ string │ Name of the │
1213 │ │ │ │ originating │
1214 │ │ │ │ device │
1215 ├───────────┼─────────┼─────────┼──────────────────┤
1216 │real_sec │ Yes │ numeric │ seconds from the │
1217 │ │ │ │ PPS source │
1218 ├───────────┼─────────┼─────────┼──────────────────┤
1219 │real_nsec │ Yes │ numeric │ nanoseconds from │
1220 │ │ │ │ the PPS source │
1221 ├───────────┼─────────┼─────────┼──────────────────┤
1222 │clock_sec │ Yes │ numeric │ seconds from the │
1223 │ │ │ │ system clock │
1224 ├───────────┼─────────┼─────────┼──────────────────┤
1225 │clock_nsec │ Yes │ numeric │ nanoseconds from │
1226 │ │ │ │ the system clock │
1227 ├───────────┼─────────┼─────────┼──────────────────┤
1228 │precision │ Yes │ numeric │ NTP style │
1229 │ │ │ │ estimate of PPS │
1230 │ │ │ │ precision │
1231 ├───────────┼─────────┼─────────┼──────────────────┤
1232 │qErr │ No │ numeric │ Quantization │
1233 │ │ │ │ error of the │
1234 │ │ │ │ PPS, in │
1235 │ │ │ │ picoseconds. │
1236 │ │ │ │ Sometimes called │
1237 │ │ │ │ the "sawtooth" │
1238 │ │ │ │ error. │
1239 └───────────┴─────────┴─────────┴──────────────────┘
1240 This message is emitted once per second to watchers of a device
1241 emitting PPS, and reports the time of the start of the GPS second
1242 (when the 1PPS arrives) and seconds as reported by the system clock
1243 (which may be NTP-corrected) at that moment.
1244 The message contains two second/nanosecond pairs: real_sec and
1246 real_nsec contain the time the GPS thinks it was at the PPS edge;
1247 clock_sec and clock_nsec contain the time the system clock thinks
1248 it was at the PPS edge. real_nsec is always to nanosecond
1249 precision. clock_nsec is nanosecond precision on most systems.
1250 There are various sources of error in the reported clock times. For
1252 PPS delivered via a real serial-line strobe, serial-interrupt
1253 latency plus processing time to the timer call should be bounded
1254 above by about 10 microseconds; that can be reduced to less than 1
1255 microsecond if your kernel supports RFC 2783. USB1.1-to-serial
1256 control-line emulation is limited to about 1 millisecond. seconds.
1257 Here's an example:
1259 {"class":"PPS","device":"/dev/ttyUSB0",
1261 "real_sec":1330212592, "real_nsec":343182,
1262 "clock_sec":1330212592,"clock_nsec":343184,
1263 "precision":-3}
1264 OSC
1266 This message reports the status of a GPS-disciplined oscillator
1267 (GPSDO). The GPS PPS output (which has excellent long-term
1268 stability) is typically used to discipline a local oscillator with
1269 much better short-term stability (such as a rubidium atomic clock).
1270 An OSC object has the following elements:
1272 Table 13. OSC object
1274 ┌────────────┬─────────┬─────────┬──────────────────┐
1275 │Name │ Always? │ Type │ Description │
1276 ├────────────┼─────────┼─────────┼──────────────────┤
1277 │class │ Yes │ string │ Fixed: "OSC" │
1278 ├────────────┼─────────┼─────────┼──────────────────┤
1279 │device │ Yes │ string │ Name of the │
1280 │ │ │ │ originating │
1281 │ │ │ │ device. │
1282 ├────────────┼─────────┼─────────┼──────────────────┤
1283 │running │ Yes │ boolean │ If true, the │
1284 │ │ │ │ oscillator is │
1285 │ │ │ │ currently │
1286 │ │ │ │ running. │
1287 │ │ │ │ Oscillators may │
1288 │ │ │ │ require warm-up │
1289 │ │ │ │ time at the │
1290 │ │ │ │ start of the │
1291 │ │ │ │ day. │
1292 ├────────────┼─────────┼─────────┼──────────────────┤
1293 │reference │ Yes │ boolean │ If true, the │
1294 │ │ │ │ oscillator is │
1295 │ │ │ │ receiving a GPS │
1296 │ │ │ │ PPS signal. │
1297 ├────────────┼─────────┼─────────┼──────────────────┤
1298 │disciplined │ Yes │ boolean │ If true, the GPS │
1299 │ │ │ │ PPS signal is │
1300 │ │ │ │ sufficiently │
1301 │ │ │ │ stable and is │
1302 │ │ │ │ being used to │
1303 │ │ │ │ discipline the │
1304 │ │ │ │ local │
1305 │ │ │ │ oscillator. │
1306 ├────────────┼─────────┼─────────┼──────────────────┤
1307 │delta │ Yes │ numeric │ The time │
1308 │ │ │ │ difference (in │
1309 │ │ │ │ nanoseconds) │
1310 │ │ │ │ between the │
1311 │ │ │ │ GPS-disciplined │
1312 │ │ │ │ oscillator PPS │
1313 │ │ │ │ output pulse and │
1314 │ │ │ │ the most recent │
1315 │ │ │ │ GPS PPS input │
1316 │ │ │ │ pulse. │
1317 └────────────┴─────────┴─────────┴──────────────────┘
1318 Here's an example:
1319 {"class":"OSC","running":true,"device":"/dev/ttyUSB0",
1321 "reference":true,"disciplined":true,"delta":67}
1322 ?DEVICE
1324 This command reports (when followed by ';') the state of a device,
1325 or sets (when followed by '=' and a DEVICE object) device-specific
1326 control bits, notably the device's speed and serial mode and the
1327 native-mode bit. The parameter-setting form will be rejected if
1328 more than one client is attached to the channel.
1329 Pay attention to the response, because it is possible for this
1331 command to fail if the GPS does not support a speed-switching
1332 command or only supports some combinations of serial modes. In case
1333 of failure, the daemon and GPS will continue to communicate at the
1334 old speed.
1335 Use the parameter-setting form with caution. On USB and Bluetooth
1337 GPSes it is also possible for serial mode setting to fail either
1338 because the serial adaptor chip does not support non-8N1 modes or
1339 because the device firmware does not properly synchronize the
1340 serial adaptor chip with the UART on the GPS chipset when the speed
1341 changes. These failures can hang your device, possibly requiring a
1342 GPS power cycle or (in extreme cases) physically disconnecting the
1343 NVRAM backup battery.
1344 A DEVICE object has the following elements:
1346 Table 14. DEVICE object
1348 ┌──────────┬─────────┬─────────┬──────────────────┐
1349 │Name │ Always? │ Type │ Description │
1350 ├──────────┼─────────┼─────────┼──────────────────┤
1351 │class │ Yes │ string │ Fixed: "DEVICE" │
1352 ├──────────┼─────────┼─────────┼──────────────────┤
1353 │path │ No │ string │ Name the device │
1354 │ │ │ │ for which the │
1355 │ │ │ │ control bits are │
1356 │ │ │ │ being reported, │
1357 │ │ │ │ or for which │
1358 │ │ │ │ they are to be │
1359 │ │ │ │ applied. This │
1360 │ │ │ │ attribute may be │
1361 │ │ │ │ omitted only │
1362 │ │ │ │ when there is │
1363 │ │ │ │ exactly one │
1364 │ │ │ │ subscribed │
1365 │ │ │ │ channel. │
1366 ├──────────┼─────────┼─────────┼──────────────────┤
1367 │activated │ No │ string │ Time the device │
1368 │ │ │ │ was activated as │
1369 │ │ │ │ an ISO8601 │
1370 │ │ │ │ timestamp. If │
1371 │ │ │ │ the device is │
1372 │ │ │ │ inactive this │
1373 │ │ │ │ attribute is │
1374 │ │ │ │ absent. │
1375 ├──────────┼─────────┼─────────┼──────────────────┤
1376 │flags │ No │ integer │ Bit vector of │
1377 │ │ │ │ property flags. │
1378 │ │ │ │ Currently │
1379 │ │ │ │ defined flags │
1380 │ │ │ │ are: describe │
1381 │ │ │ │ packet types │
1382 │ │ │ │ seen so far │
1383 │ │ │ │ (GPS, RTCM2, │
1384 │ │ │ │ RTCM3, AIS). │
1385 │ │ │ │ Won't be │
1386 │ │ │ │ reported if │
1387 │ │ │ │ empty, e.g. │
1388 │ │ │ │ before gpsd has │
1389 │ │ │ │ seen │
1390 │ │ │ │ identifiable │
1391 │ │ │ │ packets from the │
1392 │ │ │ │ device. │
1393 ├──────────┼─────────┼─────────┼──────────────────┤
1394 │driver │ No │ string │ GPSD's name for │
1395 │ │ │ │ the device │
1396 │ │ │ │ driver type. │
1397 │ │ │ │ Won't be │
1398 │ │ │ │ reported before │
1399 │ │ │ │ gpsd has │
1400 │ │ │ │ seen │
1401 │ │ │ │ identifiable │
1402 │ │ │ │ packets from the │
1403 │ │ │ │ device. │
1404 ├──────────┼─────────┼─────────┼──────────────────┤
1405 │subtype │ No │ string │ Whatever version │
1406 │ │ │ │ information the │
1407 │ │ │ │ device driver │
1408 │ │ │ │ returned. │
1409 ├──────────┼─────────┼─────────┼──────────────────┤
1410 │subtype1 │ No │ string │ More version │
1411 │ │ │ │ information the │
1412 │ │ │ │ device driver │
1413 │ │ │ │ returned. │
1414 ├──────────┼─────────┼─────────┼──────────────────┤
1415 │bps │ No │ integer │ Device speed in │
1416 │ │ │ │ bits per second. │
1417 ├──────────┼─────────┼─────────┼──────────────────┤
1418 │parity │ No │ string │ N, O or E for no │
1419 │ │ │ │ parity, odd, or │
1420 │ │ │ │ even. │
1421 ├──────────┼─────────┼─────────┼──────────────────┤
1422 │stopbits │ Yes │ string │ Stop bits (1 or │
1423 │ │ │ │ 2). │
1424 ├──────────┼─────────┼─────────┼──────────────────┤
1425 │native │ No │ integer │ 0 means NMEA │
1426 │ │ │ │ mode and 1 means │
1427 │ │ │ │ alternate mode │
1428 │ │ │ │ (binary if it │
1429 │ │ │ │ has one, for │
1430 │ │ │ │ SiRF and │
1431 │ │ │ │ Evermore │
1432 │ │ │ │ chipsets in │
1433 │ │ │ │ particular). │
1434 │ │ │ │ Attempting to │
1435 │ │ │ │ set this mode on │
1436 │ │ │ │ a non-GPS device │
1437 │ │ │ │ will yield an │
1438 │ │ │ │ error. │
1439 ├──────────┼─────────┼─────────┼──────────────────┤
1440 │cycle │ No │ real │ Device cycle │
1441 │ │ │ │ time in seconds. │
1442 ├──────────┼─────────┼─────────┼──────────────────┤
1443 │mincycle │ No │ real │ Device minimum │
1444 │ │ │ │ cycle time in │
1445 │ │ │ │ seconds. │
1446 │ │ │ │ Reported from │
1447 │ │ │ │ ?DEVICE when │
1448 │ │ │ │ (and only when) │
1449 │ │ │ │ the rate is │
1450 │ │ │ │ switchable. It │
1451 │ │ │ │ is read-only and │
1452 │ │ │ │ not settable. │
1453 └──────────┴─────────┴─────────┴──────────────────┘
1454 The serial parameters will (bps, parity, stopbits) be omitted in a
1455 response describing a TCP/IP source such as an Ntrip, DGPSIP, or
1456 AIS feed; on a serial device they will always be present.
1457 The contents of the flags field should be interpreted as follows:
1459 Table 15. Device flags
1461 ┌───────────┬───────┬─────────────────────┐
1462 │C #define │ Value │ Description │
1463 ├───────────┼───────┼─────────────────────┤
1464 │SEEN_GPS │ 0x01 │ GPS data has been │
1465 │ │ │ seen on this device │
1466 ├───────────┼───────┼─────────────────────┤
1467 │SEEN_RTCM2 │ 0x02 │ RTCM2 data has been │
1468 │ │ │ seen on this device │
1469 ├───────────┼───────┼─────────────────────┤
1470 │SEEN_RTCM3 │ 0x04 │ RTCM3 data has been │
1471 │ │ │ seen on this device │
1472 ├───────────┼───────┼─────────────────────┤
1473 │SEEN_AIS │ 0x08 │ AIS data has been │
1474 │ │ │ seen on this device │
1475 └───────────┴───────┴─────────────────────┘
1476 When the C client library parses a response of this kind, it will
1477 assert the DEVICE_SET bit in the top-level set member.
1478 Here's an example:
1480 {"class":"DEVICE","bps":4800,"parity":"N","stopbits":1,"native":0}
1482 When a client is in watcher mode, the daemon will ship it DEVICE
1484 notifications when a device is added to the pool or deactivated.
1485 When the C client library parses a response of this kind, it will
1487 assert the DEVICE_SET bit in the top-level set member.
1488 Here's an example:
1490 {"class":"DEVICE","path":"/dev/pts1","activated":0}
1492 The daemon may ship an error object in response to a syntactically
1494 invalid command line or unknown command. It has the following elements:
1495 Table 16. ERROR notification object
1497 ┌────────┬─────────┬────────┬────────────────┐
1498 │Name │ Always? │ Type │ Description │
1499 ├────────┼─────────┼────────┼────────────────┤
1500 │class │ Yes │ string │ Fixed: "ERROR" │
1501 ├────────┼─────────┼────────┼────────────────┤
1502 │message │ Yes │ string │ Textual error │
1503 │ │ │ │ message │
1504 └────────┴─────────┴────────┴────────────────┘
1505 Here's an example:
1507 {"class":"ERROR","message":"Unrecognized request '?FOO'"}
1509 When the C client library parses a response of this kind, it will
1511 assert the ERR_SET bit in the top-level set member.
1512
1514 RTCM-104 is a family of serial protocols used for broadcasting
1515 pseudorange corrections from differential-GPS reference stations. Many
1516 GPS receivers can accept these corrections to improve their reporting
1517 accuracy.
1518 RTCM-104 comes in two major and incompatible flavors, 2.x and 3.x. Each
1520 major flavor has minor (compatible) revisions.
1521 The applicable standard for RTCM Version 2.x is RTCM Recommended
1523 Standards for Differential NAVSTAR GPS Service RTCM Paper 194-93/SC
1524 104-STD. For RTCM 3.1 it is RTCM Paper 177-2006-SC104-STD. Ordering
1525 instructions for both standards are accessible from the website of the
1526 Radio Technical Commission for Maritime Services[1] under
1527 "Publications".
1528 RTCM WIRE TRANSMISSIONS
1530 Differential-GPS correction stations consist of a GPS reference
1531 receiver coupled to a low frequency (LF) transmitter. The GPS reference
1532 receiver is a survey-grade GPS that does GPS carrier tracking and can
1533 work out its position to a few millimeters. It generates range and
1534 range-rate corrections and encodes them into RTCM104. It ships the
1535 RTCM104 to the LF transmitter over serial rs-232 signal at 100 baud or
1536 200 baud depending on the requirements of the transmitter.
1537 The LF transmitter broadcasts the approximately 300khz radio signal
1539 that differential-GPS radio receivers pick up. Transmitters that are
1540 meant to have a higher range will need to transmit at a slower rate.
1541 The higher the data rate the harder it will be for the remote radio
1542 receiver to receive with a good signal-to-noise ration. (Higher data
1543 rate signals can't be averaged over as long a time frame, hence they
1544 appear noisier.)
1545 RTCM WIRE FORMATS
1547 An RTCM 2.x message consists of a sequence of up to 33 30-bit words.
1548 The 24 most significant bits of each word are data and the six least
1549 significant bits are parity. The parity algorithm used is the same
1550 ISGPS-2000 as that used on GPS satellite downlinks. Each RTCM 2.x
1551 message consists of two header words followed by zero or more data
1552 words, depending upon the message type.
1553 An RTCM 3.x message begins with a fixed leader byte 0xD3. That is
1555 followed by six bits of version information and 10 bits of payload
1556 length information. Following that is the payload; following the
1557 payload is a 3-byte checksum of the payload using the Qualcomm CRC-24Q
1558 algorithm.
1559 RTCM2 JSON FORMAT
1561 Each RTCM2 message is dumped as a single JSON object per message, with
1562 the message fields as attributes of that object. Arrays of satellite,
1563 station, and constellation statistics become arrays of JSON
1564 sub-objects. Each sentence will normally also have a "device" field
1565 containing the pathname of the originating device.
1566 All attributes other than the device field are mandatory. Header
1568 attributes are emitted before others.
1569 Header portion
1571 Table 17. SKY object
1572 ┌───────────────┬─────────┬─────────────────────┐
1573 │Name │ Type │ Description │
1574 ├───────────────┼─────────┼─────────────────────┤
1575 │class │ string │ Fixed: "RTCM2". │
1576 ├───────────────┼─────────┼─────────────────────┤
1577 │type │ integer │ Message type (1-9). │
1578 ├───────────────┼─────────┼─────────────────────┤
1579 │station_id │ integer │ The id of the GPS │
1580 │ │ │ reference receiver. │
1581 │ │ │ The LF transmitters │
1582 │ │ │ also have │
1583 │ │ │ (different) id │
1584 │ │ │ numbers. │
1585 ├───────────────┼─────────┼─────────────────────┤
1586 │zcount │ real │ The reference time │
1587 │ │ │ of the corrections │
1588 │ │ │ in the message in │
1589 │ │ │ seconds within the │
1590 │ │ │ current hour. Note │
1591 │ │ │ that it is in GPS │
1592 │ │ │ time, which is some │
1593 │ │ │ seconds ahead of │
1594 │ │ │ UTC (see the U.S. │
1595 │ │ │ Naval Observatory's │
1596 │ │ │ table of leap │
1597 │ │ │ second │
1598 │ │ │ corrections[2]). │
1599 ├───────────────┼─────────┼─────────────────────┤
1600 │seqnum │ integer │ Sequence number. │
1601 │ │ │ Only 3 bits wide, │
1602 │ │ │ wraps after 7. │
1603 ├───────────────┼─────────┼─────────────────────┤
1604 │length │ integer │ The number of words │
1605 │ │ │ after the header │
1606 │ │ │ that comprise the │
1607 │ │ │ message. │
1608 ├───────────────┼─────────┼─────────────────────┤
1609 │station_health │ integer │ Station │
1610 │ │ │ transmission │
1611 │ │ │ status. Indicates │
1612 │ │ │ the health of the │
1613 │ │ │ beacon as a │
1614 │ │ │ reference source. │
1615 │ │ │ Any nonzero value │
1616 │ │ │ means the satellite │
1617 │ │ │ is probably │
1618 │ │ │ transmitting bad │
1619 │ │ │ data and should not │
1620 │ │ │ be used in a fix. 6 │
1621 │ │ │ means the │
1622 │ │ │ transmission is │
1623 │ │ │ unmonitored. 7 │
1624 │ │ │ means the station │
1625 │ │ │ is not working │
1626 │ │ │ properly. Other │
1627 │ │ │ values are defined │
1628 │ │ │ by the beacon │
1629 │ │ │ operator. │
1630 └───────────────┴─────────┴─────────────────────┘
1631 <message type> is one of
1633 1
1635 full corrections -- one message containing corrections for all
1636 GPS satellites in view. This is not common.
1637 3
1639 reference station parameters -- the position of the reference
1640 station GPS antenna.
1641 4
1643 datum — the datum to which the DGPS data is referred.
1644 5
1646 constellation health — information about the satellites the
1647 beacon can see.
1648 6
1650 null message — just a filler.
1651 7
1653 radio beacon almanac — information about this or other beacons.
1654 9
1656 subset corrections — a message containing corrections for only
1657 a subset of the GPS satellites in view.
1658 16
1660 special message — a text message from the beacon operator.
1661 31
1663 GLONASS subset corrections — a message containing corrections
1664 for a set of the GLONASS satellites in view.
1665 Type 1 and 9: Correction data
1667 One or more satellite objects follow the header for type 1 or type
1668 9 messages. Here is the format:
1669 Table 18. Satellite object
1671 ┌──────┬─────────┬─────────────────────┐
1672 │Name │ Type │ Description │
1673 ├──────┼─────────┼─────────────────────┤
1674 │ident │ integer │ The PRN number of │
1675 │ │ │ the satellite for │
1676 │ │ │ which this is │
1677 │ │ │ correction data. │
1678 ├──────┼─────────┼─────────────────────┤
1679 │udre │ integer │ User Differential │
1680 │ │ │ Range Error (0-3). │
1681 │ │ │ See the table │
1682 │ │ │ following for │
1683 │ │ │ values. │
1684 ├──────┼─────────┼─────────────────────┤
1685 │iod │ integer │ Issue Of Data, │
1686 │ │ │ matching the IOD │
1687 │ │ │ for the current │
1688 │ │ │ ephemeris of this │
1689 │ │ │ satellite, as │
1690 │ │ │ transmitted by the │
1691 │ │ │ satellite. The IOD │
1692 │ │ │ is a unique tag │
1693 │ │ │ that identifies the │
1694 │ │ │ ephemeris; the GPS │
1695 │ │ │ using the DGPS │
1696 │ │ │ correction and the │
1697 │ │ │ DGPS generating the │
1698 │ │ │ data must use the │
1699 │ │ │ same orbital │
1700 │ │ │ positions for the │
1701 │ │ │ satellite. │
1702 ├──────┼─────────┼─────────────────────┤
1703 │prc │ real │ The pseudorange │
1704 │ │ │ error in meters for │
1705 │ │ │ this satellite as │
1706 │ │ │ measured by the │
1707 │ │ │ beacon reference │
1708 │ │ │ receiver at the │
1709 │ │ │ epoch indicated by │
1710 │ │ │ the z_count in the │
1711 │ │ │ parent record. │
1712 ├──────┼─────────┼─────────────────────┤
1713 │rrc │ real │ The rate of change │
1714 │ │ │ of pseudorange │
1715 │ │ │ error in meters/sec │
1716 │ │ │ for this satellite │
1717 │ │ │ as measured by the │
1718 │ │ │ beacon reference │
1719 │ │ │ receiver at the │
1720 │ │ │ epoch indicated by │
1721 │ │ │ the z_count field │
1722 │ │ │ in the parent │
1723 │ │ │ record. This is │
1724 │ │ │ used to calculate │
1725 │ │ │ pseudorange errors │
1726 │ │ │ at other epochs, if │
1727 │ │ │ required by the GPS │
1728 │ │ │ receiver. │
1729 └──────┴─────────┴─────────────────────┘
1730 User Differential Range Error values are as follows:
1732 Table 19. UDRE values
1734 ┌──┬────────────────────────────┐
1735 │0 │ 1-sigma error <= 1 m │
1736 ├──┼────────────────────────────┤
1737 │1 │ 1-sigma error <= 4 m │
1738 ├──┼────────────────────────────┤
1739 │2 │ 1-sigma error <= 8 m │
1740 ├──┼────────────────────────────┤
1741 │3 │ 1-sigma error > 8 m │
1742 └──┴────────────────────────────┘
1743 Here's an example:
1745 {"class":"RTCM2","type":1,
1747 "station_id":688,"zcount":843.0,"seqnum":5,"length":19,"station_health":6,
1748 "satellites":[
1749 {"ident":10,"udre":0,"iod":46,"prc":-2.400,"rrc":0.000},
1750 {"ident":13,"udre":0,"iod":94,"prc":-4.420,"rrc":0.000},
1751 {"ident":7,"udre":0,"iod":22,"prc":-5.160,"rrc":0.002},
1752 {"ident":2,"udre":0,"iod":34,"prc":-6.480,"rrc":0.000},
1753 {"ident":4,"udre":0,"iod":47,"prc":-8.860,"rrc":0.000},
1754 {"ident":8,"udre":0,"iod":76,"prc":-7.980,"rrc":0.002},
1755 {"ident":5,"udre":0,"iod":99,"prc":-8.260,"rrc":0.002},
1756 {"ident":23,"udre":0,"iod":81,"prc":-8.060,"rrc":0.000},
1757 {"ident":16,"udre":0,"iod":70,"prc":-11.740,"rrc":0.000},
1758 {"ident":30,"udre":0,"iod":4,"prc":-18.960,"rrc":-0.006},
1759 {"ident":29,"udre":0,"iod":101,"prc":-24.960,"rrc":-0.002}
1760 ]}
1761 Type 3: Reference Station Parameters
1763 Here are the payload members of a type 3 (Reference Station
1764 Parameters) message:
1765 Table 20. Reference Station Parameters
1767 ┌─────┬──────┬────────────────────┐
1768 │Name │ Type │ Description │
1769 ├─────┼──────┼────────────────────┤
1770 │x │ real │ ECEF X coordinate. │
1771 ├─────┼──────┼────────────────────┤
1772 │y │ real │ ECEF Y coordinate. │
1773 ├─────┼──────┼────────────────────┤
1774 │z │ real │ ECEF Z coordinate. │
1775 └─────┴──────┴────────────────────┘
1776 The coordinates are the position of the station, in meters to two
1778 decimal places, in Earth Centred Earth Fixed coordinates. These are
1779 usually referred to the WGS84 reference frame, but may be referred
1780 to NAD83 in the US (essentially identical to WGS84 for all except
1781 geodesists), or some other reference frame in other parts of the
1782 world.
1783 An invalid reference message is represented by a type 3 header
1785 without payload fields.
1786 Here's an example:
1788 {"class":"RTCM2","type":3,
1790 "station_id":652,"zcount":1657.2,"seqnum":2,"length":4,"station_health":6,
1791 "x":3878620.92,"y":670281.40,"z":5002093.59
1792 }
1793 Type 4: Datum
1795 Here are the payload members of a type 4 (Datum) message:
1796 Table 21. Datum
1798 ┌───────────┬─────────┬─────────────────────┐
1799 │Name │ Type │ Description │
1800 ├───────────┼─────────┼─────────────────────┤
1801 │dgnss_type │ string │ Either "GPS", │
1802 │ │ │ "GLONASS", │
1803 │ │ │ "GALILEO", or │
1804 │ │ │ "UNKNOWN". │
1805 ├───────────┼─────────┼─────────────────────┤
1806 │dat │ integer │ 0 or 1 and │
1807 │ │ │ indicates the sense │
1808 │ │ │ of the offset shift │
1809 │ │ │ given by dx, dy, │
1810 │ │ │ dz. dat = 0 means │
1811 │ │ │ that the station │
1812 │ │ │ coordinates (in the │
1813 │ │ │ reference message) │
1814 │ │ │ are referred to a │
1815 │ │ │ local datum and │
1816 │ │ │ that adding dx, dy, │
1817 │ │ │ dz to that position │
1818 │ │ │ will render it in │
1819 │ │ │ GNSS coordinates │
1820 │ │ │ (WGS84 for GPS). If │
1821 │ │ │ dat = 1 then the │
1822 │ │ │ ref station │
1823 │ │ │ position is in GNSS │
1824 │ │ │ coordinates and │
1825 │ │ │ adding dx, dy, dz │
1826 │ │ │ will give it │
1827 │ │ │ referred to the │
1828 │ │ │ local datum. │
1829 ├───────────┼─────────┼─────────────────────┤
1830 │datum_name │ string │ A standard name for │
1831 │ │ │ the datum. │
1832 ├───────────┼─────────┼─────────────────────┤
1833 │dx │ real │ X offset. │
1834 ├───────────┼─────────┼─────────────────────┤
1835 │dy │ real │ Y offset. │
1836 ├───────────┼─────────┼─────────────────────┤
1837 │dz │ real │ Z offset. │
1838 └───────────┴─────────┴─────────────────────┘
1839 <dx> <dy> <dz> are offsets to convert from local datum to GNSS
1841 datum or vice versa. These fields are optional.
1842 An invalid datum message is represented by a type 4 header without
1844 payload fields.
1845 Type 5: Constellation Health
1847 One or more of these follow the header for type 5 messages — one
1848 for each satellite.
1849 Here is the format:
1851 Table 22. Constellation health
1853 ┌────────────┬─────────┬─────────────────────┐
1854 │Name │ Type │ Description │
1855 ├────────────┼─────────┼─────────────────────┤
1856 │ident │ integer │ The PRN number of │
1857 │ │ │ the satellite. │
1858 ├────────────┼─────────┼─────────────────────┤
1859 │iodl │ bool │ True indicates that │
1860 │ │ │ this information │
1861 │ │ │ relates to the │
1862 │ │ │ satellite │
1863 │ │ │ information in an │
1864 │ │ │ accompanying type 1 │
1865 │ │ │ or type 9 message. │
1866 ├────────────┼─────────┼─────────────────────┤
1867 │health │ integer │ 0 indicates that │
1868 │ │ │ the satellite is │
1869 │ │ │ healthy. Any other │
1870 │ │ │ value indicates a │
1871 │ │ │ problem (coding is │
1872 │ │ │ not known). │
1873 ├────────────┼─────────┼─────────────────────┤
1874 │snr │ integer │ The carrier/noise │
1875 │ │ │ ratio of the │
1876 │ │ │ received signal in │
1877 │ │ │ the range 25 to 55 │
1878 │ │ │ dB(Hz). │
1879 ├────────────┼─────────┼─────────────────────┤
1880 │health_en │ bool │ If set to True it │
1881 │ │ │ indicates that the │
1882 │ │ │ satellite is │
1883 │ │ │ healthy even if the │
1884 │ │ │ satellite │
1885 │ │ │ navigation data │
1886 │ │ │ says it is │
1887 │ │ │ unhealthy. │
1888 ├────────────┼─────────┼─────────────────────┤
1889 │new_data │ bool │ True indicates that │
1890 │ │ │ the IOD for this │
1891 │ │ │ satellite will soon │
1892 │ │ │ be updated in type │
1893 │ │ │ 1 or 9 messages. │
1894 ├────────────┼─────────┼─────────────────────┤
1895 │los_warning │ bool │ Line-of-sight │
1896 │ │ │ warning. True │
1897 │ │ │ indicates that the │
1898 │ │ │ satellite will │
1899 │ │ │ shortly go │
1900 │ │ │ unhealthy. │
1901 ├────────────┼─────────┼─────────────────────┤
1902 │tou │ integer │ Healthy time │
1903 │ │ │ remaining in │
1904 │ │ │ seconds. │
1905 └────────────┴─────────┴─────────────────────┘
1906 Type 6: Null
1908 This just indicates a null message. There are no payload fields.
1909 Unknown message
1911 This format is used to dump message words in hexadecimal when the
1912 message type field doesn't match any of the known ones.
1913 Here is the format:
1915 Table 23. Unknown Message
1917 ┌─────┬──────┬────────────────────┐
1918 │Name │ Type │ Description │
1919 ├─────┼──────┼────────────────────┤
1920 │data │ list │ A list of strings. │
1921 └─────┴──────┴────────────────────┘
1922 Each string in the array is a hex literal representing 30 bits of
1924 information, after parity checks and inversion. The high two bits
1925 should be ignored.
1926 Type 7: Radio Beacon Almanac
1928 Here is the format:
1929 Table 24. Constellation health
1931 ┌───────────┬─────────┬─────────────────────┐
1932 │Name │ Type │ Description │
1933 ├───────────┼─────────┼─────────────────────┤
1934 │lat │ real │ Latitude in │
1935 │ │ │ degrees, of the LF │
1936 │ │ │ transmitter antenna │
1937 │ │ │ for the station for │
1938 │ │ │ which this is an │
1939 │ │ │ almanac. North is │
1940 │ │ │ positive. │
1941 ├───────────┼─────────┼─────────────────────┤
1942 │lon │ real │ Longitude in │
1943 │ │ │ degrees, of the LF │
1944 │ │ │ transmitter antenna │
1945 │ │ │ for the station for │
1946 │ │ │ which this is an │
1947 │ │ │ almanac. East is │
1948 │ │ │ positive. │
1949 ├───────────┼─────────┼─────────────────────┤
1950 │range │ integer │ Published range of │
1951 │ │ │ the station in km. │
1952 ├───────────┼─────────┼─────────────────────┤
1953 │frequency │ real │ Station broadcast │
1954 │ │ │ frequency in kHz. │
1955 ├───────────┼─────────┼─────────────────────┤
1956 │health │ integer │ <health> is the │
1957 │ │ │ health of the │
1958 │ │ │ station for which │
1959 │ │ │ this is an almanac. │
1960 │ │ │ If it is non-zero, │
1961 │ │ │ the station is │
1962 │ │ │ issuing suspect │
1963 │ │ │ data and should not │
1964 │ │ │ be used for fixes. │
1965 │ │ │ The ITU and RTCM104 │
1966 │ │ │ standards differ │
1967 │ │ │ about the mode │
1968 │ │ │ detailed │
1969 │ │ │ interpretation of │
1970 │ │ │ the <health> field │
1971 │ │ │ and even about its │
1972 │ │ │ bit width. │
1973 ├───────────┼─────────┼─────────────────────┤
1974 │station_id │ integer │ The id of the │
1975 │ │ │ transmitter. This │
1976 │ │ │ is not the same as │
1977 │ │ │ the reference id in │
1978 │ │ │ the header, the │
1979 │ │ │ latter being the id │
1980 │ │ │ of the reference │
1981 │ │ │ receiver. │
1982 ├───────────┼─────────┼─────────────────────┤
1983 │bitrate │ integer │ The transmitted │
1984 │ │ │ bitrate. │
1985 └───────────┴─────────┴─────────────────────┘
1986 Here's an example:
1988 {"class":"RTCM2","type":9,"station_id":268,"zcount":252.6,
1990 "seqnum":4,"length":5,"station_health":0,
1991 "satellites":[
1992 {"ident":13,"udre":0,"iod":3,"prc":-25.940,"rrc":0.066},
1993 {"ident":2,"udre":0,"iod":73,"prc":0.920,"rrc":-0.080},
1994 {"ident":8,"udre":0,"iod":22,"prc":23.820,"rrc":0.014}
1995 ]}
1996 Type 13: GPS Time of Week
1998 Here are the payload members of a type 13 (Groumf Tramitter
1999 Parameters) message:
2000 Table 25. Ground Transmitter Parameters
2002 ┌──────────┬─────────┬─────────────────────┐
2003 │Name │ Type │ Description │
2004 ├──────────┼─────────┼─────────────────────┤
2005 │status │ bool │ If True, signals │
2006 │ │ │ user to expect a │
2007 │ │ │ type 16 explanatory │
2008 │ │ │ message associated │
2009 │ │ │ with this station. │
2010 │ │ │ Probably indicates │
2011 │ │ │ some sort of │
2012 │ │ │ unusual event. │
2013 ├──────────┼─────────┼─────────────────────┤
2014 │rangeflag │ bool │ If True, indicates │
2015 │ │ │ that the estimated │
2016 │ │ │ range is different │
2017 │ │ │ from that found in │
2018 │ │ │ the type 7 message │
2019 │ │ │ (which contains the │
2020 │ │ │ beacon's listed │
2021 │ │ │ range). Generally │
2022 │ │ │ indicates a range │
2023 │ │ │ reduction due to │
2024 │ │ │ causes such as poor │
2025 │ │ │ ionospheric │
2026 │ │ │ conditions or │
2027 │ │ │ reduced │
2028 │ │ │ transmission power. │
2029 ├──────────┼─────────┼─────────────────────┤
2030 │lat │ real │ Degrees latitude, │
2031 │ │ │ signed. Positive │
2032 │ │ │ is N, negative is │
2033 │ │ │ S. │
2034 ├──────────┼─────────┼─────────────────────┤
2035 │lon │ real │ Degrees longitude, │
2036 │ │ │ signed. Positive │
2037 │ │ │ is E, negative is │
2038 │ │ │ W. │
2039 ├──────────┼─────────┼─────────────────────┤
2040 │range │ integer │ Transmission range │
2041 │ │ │ in km (1-1024). │
2042 └──────────┴─────────┴─────────────────────┘
2043 This message type replaces message type 3 (Reference Station
2045 Parameters) in RTCM 2.3.
2046 Type 14: GPS Time of Week
2048 Here are the payload members of a type 14 (GPS Time of Week)
2049 message:
2050 Table 26. Reference Station Parameters
2052 ┌─────────┬─────────┬───────────────────┐
2053 │Name │ Type │ Description │
2054 ├─────────┼─────────┼───────────────────┤
2055 │week │ integer │ GPS week (0-123). │
2056 ├─────────┼─────────┼───────────────────┤
2057 │hour │ integer │ Hour of week │
2058 │ │ │ (0-167). │
2059 ├─────────┼─────────┼───────────────────┤
2060 │leapsecs │ integer │ Leap Seconds │
2061 │ │ │ (0-63). │
2062 └─────────┴─────────┴───────────────────┘
2063 Here's an example:
2065 {"class":"RTCM2","type":14,"station_id":652,"zcount":1657.2,
2067 "seqnum":3,"length":1,"station_health":6,"week":601,"hour":109,
2068 "leapsecs":15}
2069 Type 16: Special Message
2071 Table 27. Special Message
2072 ┌────────┬────────┬─────────────────────┐
2073 │Name │ Type │ Description │
2074 ├────────┼────────┼─────────────────────┤
2075 │message │ string │ A text message sent │
2076 │ │ │ by the beacon │
2077 │ │ │ operator. │
2078 └────────┴────────┴─────────────────────┘
2079 Type 31: Correction data
2081 One or more GLONASS satellite objects follow the header for type 1
2082 or type 9 messages. Here is the format:
2083 Table 28. Satellite object
2085 ┌───────┬──────────┬─────────────────────┐
2086 │Name │ Type │ Description │
2087 ├───────┼──────────┼─────────────────────┤
2088 │ident │ integer │ The PRN number of │
2089 │ │ │ the satellite for │
2090 │ │ │ which this is │
2091 │ │ │ correction data. │
2092 ├───────┼──────────┼─────────────────────┤
2093 │udre │ integer │ User Differential │
2094 │ │ │ Range Error (0-3). │
2095 │ │ │ See the table │
2096 │ │ │ following for │
2097 │ │ │ values. │
2098 ├───────┼──────────┼─────────────────────┤
2099 │change │ boolean │ Change-of-ephemeris │
2100 │ │ │ bit. │
2101 ├───────┼──────────┼─────────────────────┤
2102 │tod │ uinteger │ Count of 30-second │
2103 │ │ │ periods since the │
2104 │ │ │ top of the hour. │
2105 ├───────┼──────────┼─────────────────────┤
2106 │prc │ real │ The pseudorange │
2107 │ │ │ error in meters for │
2108 │ │ │ this satellite as │
2109 │ │ │ measured by the │
2110 │ │ │ beacon reference │
2111 │ │ │ receiver at the │
2112 │ │ │ epoch indicated by │
2113 │ │ │ the z_count in the │
2114 │ │ │ parent record. │
2115 ├───────┼──────────┼─────────────────────┤
2116 │rrc │ real │ The rate of change │
2117 │ │ │ of pseudorange │
2118 │ │ │ error in meters/sec │
2119 │ │ │ for this satellite │
2120 │ │ │ as measured by the │
2121 │ │ │ beacon reference │
2122 │ │ │ receiver at the │
2123 │ │ │ epoch indicated by │
2124 │ │ │ the z_count field │
2125 │ │ │ in the parent │
2126 │ │ │ record. This is │
2127 │ │ │ used to calculate │
2128 │ │ │ pseudorange errors │
2129 │ │ │ at other epochs, if │
2130 │ │ │ required by the GPS │
2131 │ │ │ receiver. │
2132 └───────┴──────────┴─────────────────────┘
2133 Here's an example:
2135 {"class":"RTCM2","type":31,"station_id":652,"zcount":1642.2,
2137 "seqnum":0,"length":14,"station_health":6,
2138 "satellites":[
2139 {"ident":5,"udre":0,"change":false,"tod":0,"prc":132.360,"rrc":0.000},
2140 {"ident":15,"udre":0,"change":false,"tod":0,"prc":134.840,"rrc":0.002},
2141 {"ident":14,"udre":0,"change":false,"tod":0,"prc":141.520,"rrc":0.000},
2142 {"ident":6,"udre":0,"change":false,"tod":0,"prc":127.000,"rrc":0.000},
2143 {"ident":21,"udre":0,"change":false,"tod":0,"prc":128.780,"rrc":0.000},
2144 {"ident":22,"udre":0,"change":false,"tod":0,"prc":125.260,"rrc":0.002},
2145 {"ident":20,"udre":0,"change":false,"tod":0,"prc":117.280,"rrc":-0.004},
2146 {"ident":16,"udre":0,"change":false,"tod":17,"prc":113.460,"rrc":0.018}
2147 ]}
2148
2150 The support for RTCM104v3 dumping is incomplete and buggy. Do not
2151 attempt to use it for production! Anyone interested in it should read
2152 the source code.
2153
2155 AIS support is an extension. It may not be present if your instance of
2156 gpsd has been built with a restricted feature set.
2157 AIS packets are dumped as JSON objects with class "AIS". Each AIS
2159 report object contains a "type" field giving the AIS message type and a
2160 "scaled" field telling whether the remainder of the fields are dumped
2161 in scaled or unscaled form. (These will be emitted before any
2162 type-specific fields.) It will also contain a "device" field naming the
2163 data source. Other fields have names and types as specified in the
2164 AIVDM/AIVDO Protocol Decoding document on the GPSD project website;
2165 each message field table may be directly interpreted as a specification
2166 for the members of the corresponding JSON object type.
2167 By default, certain scaling and conversion operations are performed for
2169 JSON output. Latitudes and longitudes are scaled to decimal degrees
2170 rather than the native AIS unit of 1/10000th of a minute of arc. Ship
2171 (but not air) speeds are scaled to knots rather than tenth-of-knot
2172 units. Rate of turn may appear as "nan" if is unavailable, or as one of
2173 the strings "fastright" or "fastleft" if it is out of the AIS encoding
2174 range; otherwise it is quadratically mapped back to the turn sensor
2175 number in degrees per minute. Vessel draughts are converted to decimal
2176 meters rather than native AIS decimeters. Various other scaling
2177 conversions are described in "AIVDM/AIVDO Protocol Decoding".
2178
2180 Subframe support is always compiled into gpsd but many GPSes do not
2181 output subframe data or the gpsd driver may not support subframes.
2182 Subframe packets are dumped as JSON objects with class "SUBFRAME". Each
2184 subframe report object contains a "frame" field giving the subframe
2185 number, a "tSV" field for the transmitting satellite number, a "TOW17"
2186 field containing the 17 MSBs of the start of the next 12-second message
2187 and a "scaled" field telling whether the remainder of the fields are
2188 dumped in scaled or unscaled form. It will also contain a "device"
2189 field naming the data source. Each SUBFRAME object will have a
2190 sub-object specific to that subframe page type. Those sub-object fields
2191 have names and types similar to those specified in the IS-GPS-200E
2192 document; each message field table may be directly interpreted as a
2193 specification for the members of the corresponding JSON object type.
2194
2196 gpsd(8), libgps(3),
2197
2199 The protocol was designed and documented by Eric S. Raymond.
2200
2202 1. Radio Technical Commission for Maritime Services
2203 http://www.rtcm.org/
2204 2. table of leap second corrections
2206 ftp://maia.usno.navy.mil/ser7/tai-utc.dat
2207The GPSD Project 6 December 2020 GPSD_JSON(5)