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.
 
 
 
 
 
 

926 lines
40 KiB

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!--
  3. This file is Copyright (c) 2010 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.8'>
  12. <refentryinfo><date>9 Aug 2004</date></refentryinfo>
  13. <refmeta>
  14. <refentrytitle>gpsd</refentrytitle>
  15. <manvolnum>8</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</refname>
  21. <refpurpose>interface daemon for GPS receivers</refpurpose>
  22. </refnamediv>
  23. <refsynopsisdiv id='synopsis'>
  24. <cmdsynopsis>
  25. <command>gpsd</command>
  26. <arg choice='opt'>-b </arg>
  27. <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg>
  28. <arg choice='opt'>-F <replaceable>control-socket</replaceable></arg>
  29. <arg choice='opt'>-f <replaceable>framing</replaceable></arg>
  30. <arg choice='opt'>-G </arg>
  31. <arg choice='opt'>-h </arg>
  32. <arg choice='opt'>-l </arg>
  33. <arg choice='opt'>-n </arg>
  34. <arg choice='opt'>-N </arg>
  35. <arg choice='opt'>-P <replaceable>pidfile</replaceable></arg>
  36. <arg choice='opt'>-r </arg>
  37. <arg choice='opt'>-S <replaceable>listener-port</replaceable></arg>
  38. <arg choice='opt'>-s <replaceable>speed</replaceable></arg>
  39. <arg choice='opt'>-V </arg>
  40. <arg rep='repeat'>
  41. <group><replaceable>source-name</replaceable></group>
  42. </arg>
  43. </cmdsynopsis>
  44. </refsynopsisdiv>
  45. <refsect1 id='quickstart'><title>QUICK START</title>
  46. <para>If you have a GPS attached on the lowest-numbered USB port of a
  47. Linux system, and want to read reports from it on TCP/IP port 2947, it
  48. will normally suffice to do this:</para>
  49. <programlisting>
  50. gpsd /dev/ttyUSB0
  51. </programlisting>
  52. <para>For the lowest-numbered serial port:</para>
  53. <programlisting>
  54. gpsd /dev/ttyS0
  55. </programlisting>
  56. <para>Change the device number as appropriate if you need to use a
  57. different port. Command-line flags enable verbose logging, a control
  58. port, and other optional extras but should not be needed for basic
  59. operation; the one exception, on very badly designed hardware, might
  60. be <option>-b</option> (which see).</para>
  61. <para>On Linux systems supporting udev, <application>gpsd</application>
  62. is normally started automatically when a USB plugin event fires (if it
  63. is not already running) and is handed the name of the newly active
  64. device. In that case no invocation is required at all.</para>
  65. <para>For your initial tests set your GPS hardware to speak NMEA, as
  66. <application>gpsd</application> is guaranteed to be able to process
  67. that. If your GPS has a native or binary mode with better performance
  68. that <application>gpsd</application> knows how to speak,
  69. <application>gpsd</application> will autoconfigure that mode.</para>
  70. <para>You can verify correct operation by first starting
  71. <application>gpsd</application> and then
  72. <application>xgps</application>, the X windows test client.</para>
  73. <para>If you have problems, the GPSD project maintains a FAQ to
  74. assist troubleshooting.</para>
  75. </refsect1>
  76. <refsect1 id='description'><title>DESCRIPTION</title>
  77. <para><application>gpsd</application> is a monitor daemon that collects
  78. information from GPSes, differential-GPS radios, or AIS receivers
  79. attached to the host machine. Each GPS, DGPS radio, or AIS receiver
  80. is expected to be direct-connected to the host via a USB or RS232C
  81. serial device. The serial device may be specified to
  82. <application>gpsd</application> at startup, or it may be set via a
  83. command shipped down a local control socket (e.g. by a USB hotplug
  84. script). Given a GPS device by either means,
  85. <application>gpsd</application> discovers the correct port speed and
  86. protocol for it.</para>
  87. <para><application>gpsd</application> should be able to query any GPS
  88. that speaks either the standard textual NMEA 0183 protocol, or the
  89. (differing) extended NMEA dialects used by MKT-3301, iTrax, Motorola
  90. OnCore, Sony CXD2951, and Ashtech/Thales devices. It can also
  91. interpret the binary protocols used by EverMore, Garmin, Navcom,
  92. Rockwell/Zodiac, SiRF, Trimble, and u-blox ANTARIS devices. Under Linux
  93. it can read NMEA2000 packets through the kernel CAN socket. It can read
  94. heading and attitude information from the Oceanserver 5000 or TNT
  95. Revolution digital compasses.</para>
  96. <para>The GPS reporting formats supported by your instance of
  97. <application>gpsd</application> may differ depending on how it was
  98. compiled; general-purpose versions support many, but it can be built
  99. with protocol subsets down to a singleton for use in constrained
  100. environments. For a list of the GPS protocols supported by your
  101. instance, see the output of <command>gpsd -l</command></para>
  102. <para><application>gpsd</application> effectively hides the
  103. differences among the GPS types it supports. It also knows about and
  104. uses commands that tune these GPSes for lower latency. By using
  105. <application>gpsd</application> as an intermediary, applications
  106. avoid contention for serial devices.</para>
  107. <para><application>gpsd</application> can use differential-GPS
  108. corrections from a DGPS radio or over the net, from a ground station
  109. running a DGPSIP server or a Ntrip broadcaster that reports RTCM-104
  110. data; this will shrink position errors by roughly a factor of four.
  111. When <application>gpsd</application> opens a serial device emitting
  112. RTCM-104, it automatically recognizes this and uses the device as a
  113. correction source for all connected GPSes that accept RTCM corrections
  114. (this is dependent on the type of the GPS; not all GPSes have the
  115. firmware capability to accept RTCM correction packets). See
  116. <xref linkend='accuracy'/> and <xref linkend='files'/> for discussion.</para>
  117. <para>Client applications will communicate with <application>gpsd</application>
  118. via a TCP/IP port, 2947 by default). Both IPv4 and IPv6 connections
  119. are supported and a client may connect via either.</para>
  120. <para>The program accepts the following options:</para>
  121. <variablelist remap='TP'>
  122. <varlistentry>
  123. <term>-b</term>
  124. <listitem><para>Broken-device-safety mode, otherwise known as
  125. read-only mode. A few bluetooth and USB receivers lock up or become
  126. totally inaccessible when probed or reconfigured; see the hardware
  127. compatibility list on the GPSD project website for details. This
  128. switch prevents gpsd from writing to a receiver. This means that
  129. <application>gpsd</application> cannot configure the receiver for
  130. optimal performance, but it also means that
  131. <application>gpsd</application> cannot break the receiver. A better
  132. solution would be for Bluetooth to not be so fragile. A platform
  133. independent method to identify serial-over-Bluetooth devices would
  134. also be nice.</para></listitem>
  135. </varlistentry>
  136. <varlistentry>
  137. <term>-D</term>
  138. <listitem>
  139. <para>Set debug level. At debug levels 2 and above,
  140. <application>gpsd</application> reports incoming sentence and actions
  141. to standard error if <application>gpsd</application> is in the foreground
  142. (-N) or to syslog if in the background.</para>
  143. </listitem>
  144. </varlistentry>
  145. <varlistentry>
  146. <term>-F</term>
  147. <listitem>
  148. <para>Create a control socket for device addition and removal
  149. commands. You must specify a valid pathname on your local filesystem;
  150. this will be created as a Unix-domain socket to which you can write
  151. commands that edit the daemon's internal device list.</para>
  152. </listitem>
  153. </varlistentry>
  154. <varlistentry>
  155. <term>-f</term>
  156. <listitem><para>Fix the framing to the GNSS device.
  157. The framing parameter is of the form: [78][ENO][012].
  158. Most GNSS are 8N1. Some Trimble default to 8O1.
  159. The default is to search for the correct framing.</para></listitem>
  160. </varlistentry>
  161. <varlistentry>
  162. <term>-G</term>
  163. <listitem><para>This flag causes <application>gpsd</application> to
  164. listen on all addresses (INADDR_ANY) rather than just the loop back
  165. (INADDR_LOOPBACK) address. For the sake of privacy and security, TPV
  166. information is now private to the local machine until the user makes
  167. an effort to expose this to the world.</para></listitem>
  168. </varlistentry>
  169. <varlistentry>
  170. <term>-h</term>
  171. <listitem><para>Display help message and terminate.</para></listitem>
  172. </varlistentry>
  173. <varlistentry>
  174. <term>-l</term>
  175. <listitem><para>List all drivers compiled into this
  176. <application>gpsd</application> instance. The letters to the left of
  177. each driver name are the <application>gpsd</application>
  178. control commands supported by that driver.</para>
  179. </listitem>
  180. </varlistentry>
  181. <varlistentry>
  182. <term>-n</term>
  183. <listitem>
  184. <para>Don't wait for a client to connect before polling whatever GPS
  185. is associated with it. Some RS232 GPSes wait in a standby mode
  186. (drawing less power) when the host machine is not asserting DTR, and
  187. some cellphone and handheld embedded GPSes have similar behaviors.
  188. Accordingly, waiting for a watch request to open the device may save
  189. battery power. (This capability is rare in consumer-grade devices).
  190. You should use this option if you plan to use gpsd to provide reference
  191. clock information to ntpd through a memory-shared segment.
  192. </para>
  193. </listitem>
  194. </varlistentry>
  195. <varlistentry>
  196. <term>-N</term>
  197. <listitem><para>Don't daemonize; run in foreground.
  198. This switch is mainly useful for debugging.</para>
  199. </listitem>
  200. </varlistentry>
  201. <varlistentry>
  202. <term>-r</term>
  203. <listitem><para>Use GPS time even with no current fix. Some GPS's have
  204. battery powered Real Time Clocks (RTC's) built in, making them a valid time
  205. source even before a fix is acquired. This can be useful on a Raspberry Pi,
  206. or other device that has no battery powered RTC, and thus has no valid
  207. time at startup.</para></listitem>
  208. </varlistentry>
  209. <varlistentry>
  210. <term>-P</term>
  211. <listitem>
  212. <para>Specify the name and path to record the daemon's process ID.</para>
  213. </listitem>
  214. </varlistentry>
  215. <varlistentry>
  216. <term>-S</term>
  217. <listitem><para>Set TCP/IP port on which to listen for GPSD clients
  218. (default is 2947).</para></listitem>
  219. </varlistentry>
  220. <varlistentry>
  221. <term>-s</term>
  222. <listitem><para>Fix the speed to the GNSS device.
  223. The default is to autobaud.</para></listitem>
  224. </varlistentry>
  225. <varlistentry>
  226. <term>-V</term>
  227. <listitem>
  228. <para>Dump version and exit.</para>
  229. </listitem>
  230. </varlistentry>
  231. </variablelist>
  232. <para>Arguments are interpreted as the names of data sources.
  233. Normally, a data source is the device pathname of a local device from
  234. which the daemon may expect GPS data. But there are three other
  235. special source types recognized, for a total of four:</para>
  236. <variablelist>
  237. <varlistentry>
  238. <term>Local serial or USB device</term>
  239. <listitem>
  240. <para>A normal Unix device name of a serial or USB device to which a
  241. sensor is attached. Example:
  242. <filename>/dev/ttyUSB0</filename>.</para>
  243. </listitem>
  244. </varlistentry>
  245. <varlistentry>
  246. <term>Local PPS device</term>
  247. <listitem>
  248. <para>A normal Unix device name of a PPS device to which a PPS source
  249. is attached. The device name must start with "/dev/pps" and a local
  250. serial or USB GPS device must also be available. Example:
  251. <filename>/dev/pps0</filename>.</para>
  252. </listitem>
  253. </varlistentry>
  254. <varlistentry>
  255. <term>TCP feed</term>
  256. <listitem>
  257. <para>A URI with the prefix "tcp://", followed by a hostname, a
  258. colon, and a port number. The daemon will open a socket to the
  259. indicated address and port and read data packets from it, which will
  260. be interpreted as though they had been issued by a serial device. Example:
  261. <filename>tcp://data.aishub.net:4006</filename>.</para>
  262. </listitem>
  263. </varlistentry>
  264. <varlistentry>
  265. <term>UDP feed</term>
  266. <listitem>
  267. <para>A URI with the prefix "udp://", followed by a hostname, a
  268. colon, and a port number. The daemon will open a socket listening for
  269. UDP datagrams arriving on the indicated address and port, which will
  270. be interpreted as though they had been issued by a serial device. Example:
  271. <filename>udp://127.0.0.1:5000</filename>.</para>
  272. </listitem>
  273. </varlistentry>
  274. <varlistentry>
  275. <term>Ntrip caster</term>
  276. <listitem>
  277. <para>A URI with the prefix "ntrip://" followed by the name of an
  278. Ntrip caster (Ntrip is a protocol for broadcasting differential-GPS
  279. fixes over the net). For Ntrip services that require authentication, a
  280. prefix of the form "username:password@" can be added before the name
  281. of the Ntrip broadcaster. For Ntrip service, you must specify which
  282. stream to use; the stream is given in the form "/streamname". An
  283. example DGPSIP URI could be "dgpsip://dgpsip.example.com" and a Ntrip
  284. URI could be
  285. "ntrip://foo:bar@ntrip.example.com:80/example-stream". Corrections
  286. from the caster will be send to each attached GPS with the capability
  287. to accept them.</para>
  288. </listitem>
  289. </varlistentry>
  290. <varlistentry>
  291. <term>DGPSIP server</term>
  292. <listitem>
  293. <para>A URI with the prefix "dgpsip://" followed by a hostname, a
  294. colon, and an optional colon-separated port number (defaulting to
  295. 2101). The daemon will handshake with the DGPSIP server and
  296. read RTCM2 correction data from it. Corrections
  297. from the server will be set to each attached GPS with the capability
  298. to accept them. Example:
  299. <filename>dgpsip://dgps.wsrcc.com:2101</filename>.</para>
  300. </listitem>
  301. </varlistentry>
  302. <varlistentry>
  303. <term>Remote gpsd feed</term>
  304. <listitem>
  305. <para>A URI with the prefix "gpsd://", followed by a hostname and
  306. optionally a colon and a port number (if the port is absent the
  307. default <application>gpsd</application> port will be used). The daemon
  308. will open a socket to the indicated address and port and emulate a
  309. <application>gpsd</application> client, collecting JSON reports from
  310. the remote <application>gpsd</application> instance that will be
  311. passed to local clients.</para>
  312. </listitem>
  313. </varlistentry>
  314. <varlistentry>
  315. <term>NMEA2000 CAN data</term>
  316. <listitem>
  317. <para>A URI with the prefix "nmea2000://", followed by a CAN
  318. devicename. Only Linux socket CAN interfaces are supported. The
  319. interface must be configured to receive CAN messages
  320. before <application>gpsd</application> can be started. If
  321. there is more then one unit on the CAN bus that provides GPS data,
  322. <application>gpsd</application> chooses the unit from which a GPS message
  323. is first seen. Example: <filename>nmea2000://can0</filename>.
  324. </para>
  325. </listitem>
  326. </varlistentry>
  327. </variablelist>
  328. <para>(The "ais:://" source type supported in some older versions of
  329. the daemon has been retired in favor of the more general
  330. "tcp://".)</para>
  331. <para>Additionally, two serial device names have a side effect:</para>
  332. <variablelist>
  333. <varlistentry>
  334. <term>/dev/ttyAMA0</term>
  335. <listitem>
  336. <para>The UART device on a Raspberry Pi. Has the side effect of
  337. opening /dev/pps0 for RFC2783 1PPS data.</para>
  338. </listitem>
  339. </varlistentry>
  340. <varlistentry>
  341. <term>/dev/gpsd0</term>
  342. <listitem>
  343. <para>Generic GPS device 0. Has the side effect of
  344. opening /dev/pps0 for RFC2783 1PPS data.</para>
  345. </listitem>
  346. </varlistentry>
  347. </variablelist>
  348. <para>
  349. Note, however, that if /dev/pps0 is the fake "ktimer" PPS, then /dev/pps1
  350. will be used instead.
  351. </para>
  352. <para>Internally, the daemon maintains a device pool holding the
  353. pathnames of devices and remote servers known to the
  354. daemon. Initially, this list is the list of device-name arguments
  355. specified on the command line. That list may be empty, in which case
  356. the daemon will have no devices on its search list until they are
  357. added by a control-socket command (see <xref linkend='devices'/> for
  358. details on this). Daemon startup will abort with an error if neither
  359. any devices nor a control socket are specified.</para>
  360. <para>When a device is activated (i.e. a client requests data from it),
  361. gpsd attempts to execute a hook from
  362. <filename>/etc/gpsd/device-hook</filename> with first command line argument
  363. set to the pathname of the device and the second to
  364. <option>ACTIVATE</option>. On deactivation it does the same passing
  365. <option>DEACTIVATE</option> for the second argument.</para>
  366. <para><application>gpsd</application> can export data to client applications
  367. in three ways: via a sockets interface, via a shared-memory segment, and
  368. via D-Bus. The next three major sections describe these interfaces.</para>
  369. </refsect1>
  370. <refsect1 id='sockets'><title>THE SOCKET INTERFACE</title>
  371. <para>Clients may communicate with the daemon via textual request and
  372. responses over a socket. It is a bad idea for applications to speak the protocol
  373. directly: rather, they should use the
  374. <application>libgps</application> client library and take appropriate
  375. care to conditionalize their code on the major and minor protocol
  376. version symbols.</para>
  377. <para>The request-response protocol for the socket interface is fully
  378. documented in
  379. <citerefentry><refentrytitle>gpsd_json</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  380. </refsect1>
  381. <refsect1 id='shm'><title>SHARED-MEMORY AND DBUS INTERFACES</title>
  382. <para><application>gpsd</application> has two other (read-only)
  383. interfaces.</para>
  384. <para>Whenever the daemon recognizes a packet from any attached
  385. device, it writes the accumulated state from that device to a shared
  386. memory segment. The C and C++ client libraries shipped with GPSD can
  387. read this segment. Client methods, and various restrictions associated
  388. with the read-only nature of this interface, are documented at
  389. <citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The
  390. shared-memory interface is intended primarily for embedded deployments
  391. in which <application>gpsd</application> monitors a single device, and
  392. its principal advantage is that a daemon instance configured with
  393. shared memory but without the sockets interface loses a significant
  394. amount of runtime weight.</para>
  395. <para>The daemon may be configured to emit a D-Bus signal each time an
  396. attached device delivers a fix. The signal path is <filename>path
  397. /org/gpsd</filename>, the signal interface is "org.gpsd", and the
  398. signal name is "fix". The signal payload layout is as follows:</para>
  399. <table frame="all" pgwide="0"><title>Satellite object</title>
  400. <tgroup cols="2" align="left" colsep="1" rowsep="1">
  401. <thead>
  402. <row>
  403. <entry>Type</entry>
  404. <entry><para>Description</para></entry>
  405. </row>
  406. </thead>
  407. <tbody>
  408. <row>
  409. <entry>DBUS_TYPE_DOUBLE</entry>
  410. <entry><para>Time (seconds since Unix epoch)</para></entry>
  411. </row>
  412. <row>
  413. <entry>DBUS_TYPE_INT32</entry>
  414. <entry><para>mode</para></entry>
  415. </row>
  416. <row>
  417. <entry>DBUS_TYPE_DOUBLE</entry>
  418. <entry><para>Time uncertainty (seconds).</para></entry>
  419. </row>
  420. <row>
  421. <entry>DBUS_TYPE_DOUBLE</entry>
  422. <entry><para>Latitude in degrees.</para></entry>
  423. </row>
  424. <row>
  425. <entry>DBUS_TYPE_DOUBLE</entry>
  426. <entry><para>Longitude in degrees.</para></entry>
  427. </row>
  428. <row>
  429. <entry>DBUS_TYPE_DOUBLE</entry>
  430. <entry><para>Horizontal uncertainty in meters, 95% confidence.</para></entry>
  431. </row>
  432. <row>
  433. <entry>DBUS_TYPE_DOUBLE</entry>
  434. <entry><para>Altitude in meters.</para></entry>
  435. </row>
  436. <row>
  437. <entry>DBUS_TYPE_DOUBLE</entry>
  438. <entry><para>Altitude uncertainty in meters, 95% confidence.</para></entry>
  439. </row>
  440. <row>
  441. <entry>DBUS_TYPE_DOUBLE</entry>
  442. <entry><para>Course in degrees from true north.</para></entry>
  443. </row>
  444. <row>
  445. <entry>DBUS_TYPE_DOUBLE</entry>
  446. <entry><para>Course uncertainty in meters, 95% confidence.</para></entry>
  447. </row>
  448. <row>
  449. <entry>DBUS_TYPE_DOUBLE</entry>
  450. <entry><para>Speed, meters per second.</para></entry>
  451. </row>
  452. <row>
  453. <entry>DBUS_TYPE_DOUBLE</entry>
  454. <entry><para>Speed uncertainty in meters per second,
  455. 95% confidence.</para></entry>
  456. </row>
  457. <row>
  458. <entry>DBUS_TYPE_DOUBLE</entry>
  459. <entry><para>Climb, meters per second.</para></entry>
  460. </row>
  461. <row>
  462. <entry>DBUS_TYPE_DOUBLE</entry>
  463. <entry><para>Climb uncertainty in meters per second,
  464. 95% confidence.</para></entry>
  465. </row>
  466. <row>
  467. <entry>DBUS_TYPE_STRING</entry>
  468. <entry><para>Device name</para></entry>
  469. </row>
  470. </tbody>
  471. </tgroup>
  472. </table>
  473. </refsect1>
  474. <refsect1 id='devices'><title>GPS DEVICE MANAGEMENT</title>
  475. <para><application>gpsd</application> maintains an internal list of
  476. GPS devices (the "device pool"). If you specify devices on the
  477. command line, the list is initialized with those pathnames; otherwise
  478. the list starts empty. Commands to add and remove GPS device paths
  479. from the daemon's device list must be written to a local Unix-domain
  480. socket which will be accessible only to programs running as root.
  481. This control socket will be located wherever the -F option specifies
  482. it.</para>
  483. <para>A device may will also be dropped from the pool if GPSD gets a zero
  484. length read from it. This end-of-file condition indicates that the
  485. device has been disconnected.</para>
  486. <para>When <application>gpsd</application> is properly installed along
  487. with hotplug notifier scripts feeding it device-add commands over the
  488. control socket, <application>gpsd</application> should require no
  489. configuration or user action to find devices.</para>
  490. <para>Sending SIGHUP to a running <application>gpsd</application>
  491. forces it to close all GPSes and all client connections. It will then
  492. attempt to reconnect to any GPSes on its device list and resume
  493. listening for client connections. This may be useful if your GPS
  494. enters a wedged or confused state but can be soft-reset by pulling
  495. down DTR.</para>
  496. <para>When <application>gpsd</application> is called with no initial
  497. devices (thus, expecting devices to be passed to it by notifications to
  498. the control socket), and reaches a state where there are no devices
  499. connected and no subscribers <emphasis>after</emphasis> after some
  500. devices have been seen, it shuts down gracefully. It is expected that
  501. future device hotplug events will reactivate it.</para>
  502. <para>To point <application>gpsd</application> at a device that may be
  503. a GPS, write to the control socket a plus sign ('+') followed by the
  504. device name followed by LF or CR-LF. Thus, to point the daemon at
  505. <filename>/dev/foo</filename>. send "+/dev/foo\n". To tell the daemon
  506. that a device has been disconnected and is no longer available, send a
  507. minus sign ('-') followed by the device name followed by LF or
  508. CR-LF. Thus, to remove <filename>/dev/foo</filename> from the search
  509. list, send "-/dev/foo\n".</para>
  510. <para>To send a control string to a specified device, write to the
  511. control socket a '!', followed by the device name, followed by '=',
  512. followed by the control string.</para>
  513. <para>To send a binary control string to a specified device, write to the
  514. control socket a '&amp;', followed by the device name, followed by '=',
  515. followed by the control string in paired hex digits.</para>
  516. <para>Your client may await a response, which will be a line beginning
  517. with either "OK" or "ERROR". An ERROR response to an add command means
  518. the device did not emit data recognizable as GPS packets; an ERROR
  519. response to a remove command means the specified device was not in
  520. <application>gpsd</application>'s device pool. An ERROR response to a
  521. ! command means the daemon did not recognize the devicename
  522. specified.</para>
  523. <para>The control socket is intended for use by hotplug scripts and
  524. other device-discovery services. This control channel is separate
  525. from the public <application>gpsd</application> service port, and only
  526. locally accessible, in order to prevent remote denial-of-service and
  527. spoofing attacks.</para>
  528. </refsect1>
  529. <refsect1 id='accuracy'><title>ACCURACY</title>
  530. <para>The base User Estimated Range Error (UERE) of GPSes is 8 meters
  531. or less at 66% confidence, 15 meters or less at 95% confidence. Actual
  532. horizontal error will be UERE times a dilution factor dependent on current
  533. satellite position. Altitude determination is more sensitive to
  534. variability in ionospheric signal lag than latitude/longitude is, and is
  535. also subject to errors in the estimation of local mean sea level; base
  536. error is 12 meters at 66% confidence, 23 meters at 95% confidence.
  537. Again, this will be multiplied by a vertical dilution of precision
  538. (VDOP) dependent on satellite geometry, and VDOP is typically larger
  539. than HDOP. Users should <emphasis>not</emphasis> rely on GPS altitude for
  540. life-critical tasks such as landing an airplane.</para>
  541. <para>These errors are intrinsic to the design and physics of the GPS
  542. system. <application>gpsd</application> does its internal
  543. computations at sufficient accuracy that it will add no measurable
  544. position error of its own.</para>
  545. <para>DGPS correction will reduce UERE by a factor of 4, provided you
  546. are within about 100mi (160km) of a DGPS ground station from which you
  547. are receiving corrections.</para>
  548. <para>On a 4800bps connection, the time latency of fixes provided by
  549. <application>gpsd</application> will be one second or less 95% of the
  550. time. Most of this lag is due to the fact that GPSes normally emit
  551. fixes once per second, thus expected latency is 0.5sec. On the
  552. personal-computer hardware available in 2005 and later, computation
  553. lag induced by <application>gpsd</application> will be negligible, on
  554. the order of a millisecond. Nevertheless, latency can introduce
  555. significant errors for vehicles in motion; at 50km/h (31mi/h) of speed
  556. over ground, 1 second of lag corresponds to 13.8 meters change in
  557. position between updates.</para>
  558. <para>The time reporting of the GPS system itself has an intrinsic
  559. accuracy limit of 14 nanoseconds, but this can only be approximated by
  560. specialized receivers using that send the high-accuracy PPS
  561. (Pulse-Per-Second) over RS232 to cue a clock crystal. Most GPS
  562. receivers only report time to a precision of 0.01s or 0.001s,
  563. and with no accuracy guarantees below 1sec.</para>
  564. <para>If your GPS uses a SiRF chipset at firmware level 231, reported
  565. UTC time may be off by the difference between whatever default
  566. leap-second offset has been compiled in and whatever leap-second
  567. correction is currently applicable, from startup until complete
  568. subframe information is received. Firmware levels 232 and up don't
  569. have this problem. You may run <application>gpsd</application> at
  570. debug level 4 to see the chipset type and firmware revision
  571. level.</para>
  572. <para>There are exactly two circumstances under which
  573. <application>gpsd</application> relies on the host-system
  574. clock:</para>
  575. <para>In the GPS broadcast signal, GPS time is represented using a
  576. week number that rolls over after 2^10 or 2^13 weeks (about 19.6
  577. years, or 157 years), depending on the spacecraft. Receivers are
  578. required to disambiguate this to the correct date, but may have
  579. difficulty due to not knowing time to within half this interval, or
  580. may have bugs. Users have reported incorrect dates which appear to be
  581. due to this issue. <application>gpsd</application> uses the startup
  582. time of the daemon detect and compensate for rollovers while it is
  583. running, but otherwise reports the date as it is reported by the
  584. receiver without attempting to correct it.</para>
  585. <para>If you are using an NMEA-only GPS (that is, not using SiRF or
  586. Garmin or Zodiac binary mode), <application>gpsd</application> relies
  587. on the system clock to tell it the current century. If the system clock
  588. returns an invalid value near zero, and the GPS does not emit GPZDA at
  589. the start of its update cycle (which most consumer-grade NMEA GPSes do
  590. not) then the century part of the dates
  591. <application>gpsd</application> delivers may be wrong. Additionally,
  592. near the century turnover, a range of dates as wide in seconds as the
  593. accuracy of your system clock may be referred to the wrong
  594. century.</para>
  595. </refsect1>
  596. <refsect1 id='ntp'><title>USE WITH NTP</title>
  597. <para>gpsd can provide reference clock information to
  598. <application>ntpd</application>, to keep the system clock synchronized
  599. to the time provided by the GPS receiver.</para>
  600. <para>On Linux, <application>gpsd</application> includes support for
  601. interpreting the PPS pulses emitted at the start of every clock second
  602. on the carrier-detect lines of some serial GPSes; this pulse can be
  603. used to update NTP at much higher accuracy than message time provides.
  604. You can determine whether your GPS emits this pulse by running at -D 5
  605. and watching for carrier-detect state change messages in the logfile.
  606. In addition, if your kernel provides the RFC 2783 kernel PPS API then
  607. <application>gpsd</application> will use that for extra
  608. accuracy.</para>
  609. <para>Detailed instructions for using GPSD to set up a high-quality
  610. time service can be found among the documentation on the GPSD
  611. website.</para>
  612. </refsect1>
  613. <refsect1 id='dbus'><title>USE WITH D-BUS</title>
  614. <para>On operating systems that support D-BUS,
  615. <application>gpsd</application> can be built to broadcast GPS fixes to
  616. D-BUS-aware applications. As D-BUS is still at a pre-1.0 stage, we
  617. will not attempt to document this interface here. Read the
  618. <application>gpsd</application> source code to learn more.</para>
  619. </refsect1>
  620. <refsect1 id='security'><title>SECURITY AND PERMISSIONS ISSUES</title>
  621. <para><application>gpsd</application>, if given the -G flag, will
  622. listen for connections from any reachable host, and then disclose the
  623. current position. Before using the -G flag, consider whether you
  624. consider your computer's location to be sensitive data to be kept
  625. private or something that you wish to publish.</para>
  626. <para><application>gpsd</application> must start up as root in order
  627. to open the NTPD shared-memory segment, open its logfile, and create
  628. its local control socket. Before doing any processing of GPS data, it
  629. tries to drop root privileges by setting its UID to "nobody" (or another
  630. configured userid) and its group ID to the group of the initial
  631. GPS passed on the command line &mdash; or, if that device doesn't exist,
  632. to the group of <filename>/dev/ttyS0</filename>.</para>
  633. <para>Privilege-dropping is a hedge against the possibility that
  634. carefully crafted data, either presented from a client socket or from
  635. a subverted serial device posing as a GPS, could be used to induce
  636. misbehavior in the internals of <application>gpsd</application>.
  637. It ensures that any such compromises cannot be used for privilege
  638. elevation to root.</para>
  639. <para>The assumption behind <application>gpsd</application>'s
  640. particular behavior is that all the tty devices to which a GPS might
  641. be connected are owned by the same non-root group and allow group
  642. read/write, though the group may vary because of distribution-specific
  643. or local administrative practice. If this assumption is false,
  644. <application>gpsd</application> may not be able to open GPS devices in
  645. order to read them (such failures will be logged).</para>
  646. <para>In order to fend off inadvertent denial-of-service attacks by
  647. port scanners (not to mention deliberate ones),
  648. <application>gpsd</application> will time out inactive client
  649. connections. Before the client has issued a command that requests a
  650. channel assignment, a short timeout (60 seconds) applies. There is no
  651. timeout for clients in watcher or raw modes; rather,
  652. <application>gpsd</application> drops these clients if they fail to
  653. read data long enough for the outbound socket write buffer to fill.
  654. Clients with an assigned device in polling mode are subject to a
  655. longer timeout (15 minutes).</para>
  656. </refsect1>
  657. <refsect1 id='limitations'><title>LIMITATIONS</title>
  658. <para>If multiple NMEA talkers are feeding RMC, GLL, and GGA sentences
  659. to the same serial device (possible with an RS422 adapter hooked up to
  660. some marine-navigation systems), a 'TPV' response may mix an altitude
  661. from one device's GGA with latitude/longitude from another's RMC/GLL
  662. after the second sentence has arrived.</para>
  663. <para><application>gpsd</application> may change control settings on
  664. your GPS (such as the emission frequency of various sentences or
  665. packets) and not restore the original settings on exit. This is a
  666. result of inadequacies in NMEA and the vendor binary GPS protocols,
  667. which often do not give clients any way to query the values of control
  668. settings in order to be able to restore them later.</para>
  669. <para>When using SiRF chips, the VDOP/TDOP/GDOP figures and associated
  670. error estimates are computed by <application>gpsd</application> rather
  671. than reported by the chip. The computation does not exactly match
  672. what SiRF chips do internally, which includes some satellite weighting
  673. using parameters <application>gpsd</application> cannot see.</para>
  674. <para>Autobauding on the Trimble GPSes can take as long as 5 seconds
  675. if the device speed is not matched to the GPS speed.</para>
  676. <para>Generation of position error estimates (eph, epv, epd, eps, epc)
  677. from the incomplete data handed back by GPS reporting protocols
  678. involves both a lot of mathematical black art and fragile
  679. device-dependent assumptions. This code has been bug-prone in tbe
  680. past and problems may still lurk there.</para>
  681. <para>AIDVM decoding of types 16-17, 22-23, and 25-26 is unverified.</para>
  682. <para>GPSD presently fully recognizes only the 2.1 level of RTCM2
  683. (message types 1, 3, 4, 5, 6, 7, 9, 16). The 2.3 message types 13, 14,
  684. and 31 are recognized and reported. Message types 8, 10-12, 15-27,
  685. 28-30 (undefined), 31-37, 38-58 (undefined), and 60-63 are not yet
  686. supported.</para>
  687. <para>The ISGPS used for RTCM2 and subframes decoder logic is
  688. sufficiently convoluted to confuse some compiler optimizers, notably
  689. in GCC 3.x at -O2, into generating bad code.</para>
  690. <para>Devices meant to use PPS for high-precision timekeeping may
  691. fail if they are specified after startup by a control-socket command,
  692. as opposed to on the daemon's original command line. Root privileges
  693. are dropped early, and some Unix variants require them in order to set
  694. the PPS line discipline. Under Linux the POSIX capability to set the
  695. line discipline is retained, but other platforms cannot use this
  696. code.</para>
  697. <para>USB GPS devices often do not identify themselves through the USB
  698. subsystem; they typically present as the class 00h (undefined) or
  699. class FFh (vendor-specific) of USB-to-serial adapters. Because of
  700. this, the Linux hotplug scripts must tell
  701. <application>gpsd</application> to sniff data from every USB-to-serial
  702. adapter that goes active and is known to be of a type used in
  703. GPSes. No such device is sent configuration strings until after it has
  704. been identified as a GPS, and <application>gpsd</application> never
  705. opens a device that is opened by another process. But there is a tiny
  706. window for non-GPS devices not opened; if the application that wants
  707. them loses a race with GPSD its device open will fail and have to be
  708. retried after GPSD sniffs the device (normally less than a second
  709. later).</para>
  710. </refsect1>
  711. <refsect1 id='files'><title>FILES</title>
  712. <variablelist>
  713. <varlistentry>
  714. <term><filename>/dev/ttyS0</filename></term>
  715. <listitem>
  716. <para>Prototype TTY device. After startup,
  717. <application>gpsd</application> sets its group ID to the owning group of this
  718. device if no GPS device was specified on the command line does not
  719. exist.</para>
  720. </listitem>
  721. </varlistentry>
  722. <varlistentry>
  723. <term><filename>/etc/gpsd/device-hook</filename></term>
  724. <listitem>
  725. <para>Optional file containing the device activation/deactivation script.
  726. Note that while <filename>/etc/gpsd</filename> is the default system
  727. configuration directory, it is possible to build the GPSD source code
  728. with different assumptions. See above for further details on the
  729. device-hook mechanism.</para>
  730. </listitem>
  731. </varlistentry>
  732. <!--
  733. <varlistentry>
  734. <term><filename>/usr/share/gpsd/dgpsip-servers</filename></term>
  735. <listitem>
  736. <para>A text file listing DGPSIP servers worldwide. If no DGPSIP
  737. server is specified at startup (via the -d option)
  738. <application>gpsd</application> will look here to find the
  739. nearest one. Each line has three space-separated fields:
  740. latitude (decimal degrees), longitude (decimal degrees) and
  741. a server name (optionally followed by a colon and a port number).
  742. Text following # on a line is ignored. Blank lines are ignored.</para>
  743. </listitem>
  744. </varlistentry>
  745. -->
  746. </variablelist>
  747. </refsect1>
  748. <refsect1 id='environment'><title>ENVIRONMENT VARIABLES</title>
  749. <para>By setting the environment variable <envar>GPSD_SHM_KEY</envar>,
  750. you can control the key value used to create the shared-memory segment
  751. used for communication with the client library. This will be useful
  752. mainly when isolating test instances of
  753. <application>gpsd</application> from production ones.</para>
  754. </refsect1>
  755. <refsect1 id='standards'><title>APPLICABLE STANDARDS</title>
  756. <para>The official NMEA protocol standards for NMEA0183 and NMEA2000
  757. are available from the National Marine Electronics Association, but are
  758. proprietary and expensive; the maintainers of
  759. <application>gpsd</application> have made a point of not looking at
  760. them. The GPSD project website links to several documents that collect
  761. publicly disclosed information about the protocol.</para>
  762. <para><application>gpsd</application> parses the following NMEA
  763. sentences: RMC, GGA, GLL, GSA, GSV, VTG, ZDA, GBS, HDT, DBT, GST. It
  764. recognizes these with either the normal GP talker-ID prefix, or with
  765. the GN prefix used by GLONASS, or with the II prefix emitted by
  766. Seahawk Autohelm marine navigation systems, or with the IN prefix
  767. emitted by some Garmin units, or with the EC prefix emitted by ECDIS
  768. units, or with the SD prefix emitted by depth sounders, or with the HC
  769. and TI prefix emitted by some Airmar equipment. It recognizes some
  770. vendor extensions: the PGRME emitted by some Garmin GPS models, the
  771. OHPR emitted by Oceanserver digital compasses, the PTNTHTM emitted by
  772. True North digital compasses, the PMTK omitted by some San Jose
  773. Navigation GPSes, and the PASHR sentences emitted by some Ashtech
  774. GPSes.</para>
  775. <para>Note that <application>gpsd</application> JSON returns pure decimal
  776. degrees, not the hybrid degree/minute format described in the NMEA
  777. standard.</para>
  778. <para>Differential-GPS corrections are conveyed by the RTCM
  779. protocols. The applicable standard for RTCM-104 V2 is <citetitle>RTCM
  780. Recommended Standards for Differential GNSS (Global Navigation
  781. Satellite) Service</citetitle> RTCM Paper 136-2001/SC 104-STD. The
  782. applicable standard for RTCM-104 V3 is <citetitle>RTCM Standard
  783. 10403.1 for Differential GNSS Services - Version 3</citetitle> RTCM
  784. Paper 177-2006-SC104-STD. Ordering instructions for the RTCM standards
  785. are accessible from the website of the Radio Technical Commission for Maritime
  786. Services under "Publications".</para>
  787. <para>AIS is defined by ITU Recommendation M.1371,
  788. <citetitle>Technical Characteristics for a Universal Shipborne
  789. Automatic Identification System Using Time Division Multiple
  790. Access</citetitle>. The AIVDM/AIVDO format understood by this program
  791. is defined by IEC-PAS 61162-100, <citetitle>Maritime navigation and
  792. radiocommunication equipment and systems</citetitle>. A more accessible
  793. description of both can be found at <citetitle>AIVDM/AIVDO Protocol
  794. Decoding</citetitle>, on the references page of the GPSD project
  795. website.</para>
  796. <para>Subframe data is defined by IS-GPS-200E, <citetitle>GLOBAL
  797. POSITIONING SYSTEM WING (GPSW) SYSTEMS ENGINEERING &amp; INTEGRATION,
  798. INTERFACE SPECIFICATION IS-GPS-200 Revision E</citetitle>. The format
  799. understood by this program is defined in Section 20 (Appendix II) of
  800. the IS-GPS-200E, <citetitle>GPS NAVIGATION DATA STRUCTURE FOR DATA,
  801. D(t)</citetitle></para>
  802. <para>JSON is specified by RFC 7159, <citetitle>The JavaScript Object
  803. Notation (JSON) Data Interchange Format</citetitle>.</para>
  804. <para>The API for PPS time service is specified by RFC 2783,
  805. <citetitle>Pulse-Per-Second API for UNIX-like Operating Systems,
  806. Version 1.0</citetitle></para>
  807. </refsect1>
  808. <refsect1 id='see_also'><title>SEE ALSO</title>
  809. <para>
  810. <citerefentry><refentrytitle>gpsdctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
  811. <citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  812. <citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  813. <citerefentry><refentrytitle>gpsd_json</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  814. <citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  815. <citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  816. <citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  817. <citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  818. <citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  819. </para>
  820. </refsect1>
  821. <refsect1 id='maintainer'><title>AUTHORS</title>
  822. <para>Authors: Eric S. Raymond, Chris Kuethe, Gary Miller. Former
  823. authors whose bits have been plowed under by code turnover: Remco
  824. Treffcorn, Derrick Brashear, Russ Nelson. This manual page by Eric S. Raymond
  825. <email>esr@thyrsus.com</email>.</para>
  826. </refsect1>
  827. </refentry>