| <?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'>-L </arg> |
| <arg choice='opt'>-V </arg> |
| <arg choice='opt'>-h </arg> |
| <arg choice='opt'>-n </arg> |
| <arg choice='opt'>-a </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. 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 begins with 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. Possible cases look like this:</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term>localhost:/dev/ttyS1</term> |
| <listitem><para>Look at the default port of localhost, trying both |
| IPv4 and IPv6 and watching output from serial device 1.</para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>example.com:2317</term> |
| <listitem><para>Look at port 2317 on example.com, trying both |
| IPv4 and IPv6.</para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>71.162.241.5:2317:/dev/ttyS3</term> |
| <listitem><para>Look at port 2317 at the specified IPv4 |
| address, collecting data from attached serial device 3.</para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5</term> |
| <listitem><para>Look at port 2317 at the specified IPv6 |
| address, collecting data from attached serial device 5.</para></listitem> |
| </varlistentry> |
| </variablelist> |
| |
| <para>Unlike <application>gpsd</application>, |
| <application>gpsmon</application> run in direct mode does not do its |
| own device probing. Thus, in particular, if you point it at a |
| GPS with a native binary mode that happens to be emitting NMEA, it |
| won't identify the actual type unless the device emits a recognizable |
| NMEA trigger sentence. The -t and -i options may help you.</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 -n option forces gpsmon to request NMEA0183 packets instead of the |
| raw datastream from gpsd.</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>The -a option enables a special debugging mode that does not |
| use screen painting. Packets are dumped normally; any character |
| typed suspends packet dumping and brings up a command prompt. This |
| feature will mainly be of interest to GPSD developers.</para> |
| |
| <para>After startup (without -a), the top part of the screen reports |
| the contents of several especially interesting packet types. The |
| "PPS" field, if nonempty, is the delta between the last 1PPS top of |
| second and the system clock at that time.</para> |
| |
| <para>The bottom half of the screen is a scrolling hex dump of all |
| packets the GPS is issuing. Dump lines beginning >>> |
| represent control packets sent to the GPS. Lines consisting of "PPS" |
| surrounded by dashes, if present, indicate 1PPS and the start of the |
| reporting cycle.</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>(Direct mode only.) 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> |
| |
| <para>This command will generally do nothing after the first time you |
| use it, because the device type will already have been discovered.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>c</term> |
| <listitem> |
| <para>(Direct mode only.) 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>(Direct mode only.) 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> |
| |
| <para>After you switch a dual-protocol GPS to NMEA mode wityh this |
| command, it retains the information about the original type and its |
| control capabilities. That is why the device type listed before the |
| prompt doesn't change.</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>(Direct mode only.) 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>(Direct mode only.) 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>(Direct mode only.) 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>(Direct mode only.) 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 (a) the "Cooked PVT" |
| window near top of screen, provided as a check and (b) the "PPS |
| offset" field.</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. 1PPS is the clock lag as |
| usual.</para> |
| |
| <para>The following commands are supported for SiRF GPSes only:</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term>A</term> |
| <listitem> |
| <para>(Direct mode only.) Toggle reporting of 50BPS subframe data.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>M</term> |
| <listitem> |
| <para>(Direct mode only.) 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>(Direct mode only.) 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> |
| <refsect2><title>u-blox support</title> |
| <para>Most information is raw from the GPS. Underlined fields are |
| derived by translation from ECEF coordinates. 1PPS is the clock lag as |
| usual. There are no per-type special commands.</para> |
| |
| </refsect2> |
| </refsect1> |
| <refsect1 id='bugs'><title>BUGS AND LIMITATIONS</title> |
| |
| <para>The PPS Offset field will never be updated when running in |
| client mode, even if you can see PPS events in the packet window. |
| This limitation may be fixed in a future release.</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>gpsdctl</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>.</para> |
| </refsect1> |
| |
| </refentry> |
| |