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

NAME

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

SYNOPSIS

9       gpsmon [OPTIONS} [server[:port[:device]]]
10
11       gpsmon -h
12
13       gpsmon -V
14

DESCRIPTION

16       gpsmon is a monitor that watches packets coming from a GPS and displays
17       them along with diagnostic information. It supports commands that can
18       be used to tweak GPS settings in various ways; some are
19       device-independent, some vary with the GPS chipset type. It will behave
20       sanely, just dumping packets, when connected to a GPS type it knows
21       nothing about.
22
23       gpsmon differs from a navigation client in that it mostly dumps raw
24       data from the GPS, with only enough data-massaging to allow checks
25       against expected output. It does not use gpsd to decode packets. There
26       are many raw data types that gpsd knows about that gpsmon does not. In
27       particular, this tool does not do any interpolation or modeling to
28       derive climb/sink or error estimates. Nor does it discard altitude
29       reports when the fix quality is too low.
30
31       The casual gpsd user will be better served by the cgps clients which
32       display navigation data the same way for all GNSS receivers that gpsd
33       supports. Such as cgps and xgps.
34
35       Unlike gpsd, gpsmon never writes control or probe strings to the device
36       unless you explicitly tell it to. Thus, while it will auto-sync to
37       binary packet types, it won’t automatically recognize a device shipping
38       an extended NMEA protocol as anything other than a plain NMEA device.
39       Use the -t option or the t to work around this.
40
41       gpsmon is a designed to run in a terminal emulator with a minimum 25x80
42       size; the non-GUI interface is a design choice made to accommodate
43       users operating in constrained environments and over telnet or ssh
44       connections. If run in a larger window, the size of the packet-log
45       window will be increased to fit.
46
47       After startup (without -a or --nocurses), the top part of the screen
48       reports the contents of several especially interesting packet types.
49       The "PPS" field, if nonempty, is the delta between the last 1PPS top of
50       second and the system clock at that time.
51
52       The bottom half of the screen is a scrolling hex dump of all packets
53       the GPS is issuing. If the packet type is textual, any trailing CR/LF
54       is omitted. Dump lines beginning ">>>" represent control packets sent
55       to the GPS. Lines consisting of "PPS" surrounded by dashes, if present,
56       indicate 1PPS and the start of the reporting cycle.
57
58       Unlike gpsd, gpsmon when run in direct mode does not do its own device
59       probing. Thus, in particular, if you point it at a GPS with a native
60       binary mode that happens to be emitting NMEA, it won’t identify the
61       actual type unless the device emits a recognizable NMEA trigger
62       sentence. The -t, --type option may help you.
63
64       gpsmon does not require root privileges, except maybe to access the
65       serial port in direct mode. It will run fine as root.
66

OPTIONS

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

ARGUMENTS

107       This program may be run in either of two modes, as a client for the
108       gpsd daemon (and its associated control socket) or directly connected
109       to a specified serial device.
110
111       By default, clients collect data from the local gpsd daemon running on
112       localhost, using the default GPSD port 2947. The optional argument to
113       any client may override this behavior: [server[:port[:device]]]
114
115       For further explanation, and examples, see the ARGUMENTS section in the
116       gps(1) man page
117
118       If instead the argument contains slashes but no colons will it be
119       treated as a serial device for direct connection. In direct-connect
120       mode gpsmon will hunt for a correct baud rate and lock on to it
121       automatically.
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; in
138       particular, it will flip a SiRF chip into binary mode as if you had
139       used the "n" command. This is due to a limitation in the SiRF firmware
140       that we can’t fix.
141
142       This command will generally do nothing after the first time you use it,
143       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 command, it
165       retains the information about the original type and its control
166       capabilities. That is why the device type listed before the prompt
167       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           Note
183           Use this command with caution. On USB and Bluetooth GPSs it is also
184           possible for serial mode setting to fail either because the serial
185           adaptor chip does not support non-8N1 modes or because the device
186           firmware does not properly synchronize the serial adaptor chip with
187           the UART on the GPS chipset when the speed changes. These failures
188           can hang your device, possibly requiring a GPS power cycle or (in
189           extreme cases) physically disconnecting the NVRAM backup battery.
190
191       t
192           (Direct mode only.) Force a switch of monitoring type. Follow it
193           with a string that is unique to the name of a gpsd driver with
194           gpsmon support; gpsmon will switch to using that driver and display
195           code. Will show an error message if there is no matching gpsd
196           driver, or multiple matches, or the unique match has no display
197           support in gpsmon.
198
199       x
200           (Direct mode only.) Send hex payload to device. Following the
201           command letter you may type hex digit pairs; end with a newline.
202           These will become the payload of a control packet shipped to the
203           device. The packet will be wrapped with headers, trailers, and
204           checksum appropriate for the current driver type. The first one or
205           two bytes of the payload may be specially interpreted, see the
206           description of the -x of gpsctl 1 .
207
208       X
209           (Direct mode only.) Send raw hex bytes to device. Following the
210           command letter you may type hex digit pairs; end with a newline.
211           These will be shipped to the device.
212
213       Ctrl-S
214           Freeze display, suspend scrolling in debug window.
215
216       Ctrl-Q
217           Unfreeze display, resume normal operation.
218
219   NMEA support
220       (These remarks apply to not just generic NMEA devices but all extended
221       NMEA devices for which gpsmon presently has support.)
222
223       All fields are raw data from the GPS except (a) the "Cooked PVT" window
224       near top of screen, provided as a check and (b) the "PPS offset" field.
225
226       There are no device-specific commands. Which generic commands are
227       available may vary by type: examine the output of gpsmon -l to learn
228       more.
229
230   SiRF support
231       Most information is raw from the GPS. Underlined fields are derived by
232       translation from ECEF coordinates or application of leap-second and
233       local time-zone offsets. 1PPS is the clock lag as usual.
234
235       The following commands are supported for SiRF GPSes only:
236
237       A
238           (Direct mode only.) Toggle reporting of 50BPS subframe data.
239
240       M
241           (Direct mode only.) Set (M1) or clear (M0) static navigation. The
242           SiRF documentation says "Static navigation is a position filter
243           designed to be used with motor vehicles. When the vehicle’s
244           velocity falls below a threshold, the position and heading are
245           frozen, and velocity is set to zero. This condition will continue
246           until the computed velocity rises above 1.2 times the threshold or
247           until the computed position is at least a set distance from the
248           frozen place. The threshold velocity and set distance may vary with
249           software versions."
250
251       Non-static mode is designed for use with road navigation software,
252       which often snaps the reported position to the nearest road within some
253       uncertainty radius. You probably want to turn static navigation off for
254       pedestrian use, as it is likely to report speed zero and position
255       changing in large jumps.
256
257       P
258           (Direct mode only.) Toggle navigation-parameter display mode.
259           Toggles between normal display and one that shows selected
260           navigation parameters from MID 19, including the Static Navigation
261           bit toggled by the 'M' command.
262
263       To interpret what you see, you will need a copy of the SiRF Binary
264       Protocol Reference Manual.
265
266   u-blox support
267       Most information is raw from the GPS. Underlined fields are derived by
268       translation from ECEF coordinates. 1PPS is the clock lag as usual.
269       There are no per-type special commands.
270

BUGS AND LIMITATIONS

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

RETURN VALUES

277       0
278           on success.
279
280       1
281           on failure
282

SEE ALSO

284       gpsd(8), cgps, (1)gpsctl(1), gps(1), *xgps(1)
285

RESOURCES

287       Project web site: https://gpsd.io/
288

COPYING

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

AUTHOR

294       Eric S. Raymond
295
296
297
298GPSD, Version 3.25                2023-01-10                         GPSMON(1)
Impressum