1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!-- 3This file is Copyright (c) 2010-2018 by the GPSD project 4SPDX-License-Identifier: BSD-2-clause 5--> 6<!DOCTYPE refentry PUBLIC 7 "-//OASIS//DTD DocBook XML V4.1.2//EN" 8 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ 9<!ENTITY gpsdsock "/var/run/gpsd.sock"> 10]> 11<refentry id='gpsd_json.5'> 12<refentryinfo><date>23 June 2019</date></refentryinfo> 13<refmeta> 14<refentrytitle>gpsd_json</refentrytitle> 15<manvolnum>5</manvolnum> 16<refmiscinfo class="source">The GPSD Project</refmiscinfo> 17<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> 18</refmeta> 19<refnamediv id='name'> 20<refname>gpsd_json</refname> 21<refpurpose>gpsd request/response protocol</refpurpose> 22</refnamediv> 23 24<refsect1 id='overview'><title>OVERVIEW</title> 25 26<para><application>gpsd</application> is a service daemon that can be used 27to monitor GPSes, DGPS receivers, Marine AIS broadcasts, and various other 28location-related and kinematic sensors.</para> 29 30<para>Clients may communicate with <application>gpsd</application> via 31textual requests and responses over a socket. It is a bad idea for 32applications to speak the protocol directly: rather, they should use 33the <application>libgps</application> client library (for C; bindings 34also exist for other languages) and take appropriate care to 35conditionalize their code on the major and minor protocol version 36symbols.</para> 37 38<para>The GPSD protocol is built on top of JSON, JavaScript Object 39Notation, as specified in RFC 7159: <citetitle>The JavaScript Object 40Notation (JSON) Data Interchange Format</citetitle>. GPSD's use of 41JSON is restricted in some ways that make parsing it in fixed-extent 42languages (such as C) easier.</para> 43 44<para>A request line is introduced by "?" and may include multiple 45commands. Commands begin with a command identifier, followed either 46by a terminating ';' or by an equal sign "=" and a JSON object treated 47as an argument. Any ';' or newline indication (either LF or CR-LF) 48after the end of a command is ignored. All request lines must be 49composed of US-ASCII characters and may be no more than 80 characters 50in length, exclusive of the trailing newline.</para> 51 52<para>Responses are JSON objects all of which have a "class" attribute 53the value of which is either the name of the invoking command. There 54are reports (including but not limited to as "TPV", "SKY", "DEVICE", 55and "ERROR") which are not direct responses to commands.</para> 56 57<para> The order of JSON attributes within a response object is never 58significant, and you may specify attributes in commands in any 59order. Responses never contain the special JSON value null; instead, 60attributes with empty or undefined values are omitted. The length 61limit for responses and reports is 1536 characters, including trailing 62newline; longer responses will be truncated, so client code must be 63prepared for the possibility of invalid JSON fragments.</para> 64 65<para>In JSON reports, if an attribute is present only if the parent 66attribute is present or has a particular range, then the parent 67attribute is emitted first.</para> 68 69<para>There is one constraint on the order in which attributes will 70be omitted. If an optional attribute is present only when a parent 71attribute has a specified value or range of values, the parent 72attribute will be emitted first to make parsing easier.</para> 73 74<para>The next subsection section documents the core GPSD protocol. 75Extensions are documented in the following subsections. The extensions 76may not be supported in your <application>gpsd</application> instance 77if it has been compiled with a restricted feature set.</para> 78 79</refsect1> 80<refsect1 id='core-protocol'><title>CORE SOCKET PROTOCOL</title> 81 82<para>Here are the core-protocol responses:</para> 83 84<variablelist> 85<varlistentry> 86<term>TPV</term> 87<listitem> 88<para>A TPV object is a time-position-velocity report. The "class" and "mode" 89fields will reliably be present. The "mode" field will be emitted 90before optional fields that may be absent when there is no fix. Error 91estimates will be emitted after the fix components they're associated with. 92Others may be reported or not depending on the fix quality.</para> 93 94<para>All error estimates (epc, epd, epe, eph, ept, epv, epx, epy) 95are assumed to be 95% confidence, may also be 50%, one sigma, or two 96sigma confidence. Many GPS do not specify a confidence level. No 97GPS specifies how the value is calculated. Use error estimates with 98caution, and only as relative "goodness" indicators. If the GPS reports 99a value to gpsd, then gpsd will report that value. Otherwise gpsd will 100try to compute the value from the skyview.</para> 101 102<table frame="all" pgwide="0"><title>TPV object</title> 103<tgroup cols="3" align="left" colsep="1" rowsep="1"> 104<thead> 105<row> 106 <entry>Name</entry> 107 <entry>Always?</entry> 108 <entry>Type</entry> 109 <entry>Description</entry> 110</row> 111</thead> 112<tbody> 113<row> 114 <entry>class</entry> 115 <entry>Yes</entry> 116 <entry>string</entry> 117 <entry>Fixed: "TPV"</entry> 118</row> 119<row> 120 <entry>device</entry> 121 <entry>No</entry> 122 <entry>string</entry> 123 <entry>Name of originating device.</entry> 124</row> 125<row> 126 <entry>status</entry> 127 <entry>No</entry> 128 <entry>numeric</entry> 129 <entry>GPS status: %d, 2=DGPS fix, otherwise not present.</entry> 130</row> 131<row> 132 <entry>mode</entry> 133 <entry>Yes</entry> 134 <entry>numeric</entry> 135 <entry>NMEA mode: %d, 0=no mode value yet seen, 1=no fix, 2=2D, 3=3D.</entry> 136</row> 137<row> 138 <entry>time</entry> 139 <entry>No</entry> 140 <entry>string</entry> 141 <entry>Time/date stamp in ISO8601 format, UTC. May have a 142 fractional part of up to .001sec precision. May be absent if mode 143 is not 2 or 3.</entry> 144</row> 145<row> 146 <entry>altHAE</entry> 147 <entry>No</entry> 148 <entry>numeric</entry> 149 <entry>Altitude, height above allipsoid, in meters. Probably 150WGS84. Present if mode is 3. 151</entry> 152</row> 153<row> 154 <entry>altMSL</entry> 155 <entry>No</entry> 156 <entry>numeric</entry> 157 <entry>MSL Altitude in meters. The geoid used is rarely specified 158and is often inacurate. See the comments below on geoidSep. Present if 159 mode is 3. altMSL is altHAE - geoidSep.</entry> 160</row> 161<row> 162 <entry>alt</entry> 163 <entry>No</entry> 164 <entry>numeric</entry> 165 <entry>Deprecated. Undefined. Use altHAE or altMSL.</entry> 166</row> 167<row> 168 <entry>climb</entry> 169 <entry>No</entry> 170 <entry>numeric</entry> 171 <entry>Climb (positive) or sink (negative) rate, meters per 172 second.</entry> 173</row> 174<row> 175 <entry>datum</entry> 176 <entry>No</entry> 177 <entry>string</entry> 178 <entry>Current datum.</entry> 179</row> 180<row> 181 <entry>depth</entry> 182 <entry>No</entry> 183 <entry>numeric</entry> 184 <entry>Depth in meters. Probably depth below the keel..</entry> 185</row> 186<row> 187 <entry>dgpsAge</entry> 188 <entry>No</entry> 189 <entry>numeric</entry> 190 <entry>Age of DGPS data. In seconds</entry> 191</row> 192<row> 193 <entry>dgpsSta</entry> 194 <entry>No</entry> 195 <entry>numeric</entry> 196 <entry>Station of DGPS data.</entry> 197</row> 198<row> 199 <entry>epc</entry> 200 <entry>No</entry> 201 <entry>numeric</entry> 202 <entry>Estimated climb error in meters per second. Present 203 if consecutive 3D fixes.</entry> 204</row> 205<row> 206 <entry>epd</entry> 207 <entry>No</entry> 208 <entry>numeric</entry> 209 <entry>Estimated track (direction) error in degrees. Present if 210 consecutive 2D fixes.</entry> 211</row> 212<row> 213 <entry>eph</entry> 214 <entry>No</entry> 215 <entry>numeric</entry> 216 <entry>Estimated horizontal Position (2D) Error in meters. 217 Also known as Estimated Position Error (epe). Present 218 if mode is 2D or 3D and DOPs can be calculated from the satellite 219 view.</entry> 220</row> 221<row> 222 <entry>eps</entry> 223 <entry>No</entry> 224 <entry>numeric</entry> 225 <entry>Estimated speed error in meters per second. Present 226 for consecutive 2D or 3D fixes.</entry> 227</row> 228<row> 229 <entry>ept</entry> 230 <entry>No</entry> 231 <entry>numeric</entry> 232 <entry>Estimated timestamp error in seconds. 233 Present if time is present.</entry> 234</row> 235<row> 236 <entry>epx</entry> 237 <entry>No</entry> 238 <entry>numeric</entry> 239 <entry>Longitude error estimate in meters. Present 240 if mode is 2D or 3D and DOPs can be calculated from the satellite 241 view.</entry> 242</row> 243<row> 244 <entry>epy</entry> 245 <entry>No</entry> 246 <entry>numeric</entry> 247 <entry>Latitude error estimate in meters. Present 248 if mode is 2 or 3 and DOPs can be calculated from the satellite 249 view.</entry> 250</row> 251<row> 252 <entry>epv</entry> 253 <entry>No</entry> 254 <entry>numeric</entry> 255 <entry>Estimated vertical error in meters. Present 256 if mode is 3 and DOPs can be calculated from the satellite 257 view.</entry> 258</row> 259<row> 260 <entry>lat</entry> 261 <entry>No</entry> 262 <entry>numeric</entry> 263 <entry>Latitude in degrees: +/- signifies North/South. Present 264 when mode is 2 or 3.</entry> 265</row> 266<row> 267 <entry>leapseconds</entry> 268 <entry>integer</entry> 269 <entry><para>Current leap seconds.</para></entry> 270</row> 271<row> 272 <entry>lon</entry> 273 <entry>No</entry> 274 <entry>numeric</entry> 275 <entry>Longitude in degrees: +/- signifies East/West. Present 276 when mode is 2 or 3.</entry> 277</row> 278<row> 279 <entry>track</entry> 280 <entry>No</entry> 281 <entry>numeric</entry> 282 <entry>Course over ground, degrees from true north.</entry> 283</row> 284<row> 285 <entry>magtrack</entry> 286 <entry>No</entry> 287 <entry>numeric</entry> 288 <entry>Course over ground, degrees magnetic.</entry> 289</row> 290<row> 291 <entry>magvar</entry> 292 <entry>No</entry> 293 <entry>numeric</entry> 294 <entry>Magnetic variation, degrees. Also known as 295the magnetic declination (the direction of the horizontal component of 296the magnetic field measured clockwise from north) in degrees, 297Positive is West variation. Negative is East variation.</entry> 298</row> 299<row> 300 <entry>speed</entry> 301 <entry>No</entry> 302 <entry>numeric</entry> 303 <entry>Speed over ground, meters per second.</entry> 304</row> 305<row> 306 <entry>ecefx</entry> 307 <entry>No</entry> 308 <entry>numeric</entry> 309 <entry>ECEF X position in meters.</entry> 310</row> 311<row> 312 <entry>ecefy</entry> 313 <entry>No</entry> 314 <entry>numeric</entry> 315 <entry>ECEF Y position in meters.</entry> 316</row> 317<row> 318 <entry>ecefz</entry> 319 <entry>No</entry> 320 <entry>numeric</entry> 321 <entry>ECEF Z position in meters.</entry> 322</row> 323<row> 324 <entry>ecefpAcc</entry> 325 <entry>No</entry> 326 <entry>numeric</entry> 327 <entry>ECEF position error in meters.</entry> 328</row> 329<row> 330 <entry>ecefvx</entry> 331 <entry>No</entry> 332 <entry>numeric</entry> 333 <entry>ECEF X velocity in meters/second.</entry> 334</row> 335<row> 336 <entry>ecefvy</entry> 337 <entry>No</entry> 338 <entry>numeric</entry> 339 <entry>ECEF Y velocity in meters/second.</entry> 340</row> 341<row> 342 <entry>ecefvz</entry> 343 <entry>No</entry> 344 <entry>numeric</entry> 345 <entry>ECEF Z velocity in meters/second.</entry> 346</row> 347<row> 348 <entry>ecefvAcc</entry> 349 <entry>No</entry> 350 <entry>numeric</entry> 351 <entry>ECEF velocity error in meters/second.</entry> 352</row> 353<row> 354 <entry>sep</entry> 355 <entry>No</entry> 356 <entry>numeric</entry> 357 <entry>Estimated Spherical (3D) Position Error in meters. 358 Present if mode is 3D and DOPs can be calculated from the satellite 359 view. Assumed to be 95% confidence, but many GPS do not specify. 360 </entry> 361</row> 362<row> 363 <entry>relN</entry> 364 <entry>No</entry> 365 <entry>numeric</entry> 366 <entry>North component of relative position vector in meters.</entry> 367</row> 368<row> 369 <entry>relE</entry> 370 <entry>No</entry> 371 <entry>numeric</entry> 372 <entry>East component of relative position vector in meters.</entry> 373</row> 374<row> 375 <entry>relD</entry> 376 <entry>No</entry> 377 <entry>numeric</entry> 378 <entry>Down component of relative position vector in meters.</entry> 379</row> 380<row> 381 <entry>velN</entry> 382 <entry>No</entry> 383 <entry>numeric</entry> 384 <entry>North velocity component in meters.</entry> 385</row> 386<row> 387 <entry>velE</entry> 388 <entry>No</entry> 389 <entry>numeric</entry> 390 <entry>wEast velocity component in meters.</entry> 391</row> 392<row> 393 <entry>velD</entry> 394 <entry>No</entry> 395 <entry>numeric</entry> 396 <entry>Down velocity component in meters.</entry> 397</row> 398<row> 399 <entry>geoidSep</entry> 400 <entry>No</entry> 401 <entry>numeric</entry> 402 <entry>Geoid separation is the difference between the WGS84 403reference elipsoid and the geoid (Mean Sea Level) in meters. Almost no 404GNSS receiver specifies how they compute their geoid. gpsd interpolates the 405geoid from a 5x5 degree table of EGM2008 values when the receiver does 406not supply a geoid separation. The gpsd computed geoidSep is usually 407within one meter of the "true" value, but can be off as much as 12 meters. 408</entry> 409 410</row> 411 412</tbody> 413</tgroup> 414</table> 415 416<para>When the C client library parses a response of this kind, it 417will assert validity bits in the top-level set member for each 418field actually received; see gps.h for bitmask names and values.</para> 419 420<para>Invalid or known floating point values will be set to NAN. 421</para> 422 423<para>Here's an example:</para> 424 425<programlisting> 426{"class":"TPV","device":"/dev/pts/1", 427 "time":"2005-06-08T10:34:48.283Z","ept":0.005, 428 "lat":46.498293369,"lon":7.567411672,"alt":1343.127, 429 "eph":36.000,"epv":32.321, 430 "track":10.3788,"speed":0.091,"climb":-0.085,"mode":3} 431</programlisting> 432</listitem> 433</varlistentry> 434 435<varlistentry> 436<term>SKY</term> 437<listitem> 438<para>A SKY object reports a sky view of the GPS satellite positions. 439If there is no GPS device available, or no skyview has been reported 440yet, only the "class" field will reliably be present.</para> 441 442<table frame="all" pgwide="0"><title>SKY object</title> 443<tgroup cols="3" align="left" colsep="1" rowsep="1"> 444<thead> 445<row> 446 <entry>Name</entry> 447 <entry>Always?</entry> 448 <entry>Type</entry> 449 <entry>Description</entry> 450</row> 451</thead> 452<tbody> 453<row> 454 <entry>class</entry> 455 <entry>Yes</entry> 456 <entry>string</entry> 457 <entry>Fixed: "SKY"</entry> 458</row> 459<row> 460 <entry>device</entry> 461 <entry>No</entry> 462 <entry>string</entry> 463 <entry>Name of originating device</entry> 464</row> 465<row> 466 <entry>time</entry> 467 <entry>No</entry> 468 <entry>string</entry> 469 <entry>Time/date stamp in ISO8601 format, UTC. May have a 470 fractional part of up to .001sec precision.</entry> 471</row> 472<row> 473 <entry>gdop</entry> 474 <entry>No</entry> 475 <entry>numeric</entry> 476 <entry>Geometric (hyperspherical) dilution of precision, a 477 combination of PDOP and TDOP. A dimensionless factor which 478 should be multiplied by a base UERE 479 to get an error estimate.</entry> 480</row> 481<row> 482 <entry>hdop</entry> 483 <entry>No</entry> 484 <entry>numeric</entry> 485 <entry>Horizontal dilution of precision, a dimensionless 486 factor which should be multiplied by a base UERE to get a 487 circular error estimate.</entry> 488</row> 489<row> 490 <entry>pdop</entry> 491 <entry>No</entry> 492 <entry>numeric</entry> 493 <entry>Position (spherical/3D) dilution of precision, a dimensionless 494 factor which should be multiplied by a base UERE to get an 495 error estimate.</entry> 496</row> 497<row> 498 <entry>tdop</entry> 499 <entry>No</entry> 500 <entry>numeric</entry> 501 <entry>Time dilution of precision, a dimensionless 502 factor which should be multiplied by a base UERE to get an 503 error estimate.</entry> 504</row> 505<row> 506 <entry>vdop</entry> 507 <entry>No</entry> 508 <entry>numeric</entry> 509 <entry>Vertical (altitude) dilution of precision, a dimensionless 510 factor which should be multiplied by a base UERE to get an 511 error estimate.</entry> 512</row> 513<row> 514 <entry>xdop</entry> 515 <entry>No</entry> 516 <entry>numeric</entry> 517 <entry>Longitudinal dilution of precision, a dimensionless 518 factor which should be multiplied by a base UERE to get an 519 error estimate.</entry> 520</row> 521<row> 522 <entry>ydop</entry> 523 <entry>No</entry> 524 <entry>numeric</entry> 525 <entry>Latitudinal dilution of precision, a dimensionless 526 factor which should be multiplied by a base UERE to get an 527 error estimate.</entry> 528</row> 529<row> 530 <entry>satellites</entry> 531 <entry>Yes</entry> 532 <entry>list</entry> 533 <entry>List of satellite objects in skyview</entry> 534</row> 535 536</tbody> 537</tgroup> 538</table> 539 540<para>Many devices compute dilution of precision factors but do not 541include them in their reports. Many that do report DOPs report only 542HDOP, two-dimensional circular error. <application>gpsd</application> 543always passes through whatever the device actually reports, then 544attempts to fill in other DOPs by calculating the appropriate 545determinants in a covariance matrix based on the satellite view. DOPs 546may be missing if some of these determinants are singular. It can even 547happen that the device reports an error estimate in meters when the 548corresponding DOP is unavailable; some devices use more sophisticated 549error modeling than the covariance calculation.</para> 550 551<para>The satellite list objects have the following elements:</para> 552 553<table frame="all" pgwide="0"><title>Satellite object</title> 554<tgroup cols="3" align="left" colsep="1" rowsep="1"> 555<thead> 556<row> 557 <entry>Name</entry> 558 <entry>Always?</entry> 559 <entry>Type</entry> 560 <entry>Description</entry> 561</row> 562</thead> 563<tbody> 564<row> 565 <entry>PRN</entry> 566 <entry>Yes</entry> 567 <entry>numeric</entry> 568 <entry>PRN ID of the satellite. 1-63 are GNSS satellites, 569 64-96 are GLONASS satellites, 100-164 are SBAS satellites</entry> 570</row> 571<row> 572 <entry>az</entry> 573 <entry>No</entry> 574 <entry>numeric</entry> 575 <entry>Azimuth, degrees from true north.</entry> 576</row> 577<row> 578 <entry>el</entry> 579 <entry>No</entry> 580 <entry>numeric</entry> 581 <entry>Elevation in degrees.</entry> 582</row> 583<row> 584 <entry>ss</entry> 585 <entry>No</entry> 586 <entry>numeric</entry> 587 <entry>Signal to Noise ratio in dBHz.</entry> 588</row> 589<row> 590 <entry>used</entry> 591 <entry>Yes</entry> 592 <entry>boolean</entry> 593 <entry>Used in current solution? (SBAS/WAAS/EGNOS satellites 594 may be flagged used if the solution has corrections from them, 595 but not all drivers make this information available.)</entry> 596</row> 597<row> 598 <entry>gnssid</entry> 599 <entry>No</entry> 600 <entry>numeric</entry> 601 <entry>The GNSS ID, as defined by u-blox, not NMEA. 0=GPS, 602 2=Galileo, 3=Beidou, 5=QZSS, 6-GLONASS.</entry> 603</row> 604<row> 605 <entry>svid</entry> 606 <entry>no</entry> 607 <entry>numeric</entry> 608 <entry>The satellite ID within its constellation. As defined 609 by u-blox, not NMEA).</entry> 610</row> 611<row> 612 <entry>sigid</entry> 613 <entry>no</entry> 614 <entry>numeric</entry> 615 <entry>The signal ID of this signal. As defined by u-blox, not 616 NMEA. See u-blox doc for details.</entry> 617</row> 618<row> 619 <entry>freqid</entry> 620 <entry>no</entry> 621 <entry>numeric</entry> 622 <entry>For GLONASS satellites only: the frequency ID of the signal. 623As defined by u-blox, range 0 to 13. The freqid is the frequency slot 624plus 7.</entry> 625</row> 626<row> 627 <entry>health</entry> 628 <entry>no</entry> 629 <entry>numeric</entry> 630 <entry>The health of this satellite. 0 is unknown, 1 is 631OK, and 2 is unhealthy.</entry> 632</row> 633</tbody> 634</tgroup> 635</table> 636 637<para>Note that satellite objects do not have a "class" field, as 638they are never shipped outside of a SKY object.</para> 639 640<para>When the C client library parses a SKY response, it 641will assert the SATELLITE_SET bit in the top-level set member.</para> 642 643<para>Here's an example:</para> 644 645<programlisting> 646{"class":"SKY","device":"/dev/pts/1", 647 "time":"2005-07-08T11:28:07.114Z", 648 "xdop":1.55,"hdop":1.24,"pdop":1.99, 649 "satellites":[ 650 {"PRN":23,"el":6,"az":84,"ss":0,"used":false}, 651 {"PRN":28,"el":7,"az":160,"ss":0,"used":false}, 652 {"PRN":8,"el":66,"az":189,"ss":44,"used":true}, 653 {"PRN":29,"el":13,"az":273,"ss":0,"used":false}, 654 {"PRN":10,"el":51,"az":304,"ss":29,"used":true}, 655 {"PRN":4,"el":15,"az":199,"ss":36,"used":true}, 656 {"PRN":2,"el":34,"az":241,"ss":43,"used":true}, 657 {"PRN":27,"el":71,"az":76,"ss":43,"used":true}]} 658</programlisting> 659 660</listitem> 661</varlistentry> 662 663<varlistentry> 664<term>GST</term> 665<listitem> 666<para>A GST object is a pseudorange noise report.</para> 667 668<table frame="all" pgwide="0"><title>GST object</title> 669<tgroup cols="3" align="left" colsep="1" rowsep="1"> 670<thead> 671<row> 672 <entry>Name</entry> 673 <entry>Always?</entry> 674 <entry>Type</entry> 675 <entry>Description</entry> 676</row> 677</thead> 678<tbody> 679<row> 680 <entry>class</entry> 681 <entry>Yes</entry> 682 <entry>string</entry> 683 <entry>Fixed: "GST"</entry> 684</row> 685<row> 686 <entry>device</entry> 687 <entry>No</entry> 688 <entry>string</entry> 689 <entry>Name of originating device</entry> 690</row> 691<row> 692 <entry>time</entry> 693 <entry>No</entry> 694 <entry>string</entry> 695 <entry>Time/date stamp in ISO8601 format, UTC. May have a 696 fractional part of up to .001sec precision.</entry> 697</row> 698 699<row> 700 <entry>rms</entry> 701 <entry>No</entry> 702 <entry>numeric</entry> 703 <entry>Value of the standard deviation of the range inputs to the 704navigation process (range inputs include pseudoranges and DGPS 705corrections).</entry> 706</row> 707 708<row> 709 <entry>major</entry> 710 <entry>No</entry> 711 <entry>numeric</entry> 712 <entry>Standard deviation of semi-major axis of error ellipse, in meters.</entry> 713</row> 714 715<row> 716 <entry>minor</entry> 717 <entry>No</entry> 718 <entry>numeric</entry> 719 <entry>Standard deviation of semi-minor axis of error ellipse, in meters.</entry> 720</row> 721 722<row> 723 <entry>orient</entry> 724 <entry>No</entry> 725 <entry>numeric</entry> 726 <entry>Orientation of semi-major axis of error ellipse, in degrees from true north.</entry> 727</row> 728 729<row> 730 <entry>lat</entry> 731 <entry>No</entry> 732 <entry>numeric</entry> 733 <entry>Standard deviation of latitude error, in meters.</entry> 734</row> 735 736<row> 737 <entry>lon</entry> 738 <entry>No</entry> 739 <entry>numeric</entry> 740 <entry>Standard deviation of longitude error, in meters.</entry> 741</row> 742 743<row> 744 <entry>alt</entry> 745 <entry>No</entry> 746 <entry>numeric</entry> 747 <entry>Standard deviation of altitude error, in meters.</entry> 748</row> 749 750</tbody> 751</tgroup> 752</table> 753 754<para>Here's an example:</para> 755 756<programlisting> 757{"class":"GST","device":"/dev/ttyUSB0", 758 "time":"2010-12-07T10:23:07.096Z","rms":2.440, 759 "major":1.660,"minor":1.120,"orient":68.989, 760 "lat":1.600,"lon":1.200,"alt":2.520} 761</programlisting> 762</listitem> 763</varlistentry> 764 765<varlistentry> 766<term>ATT</term> 767<listitem> 768<para>An ATT object is a vehicle-attitude report. It is returned by 769digital-compass and gyroscope sensors; depending on device, it may 770include: heading, pitch, roll, yaw, gyroscope, and magnetic-field 771readings. Because such sensors are often bundled as part of 772marine-navigation systems, the ATT response may also include 773water depth.</para> 774 775<para>The "class" and "mode" fields will reliably be present. Others 776may be reported or not depending on the specific device type.</para> 777 778<table frame="all" pgwide="0"><title>ATT object</title> 779<tgroup cols="3" align="left" colsep="1" rowsep="1"> 780<thead> 781<row> 782 <entry>Name</entry> 783 <entry>Always?</entry> 784 <entry>Type</entry> 785 <entry>Description</entry> 786</row> 787</thead> 788<tbody> 789<row> 790 <entry>class</entry> 791 <entry>Yes</entry> 792 <entry>string</entry> 793 <entry>Fixed: "ATT"</entry> 794</row> 795<row> 796 <entry>device</entry> 797 <entry>Yes</entry> 798 <entry>string</entry> 799 <entry>Name of originating device</entry> 800</row> 801<row> 802 <entry>time</entry> 803 <entry>No</entry> 804 <entry>string</entry> 805 <entry>Time/date stamp in ISO8601 format, UTC. May have a 806 fractional part of up to .001sec precision.</entry> 807</row> 808<row> 809 <entry>heading</entry> 810 <entry>No</entry> 811 <entry>numeric</entry> 812 <entry>Heading, degrees from true north.</entry> 813</row> 814<row> 815 <entry>mag_st</entry> 816 <entry>No</entry> 817 <entry>string</entry> 818 <entry>Magnetometer status.</entry> 819</row> 820<row> 821 <entry>pitch</entry> 822 <entry>No</entry> 823 <entry>numeric</entry> 824 <entry>Pitch in degrees.</entry> 825</row> 826<row> 827 <entry>pitch_st</entry> 828 <entry>No</entry> 829 <entry>string</entry> 830 <entry>Pitch sensor status.</entry> 831</row> 832<row> 833 <entry>yaw</entry> 834 <entry>No</entry> 835 <entry>numeric</entry> 836 <entry>Yaw in degrees</entry> 837</row> 838<row> 839 <entry>yaw_st</entry> 840 <entry>No</entry> 841 <entry>string</entry> 842 <entry>Yaw sensor status.</entry> 843</row> 844<row> 845 <entry>roll</entry> 846 <entry>No</entry> 847 <entry>numeric</entry> 848 <entry>Roll in degrees.</entry> 849</row> 850<row> 851 <entry>roll_st</entry> 852 <entry>No</entry> 853 <entry>string</entry> 854 <entry>Roll sensor status.</entry> 855</row> 856<row> 857 <entry>dip</entry> 858 <entry>No</entry> 859 <entry>numeric</entry> 860 <entry>Local magnetic inclination, degrees, positive when the magnetic 861field points downward (into the Earth).</entry> 862</row> 863<row> 864 <entry>mag_len</entry> 865 <entry>No</entry> 866 <entry>numeric</entry> 867 <entry>Scalar magnetic field strength.</entry> 868</row> 869<row> 870 <entry>mag_x</entry> 871 <entry>No</entry> 872 <entry>numeric</entry> 873 <entry>X component of magnetic field strength.</entry> 874</row> 875<row> 876 <entry>mag_y</entry> 877 <entry>No</entry> 878 <entry>numeric</entry> 879 <entry>Y component of magnetic field strength.</entry> 880</row> 881<row> 882 <entry>mag_z</entry> 883 <entry>No</entry> 884 <entry>numeric</entry> 885 <entry>Z component of magnetic field strength.</entry> 886</row> 887<row> 888 <entry>acc_len</entry> 889 <entry>No</entry> 890 <entry>numeric</entry> 891 <entry>Scalar acceleration.</entry> 892</row> 893<row> 894 <entry>acc_x</entry> 895 <entry>No</entry> 896 <entry>numeric</entry> 897 <entry>X component of acceleration.</entry> 898</row> 899<row> 900 <entry>acc_y</entry> 901 <entry>No</entry> 902 <entry>numeric</entry> 903 <entry>Y component of acceleration.</entry> 904</row> 905<row> 906 <entry>acc_z</entry> 907 <entry>No</entry> 908 <entry>numeric</entry> 909 <entry>Z component of acceleration.</entry> 910</row> 911<row> 912 <entry>gyro_x</entry> 913 <entry>No</entry> 914 <entry>numeric</entry> 915 <entry>X component of acceleration.</entry> 916</row> 917<row> 918 <entry>gyro_y</entry> 919 <entry>No</entry> 920 <entry>numeric</entry> 921 <entry>Y component of acceleration.</entry> 922</row> 923<row> 924 <entry>depth</entry> 925 <entry>No</entry> 926 <entry>numeric</entry> 927 <entry>Water depth in meters.</entry> 928</row> 929<row> 930 <entry>temp</entry> 931 <entry>No</entry> 932 <entry>numeric</entry> 933 <entry>Temperature at sensor, degrees centigrade.</entry> 934</row> 935 936 937</tbody> 938</tgroup> 939</table> 940 941<para>The heading, pitch, and roll status codes (if present) vary by device. 942For the TNT Revolution digital compasses, they are coded as follows: </para> 943 944<table frame="all" pgwide="0"><title>Device flags</title> 945<tgroup cols="2" align="left" colsep="1" rowsep="1"> 946<thead> 947<row> 948 <entry>Code</entry> 949 <entry>Description</entry> 950</row> 951</thead> 952<tbody> 953<row> 954 <entry>C</entry> 955 <entry>magnetometer calibration alarm</entry> 956</row> 957<row> 958 <entry>L</entry> 959 <entry>low alarm</entry> 960</row> 961<row> 962 <entry>M</entry> 963 <entry>low warning</entry> 964</row> 965<row> 966 <entry>N</entry> 967 <entry>normal</entry> 968</row> 969<row> 970 <entry>O</entry> 971 <entry>high warning</entry> 972</row> 973<row> 974 <entry>P</entry> 975 <entry>high alarm</entry> 976</row> 977<row> 978 <entry>V</entry> 979 <entry>magnetometer voltage level alarm</entry> 980</row> 981</tbody> 982</tgroup> 983</table> 984 985 986<para>When the C client library parses a response of this kind, it 987will assert ATT_IS.</para> 988 989<para>Here's an example:</para> 990 991<programlisting> 992{"class":"ATT","time":1270938096.843, 993 "heading":14223.00,"mag_st":"N", 994 "pitch":169.00,"pitch_st":"N", "roll":-43.00,"roll_st":"N", 995 "dip":13641.000,"mag_x":2454.000} 996</programlisting> 997</listitem> 998</varlistentry> 999 1000</variablelist> 1001 1002<para>And here are the commands:</para> 1003 1004<variablelist> 1005 1006<varlistentry> 1007<term>?VERSION;</term> 1008<listitem><para>Returns an object with the following attributes:</para> 1009 1010<table frame="all" pgwide="0"><title>VERSION object</title> 1011<tgroup cols="4" align="left" colsep="1" rowsep="1"> 1012<thead> 1013<row> 1014 <entry>Name</entry> 1015 <entry>Always?</entry> 1016 <entry>Type</entry> 1017 <entry>Description</entry> 1018</row> 1019</thead> 1020<tbody> 1021<row> 1022 <entry>class</entry> 1023 <entry>Yes</entry> 1024 <entry>string</entry> 1025 <entry>Fixed: "VERSION"</entry> 1026</row> 1027<row> 1028 <entry>release</entry> 1029 <entry>Yes</entry> 1030 <entry>string</entry> 1031 <entry>Public release level</entry> 1032</row> 1033<row> 1034 <entry>rev</entry> 1035 <entry>Yes</entry> 1036 <entry>string</entry> 1037 <entry>Internal revision-control level.</entry> 1038</row> 1039<row> 1040 <entry>proto_major</entry> 1041 <entry>Yes</entry> 1042 <entry>numeric</entry> 1043 <entry>API major revision level.</entry> 1044</row> 1045<row> 1046 <entry>proto_minor</entry> 1047 <entry>Yes</entry> 1048 <entry>numeric</entry> 1049 <entry>API minor revision level.</entry> 1050</row> 1051<row> 1052 <entry>remote</entry> 1053 <entry>No</entry> 1054 <entry>string</entry> 1055 <entry>URL of the remote daemon reporting this version. If 1056 empty, this is the version of the local daemon.</entry> 1057</row> 1058</tbody> 1059</tgroup> 1060</table> 1061 1062<para>The daemon ships a VERSION response to each client when the 1063client first connects to it.</para> 1064 1065<para>When the C client library parses a response of this kind, it 1066will assert the VERSION_SET bit in the top-level set member.</para> 1067 1068<para>Here's an example:</para> 1069 1070<programlisting> 1071{"class":"VERSION","version":"2.40dev", 1072 "rev":"06f62e14eae9886cde907dae61c124c53eb1101f", 1073 "proto_major":3,"proto_minor":1 1074} 1075</programlisting> 1076 1077 1078</listitem> 1079</varlistentry> 1080 1081<varlistentry> 1082<term>?DEVICES;</term> 1083<listitem><para>Returns a device list object with the 1084following elements:</para> 1085 1086<table frame="all" pgwide="0"><title>DEVICES object</title> 1087<tgroup cols="3" align="left" colsep="1" rowsep="1"> 1088<thead> 1089<row> 1090 <entry>Name</entry> 1091 <entry>Always?</entry> 1092 <entry>Type</entry> 1093 <entry>Description</entry> 1094</row> 1095</thead> 1096<tbody> 1097<row> 1098 <entry>class</entry> 1099 <entry>Yes</entry> 1100 <entry>string</entry> 1101 <entry>Fixed: "DEVICES"</entry> 1102</row> 1103<row> 1104 <entry>devices</entry> 1105 <entry>Yes</entry> 1106 <entry>list</entry> 1107 <entry>List of device descriptions</entry> 1108</row> 1109<row> 1110 <entry>remote</entry> 1111 <entry>No</entry> 1112 <entry>string</entry> 1113 <entry>URL of the remote daemon reporting the device set. If 1114 empty, this is a DEVICES response from the local daemon.</entry> 1115</row> 1116</tbody> 1117</tgroup> 1118</table> 1119 1120<para>When the C client library parses a response of this kind, it 1121will assert the DEVICELIST_SET bit in the top-level set member.</para> 1122 1123<para>Here's an example:</para> 1124 1125<programlisting> 1126{"class"="DEVICES","devices":[ 1127 {"class":"DEVICE","path":"/dev/pts/1","flags":1,"driver":"SiRF binary"}, 1128 {"class":"DEVICE","path":"/dev/pts/3","flags":4,"driver":"AIVDM"}]} 1129</programlisting> 1130 1131<para>The daemon occasionally ships a bare DEVICE object to the client 1132(that is, one not inside a DEVICES wrapper). The data content of these 1133objects will be described later as a response to the ?DEVICE command.</para> 1134 1135</listitem> 1136</varlistentry> 1137 1138<varlistentry> 1139<term>?WATCH;</term> 1140<listitem> 1141 1142<para>This command sets watcher mode. It also sets or elicits a report 1143of per-subscriber policy and the raw bit. An argument WATCH object 1144changes the subscriber's policy. The response describes the 1145subscriber's policy. The response will also include a DEVICES 1146object.</para> 1147 1148<para>A WATCH object has the following elements:</para> 1149 1150<table frame="all" pgwide="0"><title>WATCH object</title> 1151<tgroup cols="4" align="left" colsep="1" rowsep="1"> 1152<thead> 1153<row> 1154 <entry>Name</entry> 1155 <entry>Always?</entry> 1156 <entry>Type</entry> 1157 <entry>Description</entry> 1158</row> 1159</thead> 1160<tbody> 1161<row> 1162 <entry>class</entry> 1163 <entry>Yes</entry> 1164 <entry>string</entry> 1165 <entry>Fixed: "WATCH"</entry> 1166</row> 1167<row> 1168 <entry>enable</entry> 1169 <entry>No</entry> 1170 <entry>boolean</entry> 1171 <entry>Enable (true) or disable (false) watcher mode. Default 1172 is true.</entry> 1173</row> 1174<row> 1175 <entry>json</entry> 1176 <entry>No</entry> 1177 <entry>boolean</entry> 1178 <entry>Enable (true) or disable (false) dumping of JSON reports. 1179 Default is false.</entry> 1180</row> 1181<row> 1182 <entry>nmea</entry> 1183 <entry>No</entry> 1184 <entry>boolean</entry> 1185 <entry>Enable (true) or disable (false) dumping of binary 1186 packets as pseudo-NMEA. Default 1187 is false.</entry> 1188</row> 1189<row> 1190 <entry>raw</entry> 1191 <entry>No</entry> 1192 <entry>integer</entry> 1193 1194 <entry>Controls 'raw' mode. When this attribute is set to 1 1195 for a channel, <application>gpsd</application> reports the 1196 unprocessed NMEA or AIVDM data stream from whatever device is attached. 1197 Binary GPS packets are hex-dumped. RTCM2 and RTCM3 1198 packets are not dumped in raw mode. When this attribute is set to 1199 2 for a channel that processes binary data, 1200 <application>gpsd</application> reports the received data verbatim 1201 without hex-dumping.</entry> 1202</row> 1203<row> 1204 <entry>scaled</entry> 1205 <entry>No</entry> 1206 <entry>boolean</entry> 1207 <entry>If true, apply scaling divisors to output before 1208 dumping; default is false.</entry> 1209</row> 1210<row> 1211 <entry>split24</entry> 1212 <entry>No</entry> 1213 <entry>boolean</entry> 1214 <entry>If true, aggregate AIS type24 sentence parts. If false, 1215 report each part as a separate JSON object, leaving the 1216 client to match MMSIs and aggregate. Default is 1217 false. Applies only to AIS reports.</entry> 1218</row> 1219<row> 1220 <entry>pps</entry> 1221 <entry>No</entry> 1222 <entry>boolean</entry> 1223 <entry>If true, emit the TOFF JSON message on each cycle and a 1224 PPS JSON message when the device issues 1PPS. Default is false.</entry> 1225</row> 1226<row> 1227 <entry>device</entry> 1228 <entry>No</entry> 1229 <entry>string</entry> 1230 <entry>If present, enable watching only of the specified device 1231 rather than all devices. Useful with raw and NMEA modes 1232 in which device responses aren't tagged. Has no effect when 1233 used with enable:false.</entry> 1234</row> 1235<row> 1236 <entry>remote</entry> 1237 <entry>No</entry> 1238 <entry>string</entry> 1239 <entry>URL of the remote daemon reporting the watch set. If 1240 empty, this is a WATCH response from the local daemon.</entry> 1241</row> 1242</tbody> 1243</tgroup> 1244</table> 1245 1246<para>There is an additional boolean "timing" attribute which is 1247undocumented because that portion of the interface is considered 1248unstable and for developer use only.</para> 1249 1250<para>In watcher mode, GPS reports are dumped as TPV and SKY 1251responses. AIS, Subframe and RTCM reporting is described in the next 1252section.</para> 1253 1254<para>When the C client library parses a response of this kind, it 1255will assert the POLICY_SET bit in the top-level set member.</para> 1256 1257<para>Here's an example:</para> 1258 1259<programlisting> 1260{"class":"WATCH", "raw":1,"scaled":true} 1261</programlisting> 1262 1263</listitem> 1264</varlistentry> 1265 1266<varlistentry> 1267<term>?POLL;</term> 1268<listitem> 1269 1270<para>The POLL command requests data from the last-seen fixes on all 1271active GPS devices. Devices must previously have been activated by 1272?WATCH to be pollable.</para> 1273 1274<para>Polling can lead to possibly surprising results when it is used 1275on a device such as an NMEA GPS for which a complete fix has to be 1276accumulated from several sentences. If you poll while those sentences 1277are being emitted, the response will contain the last complete fix 1278data and may be as much as one cycle time (typically 1 second) 1279stale.</para> 1280 1281<para>The POLL response will contain a timestamped list of TPV objects 1282describing cached data, and a timestamped list of SKY objects 1283describing satellite configuration. If a device has not seen fixes, it 1284will be reported with a mode field of zero.</para> 1285 1286<table frame="all" pgwide="0"><title>POLL object</title> 1287<tgroup cols="3" align="left" colsep="1" rowsep="1"> 1288<thead> 1289<row> 1290 <entry>Name</entry> 1291 <entry>Always?</entry> 1292 <entry>Type</entry> 1293 <entry>Description</entry> 1294</row> 1295</thead> 1296<tbody> 1297<row> 1298 <entry>class</entry> 1299 <entry>Yes</entry> 1300 <entry>string</entry> 1301 <entry>Fixed: "POLL"</entry> 1302</row> 1303<row> 1304 <entry>time</entry> 1305 <entry>Yes</entry> 1306 <entry>Numeric</entry> 1307 <entry>Timestamp in ISO 8601 format. May have a 1308 fractional part of up to .001sec precision.</entry> 1309</row> 1310<row> 1311 <entry>active</entry> 1312 <entry>Yes</entry> 1313 <entry>Numeric</entry> 1314 <entry>Count of active devices.</entry> 1315</row> 1316<row> 1317 <entry>tpv</entry> 1318 <entry>Yes</entry> 1319 <entry>JSON array</entry> 1320 <entry>Comma-separated list of TPV objects.</entry> 1321</row> 1322<row> 1323 <entry>sky</entry> 1324 <entry>Yes</entry> 1325 <entry>JSON array</entry> 1326 <entry>Comma-separated list of SKY objects.</entry> 1327</row> 1328</tbody> 1329</tgroup> 1330</table> 1331 1332<para>Here's an example of a POLL response:</para> 1333 1334<programlisting> 1335{"class":"POLL","time":"2010-06-04T10:31:00.289Z","active":1, 1336 "tpv":[{"class":"TPV","device":"/dev/ttyUSB0", 1337 "time":"2010-09-08T13:33:06.095Z", 1338 "ept":0.005,"lat":40.035093060, 1339 "lon":-75.519748733,"track":99.4319,"speed":0.123,"mode":2}], 1340 "sky":[{"class":"SKY","device":"/dev/ttyUSB0", 1341 "time":1270517264.240,"hdop":9.20, 1342 "satellites":[{"PRN":16,"el":55,"az":42,"ss":36,"used":true}, 1343 {"PRN":19,"el":25,"az":177,"ss":0,"used":false}, 1344 {"PRN":7,"el":13,"az":295,"ss":0,"used":false}, 1345 {"PRN":6,"el":56,"az":135,"ss":32,"used":true}, 1346 {"PRN":13,"el":47,"az":304,"ss":0,"used":false}, 1347 {"PRN":23,"el":66,"az":259,"ss":0,"used":false}, 1348 {"PRN":20,"el":7,"az":226,"ss":0,"used":false}, 1349 {"PRN":3,"el":52,"az":163,"ss":32,"used":true}, 1350 {"PRN":31,"el":16,"az":102,"ss":0,"used":false} 1351]}]} 1352</programlisting> 1353 1354<note> 1355<para>Client software should not assume the field inventory of the 1356POLL response is fixed for all time. As 1357<application>gpsd</application> collects and caches more data from 1358more sensor types, those data are likely to find their way 1359into this response.</para> 1360</note> 1361 1362</listitem> 1363</varlistentry> 1364 1365<varlistentry> 1366<term>TOFF</term> 1367<listitem> 1368 1369<para>This message is emitted on each cycle and reports the offset 1370between the host's clock time and the GPS time at top of second 1371(actually, when the first data for the reporting cycle is received).</para> 1372 1373<para>This message exactly mirrors the PPS message except for two 1374details.</para> 1375 1376<para>TOFF emits no NTP precision, this is assumed to be -2. See 1377the NTP documentation for their definition of precision.</para> 1378 1379<para> The TOFF message reports the GPS time as derived from the GPS 1380serial data stream. The PPS message reports the GPS time as derived 1381from the GPS PPS pulse.</para> 1382 1383<para>A TOFF object has the following elements:</para> 1384 1385<table frame="all" pgwide="0"><title>TOFF object</title> 1386<tgroup cols="4" align="left" colsep="1" rowsep="1"> 1387<thead> 1388<row> 1389 <entry>Name</entry> 1390 <entry>Always?</entry> 1391 <entry>Type</entry> 1392 <entry>Description</entry> 1393</row> 1394</thead> 1395<tbody> 1396<row> 1397 <entry>class</entry> 1398 <entry>Yes</entry> 1399 <entry>string</entry> 1400 <entry>Fixed: "TOFF"</entry> 1401</row> 1402<row> 1403 <entry>device</entry> 1404 <entry>Yes</entry> 1405 <entry>string</entry> 1406 <entry>Name of originating device</entry> 1407</row> 1408<row> 1409 <entry>real_sec</entry> 1410 <entry>Yes</entry> 1411 <entry>numeric</entry> 1412 <entry>seconds from the GPS clock</entry> 1413</row> 1414<row> 1415 <entry>real_nsec</entry> 1416 <entry>Yes</entry> 1417 <entry>numeric</entry> 1418 <entry>nanoseconds from the GPS clock</entry> 1419</row> 1420<row> 1421 <entry>clock_sec</entry> 1422 <entry>Yes</entry> 1423 <entry>numeric</entry> 1424 <entry>seconds from the system clock</entry> 1425</row> 1426<row> 1427 <entry>clock_nsec</entry> 1428 <entry>Yes</entry> 1429 <entry>numeric</entry> 1430 <entry>nanoseconds from the system clock</entry> 1431</row> 1432</tbody> 1433</tgroup> 1434</table> 1435 1436<para>This message is emitted once per second to watchers of a device 1437and is intended to report the time stamps of the in-band report of the 1438GPS and seconds as reported by the system clock (which may be 1439NTP-corrected) when the first valid timestamp of the reporting cycle 1440was seen.</para> 1441 1442<para>The message contains two second/nanosecond pairs: real_sec and 1443real_nsec contain the time the GPS thinks it was at the start of the 1444current cycle; clock_sec and clock_nsec contain the time the system 1445clock thinks it was on receipt of the first timing message of the cycle. 1446real_nsec is always to nanosecond precision. clock_nsec is nanosecond 1447precision on most systems.</para> 1448 1449<para>Here's an example:</para> 1450 1451<programlisting> 1452{"class":"TOFF","device":"/dev/ttyUSB0", 1453 "real_sec":1330212592, "real_nsec":343182, 1454 "clock_sec":1330212592,"clock_nsec":343184, 1455 "precision":-2}} 1456</programlisting> 1457 1458</listitem> 1459</varlistentry> 1460 1461<varlistentry> 1462<term>PPS</term> 1463<listitem> 1464 1465<para>This message is emitted each time the daemon sees a valid PPS (Pulse 1466Per Second) strobe from a device.</para> 1467 1468<para>This message exactly mirrors the TOFF message except for two 1469details.</para> 1470 1471<para>PPS emits the NTP precision. See the NTP documentation for their 1472definition of precision.</para> 1473 1474<para>The TOFF message reports the GPS time as derived from the GPS 1475serial data stream. The PPS message reports the GPS time as derived 1476from the GPS PPS pulse.</para> 1477 1478<para>There are various sources of error in the reported clock times. 1479The speed of the serial connection between the GPS and the system adds 1480a delay to start of cycle detection. An even bigger error is added 1481by the variable computation time inside the GPS. Taken together the 1482time derived from the start of the GPS cycle can have offsets of 148310 millisecond to 700 milliseconds and combined jjitter and wander of 1484100 to 300 millisecond.</para> 1485 1486<para>A PPS object has the following elements:</para> 1487 1488<table frame="all" pgwide="0"><title>PPS object</title> 1489<tgroup cols="4" align="left" colsep="1" rowsep="1"> 1490<thead> 1491<row> 1492 <entry>Name</entry> 1493 <entry>Always?</entry> 1494 <entry>Type</entry> 1495 <entry>Description</entry> 1496</row> 1497</thead> 1498<tbody> 1499<row> 1500 <entry>class</entry> 1501 <entry>Yes</entry> 1502 <entry>string</entry> 1503 <entry>Fixed: "PPS"</entry> 1504</row> 1505<row> 1506 <entry>device</entry> 1507 <entry>Yes</entry> 1508 <entry>string</entry> 1509 <entry>Name of originating device</entry> 1510</row> 1511<row> 1512 <entry>real_sec</entry> 1513 <entry>Yes</entry> 1514 <entry>numeric</entry> 1515 <entry>seconds from the PPS source</entry> 1516</row> 1517<row> 1518 <entry>real_nsec</entry> 1519 <entry>Yes</entry> 1520 <entry>numeric</entry> 1521 <entry>nanoseconds from the PPS source</entry> 1522</row> 1523<row> 1524 <entry>clock_sec</entry> 1525 <entry>Yes</entry> 1526 <entry>numeric</entry> 1527 <entry>seconds from the system clock</entry> 1528</row> 1529<row> 1530 <entry>clock_nsec</entry> 1531 <entry>Yes</entry> 1532 <entry>numeric</entry> 1533 <entry>nanoseconds from the system clock</entry> 1534</row> 1535<row> 1536 <entry>precision</entry> 1537 <entry>Yes</entry> 1538 <entry>numeric</entry> 1539 <entry>NTP style estimate of PPS precision</entry> 1540</row> 1541<row> 1542 <entry>qErr</entry> 1543 <entry>No</entry> 1544 <entry>numeric</entry> 1545 <entry>Quantization error of the PPS, in pico seconds. Sometimes 1546called the "sawtooth" error.</entry> 1547</row> 1548</tbody> 1549</tgroup> 1550</table> 1551 1552<para>This message is emitted once per second to watchers of a device 1553emitting PPS, and reports the time of the start of the GPS second (when 1554the 1PPS arrives) and seconds as reported by the system clock (which 1555may be NTP-corrected) at that moment.</para> 1556 1557<para>The message contains two second/nanosecond pairs: real_sec and 1558real_nsec contain the time the GPS thinks it was at the PPS edge; 1559clock_sec and clock_nsec contain the time the system clock thinks it was 1560at the PPS edge. real_nsec is always to nanosecond precision. clock_nsec 1561is nanosecond precision on most systems.</para> 1562 1563<para>There are various sources of error in the reported clock times. 1564For PPS delivered via a real serial-line strobe, serial-interrupt 1565latency plus processing time to the timer call should be bounded above 1566by about 10 microseconds; that can be reduced to less than 1 microsecond if 1567your kernel supports RFC 2783. USB1.1-to-serial control-line emulation is 1568limited to about 1 millisecond. seconds.</para> 1569 1570<para>Here's an example:</para> 1571 1572<programlisting> 1573{"class":"PPS","device":"/dev/ttyUSB0", 1574 "real_sec":1330212592, "real_nsec":343182, 1575 "clock_sec":1330212592,"clock_nsec":343184, 1576 "precision":-3} 1577</programlisting> 1578 1579</listitem> 1580</varlistentry> 1581 1582<varlistentry> 1583<term>OSC</term> 1584<listitem> 1585 1586<para>This message reports the status of a GPS-disciplined oscillator 1587(GPSDO). The GPS PPS output (which has excellent long-term stability) 1588is typically used to discipline a local oscillator with much better 1589short-term stability (such as a rubidium atomic clock).</para> 1590 1591<para>An OSC object has the following elements:</para> 1592 1593<table frame="all" pgwide="0"><title>OSC object</title> 1594<tgroup cols="3" align="left" colsep="1" rowsep="1"> 1595<thead> 1596<row> 1597 <entry>Name</entry> 1598 <entry>Always?</entry> 1599 <entry>Type</entry> 1600 <entry>Description</entry> 1601</row> 1602</thead> 1603<tbody> 1604<row> 1605 <entry>class</entry> 1606 <entry>Yes</entry> 1607 <entry>string</entry> 1608 <entry>Fixed: "OSC"</entry> 1609</row> 1610<row> 1611 <entry>device</entry> 1612 <entry>Yes</entry> 1613 <entry>string</entry> 1614 <entry>Name of originating device.</entry> 1615</row> 1616<row> 1617 <entry>running</entry> 1618 <entry>Yes</entry> 1619 <entry>boolean</entry> 1620 <entry>If true, the oscillator is currently running. Oscillators may require warm-up time at start of day.</entry> 1621</row> 1622<row> 1623 <entry>reference</entry> 1624 <entry>Yes</entry> 1625 <entry>boolean</entry> 1626 <entry>If true, the oscillator is receiving a GPS PPS signal.</entry> 1627</row> 1628<row> 1629 <entry>disciplined</entry> 1630 <entry>Yes</entry> 1631 <entry>boolean</entry> 1632 <entry>If true, the GPS PPS signal is sufficiently stable and is being used to discipline the local oscillator.</entry> 1633</row> 1634<row> 1635 <entry>delta</entry> 1636 <entry>Yes</entry> 1637 <entry>numeric</entry> 1638 <entry>The time difference (in nanoseconds) between the GPS-disciplined oscillator PPS output pulse and the most recent GPS PPS input pulse.</entry> 1639</row> 1640</tbody> 1641</tgroup> 1642</table> 1643 1644<para>Here's an example:</para> 1645 1646<programlisting> 1647{"class":"OSC","running":true,"device":"/dev/ttyUSB0", 1648 "reference":true,"disciplined":true,"delta":67} 1649</programlisting> 1650</listitem> 1651</varlistentry> 1652 1653<varlistentry> 1654<term>?DEVICE</term> 1655<listitem> 1656 1657<para>This command reports (when followed by ';') the state of a 1658device, or sets (when followed by '=' and a DEVICE object) 1659device-specific control bits, notably the device's speed and serial 1660mode and the native-mode bit. The parameter-setting form will be rejected if 1661more than one client is attached to the channel.</para> 1662 1663<para>Pay attention to the response, because it is 1664possible for this command to fail if the GPS does not support a 1665speed-switching command or only supports some combinations of 1666serial modes. In case of failure, the daemon and GPS will 1667continue to communicate at the old speed.</para> 1668 1669<para>Use the parameter-setting form with caution. On USB and 1670Bluetooth GPSes it is also possible for serial mode setting to fail 1671either because the serial adaptor chip does not support non-8N1 modes 1672or because the device firmware does not properly synchronize the 1673serial adaptor chip with the UART on the GPS chipset when the speed 1674changes. These failures can hang your device, possibly requiring a GPS 1675power cycle or (in extreme cases) physically disconnecting the NVRAM 1676backup battery.</para> 1677 1678<para>A DEVICE object has the following elements:</para> 1679 1680<table frame="all" pgwide="0"><title>DEVICE object</title> 1681<tgroup cols="4" align="left" colsep="1" rowsep="1"> 1682<thead> 1683<row> 1684 <entry>Name</entry> 1685 <entry>Always?</entry> 1686 <entry>Type</entry> 1687 <entry>Description</entry> 1688</row> 1689</thead> 1690<tbody> 1691<row> 1692 <entry>class</entry> 1693 <entry>Yes</entry> 1694 <entry>string</entry> 1695 <entry>Fixed: "DEVICE"</entry> 1696</row> 1697<row> 1698 <entry>path</entry> 1699 <entry>No</entry> 1700 <entry>string</entry> 1701 <entry>Name the device for which the control bits are 1702 being reported, or for which they are to be applied. This 1703 attribute may be omitted only when there is exactly one 1704 subscribed channel.</entry> 1705</row> 1706<row> 1707 <entry>activated</entry> 1708 <entry>No</entry> 1709 <entry>string</entry> 1710 <entry>Time the device was activated as an ISO8601 1711 timestamp. If the device is inactive this attribute is 1712 absent.</entry> 1713</row> 1714<row> 1715 <entry>flags</entry> 1716 <entry>No</entry> 1717 <entry>integer</entry> 1718 <entry>Bit vector of property flags. Currently defined flags are: 1719 describe packet types seen so far (GPS, RTCM2, RTCM3, 1720 AIS). Won't be reported if empty, e.g. before 1721 <application>gpsd</application> has seen identifiable packets 1722 from the device.</entry> 1723</row> 1724<row> 1725 <entry>driver</entry> 1726 <entry>No</entry> 1727 <entry>string</entry> 1728 <entry>GPSD's name for the device driver type. Won't be reported before 1729 <application>gpsd</application> has seen identifiable packets 1730 from the device.</entry> 1731</row> 1732<row> 1733 <entry>subtype</entry> 1734 <entry>No</entry> 1735 <entry>string</entry> 1736 <entry>Whatever version information the device driver returned.</entry> 1737</row> 1738<row> 1739 <entry>subtype1</entry> 1740 <entry>No</entry> 1741 <entry>string</entry> 1742 <entry>More version information the device driver returned.</entry> 1743</row> 1744<row> 1745 <entry>bps</entry> 1746 <entry>No</entry> 1747 <entry>integer</entry> 1748 <entry>Device speed in bits per second.</entry> 1749</row> 1750<row> 1751 <entry>parity</entry> 1752 <entry>No</entry> 1753 <entry>string</entry> 1754 <entry><para>N, O or E for no parity, odd, or even.</para></entry> 1755</row> 1756<row> 1757 <entry>stopbits</entry> 1758 <entry>Yes</entry> 1759 <entry>string</entry> 1760 <entry><para>Stop bits (1 or 2).</para></entry> 1761</row> 1762<row> 1763 <entry>native</entry> 1764 <entry>No</entry> 1765 <entry>integer</entry> 1766 <entry>0 means NMEA mode and 1 means 1767 alternate mode (binary if it has one, for SiRF and Evermore chipsets 1768 in particular). Attempting to set this mode on a non-GPS 1769 device will yield an error.</entry> 1770</row> 1771<row> 1772 <entry>cycle</entry> 1773 <entry>No</entry> 1774 <entry>real</entry> 1775 <entry>Device cycle time in seconds.</entry> 1776</row> 1777<row> 1778 <entry>mincycle</entry> 1779 <entry>No</entry> 1780 <entry>real</entry> 1781 <entry>Device minimum cycle time in seconds. Reported from 1782 ?DEVICE when (and only when) the rate is switchable. It is 1783 read-only and not settable.</entry> 1784</row> 1785</tbody> 1786</tgroup> 1787</table> 1788 1789<para>The serial parameters will (bps, parity, stopbits) be omitted in 1790a response describing a TCP/IP source such as an Ntrip, DGPSIP, or AIS 1791feed; on a serial device they will always be present.</para> 1792 1793<para>The contents of the flags field should be interpreted as follows:</para> 1794 1795<table frame="all" pgwide="0"><title>Device flags</title> 1796<tgroup cols="3" align="left" colsep="1" rowsep="1"> 1797<thead> 1798<row> 1799 <entry>C #define</entry> 1800 <entry>Value</entry> 1801 <entry>Description</entry> 1802</row> 1803</thead> 1804<tbody> 1805<row> 1806 <entry>SEEN_GPS</entry> 1807 <entry>0x01</entry> 1808 <entry>GPS data has been seen on this device</entry> 1809</row> 1810<row> 1811 <entry>SEEN_RTCM2</entry> 1812 <entry>0x02</entry> 1813 <entry>RTCM2 data has been seen on this device</entry> 1814</row> 1815<row> 1816 <entry>SEEN_RTCM3</entry> 1817 <entry>0x04</entry> 1818 <entry>RTCM3 data has been seen on this device</entry> 1819</row> 1820<row> 1821 <entry>SEEN_AIS</entry> 1822 <entry>0x08</entry> 1823 <entry>AIS data has been seen on this device</entry> 1824</row> 1825</tbody> 1826</tgroup> 1827</table> 1828 1829<!-- 1830<para>The mincycle member may be 0, indicating no hard lower limit on the 1831cycle time. On an NMEA device of this kind it is possible to try to 1832push more characters through per cycle than the time to transmit will 1833allow. You must set the time high enough to let all sentences come 1834through. Here are the maxima to use for computation:</para> 1835 1836<table frame='all'> 1837<tgroup cols='2'> 1838<tbody> 1839<row><entry>ZDA </entry><entry>36</entry></row> 1840<row><entry>GLL </entry><entry>47</entry></row> 1841<row><entry>GGA </entry><entry>82</entry></row> 1842<row><entry>VTG </entry><entry>46</entry></row> 1843<row><entry>RMC </entry><entry>77</entry></row> 1844<row><entry>GSA </entry><entry>67</entry></row> 1845<row><entry>GSV </entry><entry>60 (per line, thus 180 for a set of 3)</entry> </row> 1846</tbody> 1847</tgroup> 1848</table> 1849 1850<para>The transmit time for a cycle (which must be less than 1 second) 1851is the total character count multiplied by 10 and divided by the baud 1852rate. A typical budget is GGA, RMC, GSA, 3*GSV = 82+75+67+(3*60) = 1853404.</para> 1854--> 1855 1856<para>When the C client library parses a response of this kind, it 1857will assert the DEVICE_SET bit in the top-level set member.</para> 1858 1859<para>Here's an example:</para> 1860 1861<programlisting> 1862{"class":"DEVICE","bps":4800,"parity":"N","stopbits":1,"native":0} 1863</programlisting> 1864 1865</listitem> 1866</varlistentry> 1867 1868</variablelist> 1869 1870<para>When a client is in watcher mode, the daemon will ship it DEVICE 1871notifications when a device is added to the pool or 1872deactivated.</para> 1873 1874<para>When the C client library parses a response of this kind, it 1875will assert the DEVICE_SET bit in the top-level set member.</para> 1876 1877<para>Here's an example:</para> 1878 1879<programlisting> 1880{"class":"DEVICE","path":"/dev/pts1","activated":0} 1881</programlisting> 1882 1883<para>The daemon may ship an error object in response to a 1884syntactically invalid command line or unknown command. It has 1885the following elements:</para> 1886 1887<table frame="all" pgwide="0"><title>ERROR notification object</title> 1888<tgroup cols="4" align="left" colsep="1" rowsep="1"> 1889<thead> 1890<row> 1891 <entry>Name</entry> 1892 <entry>Always?</entry> 1893 <entry>Type</entry> 1894 <entry>Description</entry> 1895</row> 1896</thead> 1897<tbody> 1898<row> 1899 <entry>class</entry> 1900 <entry>Yes</entry> 1901 <entry>string</entry> 1902 <entry>Fixed: "ERROR"</entry> 1903</row> 1904<row> 1905 <entry>message</entry> 1906 <entry>Yes</entry> 1907 <entry>string</entry> 1908 <entry>Textual error message</entry> 1909</row> 1910</tbody> 1911</tgroup> 1912</table> 1913 1914<para>Here's an example:</para> 1915 1916<programlisting> 1917{"class":"ERROR","message":"Unrecognized request '?FOO'"} 1918</programlisting> 1919 1920<para>When the C client library parses a response of this kind, it 1921will assert the ERR_SET bit in the top-level set member.</para> 1922 1923</refsect1> 1924 1925<refsect1 id='rtcm2'><title>RTCM2</title> 1926 1927<para>RTCM-104 is a family of serial protocols used for broadcasting pseudorange 1928corrections from differential-GPS reference stations. Many GPS receivers can 1929accept these corrections to improve their reporting accuracy.</para> 1930 1931<para>RTCM-104 comes in two major and incompatible flavors, 2.x and 19323.x. Each major flavor has minor (compatible) revisions.</para> 1933 1934<para>The applicable standard for RTCM Version 2.x is <citetitle>RTCM 1935Recommended Standards for Differential NAVSTAR GPS Service</citetitle> 1936RTCM Paper 194-93/SC 104-STD. For RTCM 3.1 it is <citetitle>RTCM Paper 1937177-2006-SC104-STD</citetitle>. Ordering instructions for both 1938standards are accessible from the website of the <ulink 1939url='http://www.rtcm.org/'>Radio Technical Commission for Maritime 1940Services</ulink> under "Publications".</para> 1941 1942<refsect2 id='wire-format'><title>RTCM WIRE TRANSMISSIONS</title> 1943 1944<para>Differential-GPS correction stations consist of a GPS reference 1945receiver coupled to a low frequency (LF) transmitter. The GPS 1946reference receiver is a survey-grade GPS that does GPS carrier 1947tracking and can work out its own position to a few millimeters. It 1948generates range and range-rate corrections and encodes them into 1949RTCM104. It ships the RTCM104 to the LF transmitter over serial rs-232 1950signal at 100 baud or 200 baud depending on the requirements of the 1951transmitter.</para> 1952 1953<para>The LF transmitter broadcasts the approximately 300khz radio 1954signal that differential-GPS radio receivers pick up. Transmitters 1955that are meant to have a higher range will need to transmit at the 1956slower rate. The higher the data rate the harder it will be for the 1957remote radio receiver to receive with a good signal-to-noise ration. 1958(Higher data rate signals can't be averaged over as long a time frame, 1959hence they appear noisier.)</para> 1960 1961</refsect2> 1962<refsect2 id='rtcm-wire-format'><title>RTCM WIRE FORMATS</title> 1963 1964<para>An RTCM 2.x message consists of a sequence of up to 33 30-bit 1965words. The 24 most significant bits of each word are data and the six 1966least significant bits are parity. The parity algorithm used is the 1967same ISGPS-2000 as that used on GPS satellite downlinks. Each RTCM 19682.x message consists of two header words followed by zero or more data 1969words, depending upon message type.</para> 1970 1971<para>An RTCM 3.x message begins with a fixed leader byte 0xD3. That 1972is followed by six bits of version information and 10 bits of payload 1973length information. Following that is the payload; following the 1974payload is a 3-byte checksum of the payload using the Qualcomm CRC-24Q 1975algorithm.</para> 1976 1977</refsect2> 1978<refsect2 id='rtcm2-dump-format2'><title>RTCM2 JSON FORMAT</title> 1979 1980<para>Each RTCM2 message is dumped as a single JSON object per 1981message, with the message fields as attributes of that object. Arrays 1982of satellite, station, and constellation statistics become arrays of 1983JSON sub-objects. Each sentence will normally also have a "device" 1984field containing the pathname of the originating device.</para> 1985 1986<para>All attributes other than the device field are mandatory. Header 1987attributes are emitted before others.</para> 1988 1989<refsect3><title>Header portion</title> 1990 1991<table frame="all" pgwide="0"><title>SKY object</title> 1992<tgroup cols="3" align="left" colsep="1" rowsep="1"> 1993<thead> 1994<row> 1995 <entry>Name</entry> 1996 <entry>Type</entry> 1997 <entry><para>Description</para></entry> 1998</row> 1999</thead> 2000<tbody> 2001<row> 2002 <entry>class</entry> 2003 <entry>string</entry> 2004 <entry><para>Fixed: "RTCM2".</para></entry> 2005</row> 2006<row> 2007 <entry>type</entry> 2008 <entry>integer</entry> 2009 <entry><para>Message type (1-9).</para></entry> 2010</row> 2011<row> 2012 <entry>station_id</entry> 2013 <entry>integer</entry> 2014 <entry><para>The id of the GPS reference receiver. The 2015 LF transmitters also have (different) id numbers.</para></entry> 2016</row> 2017<row> 2018 <entry>zcount</entry> 2019 <entry>real</entry> 2020 <entry><para>The reference time of the 2021 corrections in the message in seconds within the current hour. Note 2022 that it is in GPS time, which is some seconds ahead of UTC (see the 2023 U.S. Naval Observatory's <ulink 2024 url="ftp://maia.usno.navy.mil/ser7/tai-utc.dat">table of leap second 2025 corrections</ulink>).</para></entry> 2026</row> 2027<row> 2028 <entry>seqnum</entry> 2029 <entry>integer</entry> 2030 <entry><para>Sequence number. Only 3 bits wide, wraps after 7.</para></entry> 2031</row> 2032<row> 2033 <entry>length</entry> 2034 <entry>integer</entry> 2035 <entry><para>The number of words after the header that comprise the 2036 message.</para></entry> 2037</row> 2038<row> 2039 <entry>station_health</entry> 2040 <entry>integer</entry> 2041 <entry><para>Station transmission status. Indicates the health of 2042 the beacon as a reference source. Any nonzero value means the 2043 satellite is probably transmitting bad data and should not be 2044 used in a fix. 6 means the transmission is unmonitored. 7 2045 means the station is not working properly. Other values are 2046 defined by the beacon operator.</para></entry> 2047</row> 2048</tbody> 2049</tgroup> 2050</table> 2051 2052<para><message type> is one of</para> 2053 2054<variablelist> 2055<varlistentry> 2056<term>1</term> 2057<listitem><para>full corrections - one message containing corrections for 2058all GPS satellites in view. This is not common.</para></listitem> 2059</varlistentry> 2060 2061<varlistentry> 2062<term>3</term> 2063<listitem><para>reference station parameters - the position of the 2064reference station GPS antenna.</para></listitem> 2065</varlistentry> 2066 2067<varlistentry> 2068<term>4</term> 2069<listitem><para>datum — the datum to which the DGPS data is 2070referred.</para></listitem> 2071</varlistentry> 2072 2073<varlistentry> 2074<term>5</term> 2075<listitem><para>constellation health — information about the 2076satellites the beacon can see.</para></listitem> 2077</varlistentry> 2078 2079<varlistentry> 2080<term>6</term> 2081<listitem><para>null message — just a filler.</para></listitem> 2082</varlistentry> 2083 2084<varlistentry> 2085<term>7</term> 2086<listitem><para>radio beacon almanac — information about this or other beacons.</para></listitem> 2087</varlistentry> 2088 2089<varlistentry> 2090<term>9</term> 2091<listitem><para>subset corrections — a message containing corrections 2092for only a subset of the GPS satellites in view.</para></listitem> 2093</varlistentry> 2094 2095<varlistentry> 2096<term>16</term> 2097<listitem><para>special message — a text message from the beacon 2098operator.</para></listitem> 2099</varlistentry> 2100 2101<varlistentry> 2102<term>31</term> 2103<listitem><para>GLONASS subset corrections — a message 2104containing corrections for a set of the GLONASS satellites in 2105view.</para></listitem> 2106</varlistentry> 2107 2108 2109</variablelist> 2110 2111</refsect3> 2112<refsect3><title>Type 1 and 9: Correction data</title> 2113 2114<para>One or more satellite objects follow the header for type 1 or type 9 2115messages. Here is the format:</para> 2116 2117<table frame="all" pgwide="0"><title>Satellite object</title> 2118<tgroup cols="3" align="left" colsep="1" rowsep="1"> 2119<thead> 2120<row> 2121 <entry>Name</entry> 2122 <entry>Type</entry> 2123 <entry><para>Description</para></entry> 2124</row> 2125</thead> 2126<tbody> 2127<row> 2128 <entry>ident</entry> 2129 <entry>integer</entry> 2130 <entry><para>The PRN number of the satellite for which this is 2131 correction data.</para></entry> 2132</row> 2133<row> 2134 <entry>udre</entry> 2135 <entry>integer</entry> 2136 <entry><para>User Differential Range Error (0-3). See the 2137 table following for values.</para></entry> 2138</row> 2139<row> 2140 <entry>iod</entry> 2141 <entry>integer</entry> 2142 <entry><para>Issue Of Data, matching the IOD for the current 2143 ephemeris of this satellite, as transmitted by the satellite. 2144 The IOD is a unique tag that identifies the ephemeris; the GPS 2145 using the DGPS correction and the DGPS generating the data 2146 must use the same orbital positions for the 2147 satellite.</para></entry> 2148</row> 2149<row> 2150 <entry>prc</entry> 2151 <entry>real</entry> 2152 <entry><para>The pseudorange error in meters for this 2153 satellite as measured by the beacon reference receiver at the 2154 epoch indicated by the z_count in the parent 2155 record.</para></entry> 2156</row> 2157<row> 2158 <entry>rrc</entry> 2159 <entry>real</entry> 2160 <entry><para>The rate of change of pseudorange error in 2161 meters/sec for this satellite as measured by the beacon 2162 reference receiver at the epoch indicated by the z_count field 2163 in the parent record. This is used to calculate pseudorange 2164 errors at other epochs, if required by the GPS 2165 receiver.</para></entry> 2166</row> 2167</tbody> 2168</tgroup> 2169</table> 2170 2171<para>User Differential Range Error values are as follows:</para> 2172 2173<table frame="all" pgwide="0"><title>UDRE values</title> 2174<tgroup cols="2" align="left" colsep="1" rowsep="1"> 2175<tbody> 2176<row><entry>0</entry><entry>1-sigma error <= 1m</entry></row> 2177<row><entry>1</entry><entry>1-sigma error <= 4m</entry></row> 2178<row><entry>2</entry><entry>1-sigma error <= 8m</entry></row> 2179<row><entry>3</entry><entry>1-sigma error > 8m</entry></row> 2180</tbody> 2181</tgroup> 2182</table> 2183 2184<para>Here's an example:</para> 2185 2186<programlisting> 2187{"class":"RTCM2","type":1, 2188 "station_id":688,"zcount":843.0,"seqnum":5,"length":19,"station_health":6, 2189 "satellites":[ 2190 {"ident":10,"udre":0,"iod":46,"prc":-2.400,"rrc":0.000}, 2191 {"ident":13,"udre":0,"iod":94,"prc":-4.420,"rrc":0.000}, 2192 {"ident":7,"udre":0,"iod":22,"prc":-5.160,"rrc":0.002}, 2193 {"ident":2,"udre":0,"iod":34,"prc":-6.480,"rrc":0.000}, 2194 {"ident":4,"udre":0,"iod":47,"prc":-8.860,"rrc":0.000}, 2195 {"ident":8,"udre":0,"iod":76,"prc":-7.980,"rrc":0.002}, 2196 {"ident":5,"udre":0,"iod":99,"prc":-8.260,"rrc":0.002}, 2197 {"ident":23,"udre":0,"iod":81,"prc":-8.060,"rrc":0.000}, 2198 {"ident":16,"udre":0,"iod":70,"prc":-11.740,"rrc":0.000}, 2199 {"ident":30,"udre":0,"iod":4,"prc":-18.960,"rrc":-0.006}, 2200 {"ident":29,"udre":0,"iod":101,"prc":-24.960,"rrc":-0.002} 2201]} 2202</programlisting> 2203 2204</refsect3> 2205<refsect3><title>Type 3: Reference Station Parameters</title> 2206 2207<para>Here are the payload members of a type 3 (Reference Station 2208Parameters) message:</para> 2209 2210<table frame="all" pgwide="0"><title>Reference Station Parameters</title> 2211<tgroup cols="3" align="left" colsep="1" rowsep="1"> 2212<thead> 2213<row> 2214 <entry>Name</entry> 2215 <entry>Type</entry> 2216 <entry><para>Description</para></entry> 2217</row> 2218</thead> 2219<tbody> 2220<row> 2221 <entry>x</entry> 2222 <entry>real</entry> 2223 <entry><para>ECEF X coordinate.</para></entry> 2224</row> 2225<row> 2226 <entry>y</entry> 2227 <entry>real</entry> 2228 <entry><para>ECEF Y coordinate.</para></entry> 2229</row> 2230<row> 2231 <entry>z</entry> 2232 <entry>real</entry> 2233 <entry><para>ECEF Z coordinate.</para></entry> 2234</row> 2235</tbody> 2236</tgroup> 2237</table> 2238 2239<para>The coordinates are the position of the station, in meters to two 2240decimal places, in Earth Centred Earth Fixed coordinates. 2241These are usually referred to the WGS84 reference frame, but may 2242be referred to NAD83 in the US (essentially identical to WGS84 for 2243all except geodesists), or to some other reference frame in other 2244parts of the world.</para> 2245 2246<para>An invalid reference message is represented by a type 3 header 2247without payload fields.</para> 2248 2249<para>Here's an example:</para> 2250 2251<programlisting> 2252{"class":"RTCM2","type":3, 2253 "station_id":652,"zcount":1657.2,"seqnum":2,"length":4,"station_health":6, 2254 "x":3878620.92,"y":670281.40,"z":5002093.59 2255} 2256</programlisting> 2257 2258</refsect3> 2259<refsect3><title>Type 4: Datum</title> 2260 2261<para>Here are the payload members of a type 4 (Datum) message:</para> 2262 2263<table frame="all" pgwide="0"><title>Datum</title> 2264<tgroup cols="3" align="left" colsep="1" rowsep="1"> 2265<thead> 2266<row> 2267 <entry>Name</entry> 2268 <entry>Type</entry> 2269 <entry><para>Description</para></entry> 2270</row> 2271</thead> 2272<tbody> 2273<row> 2274 <entry>dgnss_type</entry> 2275 <entry>string</entry> 2276 <entry><para>Either "GPS", "GLONASS", "GALILEO", or 2277 "UNKNOWN".</para></entry> 2278</row> 2279<row> 2280 <entry>dat</entry> 2281 <entry>integer</entry> 2282 <entry><para>0 or 1 and indicates the sense of the offset 2283 shift given by dx, dy, dz. dat = 0 means that the station 2284 coordinates (in the reference message) are referred to a local 2285 datum and that adding dx, dy, dz to that position will render 2286 it in GNSS coordinates (WGS84 for GPS). If dat = 1 then the 2287 ref station position is in GNSS coordinates and adding dx, dy, 2288 dz will give it referred to the local datum.</para></entry> 2289</row> 2290<row> 2291 <entry>datum_name</entry> 2292 <entry>string</entry> 2293 <entry><para>A standard name for the datum.</para></entry> 2294</row> 2295 2296<row> 2297 <entry>dx</entry> 2298 <entry>real</entry> 2299 <entry><para>X offset.</para></entry> 2300</row> 2301<row> 2302 <entry>dy</entry> 2303 <entry>real</entry> 2304 <entry><para>Y offset.</para></entry> 2305</row> 2306<row> 2307 <entry>dz</entry> 2308 <entry>real</entry> 2309 <entry><para>Z offset.</para></entry> 2310</row> 2311</tbody> 2312</tgroup> 2313</table> 2314 2315<para><dx> <dy> <dz> are offsets to convert from 2316local datum to GNSS datum or vice versa. These fields are 2317optional.</para> 2318 2319<para>An invalid datum message is represented by a type 4 header 2320without payload fields.</para> 2321 2322</refsect3> 2323<refsect3><title>Type 5: Constellation Health</title> 2324 2325<para>One or more of these follow the header for type 5 messages — one 2326for each satellite.</para> 2327 2328<para>Here is the format:</para> 2329 2330<table frame="all" pgwide="0"><title>Constellation health</title> 2331<tgroup cols="3" align="left" colsep="1" rowsep="1"> 2332<thead> 2333<row> 2334 <entry>Name</entry> 2335 <entry>Type</entry> 2336 <entry><para>Description</para></entry> 2337</row> 2338</thead> 2339<tbody> 2340<row> 2341 <entry>ident</entry> 2342 <entry>integer</entry> 2343 <entry><para>The PRN number of the satellite.</para></entry> 2344</row> 2345<row> 2346 <entry>iodl</entry> 2347 <entry>bool</entry> 2348 <entry><para>True indicates that this information relates to 2349 the satellite information in an accompanying type 1 or type 9 2350 message.</para></entry> 2351</row> 2352<row> 2353 <entry>health</entry> 2354 <entry>integer</entry> 2355 <entry>0 indicates that the satellite is healthy. Any other value 2356 indicates a problem (coding is not known).<para></para></entry> 2357</row> 2358<row> 2359 <entry>snr</entry> 2360 <entry>integer</entry> 2361 <entry><para>The carrier/noise ratio of the received signal in 2362 the range 25 to 55 dB(Hz).</para></entry> 2363</row> 2364<row> 2365 <entry>health_en</entry> 2366 <entry>bool</entry> 2367 <entry><para>If set to True it indicates that the satellite is 2368 healthy even if the satellite navigation data says it is 2369 unhealthy.</para></entry> 2370</row> 2371<row> 2372 <entry>new_data</entry> 2373 <entry>bool</entry> 2374 <entry>True indicates that the IOD for this satellite will 2375 soon be updated in type 1 or 9 messages.<para></para></entry> 2376</row> 2377<row> 2378 <entry>los_warning</entry> 2379 <entry>bool</entry> 2380 <entry><para>Line-of-sight warning. True indicates that the 2381 satellite will shortly go unhealthy.</para></entry> 2382</row> 2383<row> 2384 <entry>tou</entry> 2385 <entry>integer</entry> 2386 <entry><para>Healthy time remaining in seconds.</para></entry> 2387</row> 2388</tbody> 2389</tgroup> 2390</table> 2391 2392</refsect3> 2393<refsect3><title>Type 6: Null</title> 2394 2395<para>This just indicates a null message. There are no payload fields.</para> 2396</refsect3> 2397 2398<refsect3><title>Unknown message</title> 2399 2400<para>This format is used to dump message words in hexadecimal when the 2401message type field doesn't match any of the known ones.</para> 2402 2403<para>Here is the format:</para> 2404 2405<table frame="all" pgwide="0"><title>Unknown Message</title> 2406<tgroup cols="3" align="left" colsep="1" rowsep="1"> 2407<thead> 2408<row> 2409 <entry>Name</entry> 2410 <entry>Type</entry> 2411 <entry><para>Description</para></entry> 2412</row> 2413</thead> 2414<tbody> 2415<row> 2416 <entry>data</entry> 2417 <entry>list</entry> 2418 <entry><para>A list of strings.</para></entry> 2419</row> 2420</tbody> 2421</tgroup> 2422</table> 2423 2424<para>Each string in the array is a hex literal representing 30 bits 2425of information, after parity checks and inversion. The high two bits 2426should be ignored.</para> 2427 2428</refsect3> 2429<refsect3><title>Type 7: Radio Beacon Almanac</title> 2430 2431<para>Here is the format:</para> 2432 2433<table frame="all" pgwide="0"><title>Contellation health</title> 2434<tgroup cols="3" align="left" colsep="1" rowsep="1"> 2435<thead> 2436<row> 2437 <entry>Name</entry> 2438 <entry>Type</entry> 2439 <entry><para>Description</para></entry> 2440</row> 2441</thead> 2442<tbody> 2443<row> 2444 <entry>lat</entry> 2445 <entry>real</entry> 2446 <entry><para>Latitude in degrees, of the LF transmitter 2447 antenna for the station for which this is an almanac. North 2448 is positive.</para></entry> 2449</row> 2450<row> 2451 <entry>lon</entry> 2452 <entry>real</entry> 2453 <entry><para>Longitude in degrees, of the LF transmitter 2454 antenna for the station for which this is an almanac. 2455 East is positive.</para></entry> 2456</row> 2457<row> 2458 <entry>range</entry> 2459 <entry>integer</entry> 2460 <entry>Published range of the station in km.<para></para></entry> 2461</row> 2462<row> 2463 <entry>frequency</entry> 2464 <entry>real</entry> 2465 <entry><para>Station broadcast frequency in kHz.</para></entry> 2466</row> 2467<row> 2468 <entry>health</entry> 2469 <entry>integer</entry> 2470 <entry><para><health> is the health of the station for 2471 which this is an almanac. If it is non-zero, the station is 2472 issuing suspect data and should not be used for fixes. The 2473 ITU and RTCM104 standards differ about the mode detailed 2474 interpretation of the <health> field and even about its 2475 bit width. 2476<!-- 2477From itu p.9 just under the type7 msg figure: 2478 2479 *** Radiobeacon health: 2480 00 (0) Radiobeacon operation normal 2481 01 (1) No integrity monitor operating 2482 10 (2) No information available 2483 11 (3) Do not use this radiobeacon 2484RTCM104, in the other hand, makes it 3 bits wide. 2485 2486The Sager documentation said health has the same meaning as in the header. 2487but this cannot be true unless the field is 3 bits wide. 2488--> 2489 </para></entry> 2490</row> 2491<row> 2492 <entry>station_id</entry> 2493 <entry>integer</entry> 2494 <entry><para>The id of the transmitter. This is not the same 2495 as the reference id in the header, the latter being the id of 2496 the reference receiver. <!-- John Sager noted: "However I know 2497 of at least one station that gets it wrong." --></para></entry> 2498</row> 2499<row> 2500 <entry>bitrate</entry> 2501 <entry>integer</entry> 2502 <entry><para>The transmitted bitrate.</para></entry> 2503</row> 2504</tbody> 2505</tgroup> 2506</table> 2507 2508<para>Here's an example:</para> 2509 2510<programlisting> 2511{"class":"RTCM2","type":9,"station_id":268,"zcount":252.6, 2512 "seqnum":4,"length":5,"station_health":0, 2513 "satellites":[ 2514 {"ident":13,"udre":0,"iod":3,"prc":-25.940,"rrc":0.066}, 2515 {"ident":2,"udre":0,"iod":73,"prc":0.920,"rrc":-0.080}, 2516 {"ident":8,"udre":0,"iod":22,"prc":23.820,"rrc":0.014} 2517]} 2518</programlisting> 2519 2520</refsect3> 2521<refsect3><title>Type 13: GPS Time of Week</title> 2522 2523<para>Here are the payload members of a type 13 (Groumf Tramitter Parameters) 2524message:</para> 2525 2526<table frame="all" pgwide="0"><title>Grund Transmitter Parameters</title> 2527<tgroup cols="3" align="left" colsep="1" rowsep="1"> 2528<thead> 2529<row> 2530 <entry>Name</entry> 2531 <entry>Type</entry> 2532 <entry><para>Description</para></entry> 2533</row> 2534</thead> 2535<tbody> 2536<row> 2537 <entry>status</entry> 2538 <entry>bool</entry> 2539 <entry><para>If True, signals user to expect a type 16 explanatory 2540 message associated with this station. Probably indicates some 2541 sort of unusual event.</para></entry> 2542</row> 2543<row> 2544 <entry>rangeflag</entry> 2545 <entry>bool</entry> 2546 <entry><para>If True, indicates that the estimated range is 2547 different from that found in the Type 7 message (which contains the 2548 beacon's listed range). Generally indicates a range reduction due to 2549 causes such as poor ionospheric conditions or reduced transmission 2550 power.</para></entry> 2551</row> 2552<row> 2553 <entry>lat</entry> 2554 <entry>real</entry> 2555 <entry><para>Degrees latitude, signed. 2556 Positive is N, negative is S.</para></entry> 2557</row> 2558<row> 2559 <entry>lon</entry> 2560 <entry>real</entry> 2561 <entry><para>Degrees longitude, signed. 2562 Positive is E, negative is W.</para></entry> 2563</row> 2564<row> 2565 <entry>range</entry> 2566 <entry>integer</entry> 2567 <entry><para>Transmission range in km (1-1024).</para></entry> 2568</row> 2569</tbody> 2570</tgroup> 2571</table> 2572 2573<para>This message type replaces message type 3 (Reference Station Parameters) 2574in RTCM 2.3.</para> 2575 2576</refsect3> 2577<refsect3><title>Type 14: GPS Time of Week</title> 2578 2579<para>Here are the payload members of a type 14 (GPS Time of Week) 2580message:</para> 2581 2582<table frame="all" pgwide="0"><title>Reference Station Parameters</title> 2583<tgroup cols="3" align="left" colsep="1" rowsep="1"> 2584<thead> 2585<row> 2586 <entry>Name</entry> 2587 <entry>Type</entry> 2588 <entry><para>Description</para></entry> 2589</row> 2590</thead> 2591<tbody> 2592<row> 2593 <entry>week</entry> 2594 <entry>integer</entry> 2595 <entry><para>GPS week (0-123).</para></entry> 2596</row> 2597<row> 2598 <entry>hour</entry> 2599 <entry>integer</entry> 2600 <entry><para>Hour of week (0-167).</para></entry> 2601</row> 2602<row> 2603 <entry>leapsecs</entry> 2604 <entry>integer</entry> 2605 <entry><para>Leap Seconds (0-63).</para></entry> 2606</row> 2607</tbody> 2608</tgroup> 2609</table> 2610 2611<para>Here's an example:</para> 2612 2613<programlisting> 2614{"class":"RTCM2","type":14,"station_id":652,"zcount":1657.2, 2615 "seqnum":3,"length":1,"station_health":6,"week":601,"hour":109, 2616 "leapsecs":15} 2617</programlisting> 2618 2619</refsect3> 2620<refsect3><title>Type 16: Special Message</title> 2621 2622<table frame="all" pgwide="0"><title>Special Message</title> 2623<tgroup cols="3" align="left" colsep="1" rowsep="1"> 2624<thead> 2625<row> 2626 <entry>Name</entry> 2627 <entry>Type</entry> 2628 <entry><para>Description</para></entry> 2629</row> 2630</thead> 2631<tbody> 2632<row> 2633 <entry>message</entry> 2634 <entry>string</entry> 2635 <entry><para>A text message sent by the beacon operator.</para></entry> 2636</row> 2637</tbody> 2638</tgroup> 2639</table> 2640 2641</refsect3> 2642<refsect3><title>Type 31: Correction data</title> 2643 2644<para>One or more GLONASS satellite objects follow the header for type 26451 or type 9 messages. Here is the format:</para> 2646 2647<table frame="all" pgwide="0"><title>Satellite object</title> 2648<tgroup cols="3" align="left" colsep="1" rowsep="1"> 2649<thead> 2650<row> 2651 <entry>Name</entry> 2652 <entry>Type</entry> 2653 <entry><para>Description</para></entry> 2654</row> 2655</thead> 2656<tbody> 2657<row> 2658 <entry>ident</entry> 2659 <entry>integer</entry> 2660 <entry><para>The PRN number of the satellite for which this is 2661 correction data.</para></entry> 2662</row> 2663<row> 2664 <entry>udre</entry> 2665 <entry>integer</entry> 2666 <entry><para>User Differential Range Error (0-3). See the 2667 table following for values.</para></entry> 2668</row> 2669<row> 2670 <entry>change</entry> 2671 <entry>boolean</entry> 2672 <entry><para>Change-of-ephemeris bit.</para></entry> 2673</row> 2674<row> 2675 <entry>tod</entry> 2676 <entry>uinteger</entry> 2677 <entry><para>Count of 30-second periods since the top of the 2678 hour.</para></entry> 2679</row> 2680<row> 2681 <entry>prc</entry> 2682 <entry>real</entry> 2683 <entry><para>The pseudorange error in meters for this 2684 satellite as measured by the beacon reference receiver at the 2685 epoch indicated by the z_count in the parent 2686 record.</para></entry> 2687</row> 2688<row> 2689 <entry>rrc</entry> 2690 <entry>real</entry> 2691 <entry><para>The rate of change of pseudorange error in 2692 meters/sec for this satellite as measured by the beacon 2693 reference receiver at the epoch indicated by the z_count field 2694 in the parent record. This is used to calculate pseudorange 2695 errors at other epochs, if required by the GPS 2696 receiver.</para></entry> 2697</row> 2698</tbody> 2699</tgroup> 2700</table> 2701 2702<para>Here's an example:</para> 2703 2704<programlisting> 2705{"class":"RTCM2","type":31,"station_id":652,"zcount":1642.2, 2706 "seqnum":0,"length":14,"station_health":6, 2707 "satellites":[ 2708 {"ident":5,"udre":0,"change":false,"tod":0,"prc":132.360,"rrc":0.000}, 2709 {"ident":15,"udre":0,"change":false,"tod":0,"prc":134.840,"rrc":0.002}, 2710 {"ident":14,"udre":0,"change":false,"tod":0,"prc":141.520,"rrc":0.000}, 2711 {"ident":6,"udre":0,"change":false,"tod":0,"prc":127.000,"rrc":0.000}, 2712 {"ident":21,"udre":0,"change":false,"tod":0,"prc":128.780,"rrc":0.000}, 2713 {"ident":22,"udre":0,"change":false,"tod":0,"prc":125.260,"rrc":0.002}, 2714 {"ident":20,"udre":0,"change":false,"tod":0,"prc":117.280,"rrc":-0.004}, 2715 {"ident":16,"udre":0,"change":false,"tod":17,"prc":113.460,"rrc":0.018} 2716]} 2717</programlisting> 2718 2719</refsect3> 2720</refsect2> 2721</refsect1> 2722 2723<refsect1 id='dump-format3'><title>RTCM3 DUMP FORMAT</title> 2724 2725<para>The support for RTCM104v3 dumping is incomplete and buggy. Do not 2726attempt to use it for production! Anyone interested in it should read 2727the source code.</para> 2728</refsect1> 2729 2730<refsect1 id='ais'><title>AIS DUMP FORMATS</title> 2731 2732<para>AIS support is an extension. It may not be present if your 2733instance of <application>gpsd</application> has been built with 2734a restricted feature set.</para> 2735 2736<para>AIS packets are dumped as JSON objects with class "AIS". Each 2737AIS report object contains a "type" field giving the AIS message type 2738and a "scaled" field telling whether the remainder of the fields are 2739dumped in scaled or unscaled form. (These will be emitted before any 2740type-specific fields.) It will also contain a "device" field naming 2741the data source. Other fields have names and types as specified in 2742the <citetitle>AIVDM/AIVDO Protocol Decoding</citetitle> document on 2743the GPSD project website; each message field table may be directly 2744interpreted as a specification for the members of the corresponding 2745JSON object type.</para> 2746 2747<para>By default, certain scaling and conversion operations are 2748performed for JSON output. Latitudes and longitudes are scaled to 2749decimal degrees rather than the native AIS unit of 1/10000th of a 2750minute of arc. Ship (but not air) speeds are scaled to knots rather 2751than tenth-of-knot units. Rate of turn may appear as "nan" if is 2752unavailable, or as one of the strings "fastright" or "fastleft" if it 2753is out of the AIS encoding range; otherwise it is quadratically mapped 2754back to the turn sensor number in degrees per minute. Vessel draughts 2755are converted to decimal meters rather than native AIS 2756decimeters. Various other scaling conversions are described in 2757<citetitle>"AIVDM/AIVDO Protocol Decoding"</citetitle>.</para> 2758 2759</refsect1> 2760<refsect1 id='subframe'><title>SUBFRAME DUMP FORMATS</title> 2761 2762<para>Subframe support is always compiled into 2763<application>gpsd</application> but many GPSes do not output subframe data 2764or the <application>gpsd</application> driver may not support subframes. 2765</para> 2766 2767<para>Subframe packets are dumped as JSON objects with class "SUBFRAME". 2768Each subframe report object contains a "frame" field giving the subframe 2769number, a "tSV" field for the transmitting satellite number, a "TOW17" 2770field containing the 17 MSBs of the start of the next 12-second message 2771and a "scaled" field telling whether the remainder of the fields are 2772dumped in scaled or unscaled form. It will also contain a "device" field 2773naming the data source. Each SUBFRAME object will have a sub-object 2774specific to that subframe page type. Those sub-object fields have names 2775and types similar to those specified in the IS-GPS-200E document; each 2776message field table may be directly interpreted as a specification for 2777the members of the corresponding JSON object type.</para> 2778 2779</refsect1> 2780 2781<refsect1 id='see_also'><title>SEE ALSO</title> 2782<para> 2783<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 2784<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 2785</para> 2786</refsect1> 2787 2788<refsect1 id='maintainer'><title>AUTHOR</title> 2789 2790<para>The protocol was designed and documented by Eric S. Raymond.</para> 2791</refsect1> 2792 2793</refentry> 2794