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.
 
 
 
 
 
 

3598 lines
64 KiB

  1. '\" t
  2. .\" Title: gpsd_json
  3. .\" Author: [see the "AUTHOR" section]
  4. .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
  5. .\" Date: 23 June 2019
  6. .\" Manual: GPSD Documentation
  7. .\" Source: The GPSD Project
  8. .\" Language: English
  9. .\"
  10. .TH "GPSD_JSON" "5" "23 June 2019" "The GPSD Project" "GPSD Documentation"
  11. .\" -----------------------------------------------------------------
  12. .\" * Define some portability stuff
  13. .\" -----------------------------------------------------------------
  14. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15. .\" http://bugs.debian.org/507673
  16. .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18. .ie \n(.g .ds Aq \(aq
  19. .el .ds Aq '
  20. .\" -----------------------------------------------------------------
  21. .\" * set default formatting
  22. .\" -----------------------------------------------------------------
  23. .\" disable hyphenation
  24. .nh
  25. .\" disable justification (adjust text to left margin only)
  26. .ad l
  27. .\" -----------------------------------------------------------------
  28. .\" * MAIN CONTENT STARTS HERE *
  29. .\" -----------------------------------------------------------------
  30. .SH "NAME"
  31. gpsd_json \- gpsd request/response protocol
  32. .SH "OVERVIEW"
  33. .PP
  34. gpsd
  35. is a service daemon that can be used to monitor GPSes, DGPS receivers, Marine AIS broadcasts, and various other location\-related and kinematic sensors\&.
  36. .PP
  37. Clients may communicate with
  38. gpsd
  39. via textual requests and responses over a socket\&. It is a bad idea for applications to speak the protocol directly: rather, they should use the
  40. libgps
  41. client library (for C; bindings also exist for other languages) and take appropriate care to conditionalize their code on the major and minor protocol version symbols\&.
  42. .PP
  43. The GPSD protocol is built on top of JSON, JavaScript Object Notation, as specified in RFC 7159:
  44. The JavaScript Object Notation (JSON) Data Interchange Format\&. GPSD\*(Aqs use of JSON is restricted in some ways that make parsing it in fixed\-extent languages (such as C) easier\&.
  45. .PP
  46. A request line is introduced by "?" and may include multiple commands\&. Commands begin with a command identifier, followed either by a terminating \*(Aq;\*(Aq or by an equal sign "=" and a JSON object treated as an argument\&. Any \*(Aq;\*(Aq or newline indication (either LF or CR\-LF) after the end of a command is ignored\&. All request lines must be composed of US\-ASCII characters and may be no more than 80 characters in length, exclusive of the trailing newline\&.
  47. .PP
  48. Responses are JSON objects all of which have a "class" attribute the value of which is either the name of the invoking command\&. There are reports (including but not limited to as "TPV", "SKY", "DEVICE", and "ERROR") which are not direct responses to commands\&.
  49. .PP
  50. The order of JSON attributes within a response object is never significant, and you may specify attributes in commands in any order\&. Responses never contain the special JSON value null; instead, attributes with empty or undefined values are omitted\&. The length limit for responses and reports is 1536 characters, including trailing newline; longer responses will be truncated, so client code must be prepared for the possibility of invalid JSON fragments\&.
  51. .PP
  52. In JSON reports, if an attribute is present only if the parent attribute is present or has a particular range, then the parent attribute is emitted first\&.
  53. .PP
  54. There is one constraint on the order in which attributes will be omitted\&. If an optional attribute is present only when a parent attribute has a specified value or range of values, the parent attribute will be emitted first to make parsing easier\&.
  55. .PP
  56. The next subsection section documents the core GPSD protocol\&. Extensions are documented in the following subsections\&. The extensions may not be supported in your
  57. gpsd
  58. instance if it has been compiled with a restricted feature set\&.
  59. .SH "CORE SOCKET PROTOCOL"
  60. .PP
  61. Here are the core\-protocol responses:
  62. .PP
  63. TPV
  64. .RS 4
  65. A TPV object is a time\-position\-velocity report\&. The "class" and "mode" fields will reliably be present\&. The "mode" field will be emitted before optional fields that may be absent when there is no fix\&. Error estimates will be emitted after the fix components they\*(Aqre associated with\&. Others may be reported or not depending on the fix quality\&.
  66. .sp
  67. All error estimates (epc, epd, epe, eph, ept, epv, epx, epy) are assumed to be 95% confidence, may also be 50%, one sigma, or two sigma confidence\&. Many GPS do not specify a confidence level\&. No GPS specifies how the value is calculated\&. Use error estimates with caution, and only as relative "goodness" indicators\&. If the GPS reports a value to gpsd, then gpsd will report that value\&. Otherwise gpsd will try to compute the value from the skyview\&.
  68. .sp
  69. .it 1 an-trap
  70. .nr an-no-space-flag 1
  71. .nr an-break-flag 1
  72. .br
  73. .B Table\ \&1.\ \&TPV object
  74. .TS
  75. allbox tab(:);
  76. lB lB lB lB.
  77. T{
  78. Name
  79. T}:T{
  80. Always?
  81. T}:T{
  82. Type
  83. T}:T{
  84. Description
  85. T}
  86. .T&
  87. l l l l
  88. l l l l
  89. l l l l
  90. l l l l
  91. l l l l
  92. l l l l
  93. l l l l
  94. l l l l
  95. l l l l
  96. l l l l
  97. l l l l
  98. l l l l
  99. l l l l
  100. l l l l
  101. l l l l
  102. l l l l
  103. l l l l
  104. l l l l
  105. l l l l
  106. l l l l
  107. l l l l
  108. l l l l
  109. l l l
  110. l l l l
  111. l l l l
  112. l l l l
  113. l l l l
  114. l l l l
  115. l l l l
  116. l l l l
  117. l l l l
  118. l l l l
  119. l l l l
  120. l l l l
  121. l l l l
  122. l l l l
  123. l l l l
  124. l l l l
  125. l l l l
  126. l l l l
  127. l l l l
  128. l l l l
  129. l l l l
  130. l l l l.
  131. T{
  132. class
  133. T}:T{
  134. Yes
  135. T}:T{
  136. string
  137. T}:T{
  138. Fixed: "TPV"
  139. T}
  140. T{
  141. device
  142. T}:T{
  143. No
  144. T}:T{
  145. string
  146. T}:T{
  147. Name of originating device\&.
  148. T}
  149. T{
  150. status
  151. T}:T{
  152. No
  153. T}:T{
  154. numeric
  155. T}:T{
  156. GPS status: %d, 2=DGPS fix, otherwise not present\&.
  157. T}
  158. T{
  159. mode
  160. T}:T{
  161. Yes
  162. T}:T{
  163. numeric
  164. T}:T{
  165. NMEA mode: %d, 0=no mode value yet seen, 1=no fix, 2=2D, 3=3D\&.
  166. T}
  167. T{
  168. time
  169. T}:T{
  170. No
  171. T}:T{
  172. string
  173. T}:T{
  174. Time/date stamp in ISO8601 format, UTC\&. May have a
  175. fractional part of up to \&.001sec precision\&. May be absent if mode
  176. is not 2 or 3\&.
  177. T}
  178. T{
  179. altHAE
  180. T}:T{
  181. No
  182. T}:T{
  183. numeric
  184. T}:T{
  185. Altitude, height above allipsoid, in meters\&. Probably
  186. WGS84\&. Present if mode is 3\&.
  187. T}
  188. T{
  189. altMSL
  190. T}:T{
  191. No
  192. T}:T{
  193. numeric
  194. T}:T{
  195. MSL Altitude in meters\&. The geoid used is rarely specified
  196. and is often inacurate\&. See the comments below on geoidSep\&. Present if
  197. mode is 3\&. altMSL is altHAE \- geoidSep\&.
  198. T}
  199. T{
  200. alt
  201. T}:T{
  202. No
  203. T}:T{
  204. numeric
  205. T}:T{
  206. Deprecated\&. Undefined\&. Use altHAE or altMSL\&.
  207. T}
  208. T{
  209. climb
  210. T}:T{
  211. No
  212. T}:T{
  213. numeric
  214. T}:T{
  215. Climb (positive) or sink (negative) rate, meters per
  216. second\&.
  217. T}
  218. T{
  219. datum
  220. T}:T{
  221. No
  222. T}:T{
  223. string
  224. T}:T{
  225. Current datum\&.
  226. T}
  227. T{
  228. depth
  229. T}:T{
  230. No
  231. T}:T{
  232. numeric
  233. T}:T{
  234. Depth in meters\&. Probably depth below the keel\&.\&.
  235. T}
  236. T{
  237. dgpsAge
  238. T}:T{
  239. No
  240. T}:T{
  241. numeric
  242. T}:T{
  243. Age of DGPS data\&. In seconds
  244. T}
  245. T{
  246. dgpsSta
  247. T}:T{
  248. No
  249. T}:T{
  250. numeric
  251. T}:T{
  252. Station of DGPS data\&.
  253. T}
  254. T{
  255. epc
  256. T}:T{
  257. No
  258. T}:T{
  259. numeric
  260. T}:T{
  261. Estimated climb error in meters per second\&. Present
  262. if consecutive 3D fixes\&.
  263. T}
  264. T{
  265. epd
  266. T}:T{
  267. No
  268. T}:T{
  269. numeric
  270. T}:T{
  271. Estimated track (direction) error in degrees\&. Present if
  272. consecutive 2D fixes\&.
  273. T}
  274. T{
  275. eph
  276. T}:T{
  277. No
  278. T}:T{
  279. numeric
  280. T}:T{
  281. Estimated horizontal Position (2D) Error in meters\&.
  282. Also known as Estimated Position Error (epe)\&. Present
  283. if mode is 2D or 3D and DOPs can be calculated from the satellite
  284. view\&.
  285. T}
  286. T{
  287. eps
  288. T}:T{
  289. No
  290. T}:T{
  291. numeric
  292. T}:T{
  293. Estimated speed error in meters per second\&. Present
  294. for consecutive 2D or 3D fixes\&.
  295. T}
  296. T{
  297. ept
  298. T}:T{
  299. No
  300. T}:T{
  301. numeric
  302. T}:T{
  303. Estimated timestamp error in seconds\&.
  304. Present if time is present\&.
  305. T}
  306. T{
  307. epx
  308. T}:T{
  309. No
  310. T}:T{
  311. numeric
  312. T}:T{
  313. Longitude error estimate in meters\&. Present
  314. if mode is 2D or 3D and DOPs can be calculated from the satellite
  315. view\&.
  316. T}
  317. T{
  318. epy
  319. T}:T{
  320. No
  321. T}:T{
  322. numeric
  323. T}:T{
  324. Latitude error estimate in meters\&. Present
  325. if mode is 2 or 3 and DOPs can be calculated from the satellite
  326. view\&.
  327. T}
  328. T{
  329. epv
  330. T}:T{
  331. No
  332. T}:T{
  333. numeric
  334. T}:T{
  335. Estimated vertical error in meters\&. Present
  336. if mode is 3 and DOPs can be calculated from the satellite
  337. view\&.
  338. T}
  339. T{
  340. lat
  341. T}:T{
  342. No
  343. T}:T{
  344. numeric
  345. T}:T{
  346. Latitude in degrees: +/\- signifies North/South\&. Present
  347. when mode is 2 or 3\&.
  348. T}
  349. T{
  350. leapseconds
  351. T}:T{
  352. integer
  353. T}:T{
  354. Current leap seconds\&.
  355. T}
  356. T{
  357. lon
  358. T}:T{
  359. No
  360. T}:T{
  361. numeric
  362. T}:T{
  363. Longitude in degrees: +/\- signifies East/West\&. Present
  364. when mode is 2 or 3\&.
  365. T}
  366. T{
  367. track
  368. T}:T{
  369. No
  370. T}:T{
  371. numeric
  372. T}:T{
  373. Course over ground, degrees from true north\&.
  374. T}
  375. T{
  376. magtrack
  377. T}:T{
  378. No
  379. T}:T{
  380. numeric
  381. T}:T{
  382. Course over ground, degrees magnetic\&.
  383. T}
  384. T{
  385. magvar
  386. T}:T{
  387. No
  388. T}:T{
  389. numeric
  390. T}:T{
  391. Magnetic variation, degrees\&. Also known as
  392. the magnetic declination (the direction of the horizontal component of
  393. the magnetic field measured clockwise from north) in degrees,
  394. Positive is West variation\&. Negative is East variation\&.
  395. T}
  396. T{
  397. speed
  398. T}:T{
  399. No
  400. T}:T{
  401. numeric
  402. T}:T{
  403. Speed over ground, meters per second\&.
  404. T}
  405. T{
  406. ecefx
  407. T}:T{
  408. No
  409. T}:T{
  410. numeric
  411. T}:T{
  412. ECEF X position in meters\&.
  413. T}
  414. T{
  415. ecefy
  416. T}:T{
  417. No
  418. T}:T{
  419. numeric
  420. T}:T{
  421. ECEF Y position in meters\&.
  422. T}
  423. T{
  424. ecefz
  425. T}:T{
  426. No
  427. T}:T{
  428. numeric
  429. T}:T{
  430. ECEF Z position in meters\&.
  431. T}
  432. T{
  433. ecefpAcc
  434. T}:T{
  435. No
  436. T}:T{
  437. numeric
  438. T}:T{
  439. ECEF position error in meters\&.
  440. T}
  441. T{
  442. ecefvx
  443. T}:T{
  444. No
  445. T}:T{
  446. numeric
  447. T}:T{
  448. ECEF X velocity in meters/second\&.
  449. T}
  450. T{
  451. ecefvy
  452. T}:T{
  453. No
  454. T}:T{
  455. numeric
  456. T}:T{
  457. ECEF Y velocity in meters/second\&.
  458. T}
  459. T{
  460. ecefvz
  461. T}:T{
  462. No
  463. T}:T{
  464. numeric
  465. T}:T{
  466. ECEF Z velocity in meters/second\&.
  467. T}
  468. T{
  469. ecefvAcc
  470. T}:T{
  471. No
  472. T}:T{
  473. numeric
  474. T}:T{
  475. ECEF velocity error in meters/second\&.
  476. T}
  477. T{
  478. sep
  479. T}:T{
  480. No
  481. T}:T{
  482. numeric
  483. T}:T{
  484. Estimated Spherical (3D) Position Error in meters\&.
  485. Present if mode is 3D and DOPs can be calculated from the satellite
  486. view\&. Assumed to be 95% confidence, but many GPS do not specify\&.
  487. T}
  488. T{
  489. relN
  490. T}:T{
  491. No
  492. T}:T{
  493. numeric
  494. T}:T{
  495. North component of relative position vector in meters\&.
  496. T}
  497. T{
  498. relE
  499. T}:T{
  500. No
  501. T}:T{
  502. numeric
  503. T}:T{
  504. East component of relative position vector in meters\&.
  505. T}
  506. T{
  507. relD
  508. T}:T{
  509. No
  510. T}:T{
  511. numeric
  512. T}:T{
  513. Down component of relative position vector in meters\&.
  514. T}
  515. T{
  516. velN
  517. T}:T{
  518. No
  519. T}:T{
  520. numeric
  521. T}:T{
  522. North velocity component in meters\&.
  523. T}
  524. T{
  525. velE
  526. T}:T{
  527. No
  528. T}:T{
  529. numeric
  530. T}:T{
  531. wEast velocity component in meters\&.
  532. T}
  533. T{
  534. velD
  535. T}:T{
  536. No
  537. T}:T{
  538. numeric
  539. T}:T{
  540. Down velocity component in meters\&.
  541. T}
  542. T{
  543. geoidSep
  544. T}:T{
  545. No
  546. T}:T{
  547. numeric
  548. T}:T{
  549. Geoid separation is the difference between the WGS84
  550. reference elipsoid and the geoid (Mean Sea Level) in meters\&. Almost no
  551. GNSS receiver specifies how they compute their geoid\&. gpsd interpolates the
  552. geoid from a 5x5 degree table of EGM2008 values when the receiver does
  553. not supply a geoid separation\&. The gpsd computed geoidSep is usually
  554. within one meter of the "true" value, but can be off as much as 12 meters\&.
  555. T}
  556. .TE
  557. .sp 1
  558. When the C client library parses a response of this kind, it will assert validity bits in the top\-level set member for each field actually received; see gps\&.h for bitmask names and values\&.
  559. .sp
  560. Invalid or known floating point values will be set to NAN\&.
  561. .sp
  562. Here\*(Aqs an example:
  563. .sp
  564. .if n \{\
  565. .RS 4
  566. .\}
  567. .nf
  568. {"class":"TPV","device":"/dev/pts/1",
  569. "time":"2005\-06\-08T10:34:48\&.283Z","ept":0\&.005,
  570. "lat":46\&.498293369,"lon":7\&.567411672,"alt":1343\&.127,
  571. "eph":36\&.000,"epv":32\&.321,
  572. "track":10\&.3788,"speed":0\&.091,"climb":\-0\&.085,"mode":3}
  573. .fi
  574. .if n \{\
  575. .RE
  576. .\}
  577. .RE
  578. .PP
  579. SKY
  580. .RS 4
  581. A SKY object reports a sky view of the GPS satellite positions\&. If there is no GPS device available, or no skyview has been reported yet, only the "class" field will reliably be present\&.
  582. .sp
  583. .it 1 an-trap
  584. .nr an-no-space-flag 1
  585. .nr an-break-flag 1
  586. .br
  587. .B Table\ \&2.\ \&SKY object
  588. .TS
  589. allbox tab(:);
  590. lB lB lB lB.
  591. T{
  592. Name
  593. T}:T{
  594. Always?
  595. T}:T{
  596. Type
  597. T}:T{
  598. Description
  599. T}
  600. .T&
  601. l l l l
  602. l l l l
  603. l l l l
  604. l l l l
  605. l l l l
  606. l l l l
  607. l l l l
  608. l l l l
  609. l l l l
  610. l l l l
  611. l l l l.
  612. T{
  613. class
  614. T}:T{
  615. Yes
  616. T}:T{
  617. string
  618. T}:T{
  619. Fixed: "SKY"
  620. T}
  621. T{
  622. device
  623. T}:T{
  624. No
  625. T}:T{
  626. string
  627. T}:T{
  628. Name of originating device
  629. T}
  630. T{
  631. time
  632. T}:T{
  633. No
  634. T}:T{
  635. string
  636. T}:T{
  637. Time/date stamp in ISO8601 format, UTC\&. May have a
  638. fractional part of up to \&.001sec precision\&.
  639. T}
  640. T{
  641. gdop
  642. T}:T{
  643. No
  644. T}:T{
  645. numeric
  646. T}:T{
  647. Geometric (hyperspherical) dilution of precision, a
  648. combination of PDOP and TDOP\&. A dimensionless factor which
  649. should be multiplied by a base UERE
  650. to get an error estimate\&.
  651. T}
  652. T{
  653. hdop
  654. T}:T{
  655. No
  656. T}:T{
  657. numeric
  658. T}:T{
  659. Horizontal dilution of precision, a dimensionless
  660. factor which should be multiplied by a base UERE to get a
  661. circular error estimate\&.
  662. T}
  663. T{
  664. pdop
  665. T}:T{
  666. No
  667. T}:T{
  668. numeric
  669. T}:T{
  670. Position (spherical/3D) dilution of precision, a dimensionless
  671. factor which should be multiplied by a base UERE to get an
  672. error estimate\&.
  673. T}
  674. T{
  675. tdop
  676. T}:T{
  677. No
  678. T}:T{
  679. numeric
  680. T}:T{
  681. Time dilution of precision, a dimensionless
  682. factor which should be multiplied by a base UERE to get an
  683. error estimate\&.
  684. T}
  685. T{
  686. vdop
  687. T}:T{
  688. No
  689. T}:T{
  690. numeric
  691. T}:T{
  692. Vertical (altitude) dilution of precision, a dimensionless
  693. factor which should be multiplied by a base UERE to get an
  694. error estimate\&.
  695. T}
  696. T{
  697. xdop
  698. T}:T{
  699. No
  700. T}:T{
  701. numeric
  702. T}:T{
  703. Longitudinal dilution of precision, a dimensionless
  704. factor which should be multiplied by a base UERE to get an
  705. error estimate\&.
  706. T}
  707. T{
  708. ydop
  709. T}:T{
  710. No
  711. T}:T{
  712. numeric
  713. T}:T{
  714. Latitudinal dilution of precision, a dimensionless
  715. factor which should be multiplied by a base UERE to get an
  716. error estimate\&.
  717. T}
  718. T{
  719. satellites
  720. T}:T{
  721. Yes
  722. T}:T{
  723. list
  724. T}:T{
  725. List of satellite objects in skyview
  726. T}
  727. .TE
  728. .sp 1
  729. Many devices compute dilution of precision factors but do not include them in their reports\&. Many that do report DOPs report only HDOP, two\-dimensional circular error\&.
  730. gpsd
  731. always passes through whatever the device actually reports, then attempts to fill in other DOPs by calculating the appropriate determinants in a covariance matrix based on the satellite view\&. DOPs may be missing if some of these determinants are singular\&. It can even happen that the device reports an error estimate in meters when the corresponding DOP is unavailable; some devices use more sophisticated error modeling than the covariance calculation\&.
  732. .sp
  733. The satellite list objects have the following elements:
  734. .sp
  735. .it 1 an-trap
  736. .nr an-no-space-flag 1
  737. .nr an-break-flag 1
  738. .br
  739. .B Table\ \&3.\ \&Satellite object
  740. .TS
  741. allbox tab(:);
  742. lB lB lB lB.
  743. T{
  744. Name
  745. T}:T{
  746. Always?
  747. T}:T{
  748. Type
  749. T}:T{
  750. Description
  751. T}
  752. .T&
  753. l l l l
  754. l l l l
  755. l l l l
  756. l l l l
  757. l l l l
  758. l l l l
  759. l l l l
  760. l l l l
  761. l l l l
  762. l l l l.
  763. T{
  764. PRN
  765. T}:T{
  766. Yes
  767. T}:T{
  768. numeric
  769. T}:T{
  770. PRN ID of the satellite\&. 1\-63 are GNSS satellites,
  771. 64\-96 are GLONASS satellites, 100\-164 are SBAS satellites
  772. T}
  773. T{
  774. az
  775. T}:T{
  776. No
  777. T}:T{
  778. numeric
  779. T}:T{
  780. Azimuth, degrees from true north\&.
  781. T}
  782. T{
  783. el
  784. T}:T{
  785. No
  786. T}:T{
  787. numeric
  788. T}:T{
  789. Elevation in degrees\&.
  790. T}
  791. T{
  792. ss
  793. T}:T{
  794. No
  795. T}:T{
  796. numeric
  797. T}:T{
  798. Signal to Noise ratio in dBHz\&.
  799. T}
  800. T{
  801. used
  802. T}:T{
  803. Yes
  804. T}:T{
  805. boolean
  806. T}:T{
  807. Used in current solution? (SBAS/WAAS/EGNOS satellites
  808. may be flagged used if the solution has corrections from them,
  809. but not all drivers make this information available\&.)
  810. T}
  811. T{
  812. gnssid
  813. T}:T{
  814. No
  815. T}:T{
  816. numeric
  817. T}:T{
  818. The GNSS ID, as defined by u\-blox, not NMEA\&. 0=GPS,
  819. 2=Galileo, 3=Beidou, 5=QZSS, 6\-GLONASS\&.
  820. T}
  821. T{
  822. svid
  823. T}:T{
  824. no
  825. T}:T{
  826. numeric
  827. T}:T{
  828. The satellite ID within its constellation\&. As defined
  829. by u\-blox, not NMEA)\&.
  830. T}
  831. T{
  832. sigid
  833. T}:T{
  834. no
  835. T}:T{
  836. numeric
  837. T}:T{
  838. The signal ID of this signal\&. As defined by u\-blox, not
  839. NMEA\&. See u\-blox doc for details\&.
  840. T}
  841. T{
  842. freqid
  843. T}:T{
  844. no
  845. T}:T{
  846. numeric
  847. T}:T{
  848. For GLONASS satellites only: the frequency ID of the signal\&.
  849. As defined by u\-blox, range 0 to 13\&. The freqid is the frequency slot
  850. plus 7\&.
  851. T}
  852. T{
  853. health
  854. T}:T{
  855. no
  856. T}:T{
  857. numeric
  858. T}:T{
  859. The health of this satellite\&. 0 is unknown, 1 is
  860. OK, and 2 is unhealthy\&.
  861. T}
  862. .TE
  863. .sp 1
  864. Note that satellite objects do not have a "class" field, as they are never shipped outside of a SKY object\&.
  865. .sp
  866. When the C client library parses a SKY response, it will assert the SATELLITE_SET bit in the top\-level set member\&.
  867. .sp
  868. Here\*(Aqs an example:
  869. .sp
  870. .if n \{\
  871. .RS 4
  872. .\}
  873. .nf
  874. {"class":"SKY","device":"/dev/pts/1",
  875. "time":"2005\-07\-08T11:28:07\&.114Z",
  876. "xdop":1\&.55,"hdop":1\&.24,"pdop":1\&.99,
  877. "satellites":[
  878. {"PRN":23,"el":6,"az":84,"ss":0,"used":false},
  879. {"PRN":28,"el":7,"az":160,"ss":0,"used":false},
  880. {"PRN":8,"el":66,"az":189,"ss":44,"used":true},
  881. {"PRN":29,"el":13,"az":273,"ss":0,"used":false},
  882. {"PRN":10,"el":51,"az":304,"ss":29,"used":true},
  883. {"PRN":4,"el":15,"az":199,"ss":36,"used":true},
  884. {"PRN":2,"el":34,"az":241,"ss":43,"used":true},
  885. {"PRN":27,"el":71,"az":76,"ss":43,"used":true}]}
  886. .fi
  887. .if n \{\
  888. .RE
  889. .\}
  890. .RE
  891. .PP
  892. GST
  893. .RS 4
  894. A GST object is a pseudorange noise report\&.
  895. .sp
  896. .it 1 an-trap
  897. .nr an-no-space-flag 1
  898. .nr an-break-flag 1
  899. .br
  900. .B Table\ \&4.\ \&GST object
  901. .TS
  902. allbox tab(:);
  903. lB lB lB lB.
  904. T{
  905. Name
  906. T}:T{
  907. Always?
  908. T}:T{
  909. Type
  910. T}:T{
  911. Description
  912. T}
  913. .T&
  914. l l l l
  915. l l l l
  916. l l l l
  917. l l l l
  918. l l l l
  919. l l l l
  920. l l l l
  921. l l l l
  922. l l l l
  923. l l l l.
  924. T{
  925. class
  926. T}:T{
  927. Yes
  928. T}:T{
  929. string
  930. T}:T{
  931. Fixed: "GST"
  932. T}
  933. T{
  934. device
  935. T}:T{
  936. No
  937. T}:T{
  938. string
  939. T}:T{
  940. Name of originating device
  941. T}
  942. T{
  943. time
  944. T}:T{
  945. No
  946. T}:T{
  947. string
  948. T}:T{
  949. Time/date stamp in ISO8601 format, UTC\&. May have a
  950. fractional part of up to \&.001sec precision\&.
  951. T}
  952. T{
  953. rms
  954. T}:T{
  955. No
  956. T}:T{
  957. numeric
  958. T}:T{
  959. Value of the standard deviation of the range inputs to the
  960. navigation process (range inputs include pseudoranges and DGPS
  961. corrections)\&.
  962. T}
  963. T{
  964. major
  965. T}:T{
  966. No
  967. T}:T{
  968. numeric
  969. T}:T{
  970. Standard deviation of semi\-major axis of error ellipse, in meters\&.
  971. T}
  972. T{
  973. minor
  974. T}:T{
  975. No
  976. T}:T{
  977. numeric
  978. T}:T{
  979. Standard deviation of semi\-minor axis of error ellipse, in meters\&.
  980. T}
  981. T{
  982. orient
  983. T}:T{
  984. No
  985. T}:T{
  986. numeric
  987. T}:T{
  988. Orientation of semi\-major axis of error ellipse, in degrees from true north\&.
  989. T}
  990. T{
  991. lat
  992. T}:T{
  993. No
  994. T}:T{
  995. numeric
  996. T}:T{
  997. Standard deviation of latitude error, in meters\&.
  998. T}
  999. T{
  1000. lon
  1001. T}:T{
  1002. No
  1003. T}:T{
  1004. numeric
  1005. T}:T{
  1006. Standard deviation of longitude error, in meters\&.
  1007. T}
  1008. T{
  1009. alt
  1010. T}:T{
  1011. No
  1012. T}:T{
  1013. numeric
  1014. T}:T{
  1015. Standard deviation of altitude error, in meters\&.
  1016. T}
  1017. .TE
  1018. .sp 1
  1019. Here\*(Aqs an example:
  1020. .sp
  1021. .if n \{\
  1022. .RS 4
  1023. .\}
  1024. .nf
  1025. {"class":"GST","device":"/dev/ttyUSB0",
  1026. "time":"2010\-12\-07T10:23:07\&.096Z","rms":2\&.440,
  1027. "major":1\&.660,"minor":1\&.120,"orient":68\&.989,
  1028. "lat":1\&.600,"lon":1\&.200,"alt":2\&.520}
  1029. .fi
  1030. .if n \{\
  1031. .RE
  1032. .\}
  1033. .RE
  1034. .PP
  1035. ATT
  1036. .RS 4
  1037. An ATT object is a vehicle\-attitude report\&. It is returned by digital\-compass and gyroscope sensors; depending on device, it may include: heading, pitch, roll, yaw, gyroscope, and magnetic\-field readings\&. Because such sensors are often bundled as part of marine\-navigation systems, the ATT response may also include water depth\&.
  1038. .sp
  1039. The "class" and "mode" fields will reliably be present\&. Others may be reported or not depending on the specific device type\&.
  1040. .sp
  1041. .it 1 an-trap
  1042. .nr an-no-space-flag 1
  1043. .nr an-break-flag 1
  1044. .br
  1045. .B Table\ \&5.\ \&ATT object
  1046. .TS
  1047. allbox tab(:);
  1048. lB lB lB lB.
  1049. T{
  1050. Name
  1051. T}:T{
  1052. Always?
  1053. T}:T{
  1054. Type
  1055. T}:T{
  1056. Description
  1057. T}
  1058. .T&
  1059. l l l l
  1060. l l l l
  1061. l l l l
  1062. l l l l
  1063. l l l l
  1064. l l l l
  1065. l l l l
  1066. l l l l
  1067. l l l l
  1068. l l l l
  1069. l l l l
  1070. l l l l
  1071. l l l l
  1072. l l l l
  1073. l l l l
  1074. l l l l
  1075. l l l l
  1076. l l l l
  1077. l l l l
  1078. l l l l
  1079. l l l l
  1080. l l l l
  1081. l l l l
  1082. l l l l.
  1083. T{
  1084. class
  1085. T}:T{
  1086. Yes
  1087. T}:T{
  1088. string
  1089. T}:T{
  1090. Fixed: "ATT"
  1091. T}
  1092. T{
  1093. device
  1094. T}:T{
  1095. Yes
  1096. T}:T{
  1097. string
  1098. T}:T{
  1099. Name of originating device
  1100. T}
  1101. T{
  1102. time
  1103. T}:T{
  1104. No
  1105. T}:T{
  1106. string
  1107. T}:T{
  1108. Time/date stamp in ISO8601 format, UTC\&. May have a
  1109. fractional part of up to \&.001sec precision\&.
  1110. T}
  1111. T{
  1112. heading
  1113. T}:T{
  1114. No
  1115. T}:T{
  1116. numeric
  1117. T}:T{
  1118. Heading, degrees from true north\&.
  1119. T}
  1120. T{
  1121. mag_st
  1122. T}:T{
  1123. No
  1124. T}:T{
  1125. string
  1126. T}:T{
  1127. Magnetometer status\&.
  1128. T}
  1129. T{
  1130. pitch
  1131. T}:T{
  1132. No
  1133. T}:T{
  1134. numeric
  1135. T}:T{
  1136. Pitch in degrees\&.
  1137. T}
  1138. T{
  1139. pitch_st
  1140. T}:T{
  1141. No
  1142. T}:T{
  1143. string
  1144. T}:T{
  1145. Pitch sensor status\&.
  1146. T}
  1147. T{
  1148. yaw
  1149. T}:T{
  1150. No
  1151. T}:T{
  1152. numeric
  1153. T}:T{
  1154. Yaw in degrees
  1155. T}
  1156. T{
  1157. yaw_st
  1158. T}:T{
  1159. No
  1160. T}:T{
  1161. string
  1162. T}:T{
  1163. Yaw sensor status\&.
  1164. T}
  1165. T{
  1166. roll
  1167. T}:T{
  1168. No
  1169. T}:T{
  1170. numeric
  1171. T}:T{
  1172. Roll in degrees\&.
  1173. T}
  1174. T{
  1175. roll_st
  1176. T}:T{
  1177. No
  1178. T}:T{
  1179. string
  1180. T}:T{
  1181. Roll sensor status\&.
  1182. T}
  1183. T{
  1184. dip
  1185. T}:T{
  1186. No
  1187. T}:T{
  1188. numeric
  1189. T}:T{
  1190. Local magnetic inclination, degrees, positive when the magnetic
  1191. field points downward (into the Earth)\&.
  1192. T}
  1193. T{
  1194. mag_len
  1195. T}:T{
  1196. No
  1197. T}:T{
  1198. numeric
  1199. T}:T{
  1200. Scalar magnetic field strength\&.
  1201. T}
  1202. T{
  1203. mag_x
  1204. T}:T{
  1205. No
  1206. T}:T{
  1207. numeric
  1208. T}:T{
  1209. X component of magnetic field strength\&.
  1210. T}
  1211. T{
  1212. mag_y
  1213. T}:T{
  1214. No
  1215. T}:T{
  1216. numeric
  1217. T}:T{
  1218. Y component of magnetic field strength\&.
  1219. T}
  1220. T{
  1221. mag_z
  1222. T}:T{
  1223. No
  1224. T}:T{
  1225. numeric
  1226. T}:T{
  1227. Z component of magnetic field strength\&.
  1228. T}
  1229. T{
  1230. acc_len
  1231. T}:T{
  1232. No
  1233. T}:T{
  1234. numeric
  1235. T}:T{
  1236. Scalar acceleration\&.
  1237. T}
  1238. T{
  1239. acc_x
  1240. T}:T{
  1241. No
  1242. T}:T{
  1243. numeric
  1244. T}:T{
  1245. X component of acceleration\&.
  1246. T}
  1247. T{
  1248. acc_y
  1249. T}:T{
  1250. No
  1251. T}:T{
  1252. numeric
  1253. T}:T{
  1254. Y component of acceleration\&.
  1255. T}
  1256. T{
  1257. acc_z
  1258. T}:T{
  1259. No
  1260. T}:T{
  1261. numeric
  1262. T}:T{
  1263. Z component of acceleration\&.
  1264. T}
  1265. T{
  1266. gyro_x
  1267. T}:T{
  1268. No
  1269. T}:T{
  1270. numeric
  1271. T}:T{
  1272. X component of acceleration\&.
  1273. T}
  1274. T{
  1275. gyro_y
  1276. T}:T{
  1277. No
  1278. T}:T{
  1279. numeric
  1280. T}:T{
  1281. Y component of acceleration\&.
  1282. T}
  1283. T{
  1284. depth
  1285. T}:T{
  1286. No
  1287. T}:T{
  1288. numeric
  1289. T}:T{
  1290. Water depth in meters\&.
  1291. T}
  1292. T{
  1293. temp
  1294. T}:T{
  1295. No
  1296. T}:T{
  1297. numeric
  1298. T}:T{
  1299. Temperature at sensor, degrees centigrade\&.
  1300. T}
  1301. .TE
  1302. .sp 1
  1303. The heading, pitch, and roll status codes (if present) vary by device\&. For the TNT Revolution digital compasses, they are coded as follows:
  1304. .sp
  1305. .it 1 an-trap
  1306. .nr an-no-space-flag 1
  1307. .nr an-break-flag 1
  1308. .br
  1309. .B Table\ \&6.\ \&Device flags
  1310. .TS
  1311. allbox tab(:);
  1312. lB lB.
  1313. T{
  1314. Code
  1315. T}:T{
  1316. Description
  1317. T}
  1318. .T&
  1319. l l
  1320. l l
  1321. l l
  1322. l l
  1323. l l
  1324. l l
  1325. l l.
  1326. T{
  1327. C
  1328. T}:T{
  1329. magnetometer calibration alarm
  1330. T}
  1331. T{
  1332. L
  1333. T}:T{
  1334. low alarm
  1335. T}
  1336. T{
  1337. M
  1338. T}:T{
  1339. low warning
  1340. T}
  1341. T{
  1342. N
  1343. T}:T{
  1344. normal
  1345. T}
  1346. T{
  1347. O
  1348. T}:T{
  1349. high warning
  1350. T}
  1351. T{
  1352. P
  1353. T}:T{
  1354. high alarm
  1355. T}
  1356. T{
  1357. V
  1358. T}:T{
  1359. magnetometer voltage level alarm
  1360. T}
  1361. .TE
  1362. .sp 1
  1363. When the C client library parses a response of this kind, it will assert ATT_IS\&.
  1364. .sp
  1365. Here\*(Aqs an example:
  1366. .sp
  1367. .if n \{\
  1368. .RS 4
  1369. .\}
  1370. .nf
  1371. {"class":"ATT","time":1270938096\&.843,
  1372. "heading":14223\&.00,"mag_st":"N",
  1373. "pitch":169\&.00,"pitch_st":"N", "roll":\-43\&.00,"roll_st":"N",
  1374. "dip":13641\&.000,"mag_x":2454\&.000}
  1375. .fi
  1376. .if n \{\
  1377. .RE
  1378. .\}
  1379. .RE
  1380. .PP
  1381. And here are the commands:
  1382. .PP
  1383. ?VERSION;
  1384. .RS 4
  1385. Returns an object with the following attributes:
  1386. .sp
  1387. .it 1 an-trap
  1388. .nr an-no-space-flag 1
  1389. .nr an-break-flag 1
  1390. .br
  1391. .B Table\ \&7.\ \&VERSION object
  1392. .TS
  1393. allbox tab(:);
  1394. lB lB lB lB.
  1395. T{
  1396. Name
  1397. T}:T{
  1398. Always?
  1399. T}:T{
  1400. Type
  1401. T}:T{
  1402. Description
  1403. T}
  1404. .T&
  1405. l l l l
  1406. l l l l
  1407. l l l l
  1408. l l l l
  1409. l l l l
  1410. l l l l.
  1411. T{
  1412. class
  1413. T}:T{
  1414. Yes
  1415. T}:T{
  1416. string
  1417. T}:T{
  1418. Fixed: "VERSION"
  1419. T}
  1420. T{
  1421. release
  1422. T}:T{
  1423. Yes
  1424. T}:T{
  1425. string
  1426. T}:T{
  1427. Public release level
  1428. T}
  1429. T{
  1430. rev
  1431. T}:T{
  1432. Yes
  1433. T}:T{
  1434. string
  1435. T}:T{
  1436. Internal revision\-control level\&.
  1437. T}
  1438. T{
  1439. proto_major
  1440. T}:T{
  1441. Yes
  1442. T}:T{
  1443. numeric
  1444. T}:T{
  1445. API major revision level\&.
  1446. T}
  1447. T{
  1448. proto_minor
  1449. T}:T{
  1450. Yes
  1451. T}:T{
  1452. numeric
  1453. T}:T{
  1454. API minor revision level\&.
  1455. T}
  1456. T{
  1457. remote
  1458. T}:T{
  1459. No
  1460. T}:T{
  1461. string
  1462. T}:T{
  1463. URL of the remote daemon reporting this version\&. If
  1464. empty, this is the version of the local daemon\&.
  1465. T}
  1466. .TE
  1467. .sp 1
  1468. The daemon ships a VERSION response to each client when the client first connects to it\&.
  1469. .sp
  1470. When the C client library parses a response of this kind, it will assert the VERSION_SET bit in the top\-level set member\&.
  1471. .sp
  1472. Here\*(Aqs an example:
  1473. .sp
  1474. .if n \{\
  1475. .RS 4
  1476. .\}
  1477. .nf
  1478. {"class":"VERSION","version":"2\&.40dev",
  1479. "rev":"06f62e14eae9886cde907dae61c124c53eb1101f",
  1480. "proto_major":3,"proto_minor":1
  1481. }
  1482. .fi
  1483. .if n \{\
  1484. .RE
  1485. .\}
  1486. .RE
  1487. .PP
  1488. ?DEVICES;
  1489. .RS 4
  1490. Returns a device list object with the following elements:
  1491. .sp
  1492. .it 1 an-trap
  1493. .nr an-no-space-flag 1
  1494. .nr an-break-flag 1
  1495. .br
  1496. .B Table\ \&8.\ \&DEVICES object
  1497. .TS
  1498. allbox tab(:);
  1499. lB lB lB lB.
  1500. T{
  1501. Name
  1502. T}:T{
  1503. Always?
  1504. T}:T{
  1505. Type
  1506. T}:T{
  1507. Description
  1508. T}
  1509. .T&
  1510. l l l l
  1511. l l l l
  1512. l l l l.
  1513. T{
  1514. class
  1515. T}:T{
  1516. Yes
  1517. T}:T{
  1518. string
  1519. T}:T{
  1520. Fixed: "DEVICES"
  1521. T}
  1522. T{
  1523. devices
  1524. T}:T{
  1525. Yes
  1526. T}:T{
  1527. list
  1528. T}:T{
  1529. List of device descriptions
  1530. T}
  1531. T{
  1532. remote
  1533. T}:T{
  1534. No
  1535. T}:T{
  1536. string
  1537. T}:T{
  1538. URL of the remote daemon reporting the device set\&. If
  1539. empty, this is a DEVICES response from the local daemon\&.
  1540. T}
  1541. .TE
  1542. .sp 1
  1543. When the C client library parses a response of this kind, it will assert the DEVICELIST_SET bit in the top\-level set member\&.
  1544. .sp
  1545. Here\*(Aqs an example:
  1546. .sp
  1547. .if n \{\
  1548. .RS 4
  1549. .\}
  1550. .nf
  1551. {"class"="DEVICES","devices":[
  1552. {"class":"DEVICE","path":"/dev/pts/1","flags":1,"driver":"SiRF binary"},
  1553. {"class":"DEVICE","path":"/dev/pts/3","flags":4,"driver":"AIVDM"}]}
  1554. .fi
  1555. .if n \{\
  1556. .RE
  1557. .\}
  1558. .sp
  1559. The daemon occasionally ships a bare DEVICE object to the client (that is, one not inside a DEVICES wrapper)\&. The data content of these objects will be described later as a response to the ?DEVICE command\&.
  1560. .RE
  1561. .PP
  1562. ?WATCH;
  1563. .RS 4
  1564. This command sets watcher mode\&. It also sets or elicits a report of per\-subscriber policy and the raw bit\&. An argument WATCH object changes the subscriber\*(Aqs policy\&. The response describes the subscriber\*(Aqs policy\&. The response will also include a DEVICES object\&.
  1565. .sp
  1566. A WATCH object has the following elements:
  1567. .sp
  1568. .it 1 an-trap
  1569. .nr an-no-space-flag 1
  1570. .nr an-break-flag 1
  1571. .br
  1572. .B Table\ \&9.\ \&WATCH object
  1573. .TS
  1574. allbox tab(:);
  1575. lB lB lB lB.
  1576. T{
  1577. Name
  1578. T}:T{
  1579. Always?
  1580. T}:T{
  1581. Type
  1582. T}:T{
  1583. Description
  1584. T}
  1585. .T&
  1586. l l l l
  1587. l l l l
  1588. l l l l
  1589. l l l l
  1590. l l l l
  1591. l l l l
  1592. l l l l
  1593. l l l l
  1594. l l l l
  1595. l l l l.
  1596. T{
  1597. class
  1598. T}:T{
  1599. Yes
  1600. T}:T{
  1601. string
  1602. T}:T{
  1603. Fixed: "WATCH"
  1604. T}
  1605. T{
  1606. enable
  1607. T}:T{
  1608. No
  1609. T}:T{
  1610. boolean
  1611. T}:T{
  1612. Enable (true) or disable (false) watcher mode\&. Default
  1613. is true\&.
  1614. T}
  1615. T{
  1616. json
  1617. T}:T{
  1618. No
  1619. T}:T{
  1620. boolean
  1621. T}:T{
  1622. Enable (true) or disable (false) dumping of JSON reports\&.
  1623. Default is false\&.
  1624. T}
  1625. T{
  1626. nmea
  1627. T}:T{
  1628. No
  1629. T}:T{
  1630. boolean
  1631. T}:T{
  1632. Enable (true) or disable (false) dumping of binary
  1633. packets as pseudo\-NMEA\&. Default
  1634. is false\&.
  1635. T}
  1636. T{
  1637. raw
  1638. T}:T{
  1639. No
  1640. T}:T{
  1641. integer
  1642. T}:T{
  1643. Controls \*(Aqraw\*(Aq mode\&. When this attribute is set to 1
  1644. for a channel, gpsd reports the
  1645. unprocessed NMEA or AIVDM data stream from whatever device is attached\&.
  1646. Binary GPS packets are hex\-dumped\&. RTCM2 and RTCM3
  1647. packets are not dumped in raw mode\&. When this attribute is set to
  1648. 2 for a channel that processes binary data,
  1649. gpsd reports the received data verbatim
  1650. without hex\-dumping\&.
  1651. T}
  1652. T{
  1653. scaled
  1654. T}:T{
  1655. No
  1656. T}:T{
  1657. boolean
  1658. T}:T{
  1659. If true, apply scaling divisors to output before
  1660. dumping; default is false\&.
  1661. T}
  1662. T{
  1663. split24
  1664. T}:T{
  1665. No
  1666. T}:T{
  1667. boolean
  1668. T}:T{
  1669. If true, aggregate AIS type24 sentence parts\&. If false,
  1670. report each part as a separate JSON object, leaving the
  1671. client to match MMSIs and aggregate\&. Default is
  1672. false\&. Applies only to AIS reports\&.
  1673. T}
  1674. T{
  1675. pps
  1676. T}:T{
  1677. No
  1678. T}:T{
  1679. boolean
  1680. T}:T{
  1681. If true, emit the TOFF JSON message on each cycle and a
  1682. PPS JSON message when the device issues 1PPS\&. Default is false\&.
  1683. T}
  1684. T{
  1685. device
  1686. T}:T{
  1687. No
  1688. T}:T{
  1689. string
  1690. T}:T{
  1691. If present, enable watching only of the specified device
  1692. rather than all devices\&. Useful with raw and NMEA modes
  1693. in which device responses aren\*(Aqt tagged\&. Has no effect when
  1694. used with enable:false\&.
  1695. T}
  1696. T{
  1697. remote
  1698. T}:T{
  1699. No
  1700. T}:T{
  1701. string
  1702. T}:T{
  1703. URL of the remote daemon reporting the watch set\&. If
  1704. empty, this is a WATCH response from the local daemon\&.
  1705. T}
  1706. .TE
  1707. .sp 1
  1708. There is an additional boolean "timing" attribute which is undocumented because that portion of the interface is considered unstable and for developer use only\&.
  1709. .sp
  1710. In watcher mode, GPS reports are dumped as TPV and SKY responses\&. AIS, Subframe and RTCM reporting is described in the next section\&.
  1711. .sp
  1712. When the C client library parses a response of this kind, it will assert the POLICY_SET bit in the top\-level set member\&.
  1713. .sp
  1714. Here\*(Aqs an example:
  1715. .sp
  1716. .if n \{\
  1717. .RS 4
  1718. .\}
  1719. .nf
  1720. {"class":"WATCH", "raw":1,"scaled":true}
  1721. .fi
  1722. .if n \{\
  1723. .RE
  1724. .\}
  1725. .RE
  1726. .PP
  1727. ?POLL;
  1728. .RS 4
  1729. The POLL command requests data from the last\-seen fixes on all active GPS devices\&. Devices must previously have been activated by ?WATCH to be pollable\&.
  1730. .sp
  1731. Polling can lead to possibly surprising results when it is used on a device such as an NMEA GPS for which a complete fix has to be accumulated from several sentences\&. If you poll while those sentences are being emitted, the response will contain the last complete fix data and may be as much as one cycle time (typically 1 second) stale\&.
  1732. .sp
  1733. The POLL response will contain a timestamped list of TPV objects describing cached data, and a timestamped list of SKY objects describing satellite configuration\&. If a device has not seen fixes, it will be reported with a mode field of zero\&.
  1734. .sp
  1735. .it 1 an-trap
  1736. .nr an-no-space-flag 1
  1737. .nr an-break-flag 1
  1738. .br
  1739. .B Table\ \&10.\ \&POLL object
  1740. .TS
  1741. allbox tab(:);
  1742. lB lB lB lB.
  1743. T{
  1744. Name
  1745. T}:T{
  1746. Always?
  1747. T}:T{
  1748. Type
  1749. T}:T{
  1750. Description
  1751. T}
  1752. .T&
  1753. l l l l
  1754. l l l l
  1755. l l l l
  1756. l l l l
  1757. l l l l.
  1758. T{
  1759. class
  1760. T}:T{
  1761. Yes
  1762. T}:T{
  1763. string
  1764. T}:T{
  1765. Fixed: "POLL"
  1766. T}
  1767. T{
  1768. time
  1769. T}:T{
  1770. Yes
  1771. T}:T{
  1772. Numeric
  1773. T}:T{
  1774. Timestamp in ISO 8601 format\&. May have a
  1775. fractional part of up to \&.001sec precision\&.
  1776. T}
  1777. T{
  1778. active
  1779. T}:T{
  1780. Yes
  1781. T}:T{
  1782. Numeric
  1783. T}:T{
  1784. Count of active devices\&.
  1785. T}
  1786. T{
  1787. tpv
  1788. T}:T{
  1789. Yes
  1790. T}:T{
  1791. JSON array
  1792. T}:T{
  1793. Comma\-separated list of TPV objects\&.
  1794. T}
  1795. T{
  1796. sky
  1797. T}:T{
  1798. Yes
  1799. T}:T{
  1800. JSON array
  1801. T}:T{
  1802. Comma\-separated list of SKY objects\&.
  1803. T}
  1804. .TE
  1805. .sp 1
  1806. Here\*(Aqs an example of a POLL response:
  1807. .sp
  1808. .if n \{\
  1809. .RS 4
  1810. .\}
  1811. .nf
  1812. {"class":"POLL","time":"2010\-06\-04T10:31:00\&.289Z","active":1,
  1813. "tpv":[{"class":"TPV","device":"/dev/ttyUSB0",
  1814. "time":"2010\-09\-08T13:33:06\&.095Z",
  1815. "ept":0\&.005,"lat":40\&.035093060,
  1816. "lon":\-75\&.519748733,"track":99\&.4319,"speed":0\&.123,"mode":2}],
  1817. "sky":[{"class":"SKY","device":"/dev/ttyUSB0",
  1818. "time":1270517264\&.240,"hdop":9\&.20,
  1819. "satellites":[{"PRN":16,"el":55,"az":42,"ss":36,"used":true},
  1820. {"PRN":19,"el":25,"az":177,"ss":0,"used":false},
  1821. {"PRN":7,"el":13,"az":295,"ss":0,"used":false},
  1822. {"PRN":6,"el":56,"az":135,"ss":32,"used":true},
  1823. {"PRN":13,"el":47,"az":304,"ss":0,"used":false},
  1824. {"PRN":23,"el":66,"az":259,"ss":0,"used":false},
  1825. {"PRN":20,"el":7,"az":226,"ss":0,"used":false},
  1826. {"PRN":3,"el":52,"az":163,"ss":32,"used":true},
  1827. {"PRN":31,"el":16,"az":102,"ss":0,"used":false}
  1828. ]}]}
  1829. .fi
  1830. .if n \{\
  1831. .RE
  1832. .\}
  1833. .if n \{\
  1834. .sp
  1835. .\}
  1836. .RS 4
  1837. .it 1 an-trap
  1838. .nr an-no-space-flag 1
  1839. .nr an-break-flag 1
  1840. .br
  1841. .ps +1
  1842. \fBNote\fR
  1843. .ps -1
  1844. .br
  1845. Client software should not assume the field inventory of the POLL response is fixed for all time\&. As
  1846. gpsd
  1847. collects and caches more data from more sensor types, those data are likely to find their way into this response\&.
  1848. .sp .5v
  1849. .RE
  1850. .RE
  1851. .PP
  1852. TOFF
  1853. .RS 4
  1854. This message is emitted on each cycle and reports the offset between the host\*(Aqs clock time and the GPS time at top of second (actually, when the first data for the reporting cycle is received)\&.
  1855. .sp
  1856. This message exactly mirrors the PPS message except for two details\&.
  1857. .sp
  1858. TOFF emits no NTP precision, this is assumed to be \-2\&. See the NTP documentation for their definition of precision\&.
  1859. .sp
  1860. The TOFF message reports the GPS time as derived from the GPS serial data stream\&. The PPS message reports the GPS time as derived from the GPS PPS pulse\&.
  1861. .sp
  1862. A TOFF object has the following elements:
  1863. .sp
  1864. .it 1 an-trap
  1865. .nr an-no-space-flag 1
  1866. .nr an-break-flag 1
  1867. .br
  1868. .B Table\ \&11.\ \&TOFF object
  1869. .TS
  1870. allbox tab(:);
  1871. lB lB lB lB.
  1872. T{
  1873. Name
  1874. T}:T{
  1875. Always?
  1876. T}:T{
  1877. Type
  1878. T}:T{
  1879. Description
  1880. T}
  1881. .T&
  1882. l l l l
  1883. l l l l
  1884. l l l l
  1885. l l l l
  1886. l l l l
  1887. l l l l.
  1888. T{
  1889. class
  1890. T}:T{
  1891. Yes
  1892. T}:T{
  1893. string
  1894. T}:T{
  1895. Fixed: "TOFF"
  1896. T}
  1897. T{
  1898. device
  1899. T}:T{
  1900. Yes
  1901. T}:T{
  1902. string
  1903. T}:T{
  1904. Name of originating device
  1905. T}
  1906. T{
  1907. real_sec
  1908. T}:T{
  1909. Yes
  1910. T}:T{
  1911. numeric
  1912. T}:T{
  1913. seconds from the GPS clock
  1914. T}
  1915. T{
  1916. real_nsec
  1917. T}:T{
  1918. Yes
  1919. T}:T{
  1920. numeric
  1921. T}:T{
  1922. nanoseconds from the GPS clock
  1923. T}
  1924. T{
  1925. clock_sec
  1926. T}:T{
  1927. Yes
  1928. T}:T{
  1929. numeric
  1930. T}:T{
  1931. seconds from the system clock
  1932. T}
  1933. T{
  1934. clock_nsec
  1935. T}:T{
  1936. Yes
  1937. T}:T{
  1938. numeric
  1939. T}:T{
  1940. nanoseconds from the system clock
  1941. T}
  1942. .TE
  1943. .sp 1
  1944. This message is emitted once per second to watchers of a device and is intended to report the time stamps of the in\-band report of the GPS and seconds as reported by the system clock (which may be NTP\-corrected) when the first valid timestamp of the reporting cycle was seen\&.
  1945. .sp
  1946. The message contains two second/nanosecond pairs: real_sec and real_nsec contain the time the GPS thinks it was at the start of the current cycle; clock_sec and clock_nsec contain the time the system clock thinks it was on receipt of the first timing message of the cycle\&. real_nsec is always to nanosecond precision\&. clock_nsec is nanosecond precision on most systems\&.
  1947. .sp
  1948. Here\*(Aqs an example:
  1949. .sp
  1950. .if n \{\
  1951. .RS 4
  1952. .\}
  1953. .nf
  1954. {"class":"TOFF","device":"/dev/ttyUSB0",
  1955. "real_sec":1330212592, "real_nsec":343182,
  1956. "clock_sec":1330212592,"clock_nsec":343184,
  1957. "precision":\-2}}
  1958. .fi
  1959. .if n \{\
  1960. .RE
  1961. .\}
  1962. .RE
  1963. .PP
  1964. PPS
  1965. .RS 4
  1966. This message is emitted each time the daemon sees a valid PPS (Pulse Per Second) strobe from a device\&.
  1967. .sp
  1968. This message exactly mirrors the TOFF message except for two details\&.
  1969. .sp
  1970. PPS emits the NTP precision\&. See the NTP documentation for their definition of precision\&.
  1971. .sp
  1972. The TOFF message reports the GPS time as derived from the GPS serial data stream\&. The PPS message reports the GPS time as derived from the GPS PPS pulse\&.
  1973. .sp
  1974. There are various sources of error in the reported clock times\&. The speed of the serial connection between the GPS and the system adds a delay to start of cycle detection\&. An even bigger error is added by the variable computation time inside the GPS\&. Taken together the time derived from the start of the GPS cycle can have offsets of 10 millisecond to 700 milliseconds and combined jjitter and wander of 100 to 300 millisecond\&.
  1975. .sp
  1976. A PPS object has the following elements:
  1977. .sp
  1978. .it 1 an-trap
  1979. .nr an-no-space-flag 1
  1980. .nr an-break-flag 1
  1981. .br
  1982. .B Table\ \&12.\ \&PPS object
  1983. .TS
  1984. allbox tab(:);
  1985. lB lB lB lB.
  1986. T{
  1987. Name
  1988. T}:T{
  1989. Always?
  1990. T}:T{
  1991. Type
  1992. T}:T{
  1993. Description
  1994. T}
  1995. .T&
  1996. l l l l
  1997. l l l l
  1998. l l l l
  1999. l l l l
  2000. l l l l
  2001. l l l l
  2002. l l l l
  2003. l l l l.
  2004. T{
  2005. class
  2006. T}:T{
  2007. Yes
  2008. T}:T{
  2009. string
  2010. T}:T{
  2011. Fixed: "PPS"
  2012. T}
  2013. T{
  2014. device
  2015. T}:T{
  2016. Yes
  2017. T}:T{
  2018. string
  2019. T}:T{
  2020. Name of originating device
  2021. T}
  2022. T{
  2023. real_sec
  2024. T}:T{
  2025. Yes
  2026. T}:T{
  2027. numeric
  2028. T}:T{
  2029. seconds from the PPS source
  2030. T}
  2031. T{
  2032. real_nsec
  2033. T}:T{
  2034. Yes
  2035. T}:T{
  2036. numeric
  2037. T}:T{
  2038. nanoseconds from the PPS source
  2039. T}
  2040. T{
  2041. clock_sec
  2042. T}:T{
  2043. Yes
  2044. T}:T{
  2045. numeric
  2046. T}:T{
  2047. seconds from the system clock
  2048. T}
  2049. T{
  2050. clock_nsec
  2051. T}:T{
  2052. Yes
  2053. T}:T{
  2054. numeric
  2055. T}:T{
  2056. nanoseconds from the system clock
  2057. T}
  2058. T{
  2059. precision
  2060. T}:T{
  2061. Yes
  2062. T}:T{
  2063. numeric
  2064. T}:T{
  2065. NTP style estimate of PPS precision
  2066. T}
  2067. T{
  2068. qErr
  2069. T}:T{
  2070. No
  2071. T}:T{
  2072. numeric
  2073. T}:T{
  2074. Quantization error of the PPS, in pico seconds\&. Sometimes
  2075. called the "sawtooth" error\&.
  2076. T}
  2077. .TE
  2078. .sp 1
  2079. This message is emitted once per second to watchers of a device emitting PPS, and reports the time of the start of the GPS second (when the 1PPS arrives) and seconds as reported by the system clock (which may be NTP\-corrected) at that moment\&.
  2080. .sp
  2081. The message contains two second/nanosecond pairs: real_sec and real_nsec contain the time the GPS thinks it was at the PPS edge; clock_sec and clock_nsec contain the time the system clock thinks it was at the PPS edge\&. real_nsec is always to nanosecond precision\&. clock_nsec is nanosecond precision on most systems\&.
  2082. .sp
  2083. There are various sources of error in the reported clock times\&. For PPS delivered via a real serial\-line strobe, serial\-interrupt latency plus processing time to the timer call should be bounded above by about 10 microseconds; that can be reduced to less than 1 microsecond if your kernel supports RFC 2783\&. USB1\&.1\-to\-serial control\-line emulation is limited to about 1 millisecond\&. seconds\&.
  2084. .sp
  2085. Here\*(Aqs an example:
  2086. .sp
  2087. .if n \{\
  2088. .RS 4
  2089. .\}
  2090. .nf
  2091. {"class":"PPS","device":"/dev/ttyUSB0",
  2092. "real_sec":1330212592, "real_nsec":343182,
  2093. "clock_sec":1330212592,"clock_nsec":343184,
  2094. "precision":\-3}
  2095. .fi
  2096. .if n \{\
  2097. .RE
  2098. .\}
  2099. .RE
  2100. .PP
  2101. OSC
  2102. .RS 4
  2103. This message reports the status of a GPS\-disciplined oscillator (GPSDO)\&. The GPS PPS output (which has excellent long\-term stability) is typically used to discipline a local oscillator with much better short\-term stability (such as a rubidium atomic clock)\&.
  2104. .sp
  2105. An OSC object has the following elements:
  2106. .sp
  2107. .it 1 an-trap
  2108. .nr an-no-space-flag 1
  2109. .nr an-break-flag 1
  2110. .br
  2111. .B Table\ \&13.\ \&OSC object
  2112. .TS
  2113. allbox tab(:);
  2114. lB lB lB lB.
  2115. T{
  2116. Name
  2117. T}:T{
  2118. Always?
  2119. T}:T{
  2120. Type
  2121. T}:T{
  2122. Description
  2123. T}
  2124. .T&
  2125. l l l l
  2126. l l l l
  2127. l l l l
  2128. l l l l
  2129. l l l l
  2130. l l l l.
  2131. T{
  2132. class
  2133. T}:T{
  2134. Yes
  2135. T}:T{
  2136. string
  2137. T}:T{
  2138. Fixed: "OSC"
  2139. T}
  2140. T{
  2141. device
  2142. T}:T{
  2143. Yes
  2144. T}:T{
  2145. string
  2146. T}:T{
  2147. Name of originating device\&.
  2148. T}
  2149. T{
  2150. running
  2151. T}:T{
  2152. Yes
  2153. T}:T{
  2154. boolean
  2155. T}:T{
  2156. If true, the oscillator is currently running\&. Oscillators may require warm\-up time at start of day\&.
  2157. T}
  2158. T{
  2159. reference
  2160. T}:T{
  2161. Yes
  2162. T}:T{
  2163. boolean
  2164. T}:T{
  2165. If true, the oscillator is receiving a GPS PPS signal\&.
  2166. T}
  2167. T{
  2168. disciplined
  2169. T}:T{
  2170. Yes
  2171. T}:T{
  2172. boolean
  2173. T}:T{
  2174. If true, the GPS PPS signal is sufficiently stable and is being used to discipline the local oscillator\&.
  2175. T}
  2176. T{
  2177. delta
  2178. T}:T{
  2179. Yes
  2180. T}:T{
  2181. numeric
  2182. T}:T{
  2183. The time difference (in nanoseconds) between the GPS\-disciplined oscillator PPS output pulse and the most recent GPS PPS input pulse\&.
  2184. T}
  2185. .TE
  2186. .sp 1
  2187. Here\*(Aqs an example:
  2188. .sp
  2189. .if n \{\
  2190. .RS 4
  2191. .\}
  2192. .nf
  2193. {"class":"OSC","running":true,"device":"/dev/ttyUSB0",
  2194. "reference":true,"disciplined":true,"delta":67}
  2195. .fi
  2196. .if n \{\
  2197. .RE
  2198. .\}
  2199. .RE
  2200. .PP
  2201. ?DEVICE
  2202. .RS 4
  2203. This command reports (when followed by \*(Aq;\*(Aq) the state of a device, or sets (when followed by \*(Aq=\*(Aq and a DEVICE object) device\-specific control bits, notably the device\*(Aqs speed and serial mode and the native\-mode bit\&. The parameter\-setting form will be rejected if more than one client is attached to the channel\&.
  2204. .sp
  2205. Pay attention to the response, because it is possible for this command to fail if the GPS does not support a speed\-switching command or only supports some combinations of serial modes\&. In case of failure, the daemon and GPS will continue to communicate at the old speed\&.
  2206. .sp
  2207. Use the parameter\-setting form with caution\&. On USB and Bluetooth GPSes it is also possible for serial mode setting to fail either because the serial adaptor chip does not support non\-8N1 modes or because the device firmware does not properly synchronize the serial adaptor chip with the UART on the GPS chipset when the speed changes\&. These failures can hang your device, possibly requiring a GPS power cycle or (in extreme cases) physically disconnecting the NVRAM backup battery\&.
  2208. .sp
  2209. A DEVICE object has the following elements:
  2210. .sp
  2211. .it 1 an-trap
  2212. .nr an-no-space-flag 1
  2213. .nr an-break-flag 1
  2214. .br
  2215. .B Table\ \&14.\ \&DEVICE object
  2216. .TS
  2217. allbox tab(:);
  2218. lB lB lB lB.
  2219. T{
  2220. Name
  2221. T}:T{
  2222. Always?
  2223. T}:T{
  2224. Type
  2225. T}:T{
  2226. Description
  2227. T}
  2228. .T&
  2229. l l l l
  2230. l l l l
  2231. l l l l
  2232. l l l l
  2233. l l l l
  2234. l l l l
  2235. l l l l
  2236. l l l l
  2237. l l l l
  2238. l l l l
  2239. l l l l
  2240. l l l l
  2241. l l l l.
  2242. T{
  2243. class
  2244. T}:T{
  2245. Yes
  2246. T}:T{
  2247. string
  2248. T}:T{
  2249. Fixed: "DEVICE"
  2250. T}
  2251. T{
  2252. path
  2253. T}:T{
  2254. No
  2255. T}:T{
  2256. string
  2257. T}:T{
  2258. Name the device for which the control bits are
  2259. being reported, or for which they are to be applied\&. This
  2260. attribute may be omitted only when there is exactly one
  2261. subscribed channel\&.
  2262. T}
  2263. T{
  2264. activated
  2265. T}:T{
  2266. No
  2267. T}:T{
  2268. string
  2269. T}:T{
  2270. Time the device was activated as an ISO8601
  2271. timestamp\&. If the device is inactive this attribute is
  2272. absent\&.
  2273. T}
  2274. T{
  2275. flags
  2276. T}:T{
  2277. No
  2278. T}:T{
  2279. integer
  2280. T}:T{
  2281. Bit vector of property flags\&. Currently defined flags are:
  2282. describe packet types seen so far (GPS, RTCM2, RTCM3,
  2283. AIS)\&. Won\*(Aqt be reported if empty, e\&.g\&. before
  2284. gpsd has seen identifiable packets
  2285. from the device\&.
  2286. T}
  2287. T{
  2288. driver
  2289. T}:T{
  2290. No
  2291. T}:T{
  2292. string
  2293. T}:T{
  2294. GPSD\*(Aqs name for the device driver type\&. Won\*(Aqt be reported before
  2295. gpsd has seen identifiable packets
  2296. from the device\&.
  2297. T}
  2298. T{
  2299. subtype
  2300. T}:T{
  2301. No
  2302. T}:T{
  2303. string
  2304. T}:T{
  2305. Whatever version information the device driver returned\&.
  2306. T}
  2307. T{
  2308. subtype1
  2309. T}:T{
  2310. No
  2311. T}:T{
  2312. string
  2313. T}:T{
  2314. More version information the device driver returned\&.
  2315. T}
  2316. T{
  2317. bps
  2318. T}:T{
  2319. No
  2320. T}:T{
  2321. integer
  2322. T}:T{
  2323. Device speed in bits per second\&.
  2324. T}
  2325. T{
  2326. parity
  2327. T}:T{
  2328. No
  2329. T}:T{
  2330. string
  2331. T}:T{
  2332. N, O or E for no parity, odd, or even\&.
  2333. T}
  2334. T{
  2335. stopbits
  2336. T}:T{
  2337. Yes
  2338. T}:T{
  2339. string
  2340. T}:T{
  2341. Stop bits (1 or 2)\&.
  2342. T}
  2343. T{
  2344. native
  2345. T}:T{
  2346. No
  2347. T}:T{
  2348. integer
  2349. T}:T{
  2350. 0 means NMEA mode and 1 means
  2351. alternate mode (binary if it has one, for SiRF and Evermore chipsets
  2352. in particular)\&. Attempting to set this mode on a non\-GPS
  2353. device will yield an error\&.
  2354. T}
  2355. T{
  2356. cycle
  2357. T}:T{
  2358. No
  2359. T}:T{
  2360. real
  2361. T}:T{
  2362. Device cycle time in seconds\&.
  2363. T}
  2364. T{
  2365. mincycle
  2366. T}:T{
  2367. No
  2368. T}:T{
  2369. real
  2370. T}:T{
  2371. Device minimum cycle time in seconds\&. Reported from
  2372. ?DEVICE when (and only when) the rate is switchable\&. It is
  2373. read\-only and not settable\&.
  2374. T}
  2375. .TE
  2376. .sp 1
  2377. The serial parameters will (bps, parity, stopbits) be omitted in a response describing a TCP/IP source such as an Ntrip, DGPSIP, or AIS feed; on a serial device they will always be present\&.
  2378. .sp
  2379. The contents of the flags field should be interpreted as follows:
  2380. .sp
  2381. .it 1 an-trap
  2382. .nr an-no-space-flag 1
  2383. .nr an-break-flag 1
  2384. .br
  2385. .B Table\ \&15.\ \&Device flags
  2386. .TS
  2387. allbox tab(:);
  2388. lB lB lB.
  2389. T{
  2390. C #define
  2391. T}:T{
  2392. Value
  2393. T}:T{
  2394. Description
  2395. T}
  2396. .T&
  2397. l l l
  2398. l l l
  2399. l l l
  2400. l l l.
  2401. T{
  2402. SEEN_GPS
  2403. T}:T{
  2404. 0x01
  2405. T}:T{
  2406. GPS data has been seen on this device
  2407. T}
  2408. T{
  2409. SEEN_RTCM2
  2410. T}:T{
  2411. 0x02
  2412. T}:T{
  2413. RTCM2 data has been seen on this device
  2414. T}
  2415. T{
  2416. SEEN_RTCM3
  2417. T}:T{
  2418. 0x04
  2419. T}:T{
  2420. RTCM3 data has been seen on this device
  2421. T}
  2422. T{
  2423. SEEN_AIS
  2424. T}:T{
  2425. 0x08
  2426. T}:T{
  2427. AIS data has been seen on this device
  2428. T}
  2429. .TE
  2430. .sp 1
  2431. When the C client library parses a response of this kind, it will assert the DEVICE_SET bit in the top\-level set member\&.
  2432. .sp
  2433. Here\*(Aqs an example:
  2434. .sp
  2435. .if n \{\
  2436. .RS 4
  2437. .\}
  2438. .nf
  2439. {"class":"DEVICE","bps":4800,"parity":"N","stopbits":1,"native":0}
  2440. .fi
  2441. .if n \{\
  2442. .RE
  2443. .\}
  2444. .RE
  2445. .PP
  2446. When a client is in watcher mode, the daemon will ship it DEVICE notifications when a device is added to the pool or deactivated\&.
  2447. .PP
  2448. When the C client library parses a response of this kind, it will assert the DEVICE_SET bit in the top\-level set member\&.
  2449. .PP
  2450. Here\*(Aqs an example:
  2451. .sp
  2452. .if n \{\
  2453. .RS 4
  2454. .\}
  2455. .nf
  2456. {"class":"DEVICE","path":"/dev/pts1","activated":0}
  2457. .fi
  2458. .if n \{\
  2459. .RE
  2460. .\}
  2461. .PP
  2462. The daemon may ship an error object in response to a syntactically invalid command line or unknown command\&. It has the following elements:
  2463. .sp
  2464. .it 1 an-trap
  2465. .nr an-no-space-flag 1
  2466. .nr an-break-flag 1
  2467. .br
  2468. .B Table\ \&16.\ \&ERROR notification object
  2469. .TS
  2470. allbox tab(:);
  2471. lB lB lB lB.
  2472. T{
  2473. Name
  2474. T}:T{
  2475. Always?
  2476. T}:T{
  2477. Type
  2478. T}:T{
  2479. Description
  2480. T}
  2481. .T&
  2482. l l l l
  2483. l l l l.
  2484. T{
  2485. class
  2486. T}:T{
  2487. Yes
  2488. T}:T{
  2489. string
  2490. T}:T{
  2491. Fixed: "ERROR"
  2492. T}
  2493. T{
  2494. message
  2495. T}:T{
  2496. Yes
  2497. T}:T{
  2498. string
  2499. T}:T{
  2500. Textual error message
  2501. T}
  2502. .TE
  2503. .sp 1
  2504. .PP
  2505. Here\*(Aqs an example:
  2506. .sp
  2507. .if n \{\
  2508. .RS 4
  2509. .\}
  2510. .nf
  2511. {"class":"ERROR","message":"Unrecognized request \*(Aq?FOO\*(Aq"}
  2512. .fi
  2513. .if n \{\
  2514. .RE
  2515. .\}
  2516. .PP
  2517. When the C client library parses a response of this kind, it will assert the ERR_SET bit in the top\-level set member\&.
  2518. .SH "RTCM2"
  2519. .PP
  2520. RTCM\-104 is a family of serial protocols used for broadcasting pseudorange corrections from differential\-GPS reference stations\&. Many GPS receivers can accept these corrections to improve their reporting accuracy\&.
  2521. .PP
  2522. RTCM\-104 comes in two major and incompatible flavors, 2\&.x and 3\&.x\&. Each major flavor has minor (compatible) revisions\&.
  2523. .PP
  2524. The applicable standard for RTCM Version 2\&.x is
  2525. RTCM Recommended Standards for Differential NAVSTAR GPS Service
  2526. RTCM Paper 194\-93/SC 104\-STD\&. For RTCM 3\&.1 it is
  2527. RTCM Paper 177\-2006\-SC104\-STD\&. Ordering instructions for both standards are accessible from the website of the
  2528. \m[blue]\fBRadio Technical Commission for Maritime Services\fR\m[]\&\s-2\u[1]\d\s+2
  2529. under "Publications"\&.
  2530. .SS "RTCM WIRE TRANSMISSIONS"
  2531. .PP
  2532. Differential\-GPS correction stations consist of a GPS reference receiver coupled to a low frequency (LF) transmitter\&. The GPS reference receiver is a survey\-grade GPS that does GPS carrier tracking and can work out its own position to a few millimeters\&. It generates range and range\-rate corrections and encodes them into RTCM104\&. It ships the RTCM104 to the LF transmitter over serial rs\-232 signal at 100 baud or 200 baud depending on the requirements of the transmitter\&.
  2533. .PP
  2534. The LF transmitter broadcasts the approximately 300khz radio signal that differential\-GPS radio receivers pick up\&. Transmitters that are meant to have a higher range will need to transmit at the slower rate\&. The higher the data rate the harder it will be for the remote radio receiver to receive with a good signal\-to\-noise ration\&. (Higher data rate signals can\*(Aqt be averaged over as long a time frame, hence they appear noisier\&.)
  2535. .SS "RTCM WIRE FORMATS"
  2536. .PP
  2537. An RTCM 2\&.x message consists of a sequence of up to 33 30\-bit words\&. The 24 most significant bits of each word are data and the six least significant bits are parity\&. The parity algorithm used is the same ISGPS\-2000 as that used on GPS satellite downlinks\&. Each RTCM 2\&.x message consists of two header words followed by zero or more data words, depending upon message type\&.
  2538. .PP
  2539. An RTCM 3\&.x message begins with a fixed leader byte 0xD3\&. That is followed by six bits of version information and 10 bits of payload length information\&. Following that is the payload; following the payload is a 3\-byte checksum of the payload using the Qualcomm CRC\-24Q algorithm\&.
  2540. .SS "RTCM2 JSON FORMAT"
  2541. .PP
  2542. Each RTCM2 message is dumped as a single JSON object per message, with the message fields as attributes of that object\&. Arrays of satellite, station, and constellation statistics become arrays of JSON sub\-objects\&. Each sentence will normally also have a "device" field containing the pathname of the originating device\&.
  2543. .PP
  2544. All attributes other than the device field are mandatory\&. Header attributes are emitted before others\&.
  2545. .sp
  2546. .it 1 an-trap
  2547. .nr an-no-space-flag 1
  2548. .nr an-break-flag 1
  2549. .br
  2550. .ps +1
  2551. \fBHeader portion\fR
  2552. .RS 4
  2553. .sp
  2554. .it 1 an-trap
  2555. .nr an-no-space-flag 1
  2556. .nr an-break-flag 1
  2557. .br
  2558. .B Table\ \&17.\ \&SKY object
  2559. .TS
  2560. allbox tab(:);
  2561. lB lB lB.
  2562. T{
  2563. Name
  2564. T}:T{
  2565. Type
  2566. T}:T{
  2567. .PP
  2568. Description
  2569. T}
  2570. .T&
  2571. l l l
  2572. l l l
  2573. l l l
  2574. l l l
  2575. l l l
  2576. l l l
  2577. l l l.
  2578. T{
  2579. class
  2580. T}:T{
  2581. string
  2582. T}:T{
  2583. .PP
  2584. Fixed: "RTCM2"\&.
  2585. T}
  2586. T{
  2587. type
  2588. T}:T{
  2589. integer
  2590. T}:T{
  2591. .PP
  2592. Message type (1\-9)\&.
  2593. T}
  2594. T{
  2595. station_id
  2596. T}:T{
  2597. integer
  2598. T}:T{
  2599. .PP
  2600. The id of the GPS reference receiver\&. The LF transmitters also have (different) id numbers\&.
  2601. T}
  2602. T{
  2603. zcount
  2604. T}:T{
  2605. real
  2606. T}:T{
  2607. .PP
  2608. The reference time of the corrections in the message in seconds within the current hour\&. Note that it is in GPS time, which is some seconds ahead of UTC (see the U\&.S\&. Naval Observatory\*(Aqs
  2609. \m[blue]\fBtable of leap second corrections\fR\m[]\&\s-2\u[2]\d\s+2)\&.
  2610. T}
  2611. T{
  2612. seqnum
  2613. T}:T{
  2614. integer
  2615. T}:T{
  2616. .PP
  2617. Sequence number\&. Only 3 bits wide, wraps after 7\&.
  2618. T}
  2619. T{
  2620. length
  2621. T}:T{
  2622. integer
  2623. T}:T{
  2624. .PP
  2625. The number of words after the header that comprise the message\&.
  2626. T}
  2627. T{
  2628. station_health
  2629. T}:T{
  2630. integer
  2631. T}:T{
  2632. .PP
  2633. Station transmission status\&. Indicates the health of the beacon as a reference source\&. Any nonzero value means the satellite is probably transmitting bad data and should not be used in a fix\&. 6 means the transmission is unmonitored\&. 7 means the station is not working properly\&. Other values are defined by the beacon operator\&.
  2634. T}
  2635. .TE
  2636. .sp 1
  2637. .PP
  2638. <message type> is one of
  2639. .PP
  2640. 1
  2641. .RS 4
  2642. full corrections \- one message containing corrections for all GPS satellites in view\&. This is not common\&.
  2643. .RE
  2644. .PP
  2645. 3
  2646. .RS 4
  2647. reference station parameters \- the position of the reference station GPS antenna\&.
  2648. .RE
  2649. .PP
  2650. 4
  2651. .RS 4
  2652. datum \(em the datum to which the DGPS data is referred\&.
  2653. .RE
  2654. .PP
  2655. 5
  2656. .RS 4
  2657. constellation health \(em information about the satellites the beacon can see\&.
  2658. .RE
  2659. .PP
  2660. 6
  2661. .RS 4
  2662. null message \(em just a filler\&.
  2663. .RE
  2664. .PP
  2665. 7
  2666. .RS 4
  2667. radio beacon almanac \(em information about this or other beacons\&.
  2668. .RE
  2669. .PP
  2670. 9
  2671. .RS 4
  2672. subset corrections \(em a message containing corrections for only a subset of the GPS satellites in view\&.
  2673. .RE
  2674. .PP
  2675. 16
  2676. .RS 4
  2677. special message \(em a text message from the beacon operator\&.
  2678. .RE
  2679. .PP
  2680. 31
  2681. .RS 4
  2682. GLONASS subset corrections \(em a message containing corrections for a set of the GLONASS satellites in view\&.
  2683. .RE
  2684. .RE
  2685. .sp
  2686. .it 1 an-trap
  2687. .nr an-no-space-flag 1
  2688. .nr an-break-flag 1
  2689. .br
  2690. .ps +1
  2691. \fBType 1 and 9: Correction data\fR
  2692. .RS 4
  2693. .PP
  2694. One or more satellite objects follow the header for type 1 or type 9 messages\&. Here is the format:
  2695. .sp
  2696. .it 1 an-trap
  2697. .nr an-no-space-flag 1
  2698. .nr an-break-flag 1
  2699. .br
  2700. .B Table\ \&18.\ \&Satellite object
  2701. .TS
  2702. allbox tab(:);
  2703. lB lB lB.
  2704. T{
  2705. Name
  2706. T}:T{
  2707. Type
  2708. T}:T{
  2709. .PP
  2710. Description
  2711. T}
  2712. .T&
  2713. l l l
  2714. l l l
  2715. l l l
  2716. l l l
  2717. l l l.
  2718. T{
  2719. ident
  2720. T}:T{
  2721. integer
  2722. T}:T{
  2723. .PP
  2724. The PRN number of the satellite for which this is correction data\&.
  2725. T}
  2726. T{
  2727. udre
  2728. T}:T{
  2729. integer
  2730. T}:T{
  2731. .PP
  2732. User Differential Range Error (0\-3)\&. See the table following for values\&.
  2733. T}
  2734. T{
  2735. iod
  2736. T}:T{
  2737. integer
  2738. T}:T{
  2739. .PP
  2740. Issue Of Data, matching the IOD for the current ephemeris of this satellite, as transmitted by the satellite\&. The IOD is a unique tag that identifies the ephemeris; the GPS using the DGPS correction and the DGPS generating the data must use the same orbital positions for the satellite\&.
  2741. T}
  2742. T{
  2743. prc
  2744. T}:T{
  2745. real
  2746. T}:T{
  2747. .PP
  2748. The pseudorange error in meters for this satellite as measured by the beacon reference receiver at the epoch indicated by the z_count in the parent record\&.
  2749. T}
  2750. T{
  2751. rrc
  2752. T}:T{
  2753. real
  2754. T}:T{
  2755. .PP
  2756. The rate of change of pseudorange error in meters/sec for this satellite as measured by the beacon reference receiver at the epoch indicated by the z_count field in the parent record\&. This is used to calculate pseudorange errors at other epochs, if required by the GPS receiver\&.
  2757. T}
  2758. .TE
  2759. .sp 1
  2760. .PP
  2761. User Differential Range Error values are as follows:
  2762. .sp
  2763. .it 1 an-trap
  2764. .nr an-no-space-flag 1
  2765. .nr an-break-flag 1
  2766. .br
  2767. .B Table\ \&19.\ \&UDRE values
  2768. .TS
  2769. allbox tab(:);
  2770. l l
  2771. l l
  2772. l l
  2773. l l.
  2774. T{
  2775. 0
  2776. T}:T{
  2777. 1\-sigma error <= 1m
  2778. T}
  2779. T{
  2780. 1
  2781. T}:T{
  2782. 1\-sigma error <= 4m
  2783. T}
  2784. T{
  2785. 2
  2786. T}:T{
  2787. 1\-sigma error <= 8m
  2788. T}
  2789. T{
  2790. 3
  2791. T}:T{
  2792. 1\-sigma error > 8m
  2793. T}
  2794. .TE
  2795. .sp 1
  2796. .PP
  2797. Here\*(Aqs an example:
  2798. .sp
  2799. .if n \{\
  2800. .RS 4
  2801. .\}
  2802. .nf
  2803. {"class":"RTCM2","type":1,
  2804. "station_id":688,"zcount":843\&.0,"seqnum":5,"length":19,"station_health":6,
  2805. "satellites":[
  2806. {"ident":10,"udre":0,"iod":46,"prc":\-2\&.400,"rrc":0\&.000},
  2807. {"ident":13,"udre":0,"iod":94,"prc":\-4\&.420,"rrc":0\&.000},
  2808. {"ident":7,"udre":0,"iod":22,"prc":\-5\&.160,"rrc":0\&.002},
  2809. {"ident":2,"udre":0,"iod":34,"prc":\-6\&.480,"rrc":0\&.000},
  2810. {"ident":4,"udre":0,"iod":47,"prc":\-8\&.860,"rrc":0\&.000},
  2811. {"ident":8,"udre":0,"iod":76,"prc":\-7\&.980,"rrc":0\&.002},
  2812. {"ident":5,"udre":0,"iod":99,"prc":\-8\&.260,"rrc":0\&.002},
  2813. {"ident":23,"udre":0,"iod":81,"prc":\-8\&.060,"rrc":0\&.000},
  2814. {"ident":16,"udre":0,"iod":70,"prc":\-11\&.740,"rrc":0\&.000},
  2815. {"ident":30,"udre":0,"iod":4,"prc":\-18\&.960,"rrc":\-0\&.006},
  2816. {"ident":29,"udre":0,"iod":101,"prc":\-24\&.960,"rrc":\-0\&.002}
  2817. ]}
  2818. .fi
  2819. .if n \{\
  2820. .RE
  2821. .\}
  2822. .RE
  2823. .sp
  2824. .it 1 an-trap
  2825. .nr an-no-space-flag 1
  2826. .nr an-break-flag 1
  2827. .br
  2828. .ps +1
  2829. \fBType 3: Reference Station Parameters\fR
  2830. .RS 4
  2831. .PP
  2832. Here are the payload members of a type 3 (Reference Station Parameters) message:
  2833. .sp
  2834. .it 1 an-trap
  2835. .nr an-no-space-flag 1
  2836. .nr an-break-flag 1
  2837. .br
  2838. .B Table\ \&20.\ \&Reference Station Parameters
  2839. .TS
  2840. allbox tab(:);
  2841. lB lB lB.
  2842. T{
  2843. Name
  2844. T}:T{
  2845. Type
  2846. T}:T{
  2847. .PP
  2848. Description
  2849. T}
  2850. .T&
  2851. l l l
  2852. l l l
  2853. l l l.
  2854. T{
  2855. x
  2856. T}:T{
  2857. real
  2858. T}:T{
  2859. .PP
  2860. ECEF X coordinate\&.
  2861. T}
  2862. T{
  2863. y
  2864. T}:T{
  2865. real
  2866. T}:T{
  2867. .PP
  2868. ECEF Y coordinate\&.
  2869. T}
  2870. T{
  2871. z
  2872. T}:T{
  2873. real
  2874. T}:T{
  2875. .PP
  2876. ECEF Z coordinate\&.
  2877. T}
  2878. .TE
  2879. .sp 1
  2880. .PP
  2881. The coordinates are the position of the station, in meters to two decimal places, in Earth Centred Earth Fixed coordinates\&. These are usually referred to the WGS84 reference frame, but may be referred to NAD83 in the US (essentially identical to WGS84 for all except geodesists), or to some other reference frame in other parts of the world\&.
  2882. .PP
  2883. An invalid reference message is represented by a type 3 header without payload fields\&.
  2884. .PP
  2885. Here\*(Aqs an example:
  2886. .sp
  2887. .if n \{\
  2888. .RS 4
  2889. .\}
  2890. .nf
  2891. {"class":"RTCM2","type":3,
  2892. "station_id":652,"zcount":1657\&.2,"seqnum":2,"length":4,"station_health":6,
  2893. "x":3878620\&.92,"y":670281\&.40,"z":5002093\&.59
  2894. }
  2895. .fi
  2896. .if n \{\
  2897. .RE
  2898. .\}
  2899. .RE
  2900. .sp
  2901. .it 1 an-trap
  2902. .nr an-no-space-flag 1
  2903. .nr an-break-flag 1
  2904. .br
  2905. .ps +1
  2906. \fBType 4: Datum\fR
  2907. .RS 4
  2908. .PP
  2909. Here are the payload members of a type 4 (Datum) message:
  2910. .sp
  2911. .it 1 an-trap
  2912. .nr an-no-space-flag 1
  2913. .nr an-break-flag 1
  2914. .br
  2915. .B Table\ \&21.\ \&Datum
  2916. .TS
  2917. allbox tab(:);
  2918. lB lB lB.
  2919. T{
  2920. Name
  2921. T}:T{
  2922. Type
  2923. T}:T{
  2924. .PP
  2925. Description
  2926. T}
  2927. .T&
  2928. l l l
  2929. l l l
  2930. l l l
  2931. l l l
  2932. l l l
  2933. l l l.
  2934. T{
  2935. dgnss_type
  2936. T}:T{
  2937. string
  2938. T}:T{
  2939. .PP
  2940. Either "GPS", "GLONASS", "GALILEO", or "UNKNOWN"\&.
  2941. T}
  2942. T{
  2943. dat
  2944. T}:T{
  2945. integer
  2946. T}:T{
  2947. .PP
  2948. 0 or 1 and indicates the sense of the offset shift given by dx, dy, dz\&. dat = 0 means that the station coordinates (in the reference message) are referred to a local datum and that adding dx, dy, dz to that position will render it in GNSS coordinates (WGS84 for GPS)\&. If dat = 1 then the ref station position is in GNSS coordinates and adding dx, dy, dz will give it referred to the local datum\&.
  2949. T}
  2950. T{
  2951. datum_name
  2952. T}:T{
  2953. string
  2954. T}:T{
  2955. .PP
  2956. A standard name for the datum\&.
  2957. T}
  2958. T{
  2959. dx
  2960. T}:T{
  2961. real
  2962. T}:T{
  2963. .PP
  2964. X offset\&.
  2965. T}
  2966. T{
  2967. dy
  2968. T}:T{
  2969. real
  2970. T}:T{
  2971. .PP
  2972. Y offset\&.
  2973. T}
  2974. T{
  2975. dz
  2976. T}:T{
  2977. real
  2978. T}:T{
  2979. .PP
  2980. Z offset\&.
  2981. T}
  2982. .TE
  2983. .sp 1
  2984. .PP
  2985. <dx> <dy> <dz> are offsets to convert from local datum to GNSS datum or vice versa\&. These fields are optional\&.
  2986. .PP
  2987. An invalid datum message is represented by a type 4 header without payload fields\&.
  2988. .RE
  2989. .sp
  2990. .it 1 an-trap
  2991. .nr an-no-space-flag 1
  2992. .nr an-break-flag 1
  2993. .br
  2994. .ps +1
  2995. \fBType 5: Constellation Health\fR
  2996. .RS 4
  2997. .PP
  2998. One or more of these follow the header for type 5 messages \(em one for each satellite\&.
  2999. .PP
  3000. Here is the format:
  3001. .sp
  3002. .it 1 an-trap
  3003. .nr an-no-space-flag 1
  3004. .nr an-break-flag 1
  3005. .br
  3006. .B Table\ \&22.\ \&Constellation health
  3007. .TS
  3008. allbox tab(:);
  3009. lB lB lB.
  3010. T{
  3011. Name
  3012. T}:T{
  3013. Type
  3014. T}:T{
  3015. .PP
  3016. Description
  3017. T}
  3018. .T&
  3019. l l l
  3020. l l l
  3021. l l l
  3022. l l l
  3023. l l l
  3024. l l l
  3025. l l l
  3026. l l l.
  3027. T{
  3028. ident
  3029. T}:T{
  3030. integer
  3031. T}:T{
  3032. .PP
  3033. The PRN number of the satellite\&.
  3034. T}
  3035. T{
  3036. iodl
  3037. T}:T{
  3038. bool
  3039. T}:T{
  3040. .PP
  3041. True indicates that this information relates to the satellite information in an accompanying type 1 or type 9 message\&.
  3042. T}
  3043. T{
  3044. health
  3045. T}:T{
  3046. integer
  3047. T}:T{
  3048. 0 indicates that the satellite is healthy\&. Any other value
  3049. indicates a problem (coding is not known)\&..PP
  3050. T}
  3051. T{
  3052. snr
  3053. T}:T{
  3054. integer
  3055. T}:T{
  3056. .PP
  3057. The carrier/noise ratio of the received signal in the range 25 to 55 dB(Hz)\&.
  3058. T}
  3059. T{
  3060. health_en
  3061. T}:T{
  3062. bool
  3063. T}:T{
  3064. .PP
  3065. If set to True it indicates that the satellite is healthy even if the satellite navigation data says it is unhealthy\&.
  3066. T}
  3067. T{
  3068. new_data
  3069. T}:T{
  3070. bool
  3071. T}:T{
  3072. True indicates that the IOD for this satellite will
  3073. soon be updated in type 1 or 9 messages\&..PP
  3074. T}
  3075. T{
  3076. los_warning
  3077. T}:T{
  3078. bool
  3079. T}:T{
  3080. .PP
  3081. Line\-of\-sight warning\&. True indicates that the satellite will shortly go unhealthy\&.
  3082. T}
  3083. T{
  3084. tou
  3085. T}:T{
  3086. integer
  3087. T}:T{
  3088. .PP
  3089. Healthy time remaining in seconds\&.
  3090. T}
  3091. .TE
  3092. .sp 1
  3093. .RE
  3094. .sp
  3095. .it 1 an-trap
  3096. .nr an-no-space-flag 1
  3097. .nr an-break-flag 1
  3098. .br
  3099. .ps +1
  3100. \fBType 6: Null\fR
  3101. .RS 4
  3102. .PP
  3103. This just indicates a null message\&. There are no payload fields\&.
  3104. .RE
  3105. .sp
  3106. .it 1 an-trap
  3107. .nr an-no-space-flag 1
  3108. .nr an-break-flag 1
  3109. .br
  3110. .ps +1
  3111. \fBUnknown message\fR
  3112. .RS 4
  3113. .PP
  3114. This format is used to dump message words in hexadecimal when the message type field doesn\*(Aqt match any of the known ones\&.
  3115. .PP
  3116. Here is the format:
  3117. .sp
  3118. .it 1 an-trap
  3119. .nr an-no-space-flag 1
  3120. .nr an-break-flag 1
  3121. .br
  3122. .B Table\ \&23.\ \&Unknown Message
  3123. .TS
  3124. allbox tab(:);
  3125. lB lB lB.
  3126. T{
  3127. Name
  3128. T}:T{
  3129. Type
  3130. T}:T{
  3131. .PP
  3132. Description
  3133. T}
  3134. .T&
  3135. l l l.
  3136. T{
  3137. data
  3138. T}:T{
  3139. list
  3140. T}:T{
  3141. .PP
  3142. A list of strings\&.
  3143. T}
  3144. .TE
  3145. .sp 1
  3146. .PP
  3147. Each string in the array is a hex literal representing 30 bits of information, after parity checks and inversion\&. The high two bits should be ignored\&.
  3148. .RE
  3149. .sp
  3150. .it 1 an-trap
  3151. .nr an-no-space-flag 1
  3152. .nr an-break-flag 1
  3153. .br
  3154. .ps +1
  3155. \fBType 7: Radio Beacon Almanac\fR
  3156. .RS 4
  3157. .PP
  3158. Here is the format:
  3159. .sp
  3160. .it 1 an-trap
  3161. .nr an-no-space-flag 1
  3162. .nr an-break-flag 1
  3163. .br
  3164. .B Table\ \&24.\ \&Contellation health
  3165. .TS
  3166. allbox tab(:);
  3167. lB lB lB.
  3168. T{
  3169. Name
  3170. T}:T{
  3171. Type
  3172. T}:T{
  3173. .PP
  3174. Description
  3175. T}
  3176. .T&
  3177. l l l
  3178. l l l
  3179. l l l
  3180. l l l
  3181. l l l
  3182. l l l
  3183. l l l.
  3184. T{
  3185. lat
  3186. T}:T{
  3187. real
  3188. T}:T{
  3189. .PP
  3190. Latitude in degrees, of the LF transmitter antenna for the station for which this is an almanac\&. North is positive\&.
  3191. T}
  3192. T{
  3193. lon
  3194. T}:T{
  3195. real
  3196. T}:T{
  3197. .PP
  3198. Longitude in degrees, of the LF transmitter antenna for the station for which this is an almanac\&. East is positive\&.
  3199. T}
  3200. T{
  3201. range
  3202. T}:T{
  3203. integer
  3204. T}:T{
  3205. Published range of the station in km\&..PP
  3206. T}
  3207. T{
  3208. frequency
  3209. T}:T{
  3210. real
  3211. T}:T{
  3212. .PP
  3213. Station broadcast frequency in kHz\&.
  3214. T}
  3215. T{
  3216. health
  3217. T}:T{
  3218. integer
  3219. T}:T{
  3220. .PP
  3221. <health> is the health of the station for which this is an almanac\&. If it is non\-zero, the station is issuing suspect data and should not be used for fixes\&. The ITU and RTCM104 standards differ about the mode detailed interpretation of the <health> field and even about its bit width\&.
  3222. T}
  3223. T{
  3224. station_id
  3225. T}:T{
  3226. integer
  3227. T}:T{
  3228. .PP
  3229. The id of the transmitter\&. This is not the same as the reference id in the header, the latter being the id of the reference receiver\&.
  3230. T}
  3231. T{
  3232. bitrate
  3233. T}:T{
  3234. integer
  3235. T}:T{
  3236. .PP
  3237. The transmitted bitrate\&.
  3238. T}
  3239. .TE
  3240. .sp 1
  3241. .PP
  3242. Here\*(Aqs an example:
  3243. .sp
  3244. .if n \{\
  3245. .RS 4
  3246. .\}
  3247. .nf
  3248. {"class":"RTCM2","type":9,"station_id":268,"zcount":252\&.6,
  3249. "seqnum":4,"length":5,"station_health":0,
  3250. "satellites":[
  3251. {"ident":13,"udre":0,"iod":3,"prc":\-25\&.940,"rrc":0\&.066},
  3252. {"ident":2,"udre":0,"iod":73,"prc":0\&.920,"rrc":\-0\&.080},
  3253. {"ident":8,"udre":0,"iod":22,"prc":23\&.820,"rrc":0\&.014}
  3254. ]}
  3255. .fi
  3256. .if n \{\
  3257. .RE
  3258. .\}
  3259. .RE
  3260. .sp
  3261. .it 1 an-trap
  3262. .nr an-no-space-flag 1
  3263. .nr an-break-flag 1
  3264. .br
  3265. .ps +1
  3266. \fBType 13: GPS Time of Week\fR
  3267. .RS 4
  3268. .PP
  3269. Here are the payload members of a type 13 (Groumf Tramitter Parameters) message:
  3270. .sp
  3271. .it 1 an-trap
  3272. .nr an-no-space-flag 1
  3273. .nr an-break-flag 1
  3274. .br
  3275. .B Table\ \&25.\ \&Grund Transmitter Parameters
  3276. .TS
  3277. allbox tab(:);
  3278. lB lB lB.
  3279. T{
  3280. Name
  3281. T}:T{
  3282. Type
  3283. T}:T{
  3284. .PP
  3285. Description
  3286. T}
  3287. .T&
  3288. l l l
  3289. l l l
  3290. l l l
  3291. l l l
  3292. l l l.
  3293. T{
  3294. status
  3295. T}:T{
  3296. bool
  3297. T}:T{
  3298. .PP
  3299. If True, signals user to expect a type 16 explanatory message associated with this station\&. Probably indicates some sort of unusual event\&.
  3300. T}
  3301. T{
  3302. rangeflag
  3303. T}:T{
  3304. bool
  3305. T}:T{
  3306. .PP
  3307. If True, indicates that the estimated range is different from that found in the Type 7 message (which contains the beacon\*(Aqs listed range)\&. Generally indicates a range reduction due to causes such as poor ionospheric conditions or reduced transmission power\&.
  3308. T}
  3309. T{
  3310. lat
  3311. T}:T{
  3312. real
  3313. T}:T{
  3314. .PP
  3315. Degrees latitude, signed\&. Positive is N, negative is S\&.
  3316. T}
  3317. T{
  3318. lon
  3319. T}:T{
  3320. real
  3321. T}:T{
  3322. .PP
  3323. Degrees longitude, signed\&. Positive is E, negative is W\&.
  3324. T}
  3325. T{
  3326. range
  3327. T}:T{
  3328. integer
  3329. T}:T{
  3330. .PP
  3331. Transmission range in km (1\-1024)\&.
  3332. T}
  3333. .TE
  3334. .sp 1
  3335. .PP
  3336. This message type replaces message type 3 (Reference Station Parameters) in RTCM 2\&.3\&.
  3337. .RE
  3338. .sp
  3339. .it 1 an-trap
  3340. .nr an-no-space-flag 1
  3341. .nr an-break-flag 1
  3342. .br
  3343. .ps +1
  3344. \fBType 14: GPS Time of Week\fR
  3345. .RS 4
  3346. .PP
  3347. Here are the payload members of a type 14 (GPS Time of Week) message:
  3348. .sp
  3349. .it 1 an-trap
  3350. .nr an-no-space-flag 1
  3351. .nr an-break-flag 1
  3352. .br
  3353. .B Table\ \&26.\ \&Reference Station Parameters
  3354. .TS
  3355. allbox tab(:);
  3356. lB lB lB.
  3357. T{
  3358. Name
  3359. T}:T{
  3360. Type
  3361. T}:T{
  3362. .PP
  3363. Description
  3364. T}
  3365. .T&
  3366. l l l
  3367. l l l
  3368. l l l.
  3369. T{
  3370. week
  3371. T}:T{
  3372. integer
  3373. T}:T{
  3374. .PP
  3375. GPS week (0\-123)\&.
  3376. T}
  3377. T{
  3378. hour
  3379. T}:T{
  3380. integer
  3381. T}:T{
  3382. .PP
  3383. Hour of week (0\-167)\&.
  3384. T}
  3385. T{
  3386. leapsecs
  3387. T}:T{
  3388. integer
  3389. T}:T{
  3390. .PP
  3391. Leap Seconds (0\-63)\&.
  3392. T}
  3393. .TE
  3394. .sp 1
  3395. .PP
  3396. Here\*(Aqs an example:
  3397. .sp
  3398. .if n \{\
  3399. .RS 4
  3400. .\}
  3401. .nf
  3402. {"class":"RTCM2","type":14,"station_id":652,"zcount":1657\&.2,
  3403. "seqnum":3,"length":1,"station_health":6,"week":601,"hour":109,
  3404. "leapsecs":15}
  3405. .fi
  3406. .if n \{\
  3407. .RE
  3408. .\}
  3409. .RE
  3410. .sp
  3411. .it 1 an-trap
  3412. .nr an-no-space-flag 1
  3413. .nr an-break-flag 1
  3414. .br
  3415. .ps +1
  3416. \fBType 16: Special Message\fR
  3417. .RS 4
  3418. .sp
  3419. .it 1 an-trap
  3420. .nr an-no-space-flag 1
  3421. .nr an-break-flag 1
  3422. .br
  3423. .B Table\ \&27.\ \&Special Message
  3424. .TS
  3425. allbox tab(:);
  3426. lB lB lB.
  3427. T{
  3428. Name
  3429. T}:T{
  3430. Type
  3431. T}:T{
  3432. .PP
  3433. Description
  3434. T}
  3435. .T&
  3436. l l l.
  3437. T{
  3438. message
  3439. T}:T{
  3440. string
  3441. T}:T{
  3442. .PP
  3443. A text message sent by the beacon operator\&.
  3444. T}
  3445. .TE
  3446. .sp 1
  3447. .RE
  3448. .sp
  3449. .it 1 an-trap
  3450. .nr an-no-space-flag 1
  3451. .nr an-break-flag 1
  3452. .br
  3453. .ps +1
  3454. \fBType 31: Correction data\fR
  3455. .RS 4
  3456. .PP
  3457. One or more GLONASS satellite objects follow the header for type 1 or type 9 messages\&. Here is the format:
  3458. .sp
  3459. .it 1 an-trap
  3460. .nr an-no-space-flag 1
  3461. .nr an-break-flag 1
  3462. .br
  3463. .B Table\ \&28.\ \&Satellite object
  3464. .TS
  3465. allbox tab(:);
  3466. lB lB lB.
  3467. T{
  3468. Name
  3469. T}:T{
  3470. Type
  3471. T}:T{
  3472. .PP
  3473. Description
  3474. T}
  3475. .T&
  3476. l l l
  3477. l l l
  3478. l l l
  3479. l l l
  3480. l l l
  3481. l l l.
  3482. T{
  3483. ident
  3484. T}:T{
  3485. integer
  3486. T}:T{
  3487. .PP
  3488. The PRN number of the satellite for which this is correction data\&.
  3489. T}
  3490. T{
  3491. udre
  3492. T}:T{
  3493. integer
  3494. T}:T{
  3495. .PP
  3496. User Differential Range Error (0\-3)\&. See the table following for values\&.
  3497. T}
  3498. T{
  3499. change
  3500. T}:T{
  3501. boolean
  3502. T}:T{
  3503. .PP
  3504. Change\-of\-ephemeris bit\&.
  3505. T}
  3506. T{
  3507. tod
  3508. T}:T{
  3509. uinteger
  3510. T}:T{
  3511. .PP
  3512. Count of 30\-second periods since the top of the hour\&.
  3513. T}
  3514. T{
  3515. prc
  3516. T}:T{
  3517. real
  3518. T}:T{
  3519. .PP
  3520. The pseudorange error in meters for this satellite as measured by the beacon reference receiver at the epoch indicated by the z_count in the parent record\&.
  3521. T}
  3522. T{
  3523. rrc
  3524. T}:T{
  3525. real
  3526. T}:T{
  3527. .PP
  3528. The rate of change of pseudorange error in meters/sec for this satellite as measured by the beacon reference receiver at the epoch indicated by the z_count field in the parent record\&. This is used to calculate pseudorange errors at other epochs, if required by the GPS receiver\&.
  3529. T}
  3530. .TE
  3531. .sp 1
  3532. .PP
  3533. Here\*(Aqs an example:
  3534. .sp
  3535. .if n \{\
  3536. .RS 4
  3537. .\}
  3538. .nf
  3539. {"class":"RTCM2","type":31,"station_id":652,"zcount":1642\&.2,
  3540. "seqnum":0,"length":14,"station_health":6,
  3541. "satellites":[
  3542. {"ident":5,"udre":0,"change":false,"tod":0,"prc":132\&.360,"rrc":0\&.000},
  3543. {"ident":15,"udre":0,"change":false,"tod":0,"prc":134\&.840,"rrc":0\&.002},
  3544. {"ident":14,"udre":0,"change":false,"tod":0,"prc":141\&.520,"rrc":0\&.000},
  3545. {"ident":6,"udre":0,"change":false,"tod":0,"prc":127\&.000,"rrc":0\&.000},
  3546. {"ident":21,"udre":0,"change":false,"tod":0,"prc":128\&.780,"rrc":0\&.000},
  3547. {"ident":22,"udre":0,"change":false,"tod":0,"prc":125\&.260,"rrc":0\&.002},
  3548. {"ident":20,"udre":0,"change":false,"tod":0,"prc":117\&.280,"rrc":\-0\&.004},
  3549. {"ident":16,"udre":0,"change":false,"tod":17,"prc":113\&.460,"rrc":0\&.018}
  3550. ]}
  3551. .fi
  3552. .if n \{\
  3553. .RE
  3554. .\}
  3555. .RE
  3556. .SH "RTCM3 DUMP FORMAT"
  3557. .PP
  3558. The support for RTCM104v3 dumping is incomplete and buggy\&. Do not attempt to use it for production! Anyone interested in it should read the source code\&.
  3559. .SH "AIS DUMP FORMATS"
  3560. .PP
  3561. AIS support is an extension\&. It may not be present if your instance of
  3562. gpsd
  3563. has been built with a restricted feature set\&.
  3564. .PP
  3565. AIS packets are dumped as JSON objects with class "AIS"\&. Each AIS report object contains a "type" field giving the AIS message type and a "scaled" field telling whether the remainder of the fields are dumped in scaled or unscaled form\&. (These will be emitted before any type\-specific fields\&.) It will also contain a "device" field naming the data source\&. Other fields have names and types as specified in the
  3566. AIVDM/AIVDO Protocol Decoding
  3567. document on the GPSD project website; each message field table may be directly interpreted as a specification for the members of the corresponding JSON object type\&.
  3568. .PP
  3569. By default, certain scaling and conversion operations are performed for JSON output\&. Latitudes and longitudes are scaled to decimal degrees rather than the native AIS unit of 1/10000th of a minute of arc\&. Ship (but not air) speeds are scaled to knots rather than tenth\-of\-knot units\&. Rate of turn may appear as "nan" if is unavailable, or as one of the strings "fastright" or "fastleft" if it is out of the AIS encoding range; otherwise it is quadratically mapped back to the turn sensor number in degrees per minute\&. Vessel draughts are converted to decimal meters rather than native AIS decimeters\&. Various other scaling conversions are described in
  3570. "AIVDM/AIVDO Protocol Decoding"\&.
  3571. .SH "SUBFRAME DUMP FORMATS"
  3572. .PP
  3573. Subframe support is always compiled into
  3574. gpsd
  3575. but many GPSes do not output subframe data or the
  3576. gpsd
  3577. driver may not support subframes\&.
  3578. .PP
  3579. Subframe packets are dumped as JSON objects with class "SUBFRAME"\&. Each subframe report object contains a "frame" field giving the subframe number, a "tSV" field for the transmitting satellite number, a "TOW17" field containing the 17 MSBs of the start of the next 12\-second message and a "scaled" field telling whether the remainder of the fields are dumped in scaled or unscaled form\&. It will also contain a "device" field naming the data source\&. Each SUBFRAME object will have a sub\-object specific to that subframe page type\&. Those sub\-object fields have names and types similar to those specified in the IS\-GPS\-200E document; each message field table may be directly interpreted as a specification for the members of the corresponding JSON object type\&.
  3580. .SH "SEE ALSO"
  3581. .PP
  3582. \fBgpsd\fR(8),
  3583. \fBlibgps\fR(3),
  3584. .SH "AUTHOR"
  3585. .PP
  3586. The protocol was designed and documented by Eric S\&. Raymond\&.
  3587. .SH "NOTES"
  3588. .IP " 1." 4
  3589. Radio Technical Commission for Maritime Services
  3590. .RS 4
  3591. \%http://www.rtcm.org/
  3592. .RE
  3593. .IP " 2." 4
  3594. table of leap second corrections
  3595. .RS 4
  3596. \%ftp://maia.usno.navy.mil/ser7/tai-utc.dat
  3597. .RE