Devuan fork of gpsd
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

2794 lines
80 KiB

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