1GPSMON(1)                     GPSD Documentation                     GPSMON(1)
2
3
4

NAME

6       gpsmon - real-time GPS packet monitor and control utility
7

SYNOPSIS

9       gpsmon [-?] [--debug LVL] [--help] [--list] [--logfile FILE] [--nmea]
10              [--nocurses] [--type TYPE] [--version] [-a] [-D LVL] [-h] [-L]
11              [-l FILE] [-n] [-t TYPE] [-V]
12              [[ server [:port [:device]] | device ]]
13

DESCRIPTION

15       gpsmon is a monitor that watches packets coming from a GPS and displays
16       them along with diagnostic information. It supports commands that can
17       be used to tweak GPS settings in various ways; some are
18       device-independent, some vary with the GPS chipset type. It will behave
19       sanely, just dumping packets, when connected to a GPS type it knows
20       nothing about.
21
22       gpsmon differs from a navigation client in that it mostly dumps raw
23       data from the GPS, with only enough data-massaging to allow checks
24       against expected output. In particular, this tool does not do any
25       interpolation or modeling to derive climb/sink or error estimates. Nor
26       does it discard altitude reports when the fix quality is too low.
27
28       Unlike gpsd, gpsmon never writes control or probe strings to the device
29       unless you explicitly tell it to. Thus, while it will auto-sync to
30       binary packet types, it won't automatically recognize a device shipping
31       an extended NMEA protocol as anything other than a plain NMEA device.
32       Use the -t option or the t to work around this.
33
34       gpsmon is a designed to run in a terminal emulator with a minimum 25x80
35       size; the non-GUI interface is a design choice made to accommodate
36       users operating in constrained environments and over telnet or ssh
37       connections. If run in a larger window, the size of the packet-log
38       window will be increased to fit.
39
40       This program may be run in either of two modes, as a client for the
41       gpsd daemon (and its associated control socket) or directly connected
42       to a specified serial device. When run with no argument, it attempts to
43       connect to the daemon. If the argument begins with a server:port
44       specification it will also attempt to connect to the daemon. If the
45       argument looks like a bare server name it will attempt to connect to a
46       daemon running on the default gpsd port on that server. Only if the
47       device argument contains slashes but no colons will it be treated as a
48       serial device for direct connection. In direct-connect mode gpsmon will
49       hunt for a correct baud rate and lock on to it automatically. Possible
50       cases look like this:
51
52       localhost:/dev/ttyS1
53           Look at the default port of localhost, trying both IPv4 and IPv6
54           and watching output from serial device 1.
55
56       example.com:2317
57           Look at port 2317 on example.com, trying both IPv4 and IPv6.
58
59       71.162.241.5:2317:/dev/ttyS3
60           Look at port 2317 at the specified IPv4 address, collecting data
61           from attached serial device 3.
62
63       [FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5
64           Look at port 2317 at the specified IPv6 address, collecting data
65           from attached serial device 5.
66
67       After startup (without -a, --nocurses), the top part of the screen
68       reports the contents of several especially interesting packet types.
69       The "PPS" field, if nonempty, is the delta between the last 1PPS top of
70       second and the system clock at that time.
71
72       The bottom half of the screen is a scrolling hex dump of all packets
73       the GPS is issuing. If the packet type is textual, any trailing CR/LF
74       is omitted. Dump lines beginning >>> represent control packets sent to
75       the GPS. Lines consisting of "PPS" surrounded by dashes, if present,
76       indicate 1PPS and the start of the reporting cycle.
77
78       Unlike gpsd, gpsmon run in direct mode does not do its own device
79       probing. Thus, in particular, if you point it at a GPS with a native
80       binary mode that happens to be emitting NMEA, it won't identify the
81       actual type unless the device emits a recognizable NMEA trigger
82       sentence. The -t, --type option may help you.
83

OPTIONS

85       -?, -h, --help
86           Print a usage message and exit.
87
88       -a, --nocurses
89           Enables a special debugging mode that does not use screen painting.
90           Packets are dumped normally; any character typed suspends packet
91           dumping and brings up a command prompt. This feature will mainly be
92           of interest to GPSD developers.
93
94       -d LVL, --debug LVL
95           Enable packet-getter debugging output and is probably only useful
96           to developers of the GPSD code. Consult the packet-getter source
97           code for relevant values.
98
99       -l FILE, --logfile FILE
100           Set up logging to a specified file (FILE) to start immediately on
101           device open. This may be useful is, for example, you want to
102           capture the startup message from a device that displays firmware
103           version information there.
104
105       -L, --list
106           Lists a table showing which GPS device types this gpsmon has
107           built-in support for, and which generic commands can be applied to
108           which GPS types, and then exits. Note that this does not list
109           type-specific commands associated with individual GPS types.
110
111       -n, --nmea
112           Force gpsmon to request NMEA0183 packets instead of the raw data
113           stream from gpsd.
114
115       -t TYPE, --type TYPE
116           Set a fallback type (TYPE). Give it a string that is a
117           distinguishing prefix of exactly one driver type name; this will be
118           used for mode, speed, and rate switching if the driver selected by
119           the packet type lacks those capabilities. Most useful when the
120           packet type is NMEA but the device is known to have a binary mode,
121           such as SiRF binary.
122

COMMANDS

124       The following device-independent commands are available while gpsmon is
125       running:
126
127       i
128           (Direct mode only.) Enable/disable subtype probing and reinitialize
129           the driver. In normal operation, gpsmon does not send configuration
130           strings to the device (except for wakeup strings needed to get it
131           to send data, if any). The command 'i1' causes it to send the same
132           sequence of subtype probes that gpsd would. The command 'i0' turns
133           off probing; 'i' alone toggles the bit. In either case, the current
134           driver is re-selected; if the probe bit is enabled, probes will
135           begin to be issued immediately.
136
137           Note that enabling probing might flip the device into another mode;
138           in particular, it will flip a SiRF chip into binary mode as if you
139           had used the “n” command. This is due to a limitation in the SiRF
140           firmware that we can't fix.
141
142           This command will generally do nothing after the first time you use
143           it, because the device type will already have been discovered.
144
145       c
146           (Direct mode only.) Change cycle time. Follow it with a number
147           interpreted as a cycle time in seconds. Most devices have a fixed
148           cycle time of 1 second, so this command may fail with a message.
149
150       l
151           Toggle packet logging. If packet logging is on, it will be turned
152           off and the log closed. If it is off, logging to the filename
153           following the l will be enabled. Differs from simply capturing the
154           data from the GPS device in that only whole packets are logged. The
155           logfile is opened for append, so you can log more than one portion
156           of the packet stream and they will be stitched together correctly.
157
158       n
159           (Direct mode only.) With an argument of 0, switch device to NMEA
160           mode at current speed; with an argument of 1, change to binary
161           (native) mode. With no argument, toggle the setting. Will show an
162           error if the device doesn't have such modes.
163
164           After you switch a dual-protocol GPS to NMEA mode with this
165           command, it retains the information about the original type and its
166           control capabilities. That is why the device type listed before the
167           prompt doesn't change.
168
169       q
170           Quit gpsmon. Control-C, or whatever your current interrupt
171           character is, works as well.
172
173       s
174           (Direct mode only.) Change baud rate. Follow it with a number
175           interpreted as bits per second, for example "s9600". The speed
176           number may optionally be followed by a colon and a
177           wordlength-parity-stopbits specification in the traditional style,
178           e.g 8N1 (the default), 7E1, etc. Some devices don't support serial
179           modes other than their default, so this command may fail with a
180           message.
181
182           Use this command with caution. On USB and Bluetooth GPSs it is also
183           possible for serial mode setting to fail either because the serial
184           adaptor chip does not support non-8N1 modes or because the device
185           firmware does not properly synchronize the serial adaptor chip with
186           the UART on the GPS chipset when the speed changes. These failures
187           can hang your device, possibly requiring a GPS power cycle or (in
188           extreme cases) physically disconnecting the NVRAM backup battery.
189
190       t
191           (Direct mode only.) Force a switch of monitoring type. Follow it
192           with a string that is unique to the name of a gpsd driver with
193           gpsmon support; gpsmon will switch to using that driver and display
194           code. Will show an error message if there is no matching gpsd
195           driver, or multiple matches, or the unique match has no display
196           support in gpsmon.
197
198       x
199           (Direct mode only.) Send hex payload to device. Following the
200           command letter you may type hex digit pairs; end with a newline.
201           These will become the payload of a control packet shipped to the
202           device. The packet will be wrapped with headers, trailers, and
203           checksum appropriate for the current driver type. The first one or
204           two bytes of the payload may be specially interpreted, see the
205           description of the -x of gpsctl(1).
206
207       X
208           (Direct mode only.) Send raw hex bytes to device. Following the
209           command letter you may type hex digit pairs; end with a newline.
210           These will be shipped to the device.
211
212       Ctrl-S
213           Freeze display, suspend scrolling in debug window.
214
215       Ctrl-Q
216           Unfreeze display, resume normal operation.
217
218   NMEA support
219       (These remarks apply to not just generic NMEA devices but all extended
220       NMEA devices for which gpsmon presently has support.)
221
222       All fields are raw data from the GPS except (a) the "Cooked PVT" window
223       near top of screen, provided as a check and (b) the "PPS offset" field.
224
225       There are no device-specific commands. Which generic commands are
226       available may vary by type: examine the output of gpsmon -l to learn
227       more.
228
229   SiRF support
230       Most information is raw from the GPS. Underlined fields are derived by
231       translation from ECEF coordinates or application of leap-second and
232       local time-zone offsets. 1PPS is the clock lag as usual.
233
234       The following commands are supported for SiRF GPSes only:
235
236       A
237           (Direct mode only.) Toggle reporting of 50BPS subframe data.
238
239       M
240           (Direct mode only.) Set (M1) or clear (M0) static navigation. The
241           SiRF documentation says “Static navigation is a position filter
242           designed to be used with motor vehicles. When the vehicle's
243           velocity falls below a threshold, the position and heading are
244           frozen, and velocity is set to zero. This condition will continue
245           until the computed velocity rises above 1.2 times the threshold or
246           until the computed position is at least a set distance from the
247           frozen place. The threshold velocity and set distance may vary with
248           software versions.”
249
250           Non-static mode is designed for use with road navigation software,
251           which often snaps the reported position to the nearest road within
252           some uncertainty radius. You probably want to turn static
253           navigation off for pedestrian use, as it is likely to report speed
254           zero and position changing in large jumps.
255
256       P
257           (Direct mode only.) Toggle navigation-parameter display mode.
258           Toggles between normal display and one that shows selected
259           navigation parameters from MID 19, including the Static Navigation
260           bit toggled by the 'M' command.
261
262       To interpret what you see, you will need a copy of the SiRF Binary
263       Protocol Reference Manual.
264
265   u-blox support
266       Most information is raw from the GPS. Underlined fields are derived by
267       translation from ECEF coordinates. 1PPS is the clock lag as usual.
268       There are no per-type special commands.
269

BUGS AND LIMITATIONS

271       The PPS Offset field will never be updated when running in client mode,
272       even if you can see PPS events in the packet window. This limitation
273       may be fixed in a future release.
274

SEE ALSO

276       gpsd(8), gpsdctl(8), gps(1), libgps(3), libgpsmm(3), gpsprof(1),
277       gpsfake(1), gpsctl(1), gpscat(1).  gpspipe(1).
278

AUTHOR

280       Eric S. Raymond <esr@thyrsus.com>.
281
282
283
284The GPSD Project                6 December 2020                      GPSMON(1)
Impressum