NAME

       gpsmon - real-time GPS packet monitor and control utility

SYNOPSIS

       gpsmon [OPTIONS} [server[:port[:device]]]

       gpsmon -h

       gpsmon -V

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. 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. It does not use gpsd to decode packets. There are
       many raw data types that gpsd knows about that gpsmon does not. 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.

       The casual gpsd user will be better served by the cgps clients which display navigation data the same way
       for all GNSS receivers that gpsd supports. Such as cgps and xgps.

       Unlike gpsd, gpsmon never writes control or probe strings to the device unless you explicitly tell it to.
       Thus, while it will auto-sync to binary packet types, it won’t automatically recognize a device shipping
       an extended NMEA protocol as anything other than a plain NMEA device. Use the -t option or the t to work
       around this.

       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.

       After startup (without -a or --nocurses), 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.

       The bottom half of the screen is a scrolling hex dump of all packets the GPS is issuing. If the packet
       type is textual, any trailing CR/LF is omitted. 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.

       Unlike gpsd, gpsmon when 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, --type option may help
       you.

       gpsmon does not require root privileges, except maybe to access the serial port in direct mode. It will
       run fine as root.

OPTIONS

       -?, -h, --help
           Print a usage message and exit.

       -a, --nocurses
           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.

       -d LVL, --debug LVL
           Enable packet-getter debugging output and is probably only useful to developers of the GPSD code.
           Consult the packet-getter source code for relevant values.

       -l FILE, --logfile FILE
           Set up logging to a specified file (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.

       -L, --list
           Lists a table showing which GPS device types this 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.

       -n, --nmea
           Force gpsmon to request NMEA0183 packets instead of the raw data stream from gpsd.

       -t TYPE, --type TYPE
           Set a fallback type (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.

ARGUMENTS

       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.

       By default, clients collect data from the local gpsd daemon running on localhost, using the default GPSD
       port 2947. The optional argument to any client may override this behavior: [server[:port[:device]]]

       For further explanation, and examples, see the ARGUMENTS section in the gps(1) man page

       If instead the 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.

COMMANDS

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

       i
           (Direct mode only.) 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.

       This command will generally do nothing after the first time you use it, because the device type will
       already have been discovered.

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

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

       After you switch a dual-protocol GPS to NMEA mode with 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.

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

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

           Note

           Use this command with caution. On USB and Bluetooth GPSs 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.

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

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

       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 (a) the "Cooked PVT" window near top of screen, provided as a
       check and (b) the "PPS offset" field.

       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. 1PPS is the clock lag as usual.

       The following commands are supported for SiRF GPSes only:

       A
           (Direct mode only.) Toggle reporting of 50BPS subframe data.

       M
           (Direct mode only.) 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
           (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.

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

   u-blox support
       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.

BUGS AND LIMITATIONS

       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.

RETURN VALUES

       0
           on success.

       1
           on failure

SEE ALSO

       gpsd(8), cgps, (1)gpsctl(1), gps(1), *xgps(1)

RESOURCES

       Project web site: https://gpsd.io/

COPYING

       This file is Copyright 2013 by the GPSD project
       SPDX-License-Identifier: BSD-2-clause

AUTHOR

       Eric S. Raymond

GPSD, Version 3.25                                 2023-01-10                                          GPSMON(1)