1GPSMON(1) GPSD Documentation GPSMON(1)
2
6 gpsmon - real-time GPS packet monitor and control utility
7
9 gpsmon [OPTIONS} [server[:port[:device]]]
10 gpsmon -h
12 gpsmon -V
14
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 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. There are many raw data types that "gpsd*
26 knows about that gpsmon does not. In particular, this tool does not do
27 any interpolation or modeling to derive climb/sink or error estimates.
28 Nor does it discard altitude reports when the fix quality is too low.
29 The casue gpsd user will be better served by the cgps client which
31 display navigation data the same way for all GNSS recivers that gpsd
32 supports.
33 Unlike gpsd, gpsmon never writes control or probe strings to the device
35 unless you explicitly tell it to. Thus, while it will auto-sync to
36 binary packet types, it won’t automatically recognize a device shipping
37 an extended NMEA protocol as anything other than a plain NMEA device.
38 Use the -t option or the t to work around this.
39 gpsmon is a designed to run in a terminal emulator with a minimum 25x80
41 size; the non-GUI interface is a design choice made to accommodate
42 users operating in constrained environments and over telnet or ssh
43 connections. If run in a larger window, the size of the packet-log
44 window will be increased to fit.
45 After startup (without -a or --nocurses), the top part of the screen
47 reports the contents of several especially interesting packet types.
48 The "PPS" field, if nonempty, is the delta between the last 1PPS top of
49 second and the system clock at that time.
50 The bottom half of the screen is a scrolling hex dump of all packets
52 the GPS is issuing. If the packet type is textual, any trailing CR/LF
53 is omitted. Dump lines beginning ">>>" represent control packets sent
54 to the GPS. Lines consisting of "PPS" surrounded by dashes, if present,
55 indicate 1PPS and the start of the reporting cycle.
56 Unlike gpsd, gpsmon when run in direct mode does not do its own device
58 probing. Thus, in particular, if you point it at a GPS with a native
59 binary mode that happens to be emitting NMEA, it won’t identify the
60 actual type unless the device emits a recognizable NMEA trigger
61 sentence. The -t, --type option may help you.
62 gpsmon does not require root privileges, except maybe to access the
64 serial port in direct mode. It will run fine as root.
65
67 -?, -h, --help
68 Print a usage message and exit.
69 -a, --nocurses
71 Enables a special debugging mode that does not use screen painting.
72 Packets are dumped normally, any character typed suspends packet
73 dumping and brings up a command prompt. This feature will mainly be
74 of interest to GPSD developers.
75 -d LVL, --debug LVL
77 Enable packet-getter debugging output and is probably only useful
78 to developers of the GPSD code. Consult the packet-getter source
79 code for relevant values.
80 -l FILE, --logfile FILE
82 Set up logging to a specified file (FILE) to start immediately on
83 device open. This may be useful is, for example, you want to
84 capture the startup message from a device that displays firmware
85 version information there.
86 -L, --list
88 Lists a table showing which GPS device types this gpsmon has
89 built-in support for, and which generic commands can be applied to
90 which GPS types, and then exits. Note that this does not list
91 type-specific commands associated with individual GPS types.
92 -n, --nmea
94 Force gpsmon to request NMEA0183 packets instead of the raw data
95 stream from gpsd.
96 -t TYPE, --type TYPE
98 Set a fallback type (TYPE). Give it a string that is a
99 distinguishing prefix of exactly one driver type name; this will be
100 used for mode, speed, and rate switching if the driver selected by
101 the packet type lacks those capabilities. Most useful when the
102 packet type is NMEA but the device is known to have a binary mode,
103 such as SiRF binary.
104
106 This program may be run in either of two modes, as a client for the
107 gpsd daemon (and its associated control socket) or directly connected
108 to a specified serial device.
109 By default, clients collect data from the local gpsd daemon running on
111 localhost, using the default GPSD port 2947. The optional argument to
112 any client may override this behavior: [server[:port[:device]]]
113 For further explanation, and examples, see the ARGUMENTS section in the
115 gps(1) man page
116 If instead the argument contains slashes but no colons will it be
118 treated as a serial device for direct connection. In direct-connect
119 mode gpsmon will hunt for a correct baud rate and lock on to it
120 automatically.
121
123 The following device-independent commands are available while gpsmon is
124 running:
125 i
127 (Direct mode only.) Enable/disable subtype probing and reinitialize
128 the driver. In normal operation, gpsmon does not send configuration
129 strings to the device (except for wakeup strings needed to get it
130 to send data, if any). The command 'i1' causes it to send the same
131 sequence of subtype probes that gpsd would. The command 'i0' turns
132 off probing; 'i' alone toggles the bit. In either case, the current
133 driver is re-selected; if the probe bit is enabled, probes will
134 begin to be issued immediately.
135 Note that enabling probing might flip the device into another mode; in
137 particular, it will flip a SiRF chip into binary mode as if you had
138 used the "n" command. This is due to a limitation in the SiRF firmware
139 that we can’t fix.
140 This command will generally do nothing after the first time you use it,
142 because the device type will already have been discovered.
143 c
145 (Direct mode only.) Change cycle time. Follow it with a number
146 interpreted as a cycle time in seconds. Most devices have a fixed
147 cycle time of 1 second, so this command may fail with a message.
148 l
150 Toggle packet logging. If packet logging is on, it will be turned
151 off and the log closed. If it is off, logging to the filename
152 following the l will be enabled. Differs from simply capturing the
153 data from the GPS device in that only whole packets are logged. The
154 logfile is opened for append, so you can log more than one portion
155 of the packet stream and they will be stitched together correctly.
156 n
158 (Direct mode only.) With an argument of 0, switch device to NMEA
159 mode at current speed; with an argument of 1, change to binary
160 (native) mode. With no argument, toggle the setting. Will show an
161 error if the device doesn’t have such modes.
162 After you switch a dual-protocol GPS to NMEA mode with this command, it
164 retains the information about the original type and its control
165 capabilities. That is why the device type listed before the prompt
166 doesn’t change.
167 q
169 Quit gpsmon. Control-C, or whatever your current interrupt
170 character is, works as well.
171 s
173 (Direct mode only.) Change baud rate. Follow it with a number
174 interpreted as bits per second, for example "s9600". The speed
175 number may optionally be followed by a colon and a
176 wordlength-parity-stopbits specification in the traditional style,
177 e.g 8N1 (the default), 7E1, etc. Some devices don’t support serial
178 modes other than their default, so this command may fail with a
179 message.
180 Note
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 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 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 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 Ctrl-S
213 Freeze display, suspend scrolling in debug window.
214 Ctrl-Q
216 Unfreeze display, resume normal operation.
217 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 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 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 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 The following commands are supported for SiRF GPSes only:
235 A
237 (Direct mode only.) Toggle reporting of 50BPS subframe data.
238 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 Non-static mode is designed for use with road navigation software,
251 which often snaps the reported position to the nearest road within some
252 uncertainty radius. You probably want to turn static navigation off for
253 pedestrian use, as it is likely to report speed zero and position
254 changing in large jumps.
255 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 To interpret what you see, you will need a copy of the SiRF Binary
263 Protocol Reference Manual.
264 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
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
276 0
277 on success.
278 1
280 on failure
281
283 gpsd(8), gpsctl(1), gps(1), cgps(3)
284
286 Project web site: https://gpsd.io/
287
289 This file is Copyright 2013 by the GPSD project
290 SPDX-License-Identifier: BSD-2-clause
291
293 Eric S. Raymond
294GPSD, Version 3.23.1 2021-09-03 GPSMON(1)