path: root/gpsmon.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
This file is Copyright (c) 2010 by the GPSD project
BSD terms apply: see the file COPYING in the distribution root for details.
-->
<!DOCTYPE refentry PUBLIC
   "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id='gpsmon.1'>
<refentryinfo><date>17 Feb 2009</date></refentryinfo>
<refmeta>
<refentrytitle>gpsmon</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source">The GPSD Project</refmiscinfo>
<refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>gpsmon</refname>
<refpurpose>real-time GPS packet monitor and control utility</refpurpose>
</refnamediv>
<refsynopsisdiv id='synopsis'>

<cmdsynopsis>
  <command>gpsmon</command>
      <arg choice='opt'>-F <replaceable>control-socket</replaceable></arg>
      <arg choice='opt'>-L </arg>
      <arg choice='opt'>-V </arg>
      <arg choice='opt'>-h </arg>
      <arg choice='opt'>-l <replaceable>logfile</replaceable></arg>
      <arg choice='opt'>-t <replaceable>driver-prefix</replaceable></arg>
      <arg choice='opt'>
	<group>
	  <arg choice='plain'>
            <replaceable>server</replaceable>
            <group>
	      <replaceable>:port</replaceable>
              <group><replaceable>:device</replaceable></group>
            </group>
          </arg>
          <arg choice='plain'><replaceable>device</replaceable></arg>
        </group>
      </arg>
      <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1 id='description'><title>DESCRIPTION</title>

<para><application>gpsmon</application> is a monitor that watches
packets coming from a GPS and displays them along with diagnostic
information. It supports commands that can be used to tweak GPS
settings in various ways; some are device-independent, some vary
with the GPS chipset type.</para>

<para>This tool used to be called 'sirfmon', and worked only on SiRF
devices (and the command set has changed to resemble the command
switches of <application>gpsctl</application>). It now has support for
a range of NMEA and other other binary-protocol devices as well.  It
will behave sanely, just dumping packets, when connected to a GPS type
it knows nothing about.</para>

<para><application>gpsmon</application> differs from a navigation
client in that it mostly dumps raw data from the GPS, with only enough
data-massaging to allow checks against expected output.  In
particular, this tool does not do any interpolation or modeling
to derive climb/sink or error estimates. Nor does it discard
altitude reports when the fix quality is too low.</para>

<para><application>gpsmon</application> is a designed to run in a
terminal emulator with a minimum 25x80 size; the non-GUI interface is
a design choice made to accommodate users operating in constrained
environments and over telnet or ssh connections.  If run in a larger
window, the size of the packet-log window will be increased to
fit.</para>

<para><application>gpsmon</application> accepts an -h option that
displays a usage message, or a -V option to dump the package
version and exit.</para>

<para>This program may be run in either of two modes, as a client for
the <application>gpsd</application> daemon (and its associated control
socket) or directly connected to a specified serial device.  When run
with no argument, it attempts to connect to the daemon.  If the
argument looks like a server:port specification it will also attempt
to connect to the daemon.  If the argument looks like a bare server
name it will attempt to connect to a daemon running on the default
gpsd port on that server.  Only if the device argument contains
slashes but no colons will it be treated as a serial device for direct
connection. In direct-connect mode <application>gpsmon</application>
will hunt for a correct baud rate and lock on to it
automatically.</para>

<para>The -F option is only valid in client mode; it specifies a
control socket to which the program should send device control
strings.  You must specify a valid pathname of a Unix-domain socket on
your local filesystem.</para>

<para>The -D option enables packet-getter debugging output and is
probably only useful to developers of the GPSD code.  Consult the
packet-getter source code for relevant values.</para>

<para>The -L option lists a table showing which GPS device types
<application>gpsmon</application> has built-in support for, and which
generic commands can be applied to which GPS types, and then
exits. Note that this does not list type-specific commands associated
with individual GPS types.</para>

<para>The -l option sets up logging to a specified file to start
immediately on device open.  This may be useful is, for example,
you want to capture the startup message from a device that displays
firmware version information there.</para>

<para>The -t option sets up a fallback type. Give it a string that
is a distinguishing prefix of exactly one driver type name; this will
be used for mode, speed, and rate switching if the driver selected
by the packet type lacks those capabilities.  Most useful when the
packet type is NMEA but the device is known to have a binary mode,
such as SiRF binary.</para>

<para>After startup, the top part of the screen reports the contents
of several especially interesting packet types.  The bottom half of
the screen is a scrolling hex dump of all packets the GPS is issuing.
Dump lines beginning &gt;&gt;&gt; represent control packets sent to the
GPS.</para>

</refsect1>
<refsect1 id='commands'><title>COMMANDS</title>

<para>The following device-independent commands are available while
<application>gpsmon</application> is running:</para>

<variablelist>

<varlistentry>
<term>i</term>
<listitem>
<para>Enable/disable subtype probing and reinitialize the driver. In
normal operation, <application>gpsmon</application> does not send
configuration strings to the device (except for wakeup strings needed
to get it to send data, if any). The command 'i1' causes it to send
the same sequence of subtype probes that
<application>gpsd</application> would.  The command 'i0' turns off
probing; 'i' alone toggles the bit. In either case, the current driver
is re-selected; if the probe bit is enabled, probes will begin to be
issued immediately.</para>

<para>Note that enabling probing might flip the device into another
mode; in particular, it will flip a SiRF chip into binary mode as if
you had used the <quote>n</quote> command.  This is due to a
limitation in the SiRF firmware that we can't fix.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>c</term>
<listitem>
<para>Change cycle time. Follow it with a number interpreted as a
cycle time in seconds. Most devices have a fixed cycle time of 1
second, so this command may fail with a message.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>l</term>
<listitem>
<para>Toggle packet logging. If packet logging is on, it will be
turned off and the log closed.  If it is off, logging to the filename
following the l will be enabled.  Differs from simply capturing the
data from the GPS device in that only whole packets are logged.
The logfile is opened for append, so you can log more than one
portion of the packet stream and they will be stitched together
correctly.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>n</term>
<listitem>
<para>With an argument of 0, switch device to NMEA mode at current
speed; with an argument of 1, change to binary (native) mode. With no
argument, toggle the setting. Will show an error if the device doesn't
have such modes.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>q</term>
<listitem>
<para>Quit <application>gpsmon</application>.  Control-C, or whatever
your current interrupt character is, works as well.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>s</term>
<listitem>
<para>Change baud rate. Follow it with a number interpreted as bits
per second, for example "s9600". The speed number may optionally be
followed by a colon and a wordlength-parity-stopbits specification in
the traditional style, e.g 8N1 (the default), 7E1, etc.  Some
devices don't support serial modes other than their default, so
this command may fail with a message.</para>

<para>Use this command with caution.  On USB and Bluetooth GPSes it is
also possible for serial mode setting to fail either because the
serial adaptor chip does not support non-8N1 modes or because the
device firmware does not properly synchronize the serial adaptor chip
with the UART on the GPS chipset when the speed changes. These
failures can hang your device, possibly requiring a GPS power cycle or (in
extreme cases) physically disconnecting the NVRAM backup battery.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>t</term>
<listitem>
<para>Force a switch of monitoring type. Follow it with a string that
is unique to the name of a gpsd driver with
<application>gpsmon</application> support;
<application>gpsmon</application> will switch to using that driver and
display code. Will show an error message if there is no matching gpsd
driver, or multiple matches, or the unique match has no display
support in <application>gpsmon</application>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>x</term>
<listitem>
<para>Send hex payload to device. Following the command letter you may
type hex digit pairs; end with a newline.  These will become the
payload of a control packet shipped to the device. The packet will be
wrapped with headers, trailers, and checksum appropriate for the
current driver type. The first one or two bytes of the payload may be
specially interpreted, see the description of the <option>-x</option>
of
<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>X</term>
<listitem>
<para>Send raw hex bytes to device. Following the command letter you
may type hex digit pairs; end with a newline.  These will be shipped
to the device.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Ctrl-S</term>
<listitem>
<para>Freeze display, suspend scrolling in debug window.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Ctrl-Q</term>
<listitem>
<para>Unfreeze display, resume normal operation.</para>
</listitem>
</varlistentry>
</variablelist>

<refsect2><title>NMEA support</title>

<para>(These remarks apply to not just generic NMEA devices
but all extended NMEA devices for which
<application>gpsmon</application> presently has support.)</para>

<para>All fields are raw data from the GPS except the "Cooked PVT"
window near top of screen, provided as a sheck.</para>

<para>There are no device-specific commands. Which generic
commands are available may vary by type: examine the output
of <command>gpsmon -l</command> to learn more.</para>
</refsect2>

<refsect2><title>SiRF support</title>
<para>Most information is raw from the GPS.  Underlined fields are
derived by translation from ECEF coordinates or application of
leap-second and local time-zone offsets.</para>

<para>The following commands are supported for SiRF GPSes only:</para>

<variablelist>
<varlistentry>
<term>A</term>
<listitem>
<para>Toggle reporting of 50BPS subframe data.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>M</term>
<listitem>
<para>Set (M1) or clear (M0) static navigation. The SiRF documentation
says <quote>Static navigation is a position filter designed to be used
with motor vehicles.  When the vehicle's velocity falls below a
threshold, the position and heading are frozen, and velocity is set to
zero. This condition will continue until the computed velocity rises
above 1.2 times the threshold or until the computed position is at
least a set distance from the frozen place. The threshold velocity and
set distance may vary with software versions.</quote></para>

<para>Non-static mode is designed for use with road navigation
software, which often snaps the reported position to the nearest road
within some uncertainty radius.  You probably want to turn static
navigation off for pedestrian use, as it is likely to report speed
zero and position changing in large jumps.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>P</term>
<listitem>
<para>Toggle navigation-parameter display mode.  Toggles between
normal display and one that shows selected navigation parameters from
MID 19, including the Static Navigation bit toggled by the 'M' command.</para>
</listitem>
</varlistentry>
</variablelist>

<para>To interpret what you see, you will need a copy of the
<citetitle>SiRF Binary Protocol Reference Manual</citetitle>.</para>

</refsect2>
</refsect1>
<refsect1 id='files'><title>FILES</title>

<variablelist>
<varlistentry>
<term><filename>/var/run/gpsd.sock</filename></term>
<listitem>
<para>The default location of the control socket.</para>
</listitem>
</varlistentry>
</variablelist>

</refsect1>
<refsect1 id='bugs'><title>BUGS AND LIMITATIONS</title>

<para>If you run <application>gpsmon</application> in client mode,
and kill the daemon while <application>gpsmon</application> is
still running, <application>gpsmon</application> will hang.
Don't do that...</para>

<!--
Debug window dumps of control message sends to the GPS (preceded
by '>>>') are only supported for the following drivers: NMEA, SiRF,
EverMore, Navcom, UBX, TSIP, iTalk, Garmintxt. This feature will not
work for Zodiacs and not always work for Garmins in binary
mode.
-->

</refsect1>
<refsect1 id='see_also'><title>SEE ALSO</title>
<para>
<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
<citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>
</refsect1>

<refsect1 id='maintainer'><title>AUTHOR</title>

<para>Eric S. Raymond <email>esr@thyrsus.com</email>.  This code is
part of the gpsd toolset; there is a project page for
<application>gpsd</application> <ulink
url="http://gpsd.berlios.de/">here</ulink>.</para>
</refsect1>

</refentry>