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.
 
 
 
 
 
 

338 lines
13 KiB

  1. <?xml version="1.0" encoding="ISO-8859-1"?>
  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. <refentry id='gps.1'>
  10. <refentryinfo><date>9 Aug 2004</date></refentryinfo>
  11. <refmeta>
  12. <refentrytitle>gps</refentrytitle>
  13. <manvolnum>1</manvolnum>
  14. <refmiscinfo class="source">The GPSD Project</refmiscinfo>
  15. <refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
  16. </refmeta>
  17. <refnamediv id='name'>
  18. <refname>cgps</refname>
  19. <refname>gegps</refname>
  20. <refname>gps</refname>
  21. <refname>lcdgps</refname>
  22. <refname>xgps</refname>
  23. <refname>xgpsspeed</refname>
  24. <refpurpose>test clients for gpsd</refpurpose>
  25. </refnamediv>
  26. <refsynopsisdiv id='synopsis'>
  27. <cmdsynopsis>
  28. <command>cgps</command>
  29. <arg choice='opt'>-D <replaceable>debug-level</replaceable></arg>
  30. <arg choice='opt'>-h </arg>
  31. <arg choice='opt'>-l <group><arg>d</arg><arg>m</arg><arg>s</arg></group></arg>
  32. <arg choice='opt'>-m </arg>
  33. <arg choice='opt'>-s </arg>
  34. <arg choice='opt'>-u <group><arg>i</arg><arg>n</arg><arg>m</arg></group></arg>
  35. <arg choice='opt'>-V </arg>
  36. <group>
  37. <replaceable>server</replaceable>
  38. <group>
  39. <replaceable>:port</replaceable>
  40. <group><replaceable>:device</replaceable></group>
  41. </group>
  42. </group>
  43. </cmdsynopsis>
  44. <cmdsynopsis>
  45. <command>gegps</command>
  46. <arg choice='opt'>-d <replaceable>directory</replaceable></arg>
  47. <arg choice='opt'>-h </arg>
  48. <arg choice='opt'>-i </arg>
  49. <arg choice='opt'>-V </arg>
  50. </cmdsynopsis>
  51. <cmdsynopsis>
  52. <command>lcdgps</command>
  53. <arg choice='opt'>-h </arg>
  54. <arg choice='opt'>-j </arg>
  55. <arg choice='opt'>-l <group><arg>d</arg><arg>m</arg><arg>s</arg></group></arg>
  56. <arg choice='opt'>-s </arg>
  57. <arg choice='opt'>-u <group><arg>i</arg><arg>n</arg><arg>m</arg></group></arg>
  58. <arg choice='opt'>-V </arg>
  59. <group>
  60. <replaceable>server</replaceable>
  61. <group>
  62. <replaceable>:port</replaceable>
  63. <group><replaceable>:device</replaceable></group>
  64. </group>
  65. </group>
  66. </cmdsynopsis>
  67. <cmdsynopsis>
  68. <command>xgps</command>
  69. <arg choice='opt'>-? </arg>
  70. <arg choice='opt'>-D <replaceable>debug-level</replaceable></arg>
  71. <arg choice='opt'>-h </arg>
  72. <arg choice='opt'>-l <group><arg>d</arg><arg>m</arg><arg>s</arg></group></arg>
  73. <arg choice='opt'>-u <group><arg>i</arg><arg>n</arg><arg>m</arg></group></arg>
  74. <arg choice='opt'>-r <replaceable>degrees</replaceable></arg>
  75. <arg choice='opt'>-V </arg>
  76. <group>
  77. <replaceable>server</replaceable>
  78. <group>
  79. <replaceable>:port</replaceable>
  80. <group><replaceable>:device</replaceable></group>
  81. </group>
  82. </group>
  83. </cmdsynopsis>
  84. <cmdsynopsis>
  85. <command>xgpsspeed</command>
  86. <arg choice='opt'>--debug <replaceable>debug-level</replaceable></arg>
  87. <arg choice='opt'>--device <replaceable>device</replaceable></arg>
  88. <arg choice='opt'>-h </arg>
  89. <arg choice='opt'>--host <replaceable>host</replaceable></arg>
  90. <arg choice='opt'>--landspeed </arg>
  91. <arg choice='opt'>--maxspeed <replaceable>maxspeed</replaceable></arg>
  92. <arg choice='opt'>--nautical </arg>
  93. <arg choice='opt'>--port <replaceable>port</replaceable></arg>
  94. <arg choice='opt'>--speedunits
  95. <group choice='req'>
  96. <arg>mph</arg><arg>kph</arg><arg>knots</arg>
  97. </group>
  98. </arg>
  99. <arg choice='opt'>-V </arg>
  100. <group>
  101. <replaceable>server</replaceable>
  102. <group>
  103. <replaceable>:port</replaceable>
  104. <group><replaceable>:device</replaceable></group>
  105. </group>
  106. </group>
  107. </cmdsynopsis>
  108. </refsynopsisdiv>
  109. <refsect1 id='description'><title>DESCRIPTION</title>
  110. <para>These are the demonstration clients shipped with
  111. <application>gpsd</application>. They have some common options:</para>
  112. <para>The <option>-h</option> option causes each client to emit a summary of its
  113. options and then exit.</para>
  114. <para>The <option>-V</option> option causes each client to dump the package
  115. version and exit.</para>
  116. <para> The <option>-l</option> option, when present, sets the format
  117. of latitude and longitude reports. The value 'd' produces decimal
  118. degrees and is the default. The value 'm' produces degrees and
  119. decimal minutes. The value 's' produces degrees, minutes, and decimal
  120. seconds.</para>
  121. <para><application>xgps</application>,
  122. <application>cgps</application>, and <application>lcdgps</application>
  123. look at variables in the environment to figure out what units they
  124. should default to using for display &mdash; imperial, nautical, or
  125. metric. Here are the variables and values they check:</para>
  126. <screen>
  127. GPSD_UNITS one of:
  128. imperial = miles/feet
  129. nautical = knots/feet
  130. metric = km/meters
  131. LC_MEASUREMENT
  132. en_US = miles/feet
  133. C = miles/feet
  134. POSIX = miles/feet
  135. [other] = km/meters
  136. LANG
  137. en_US = miles/feet
  138. C = miles/feet
  139. POSIX = miles/feet
  140. [other] = km/meters
  141. </screen>
  142. <para>These preferences may be overridden by the <option>-u</option>
  143. option.</para>
  144. <para>Where present, the <option>-u</option> option can be used to set
  145. the system units for display; follow the keyword with 'i' for
  146. 'imperial' for American units (International Feet in altitude and error
  147. estimates, miles per hour in speeds), 'n' for 'nautical' (feet in altitude
  148. and error estimates, knots in speed) or 'm' for 'metric' (meters in
  149. altitude and error estimates, kilometers per hour in speeds).</para>
  150. <para>Note: The USA Survey Foot is not supported.</para>
  151. <para> The <option>-D</option> option, when present, sets a debug
  152. level; it is primarily for use by GPSD developers. It enables
  153. various progress messages to standard error.</para>
  154. <para>By default, clients collect data from all compatible devices on
  155. localhost, using the default GPSD port 2947. An optional argument to any
  156. client may specify a server to get data from. A colon-separated suffix
  157. is taken as a port number. If there is a second colon-separated
  158. suffix, that is taken as a specific device name to be
  159. watched. However, if the server specification contains square
  160. brackets, the part inside them is taken as an IPv6 address and
  161. port/device suffixes are only parsed after the trailing bracket.
  162. Possible cases look like this:</para>
  163. <para>The options for xgps can be placed in the XGPSOPTS environment variable.
  164. XGPSOPTS is processed before the CLI options.</para>
  165. <variablelist>
  166. <varlistentry>
  167. <term>localhost:/dev/ttyS1</term>
  168. <listitem><para>Look at the default port of localhost, trying both
  169. IPv4 and IPv6 and watching output from serial device 1.</para></listitem>
  170. </varlistentry>
  171. <varlistentry>
  172. <term>example.com:2317</term>
  173. <listitem><para>Look at port 2317 on example.com, trying both
  174. IPv4 and IPv6.</para></listitem>
  175. </varlistentry>
  176. <varlistentry>
  177. <term>71.162.241.5:2317:/dev/ttyS3</term>
  178. <listitem><para>Look at port 2317 at the specified IPv4
  179. address, collecting data from attached serial device 3.</para></listitem>
  180. </varlistentry>
  181. <varlistentry>
  182. <term>[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5</term>
  183. <listitem><para>Look at port 2317 at the specified IPv6
  184. address, collecting data from attached serial device 5.</para></listitem>
  185. </varlistentry>
  186. </variablelist>
  187. <para>Not all clients shipped with GPSD are documented here. See also
  188. the separate manual pages for
  189. <citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  190. and
  191. <citerefentry><refentrytitle>gpsmon</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  192. and
  193. <citerefentry><refentrytitle>gpxlogger</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  194. .</para>
  195. <refsect2><title>xgps</title>
  196. <para><application>xgps</application> is a simple test client for
  197. <application>gpsd</application> with an X interface. It displays
  198. current GPS position/time/velocity information and (for GPSes that
  199. support the feature) the locations of accessible satellites.</para>
  200. <para>In the sky view, satellites are color-coded to indicate quality
  201. of signal; consult the data display to the left for exact figures in
  202. dB. Square icons indicate SBAS/WAAS/EGNOS satellites, circles indicate
  203. ordinary GPS satellites. Filled icons were used in the current fix,
  204. outline icons were not.</para>
  205. <para>The -r option accepts an argument in degrees, to rotate the
  206. skyview counterclockwise.</para>
  207. </refsect2>
  208. <refsect2><title>xgpsspeed</title>
  209. <para><application>xgpsspeed</application> is a speedometer that uses
  210. position information from the GPS. It accepts an -h option and
  211. optional argument as for <application>gps</application>, or a -V
  212. option to dump the package version and exit.</para>
  213. <para>The default display mode is a speed and track presentation
  214. modeled after a marine navigation display; for backward compatibility
  215. the --nautical option forces this mode. The --landspeed option produces
  216. a simple speedometer.</para>
  217. <para>The -speedunits option can be used to set the speed units for
  218. display; follow the keyword with knots for nautical miles per hour,
  219. kph for kilometres per hour, or mph for miles per hour. The default
  220. is miles per hour. </para>
  221. <para>In the nautical mode only, --maxspeed sets the maximum on the
  222. speedometer.</para>
  223. </refsect2>
  224. <refsect2><title>cgps</title>
  225. <para><application>cgps</application> is a client resembling
  226. <application>xgps</application>, but without the pictorial
  227. satellite display and able to run on a serial terminal or
  228. terminal emulator.</para>
  229. <para> The <option>-s</option> option prevents
  230. <application>cgps</application> from displaying the data coming from
  231. the daemon. This display can also be toggled with the s
  232. command.</para>
  233. <para>The <option>-m</option> option will display your magnetic
  234. track (as opposed to your true track). This is a calculated
  235. value, not a measured value. Magnetic variation is always potentially
  236. subject to large errors, but is usually better than two degrees.</para>
  237. <para><application>cgps</application> terminates when you send it a
  238. SIGHUP or SIGINT; given default terminal settings this will happen
  239. when you type Ctrl-C at it. It will also terminate on 'q'</para>
  240. </refsect2>
  241. <refsect2><title>lcdgps</title>
  242. <para>A client that passes <application>gpsd</application> data to
  243. <application>lcdproc</application>, turning your car computer into a
  244. very expensive and nearly feature-free GPS receiver. Currently
  245. assumes a 4x40 LCD and writes data formatted to fit that size screen.
  246. Also displays 4- or 6-character Maidenhead grid square output.</para>
  247. </refsect2>
  248. <refsect2><title>gegps</title>
  249. <para>This program collects fixes from <application>gpsd</application>
  250. and feeds them to a running instance of Google Earth for live location
  251. tracking.</para>
  252. <para>The <option>-d</option> argument is the location of the Google
  253. Earth installation directory. If not specified, it defaults to the
  254. current directory.</para>
  255. <para>If you have the free (non-subscription) version, start by
  256. running with the <option>-i</option> option to drop a clue in the
  257. Google Earth installation directory, as
  258. 'Open_in_Google_Earth_RT_GPS.kml', then open that file in Places (File
  259. > Open...). Run <application>gegps</application> in the normal way
  260. after that.</para>
  261. </refsect2>
  262. </refsect1>
  263. <refsect1 id='environment'><title>ENVIRONMENT</title>
  264. <para>The <option>XGPSOPTS></option> environment variable may be set to
  265. pass commonly used command line options to <command>xgps</command>
  266. and <command>xgpsspeed</command>. This is often used to set the
  267. <option>-u</option> option for locale specific units.
  268. <option>XGPSOPTS</option> is processed before the CLI options.</para>
  269. </refsect1>
  270. <refsect1 id='see_also'><title>SEE ALSO</title>
  271. <para>
  272. <citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
  273. <citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  274. <citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  275. <citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  276. <citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  277. <citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  278. <citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
  279. <citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
  280. <citerefentry><refentrytitle>gpsmon</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
  281. <citerefentry><refentrytitle>gpxlogger</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
  282. </para>
  283. </refsect1>
  284. <refsect1 id='maintainer'><title>AUTHORS</title>
  285. <para>
  286. Remco Treffcorn, Derrick Brashear, Russ Nelson &amp; Eric S. Raymond,
  287. Jeff Francis (cgps), Chen Wei <email>weichen302@aol.com</email> (gegps &amp; xgpsspeed),
  288. Robin Wittler <email>real@the-real.org</email> (xgpsspeed).
  289. </para>
  290. <para>This manual page by Eric S. Raymond <email>esr@thyrsus.com</email></para>
  291. </refsect1>
  292. </refentry>