'\" t
.\"     Title: gpsmon
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 6 December 2020
.\"    Manual: GPSD Documentation
.\"    Source: The GPSD Project
.\"  Language: English
.\"
.TH "GPSMON" "1" "6 December 2020" "The GPSD Project" "GPSD Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
gpsmon \- real\-time GPS packet monitor and control utility
.SH "SYNOPSIS"
.HP \w'\fBgpsmon\fR\ 'u
\fBgpsmon\fR [\-?] [\-\-debug\ \fILVL\fR] [\-\-help] [\-\-list] [\-\-logfile\ \fIFILE\fR] [\-\-nmea] [\-\-nocurses] [\-\-type\ \fITYPE\fR] [\-\-version] [\-a] [\-D\ \fILVL\fR] [\-h] [\-L] [\-l\ \fIFILE\fR] [\-n] [\-t\ \fITYPE\fR] [\-V] [[\ \fIserver\fR\ [\fI:port\fR\ [\fI:device\fR]]\ |\ \fIdevice\fR\ ]]
.SH "DESCRIPTION"
.PP
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\&.
.PP
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\&.
.PP
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\*(Aqt automatically recognize a device shipping an extended NMEA protocol as anything other than a plain NMEA device\&. Use the
\fB\-t\fR
option or the
\fBt\fR
to work around this\&.
.PP
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\&.
.PP
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 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
gpsmon
will hunt for a correct baud rate and lock on to it automatically\&. Possible cases look like this:
.PP
localhost:/dev/ttyS1
.RS 4
Look at the default port of localhost, trying both IPv4 and IPv6 and watching output from serial device 1\&.
.RE
.PP
example\&.com:2317
.RS 4
Look at port 2317 on example\&.com, trying both IPv4 and IPv6\&.
.RE
.PP
71\&.162\&.241\&.5:2317:/dev/ttyS3
.RS 4
Look at port 2317 at the specified IPv4 address, collecting data from attached serial device 3\&.
.RE
.PP
[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5
.RS 4
Look at port 2317 at the specified IPv6 address, collecting data from attached serial device 5\&.
.RE
.PP
After startup (without
\fB\-a, \-\-nocurses\fR), 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\&.
.PP
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\&.
.PP
Unlike
gpsd,
gpsmon
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\*(Aqt identify the actual type unless the device emits a recognizable NMEA trigger sentence\&. The
\fB\-t, \-\-type\fR
option may help you\&.
.SH "OPTIONS"
.PP
\fB\-?\fR, \fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a usage message and exit\&.
.RE
.PP
\fB\-a\fR, \fB\-\-nocurses\fR
.RS 4
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\&.
.RE
.PP
\fB\-d LVL\fR, \fB\-\-debug LVL\fR
.RS 4
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\&.
.RE
.PP
\fB\-l FILE\fR, \fB\-\-logfile FILE\fR
.RS 4
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\&.
.RE
.PP
\fB\-L\fR, \fB\-\-list\fR
.RS 4
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\&.
.RE
.PP
\fB\-n\fR, \fB\-\-nmea\fR
.RS 4
Force gpsmon to request NMEA0183 packets instead of the raw data stream from gpsd\&.
.RE
.PP
\fB\-t TYPE\fR, \fB\-\-type TYPE\fR
.RS 4
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\&.
.RE
.SH "COMMANDS"
.PP
The following device\-independent commands are available while
gpsmon
is running:
.PP
i
.RS 4
(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 \*(Aqi1\*(Aq causes it to send the same sequence of subtype probes that
gpsd
would\&. The command \*(Aqi0\*(Aq turns off probing; \*(Aqi\*(Aq 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\&.
.sp
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
\(lqn\(rq
command\&. This is due to a limitation in the SiRF firmware that we can\*(Aqt fix\&.
.sp
This command will generally do nothing after the first time you use it, because the device type will already have been discovered\&.
.RE
.PP
c
.RS 4
(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\&.
.RE
.PP
l
.RS 4
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\&.
.RE
.PP
n
.RS 4
(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\*(Aqt have such modes\&.
.sp
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\*(Aqt change\&.
.RE
.PP
q
.RS 4
Quit
gpsmon\&. Control\-C, or whatever your current interrupt character is, works as well\&.
.RE
.PP
s
.RS 4
(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\*(Aqt support serial modes other than their default, so this command may fail with a message\&.
.sp
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\&.
.RE
.PP
t
.RS 4
(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\&.
.RE
.PP
x
.RS 4
(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
\fB\-x\fR
of
\fBgpsctl\fR(1)\&.
.RE
.PP
X
.RS 4
(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\&.
.RE
.PP
Ctrl\-S
.RS 4
Freeze display, suspend scrolling in debug window\&.
.RE
.PP
Ctrl\-Q
.RS 4
Unfreeze display, resume normal operation\&.
.RE
.SS "NMEA support"
.PP
(These remarks apply to not just generic NMEA devices but all extended NMEA devices for which
gpsmon
presently has support\&.)
.PP
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\&.
.PP
There are no device\-specific commands\&. Which generic commands are available may vary by type: examine the output of
\fBgpsmon \-l\fR
to learn more\&.
.SS "SiRF support"
.PP
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\&.
.PP
The following commands are supported for SiRF GPSes only:
.PP
A
.RS 4
(Direct mode only\&.) Toggle reporting of 50BPS subframe data\&.
.RE
.PP
M
.RS 4
(Direct mode only\&.) Set (M1) or clear (M0) static navigation\&. The SiRF documentation says
\(lqStatic navigation is a position filter designed to be used with motor vehicles\&. When the vehicle\*(Aqs 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\&.\(rq
.sp
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\&.
.RE
.PP
P
.RS 4
(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 \*(AqM\*(Aq command\&.
.RE
.PP
To interpret what you see, you will need a copy of the
SiRF Binary Protocol Reference Manual\&.
.SS "u\-blox support"
.PP
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\&.
.SH "BUGS AND LIMITATIONS"
.PP
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\&.
.SH "SEE ALSO"
.PP
\fBgpsd\fR(8),
\fBgpsdctl\fR(8),
\fBgps\fR(1),
\fBlibgps\fR(3),
\fBlibgpsmm\fR(3),
\fBgpsprof\fR(1),
\fBgpsfake\fR(1),
\fBgpsctl\fR(1),
\fBgpscat\fR(1)\&.
\fBgpspipe\fR(1)\&.
.SH "AUTHOR"
.PP
Eric S\&. Raymond
<esr@thyrsus\&.com>\&.