table of contents
GPSMON(1) | GPSD Documentation | GPSMON(1) |
NAME¶
gpsmon - real-time GPS packet monitor and control utility
SYNOPSIS¶
gpsmon [-?] [--debug LVL] [--help] [--list] [--logfile FILE] [--nmea] [--nocurses] [--type TYPE] [--version] [-a] [-D LVL] [-h] [-L] [-l FILE] [-n] [-t TYPE] [-V] [[ server [:port [:device]] | device ]]
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 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.
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
example.com:2317
71.162.241.5:2317:/dev/ttyS3
[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5
After startup (without -a, --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 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.
OPTIONS¶
-?, -h, --help
-a, --nocurses
-d LVL, --debug LVL
-l FILE, --logfile FILE
-L, --list
-n, --nmea
-t TYPE, --type TYPE
COMMANDS¶
The following device-independent commands are available while gpsmon is running:
i
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
l
n
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
s
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
x
X
Ctrl-S
Ctrl-Q
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
M
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
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), libgpsmm(3), gpsprof(1), gpsfake(1), gpsctl(1), gpscat(1). gpspipe(1).
AUTHOR¶
Eric S. Raymond <esr@thyrsus.com>.
6 December 2020 | The GPSD Project |