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