GPSMON(1)                     GPSD Documentation                     GPSMON(1)



NAME
       gpsmon - real-time GPS packet monitor and control utility

SYNOPSIS
       gpsmon [-h] [-L] [-V] [-l logfile] [-F control-socket]
              [[ server [:port [:device]] | device]] [-D debuglevel]

DESCRIPTION
       gpsmon 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.

       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
       gpsctl). It now has support for a range of NMEA devices as well;
       support for other (binary-protocol) device types is planned. It will
       behave sanely, just dumping packets, when connected to a GPS type it
       knows nothing about.

       gpsmon 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.

       gpsmon 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.

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

       This program may be run in either of two modes, as a client for the
       gpsd 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 gpsmon will
       hunt for a correct baud rate and lock on to it automatically.

       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.

       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.

       The -L option lists a table showing which GPS device types gpsmon 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.

       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.

       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 >>> represent control packets sent to the GPS.

COMMANDS
       The following device-independent comands are available while gpsmon is
       running:

       i
           Enable/disable subtype probing and reinitialize the driver. In
           normal operation, gpsmon 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 gpsd 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.

           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 "n" command. This is due to a limitation in the SiRF
           firmware that we can't fix.

       c
           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.

       l
           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.

       n
           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.

       q
           Quit gpsmon. Control-C, or whatever your current interrupt chracter
           is, works as well.

       s
           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.

           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 serrial adaptor
           chip with the UART on the GPS chipset whjen 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.

       t
           Force a switch of monitoring type. Follow it with a string that is
           unique to the name of a gpsd driver with gpsmon support; gpsmon
           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 gpsmon.

       x
           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 -x of
           gpsctl(1).

       X
           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.

       Ctrl-S
           Freeze display, suspend scrolling in debug window.

       Ctrl-Q
           Unfreeze display, resume normal operation.

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

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

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

   SiRF support
       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.

       The following commands are supported for SiRF GPSes only:

       A
           Toggle reporting of 50BPS subframe data.

       M
           Set (M1) or clear (M0) static navigation. The SiRF documentation
           says "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."

           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.

       P
           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.

       To interpret what you see, you will need a copy of the SiRF Binary
       Protocol Reference Manual.

FILES
       /var/run/gpsd.sock
           The default location of the control socket.

BUGS AND LIMITATIONS
       If you run gpsmon in client mode, and kill the daemon while gpsmon is
       still running, gpsmon will hang. Don't do that...

SEE ALSO
       gpsd(8), gps(1), libgps(3), libgpsd(3), gpsprof(1), gpsfake(1),
       gpsctl(1), gpscat(1).  gpspipe(1).

AUTHOR
       Eric S. Raymond esr@thyrsus.com. This code is part of the gpsd toolset;
       there is a project page for gpsd here[1].

NOTES
        1. here
           http://gpsd.berlios.de/



The GPSD Project                  17 Feb 2009                        GPSMON(1)
