gpsmon(1)
NAME
gpsmon - real-time GPS packet monitor and control utility
SYNOPSIS
gpsmon [-L] [-V] [-h] [-n] [-a] [-l logfile] [-t driver-prefix]
[[ 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. 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.
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 reecognize 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.
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 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:
localhost:/dev/ttyS1
Look at the default port of localhost, trying both IPv4 and IPv6
and watching output from serial device 1.
example.com:2317
Look at port 2317 on example.com, trying both IPv4 and IPv6.
71.162.241.5:2317:/dev/ttyS3
Look at port 2317 at the specified IPv4 address, collecting data
from attached serial device 3.
[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5
Look at port 2317 at the specified IPv6 address, collecting data
from attached serial device 5.
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't identify the
actual type unless the device emits a recognizable NMEA trigger
sentence. The -t and -i options may help you.
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.
The -n option forces gpsmon to request NMEA0183 packets instead of the
raw datastream from gpsd.
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.
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.
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.
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.
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 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.
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.
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.
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.
SEE ALSO
gpsd(8), gpsdctl(8), gps(1), libgps(3), libgpsd(3), gpsprof(1), gpsfake(1), gpsctl(1), gpscat(1). gpspipe(1).
AUTHOR
Eric S. Raymond <[email protected]>.
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
