gpsmon.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='gpsmon.1'>
  10 <refentryinfo><date>17 Feb 2009</date></refentryinfo>
  11 <refmeta>
  12 <refentrytitle>gpsmon</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>gpsmon</refname>
  19 <refpurpose>real-time GPS packet monitor and control utility</refpurpose>
  20 </refnamediv>
  21 <refsynopsisdiv id='synopsis'>
  22
  23 <cmdsynopsis>
  24   <command>gpsmon</command>
  25       <arg choice='opt'>-h </arg>
  26       <arg choice='opt'>-L </arg>
  27       <arg choice='opt'>-V </arg>
  28       <arg>-l <replaceable>logfile</replaceable></arg>
  29       <arg>-F <replaceable>control-socket</replaceable></arg>
  30       <arg choice='opt'>
  31         <group>
  32           <arg choice='plain'>
  33             <replaceable>server</replaceable>
  34             <group>
  35               <replaceable>:port</replaceable>
  36               <group><replaceable>:device</replaceable></group>
  37             </group>
  38           </arg>
  39           <arg choice='plain'><replaceable>device</replaceable></arg>
  40         </group>
  41       </arg>
  42       <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg>
  43 </cmdsynopsis>
  44 </refsynopsisdiv>
  45
  46 <refsect1 id='description'><title>DESCRIPTION</title>
  47
  48 <para><application>gpsmon</application> is a monitor that watches
  49 packets coming from a GPS and displays them along with diagnostic
  50 information. It supports commands that can be used to tweak GPS
  51 settings in various ways; some are device-independent, some vary
  52 with the GPS chipset type.</para>
  53
  54 <para>This tool used to be called 'sirfmon', and worked only on SiRF
  55 devices (and the command set has changed to resemble the command
  56 switches of <application>gpsctl</application>). It now has support for a range
  57 of NMEA devices as well; support for other (binary-protocol) device
  58 types is planned. It will behave sanely, just dumping packets, when
  59 connected to a GPS type it knows nothing about.</para>
  60
  61 <para><application>gpsmon</application> differs from a navigation
  62 client in that it mostly dumps raw data from the GPS, with only enough
  63 data-massaging to allow checks against expected output.  In
  64 particular, this tool does not do any interpolation or modeling
  65 to derive climb/sink or error estimates. Nor does it discard
  66 altitude reports when the fix quality is too low.</para>
  67
  68 <para><application>gpsmon</application> is a designed to run in a
  69 terminal emulator with a minimum 25x80 size; the non-GUI interface is
  70 a design choice made to accommodate users operating in constrained
  71 environments and over telnet or ssh connections.  If run in a larger
  72 window, the size of the packet-log window will be increased to
  73 fit.</para>
  74
  75 <para><application>gpsmon</application> accepts an -h option that
  76 displays a usage message, or a -V option to dump the package
  77 version and exit.</para>
  78
  79 <para>This program may be run in either of two modes, as a client for
  80 the <application>gpsd</application> daemon (and its associated control
  81 socket) or directly connected to a specified serial device.  When run
  82 with no argument, it attempts to connect to the daemon.  If the
  83 argument looks like a server:port specification it will also attempt
  84 to connect to the daemon.  If the argument looks like a bare server
  85 name it will attempt to connect to a daemon running on the default
  86 gpsd port on that server.  Only if the device argument contains
  87 slashes but no colons will it be treated as a serial device for direct
  88 connection. In direct-connect mode <application>gpsmon</application>
  89 will hunt for a correct baud rate and lock on to it
  90 automatically.</para>
  91
  92 <para>The -F option is only valid in client mode; it specifies a
  93 control socket to which the program should send device control
  94 strings.  You must specify a valid pathname of a Unix-domain socket on
  95 your local filesystem.</para>
  96
  97 <para>The -D option enables packet-getter debugging output and is
  98 probably only useful to developers of the GPSD code.  Consult the
  99 packet-getter source code for relevant values.</para>
 100
 101 <para>The -L option lists a table showing which GPS device types
 102 <application>gpsmon</application> has built-in support for, and which
 103 generic commands can be applied to which GPS types, and then
 104 exits. Note that this does not list type-specific commands associated
 105 with individual GPS types.</para>
 106
 107 <para>The -l option sets up logging to a specified file to start
 108 immediately on device open.  This may be useful is, for example,
 109 you want to capture the startup message from a device that displays
 110 firmware version information there.</para>
 111
 112 <para>After startup, the top part of the screen reports the contents
 113 of several especially interesting packet types.  The bottom half of
 114 the screen is a scrolling hex dump of all packets the GPS is issuing.
 115 Dump lines beginning &gt;&gt;&gt; represent control packets sent to the
 116 GPS.</para>
 117
 118 </refsect1>
 119 <refsect1 id='commands'><title>COMMANDS</title>
 120
 121 <para>The following device-independent comands are available while
 122 <application>gpsmon</application> is running:</para>
 123
 124 <variablelist>
 125
 126 <varlistentry>
 127 <term>i</term>
 128 <listitem>
 129 <para>Enable/disable subtype probing and reinitialize the driver. In
 130 normal operation, <application>gpsmon</application> does not send
 131 configuration strings to the device (except for wakeup strings needed
 132 to get it to send data, if any). The command 'i1' causes it to send
 133 the same sequence of subtype probes that
 134 <application>gpsd</application> would.  The command 'i0' turns off
 135 probing; 'i' alone toggles the bit. In either case, the current driver
 136 is re-selected; if the probe bit is enabled, probes will begin to be
 137 issued immediately.</para>
 138
 139 <para>Note that enabling probing might flip the device into another
 140 mode; in particular, it will flip a SiRF chip into binary mode as if
 141 you had used the <quote>n</quote> command.  This is due to a
 142 limitation in the SiRF firmware that we can't fix.</para>
 143 </listitem>
 144 </varlistentry>
 145
 146 <varlistentry>
 147 <term>c</term>
 148 <listitem>
 149 <para>Change cycle time. Follow it with a number interpreted as a
 150 cycle time in seconds. Most devices have a fixed cycle time of 1
 151 second, so this command may fail with a message.</para>
 152 </listitem>
 153 </varlistentry>
 154
 155 <varlistentry>
 156 <term>l</term>
 157 <listitem>
 158 <para>Toggle packet logging. If packet logging is on, it will be
 159 turned off and the log closed.  If it is off, logging to the filename
 160 following the l will be enabled.  Differs from simply capturing the
 161 data from the GPS device in that only whole packets are logged.
 162 The logfile is opened for append, so you can log more than one
 163 portion of the packet stream and they will be stitched together
 164 correctly.</para>
 165 </listitem>
 166 </varlistentry>
 167
 168 <varlistentry>
 169 <term>n</term>
 170 <listitem>
 171 <para>With an argument of 0, switch device to NMEA mode at current
 172 speed; with an argument of 1, change to binary (native) mode. With no
 173 argument, toggle the setting. Will show an error if the device doesn't
 174 have such modes.</para>
 175 </listitem>
 176 </varlistentry>
 177
 178 <varlistentry>
 179 <term>q</term>
 180 <listitem>
 181 <para>Quit <application>gpsmon</application>.  Control-C, or whatever
 182 your current interrupt chracter is, works as well.</para>
 183 </listitem>
 184 </varlistentry>
 185
 186 <varlistentry>
 187 <term>s</term>
 188 <listitem>
 189 <para>Change baud rate. Follow it with a number interpreted as bits
 190 per second, for example "s9600". The speed number may optionally be
 191 followed by a colon and a wordlength-parity-stopbits specification in
 192 the traditional style, e.g 8N1 (the default), 7E1, etc.  Some
 193 devices don't support serial modes other than their default, so
 194 this command may fail with a message.</para>
 195
 196 <para>Use this command with caution.  On USB and Bluetooth GPSes it is
 197 also possible for serial mode setting to fail either because the
 198 serial adaptor chip does not support non-8N1 modes or because the
 199 device firmware does not properly synchronize the serrial adaptor chip
 200 with the UART on the GPS chipset whjen the speed changes. These
 201 failures can hang your device, possibly requiring a GPS power cycle or (in
 202 extreme cases) physically disconnecting the NVRAM backup battery.</para>
 203 </listitem>
 204 </varlistentry>
 205
 206 <varlistentry>
 207 <term>t</term>
 208 <listitem>
 209 <para>Force a switch of monitoring type. Follow it with a string that
 210 is unique to the name of a gpsd driver with
 211 <application>gpsmon</application> support;
 212 <application>gpsmon</application> will switch to using that driver and
 213 display code. Will show an error message if there is no matching gpsd
 214 driver, or multiple matches, or the unique match has no display
 215 support in <application>gpsmon</application>.</para>
 216 </listitem>
 217 </varlistentry>
 218
 219 <varlistentry>
 220 <term>x</term>
 221 <listitem>
 222 <para>Send hex payload to device. Following the command letter you may
 223 type hex digit pairs; end with a newline.  These will become the
 224 payload of a control packet shipped to the device. The packet will be
 225 wrapped with headers, trailers, and checksum appropriate for the
 226 current driver type. The first one or two bytes of the payload may be
 227 specially interpreted, see the description of the <option>-x</option>
 228 of
 229 <citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
 230 </listitem>
 231 </varlistentry>
 232
 233 <varlistentry>
 234 <term>X</term>
 235 <listitem>
 236 <para>Send raw hex bytes to device. Following the command letter you
 237 may type hex digit pairs; end with a newline.  These will be shipped
 238 to the device.</para>
 239 </listitem>
 240 </varlistentry>
 241
 242 <varlistentry>
 243 <term>Ctrl-S</term>
 244 <listitem>
 245 <para>Freeze display, suspend scrolling in debug window.</para>
 246 </listitem>
 247 </varlistentry>
 248 <varlistentry>
 249 <term>Ctrl-Q</term>
 250 <listitem>
 251 <para>Unfreeze display, resume normal operation.</para>
 252 </listitem>
 253 </varlistentry>
 254 </variablelist>
 255
 256 <refsect2><title>NMEA support</title>
 257
 258 <para>(These remarks apply to not just generic NMEA devices
 259 but all extended NMEA devices for which
 260 <application>gpsmon</application> presently has support.)</para>
 261
 262 <para>All fields are raw data from the GPS except the "Cooked PVT"
 263 window near top of screen, provided as a sheck.</para>
 264
 265 <para>There are no device-specific commands. Which generic
 266 commands are available may vary by type: examine the output
 267 of <command>gpsmon -l</command> to learn more.</para>
 268 </refsect2>
 269
 270 <refsect2><title>SiRF support</title>
 271 <para>Most information is raw from the GPS.  Underlined fields are
 272 derived by translation from ECEF coordinates or application of
 273 leap-second and local time-zone offsets.</para>
 274
 275 <para>The following commands are supported for SiRF GPSes only:</para>
 276
 277 <variablelist>
 278 <varlistentry>
 279 <term>A</term>
 280 <listitem>
 281 <para>Toggle reporting of 50BPS subframe data.</para>
 282 </listitem>
 283 </varlistentry>
 284 <varlistentry>
 285 <term>M</term>
 286 <listitem>
 287 <para>Set (M1) or clear (M0) static navigation. The SiRF documentation
 288 says <quote>Static navigation is a position filter designed to be used
 289 with motor vehicles.  When the vehicle's velocity falls below a
 290 threshold, the position and heading are frozen, and velocity is set to
 291 zero. This condition will continue until the computed velocity rises
 292 above 1.2 times the threshold or until the computed position is at
 293 least a set distance from the frozen place. The threshold velocity and
 294 set distance may vary with software versions.</quote></para>
 295
 296 <para>Non-static mode is designed for use with road navigation
 297 software, which often snaps the reported position to the nearest road
 298 within some uncertainty radius.  You probably want to turn static
 299 navigation off for pedestrian use, as it is likely to report speed
 300 zero and position changing in large jumps.</para>
 301 </listitem>
 302 </varlistentry>
 303 <varlistentry>
 304 <term>P</term>
 305 <listitem>
 306 <para>Toggle navigation-parameter display mode.  Toggles between
 307 normal display and one that shows selected navigation parameters from
 308 MID 19, including the Static Navigation bit toggled by the 'M' command.</para>
 309 </listitem>
 310 </varlistentry>
 311 </variablelist>
 312
 313 <para>To interpret what you see, you will need a copy of the
 314 <citetitle>SiRF Binary Protocol Reference Manual</citetitle>.</para>
 315
 316 </refsect2>
 317 </refsect1>
 318 <refsect1 id='files'><title>FILES</title>
 319
 320 <variablelist>
 321 <varlistentry>
 322 <term><filename>/var/run/gpsd.sock</filename></term>
 323 <listitem>
 324 <para>The default location of the control socket.</para>
 325 </listitem>
 326 </varlistentry>
 327 </variablelist>
 328
 329 </refsect1>
 330 <refsect1 id='bugs'><title>BUGS AND LIMITATIONS</title>
 331
 332 <para>If you run <application>gpsmon</application> in client mode,
 333 and kill the daemon while <application>gpsmon</application> is
 334 still running, <application>gpsmon</application> will hang.
 335 Don't do that...</para>
 336
 337 <!--
 338 Debug window dumps of control message sends to the GPS (preceded
 339 by '>>>') are only supported for the following drivers: NMEA, SiRF,
 340 EverMore, Navcom, UBX, TSIP, iTalk, Garmintxt. This feature will not
 341 work for Zodiacs and not always work for Garmins in binary
 342 mode.
 343 -->
 344
 345 </refsect1>
 346 <refsect1 id='see_also'><title>SEE ALSO</title>
 347 <para>
 348 <citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 349 <citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 350 <citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 351 <citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 352 <citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 353 <citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 354 <citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 355 <citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 356 <citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 357 </para>
 358 </refsect1>
 359
 360 <refsect1 id='maintainer'><title>AUTHOR</title>
 361
 362 <para>Eric S. Raymond <email>esr@thyrsus.com</email>.  This code is
 363 part of the gpsd toolset; there is a project page for
 364 <application>gpsd</application> <ulink
 365 url="http://gpsd.berlios.de/">here</ulink>.</para>
 366 </refsect1>
 367
 368 </refentry>
 369