gps.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!--
   3 This file is Copyright (c) 2010 by the GPSD project
   4 BSD terms apply: see the file COPYING in the distribution root for details.
   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>gps</refname>
  19 <refname>xgps</refname>
  20 <refname>xgpsspeed</refname>
  21 <refname>cgps</refname>
  22 <refname>lcdgps</refname>
  23 <refpurpose>test clients for gpsd</refpurpose>
  24 </refnamediv>
  25 <refsynopsisdiv id='synopsis'>
  26
  27 <cmdsynopsis>
  28   <command>xgps</command>
  29       <arg choice='opt'>-D <replaceable>debug-level</replaceable></arg>
  30       <arg choice='opt'>-h </arg>
  31       <arg choice='opt'>-V </arg>
  32       <arg choice='opt'>-l <group><arg>d</arg><arg>m</arg><arg>s</arg></group></arg>
  33       <arg choice='opt'>-u <group><arg>i</arg><arg>n</arg><arg>m</arg></group></arg>
  34       <group>
  35         <replaceable>server</replaceable>
  36           <group>
  37             <replaceable>:port</replaceable>
  38               <group><replaceable>:device</replaceable></group>
  39           </group>
  40       </group>
  41 </cmdsynopsis>
  42 <cmdsynopsis>
  43   <command>xgpsspeed</command>
  44       <arg choice='opt'>-D <replaceable>debug-level</replaceable></arg>
  45       <arg choice='opt'>-h </arg>
  46       <arg choice='opt'>-V </arg>
  47       <arg choice='opt'>--speedunits
  48               <group choice='req'>
  49                       <arg>mph</arg><arg>kph</arg><arg>knots</arg>
  50               </group>
  51       </arg>
  52       <group>
  53         <replaceable>server</replaceable>
  54           <group>
  55             <replaceable>:port</replaceable>
  56               <group><replaceable>:device</replaceable></group>
  57           </group>
  58       </group>
  59 </cmdsynopsis>
  60 <cmdsynopsis>
  61   <command>cgps</command>
  62       <arg choice='opt'>-D <replaceable>debug-level</replaceable></arg>
  63       <arg choice='opt'>-h </arg>
  64       <arg choice='opt'>-V </arg>
  65       <arg choice='opt'>-l <group><arg>d</arg><arg>m</arg><arg>s</arg></group></arg>
  66       <arg choice='opt'>-m </arg>
  67       <arg choice='opt'>-s </arg>
  68       <arg choice='opt'>-u <group><arg>i</arg><arg>n</arg><arg>m</arg></group></arg>
  69       <group>
  70         <replaceable>server</replaceable>
  71           <group>
  72             <replaceable>:port</replaceable>
  73               <group><replaceable>:device</replaceable></group>
  74           </group>
  75       </group>
  76 </cmdsynopsis>
  77 <cmdsynopsis>
  78   <command>lcdgps</command>
  79       <arg choice='opt'>-h </arg>
  80       <arg choice='opt'>-V </arg>
  81       <arg choice='opt'>-l <group><arg>d</arg><arg>m</arg><arg>s</arg></group></arg>
  82       <arg choice='opt'>-u <group><arg>i</arg><arg>n</arg><arg>m</arg></group></arg>
  83       <group>
  84         <replaceable>server</replaceable>
  85           <group>
  86             <replaceable>:port</replaceable>
  87               <group><replaceable>:device</replaceable></group>
  88           </group>
  89       </group>
  90 </cmdsynopsis>
  91 <cmdsynopsis>
  92   <command>gpxlogger</command>
  93 </cmdsynopsis>
  94 <cmdsynopsis>
  95   <command>gpxlogger</command>
  96       <arg choice='opt'>-D <replaceable>debug-level</replaceable></arg>
  97       <arg choice='opt'>-h </arg>
  98       <arg choice='opt'>-V </arg>
  99       <arg choice='opt'>-i <replaceable>track timeout</replaceable></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
 110 <refsect1 id='description'><title>DESCRIPTION</title>
 111
 112 <para>These are the demonstration clients shipped with
 113 <application>gpsd</application>. They have some common options:</para>
 114
 115 <para>The <option>-h</option> option causes each client to emit a summary of its
 116 options and then exit.</para>
 117
 118 <para>The <option>-V</option> option causes each client to dump the package
 119 version and exit.</para>
 120
 121 <para> The <option>-l</option> option, when present, sets the format
 122 of latitude and longitude reports.  The value 'd' produces decimal
 123 degrees and is the default.  The value 'm' produces degrees and
 124 decimal minutes.  The value 's' produces degrees, minutes, and decimal
 125 seconds.</para>
 126
 127 <para><application>xgps</application>,
 128 <application>cgps</application>, and <application>ldcgps</application>
 129 look at variables in the environment to figure out what units they
 130 should default to using for display &mdash; imperial, nautical, or
 131 metric.  Here are the variables and values they check:</para>
 132
 133 <screen>
 134     GPSD_UNITS one of:
 135               imperial   = miles/feet
 136               nautical   = knots/feet
 137               metric     = km/meters
 138     LC_MEASUREMENT
 139               en_US      = miles/feet
 140               C          = miles/feet
 141               POSIX      = miles/feet
 142               [other]    = km/meters
 143     LANG
 144               en_US      = miles/feet
 145               C          = miles/feet
 146               POSIX      = miles/feet
 147               [other]    = km/meters
 148 </screen>
 149 <para>These preferences may be overridden by the <option>-u</option>
 150 option.</para>
 151
 152 <para>Where present, the <option>-u</option> option can be used to set
 153 the system units for display; follow the keyword with 'i' for
 154 'imperial' for American units (feet in altitude and error estimates,
 155 miles per hour in speeds), 'n' for 'nautical' (feet in altitude and
 156 error estimates, knots in speed) or 'm' for 'metric' (meters in
 157 altitude and error estimates, kiliometers per hour in speeds). </para>
 158
 159 <para> The <option>-D</option> option, when present, sets a debug
 160 level; it is primarily for use by GPSD developers.  It enables
 161 various progress messages to standard error.</para>
 162
 163 <para>By default, clients collect data from all compatible devices on
 164 localhost, using the defalt GPSD port 2947. An optional argument to any
 165 client may specify a server to get data from. A colon-separated suffix
 166 is taken as a port number. If there is a second colon-separated
 167 suffix, that is taken as a specific device name to be
 168 watched. However, if the server specification contains square
 169 brackets, the part inside them is taken as an IPv6 address and
 170 port/device suffixes are obnly parsed after the trailing bracket.
 171 Possible cases look like this:</para>
 172
 173 <variablelist>
 174 <varlistentry>
 175 <term>localhost:/dev/ttyS1</term>
 176 <listitem><para>Look at the default port of localhost, trying both
 177 IPv4 and IPv6 and watching ouput from serial device 1.</para></listitem>
 178 </varlistentry>
 179 <varlistentry>
 180 <term>example.com:2317</term>
 181 <listitem><para>Look at port 2317 on example.com, trying both
 182 IPv4 and IPv6.</para></listitem>
 183 </varlistentry>
 184 <varlistentry>
 185 <term>71.162.241.5:2317:/dev/ttyS3</term>
 186 <listitem><para>Look at port 2317 at the specified IPv4
 187 address, collecting data from attached serial device 3.</para></listitem>
 188 </varlistentry>
 189 <varlistentry>
 190 <term>[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5</term>
 191 <listitem><para>Look at port 2317 at the specified IPv6
 192 address, collecting data from attached serial device 5.</para></listitem>
 193 </varlistentry>
 194 </variablelist>
 195
 196 <para>Not all clients shipped with GPSD are documented here. See also
 197 the separate manual pages for
 198 <citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 199 and
 200 <citerefentry><refentrytitle>gpsmon</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
 201
 202 <refsect2><title>xgps</title>
 203
 204 <para><application>xgps</application> is a simple test client for
 205 <application>gpsd</application> with an X interface. It displays
 206 current GPS position/time/velocity information and (for GPSes that
 207 support the feature) the locations of accessible satellites.</para>
 208
 209 <para>In the sky view, satellites are color-coded to indicate quality
 210 of signal; consult the data display to the left for exact figures in
 211 dB. Square icons indicate WAAS/EGNOS satellites, circles indicate
 212 ordinary GPS satellites.  Filled icons were used in the last fix,
 213 outline icons were not.</para>
 214
 215 </refsect2>
 216 <refsect2><title>xgpsspeed</title>
 217
 218 <para><application>xgpsspeed</application> is a speedometer that uses
 219 position information from the GPS. It accepts an -h option and
 220 optional argument as for <application>gps</application>, or a -V
 221 option to dump the package version and exit.</para>
 222
 223 <para>The -speedunits option can be used to set the speed units for
 224 display; follow the keyword with knots for nautical miles per hour,
 225 kph for kilometres per hour, or mph for miles per hour.  The default
 226 is miles per hour. </para>
 227
 228 </refsect2>
 229 <refsect2><title>cgps</title>
 230
 231 <para><application>cgps</application> is a client resembling
 232 <application>xgps</application>, but without the pictorial
 233 satellite display and able to run on a serial terminal or
 234 terminal emulator.</para>
 235
 236 <para> The <option>-s</option> option prevents <application>cgps</application>
 237 from displaying the raw data. This display can also be toggled with the s
 238 command.</para>
 239
 240 <para>The <option>-m</option> option will display your magnetic
 241 heading (as opposed to your true heading).  This is a calculated
 242 value, not a measured value, and is subject to a potential error of up
 243 to two degrees in the areas for which the calculation is valid
 244 (currently Western Europe, Alaska, and Lower 48 in the USA).  The
 245 formulas used are those found in the Aviation Formulary v1.43.</para>
 246
 247 <para><application>cgps</application> terminates when you send it a
 248 SIGHUP or SIGINT; given default terminal settings this will happen
 249 when you type Ctl-C at it.  It will also terminate on 'q'</para>
 250
 251 </refsect2>
 252 <refsect2><title>lcdgps</title>
 253
 254 <para>A client that passes <application>gpsd</application> data to
 255 <application>lcdproc</application>, turning your car computer into a
 256 very expensive and nearly feature-free GPS receiver.  Currently
 257 assumes a 4x40 LCD and writes data formatted to fit that size screen.
 258 Also displays 4- or 6-character Maidenhead grid square output.</para>
 259
 260 </refsect2>
 261 <refsect2><title>gpxlogger</title>
 262
 263 <para>This program collects fixes from <application>gpsd</application>
 264 and logs them to standard output in GPX, an XML profile for track
 265 logging.</para>
 266
 267 <para>The output may be composed of multiple tracks. A new track is
 268 created if there's no fix for an interval specified by the
 269 <option>-i</option> and defaulting to 5 seconds.</para>
 270
 271 <para>If D-Bus support is available on the host and GPSD is
 272 configured  to use it, this program listens to DBUS broadcasts
 273 from <application>gpsd</application>. (org.gpsd.fix).  Otherwise,
 274 it uses a conventional socket connection. </para>
 275
 276 <para>Presence of a server-port-device specification forces use of
 277 sockets even on a D-Bus capable system, though this is unlikely to be
 278 of interest to anyone except GPSD developers.</para>
 279
 280 </refsect2>
 281 </refsect1>
 282 <refsect1 id='see_also'><title>SEE ALSO</title>
 283 <para>
 284 <citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 285 <citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 286 <citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 287 <citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 288 <citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 289 <citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 290 <citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 291 <citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 292 <citerefentry><refentrytitle>gpsmon</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 293 </para>
 294 </refsect1>
 295
 296 <refsect1 id='maintainer'><title>AUTHORS</title>
 297
 298 <para>
 299 Remco Treffcorn, Derrick Brashear, Russ Nelson &amp; Eric S. Raymond,
 300 Jeff Francis (cgps). Amaury Jacquot <email>sxpert@sxpert.org</email>
 301 &amp; Petter Reinholdtsen <email>pere@hungry.com</email> (gpxlogger).
 302 Chris Kuethe <email>chris.kuethe@gmail.com</email> (cgpxlogger).
 303 </para>
 304
 305 <para>This manual page by Eric S. Raymond <email>esr@thyrsus.com</email>.
 306 There is a project page, with <application>xgps</application>
 307 screenshots, at <ulink url="http://gpsd.berlios.de/">berlios.de</ulink>.</para>
 308
 309 </refsect1>
 310
 311 </refentry>
 312