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. 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 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 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 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 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 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 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 gpsmon does not require root privileges, except maybe to access the
65 serial port in direct mode. It will run fine as root.
66
68 -?, -h, --help
69 Print a usage message and exit.
70 -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 -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 -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 -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 -n, --nmea
95 Force gpsmon to request NMEA0183 packets instead of the raw data
96 stream from gpsd.
97 -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
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 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 For further explanation, and examples, see the ARGUMENTS section in the
116 gps(1) man page
117 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
124 The following device-independent commands are available while gpsmon is
125 running:
126 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 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 This command will generally do nothing after the first time you use it,
143 because the device type will already have been discovered.
144 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 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 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 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 q
170 Quit gpsmon. Control-C, or whatever your current interrupt
171 character is, works as well.
172 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 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 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 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 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 Ctrl-S
214 Freeze display, suspend scrolling in debug window.
215 Ctrl-Q
217 Unfreeze display, resume normal operation.
218 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 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 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 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 The following commands are supported for SiRF GPSes only:
236 A
238 (Direct mode only.) Toggle reporting of 50BPS subframe data.
239 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 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 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 To interpret what you see, you will need a copy of the SiRF Binary
264 Protocol Reference Manual.
265 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
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
277 0
278 on success.
279 1
281 on failure
282
284 gpsd(8), cgps, (1)gpsctl(1), gps(1), *xgps(1)
285
287 Project web site: https://gpsd.io/
288
290 This file is Copyright 2013 by the GPSD project
291 SPDX-License-Identifier: BSD-2-clause
292
294 Eric S. Raymond
295GPSD, Version 3.25 2023-01-10 GPSMON(1)