1 <?xml version="1.0" encoding="ISO-8859-1"?>
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.
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">
10 <refentryinfo><date>9 Aug 2004</date></refentryinfo>
12 <refentrytitle>gps</refentrytitle>
13 <manvolnum>1</manvolnum>
14 <refmiscinfo class="source">The GPSD Project</refmiscinfo>
15 <refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
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>
25 <refsynopsisdiv id='synopsis'>
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>
35 <replaceable>server</replaceable>
37 <replaceable>:port</replaceable>
38 <group><replaceable>:device</replaceable></group>
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
49 <arg>mph</arg><arg>kph</arg><arg>knots</arg>
53 <replaceable>server</replaceable>
55 <replaceable>:port</replaceable>
56 <group><replaceable>:device</replaceable></group>
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>
70 <replaceable>server</replaceable>
72 <replaceable>:port</replaceable>
73 <group><replaceable>:device</replaceable></group>
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>
84 <replaceable>server</replaceable>
86 <replaceable>:port</replaceable>
87 <group><replaceable>:device</replaceable></group>
92 <command>gpxlogger</command>
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>
101 <replaceable>server</replaceable>
103 <replaceable>:port</replaceable>
104 <group><replaceable>:device</replaceable></group>
110 <refsect1 id='description'><title>DESCRIPTION</title>
112 <para>These are the demonstration clients shipped with
113 <application>gpsd</application>. They have some common options:</para>
115 <para>The <option>-h</option> option causes each client to emit a summary of its
116 options and then exit.</para>
118 <para>The <option>-V</option> option causes each client to dump the package
119 version and exit.</para>
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
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 — imperial, nautical, or
131 metric. Here are the variables and values they check:</para>
135 imperial = miles/feet
136 nautical = knots/feet
149 <para>These preferences may be overridden by the <option>-u</option>
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>
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>
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>
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>
180 <term>example.com:2317</term>
181 <listitem><para>Look at port 2317 on example.com, trying both
182 IPv4 and IPv6.</para></listitem>
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>
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>
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>
200 <citerefentry><refentrytitle>gpsmon</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
202 <refsect2><title>xgps</title>
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>
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>
216 <refsect2><title>xgpsspeed</title>
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>
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>
229 <refsect2><title>cgps</title>
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>
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
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>
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>
252 <refsect2><title>lcdgps</title>
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>
261 <refsect2><title>gpxlogger</title>
263 <para>This program collects fixes from <application>gpsd</application>
264 and logs them to standard output in GPX, an XML profile for track
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>
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>
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>
282 <refsect1 id='see_also'><title>SEE ALSO</title>
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>.
296 <refsect1 id='maintainer'><title>AUTHORS</title>
299 Remco Treffcorn, Derrick Brashear, Russ Nelson & Eric S. Raymond,
300 Jeff Francis (cgps). Amaury Jacquot <email>sxpert@sxpert.org</email>
301 & Petter Reinholdtsen <email>pere@hungry.com</email> (gpxlogger).
302 Chris Kuethe <email>chris.kuethe@gmail.com</email> (cgpxlogger).
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>