= gpsmon(1)
:author: Eric S. Raymond
:date: 19 November 2021
:email: <esr@thyrsus.com.>
:keywords: gps, gpsd, gpsmon
:manmanual: GPSD Documentation
:mansource: GPSD, Version {gpsdver}
:robots: index,follow
:sectlinks:
:toc: macro
:type: manpage

include::../www/inc-menu.adoc[]

== 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:* {gpsdweb}

== COPYING

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