1GPSMON(1) GPSD Documentation GPSMON(1)
2
6 gpsmon - real-time GPS packet monitor and control utility
7
9 gpsmon [-L] [-V] [-h] [-n] [-a] [-l logfile] [-t driver-prefix]
10 [[ server [:port [:device]] | device]] [-D debuglevel]
11
13 gpsmon is a monitor that watches packets coming from a GPS and displays
14 them along with diagnostic information. It supports commands that can
15 be used to tweak GPS settings in various ways; some are
16 device-independent, some vary with the GPS chipset type. It will behave
17 sanely, just dumping packets, when connected to a GPS type it knows
18 nothing about.
19 gpsmon differs from a navigation client in that it mostly dumps raw
21 data from the GPS, with only enough data-massaging to allow checks
22 against expected output. In particular, this tool does not do any
23 interpolation or modeling to derive climb/sink or error estimates. Nor
24 does it discard altitude reports when the fix quality is too low.
25 Unlike gpsd, gpsmon never writes control or probe strings to the device
27 unless you explicitly tell it to. Thus, while it will auto-sync to
28 binary packet types, it won't automatically recognize a device shipping
29 an extended NMEA protocol as anything other than a plain NMEA device.
30 Use the -t option or the t to work around this.
31 gpsmon is a designed to run in a terminal emulator with a minimum 25x80
33 size; the non-GUI interface is a design choice made to accommodate
34 users operating in constrained environments and over telnet or ssh
35 connections. If run in a larger window, the size of the packet-log
36 window will be increased to fit.
37 gpsmon accepts an -h option that displays a usage message, or a -V
39 option to dump the package version and exit.
40 This program may be run in either of two modes, as a client for the
42 gpsd daemon (and its associated control socket) or directly connected
43 to a specified serial device. When run with no argument, it attempts to
44 connect to the daemon. If the argument begins with a server:port
45 specification it will also attempt to connect to the daemon. If the
46 argument looks like a bare server name it will attempt to connect to a
47 daemon running on the default gpsd port on that server. Only if the
48 device argument contains slashes but no colons will it be treated as a
49 serial device for direct connection. In direct-connect mode gpsmon will
50 hunt for a correct baud rate and lock on to it automatically. Possible
51 cases look like this:
52 localhost:/dev/ttyS1
54 Look at the default port of localhost, trying both IPv4 and IPv6
55 and watching output from serial device 1.
56 example.com:2317
58 Look at port 2317 on example.com, trying both IPv4 and IPv6.
59 71.162.241.5:2317:/dev/ttyS3
61 Look at port 2317 at the specified IPv4 address, collecting data
62 from attached serial device 3.
63 [FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5
65 Look at port 2317 at the specified IPv6 address, collecting data
66 from attached serial device 5.
67 Unlike gpsd, gpsmon run in direct mode does not do its own device
69 probing. Thus, in particular, if you point it at a GPS with a native
70 binary mode that happens to be emitting NMEA, it won't identify the
71 actual type unless the device emits a recognizable NMEA trigger
72 sentence. The -t and -i options may help you.
73 The -F option is only valid in client mode; it specifies a control
75 socket to which the program should send device control strings. You
76 must specify a valid pathname of a Unix-domain socket on your local
77 filesystem.
78 The -D option enables packet-getter debugging output and is probably
80 only useful to developers of the GPSD code. Consult the packet-getter
81 source code for relevant values.
82 The -L option lists a table showing which GPS device types gpsmon has
84 built-in support for, and which generic commands can be applied to
85 which GPS types, and then exits. Note that this does not list
86 type-specific commands associated with individual GPS types.
87 The -l option sets up logging to a specified file to start immediately
89 on device open. This may be useful is, for example, you want to capture
90 the startup message from a device that displays firmware version
91 information there.
92 The -n option forces gpsmon to request NMEA0183 packets instead of the
94 raw datastream from gpsd.
95 The -t option sets up a fallback type. Give it a string that is a
97 distinguishing prefix of exactly one driver type name; this will be
98 used for mode, speed, and rate switching if the driver selected by the
99 packet type lacks those capabilities. Most useful when the packet type
100 is NMEA but the device is known to have a binary mode, such as SiRF
101 binary.
102 The -a option enables a special debugging mode that does not use screen
104 painting. Packets are dumped normally; any character typed suspends
105 packet dumping and brings up a command prompt. This feature will mainly
106 be of interest to GPSD developers.
107 After startup (without -a), the top part of the screen reports the
109 contents of several especially interesting packet types. The "PPS"
110 field, if nonempty, is the delta between the last 1PPS top of second
111 and the system clock at that time.
112 The bottom half of the screen is a scrolling hex dump of all packets
114 the GPS is issuing. If the packet type is textual, any trailing CR/LF
115 is omitted. Dump lines beginning >>> represent control packets sent to
116 the GPS. Lines consisting of "PPS" surrounded by dashes, if present,
117 indicate 1PPS and the start of the reporting cycle.
118
120 The following device-independent commands are available while gpsmon is
121 running:
122 i
124 (Direct mode only.) Enable/disable subtype probing and reinitialize
125 the driver. In normal operation, gpsmon does not send configuration
126 strings to the device (except for wakeup strings needed to get it
127 to send data, if any). The command 'i1' causes it to send the same
128 sequence of subtype probes that gpsd would. The command 'i0' turns
129 off probing; 'i' alone toggles the bit. In either case, the current
130 driver is re-selected; if the probe bit is enabled, probes will
131 begin to be issued immediately.
132 Note that enabling probing might flip the device into another mode;
134 in particular, it will flip a SiRF chip into binary mode as if you
135 had used the “n” command. This is due to a limitation in the SiRF
136 firmware that we can't fix.
137 This command will generally do nothing after the first time you use
139 it, because the device type will already have been discovered.
140 c
142 (Direct mode only.) Change cycle time. Follow it with a number
143 interpreted as a cycle time in seconds. Most devices have a fixed
144 cycle time of 1 second, so this command may fail with a message.
145 l
147 Toggle packet logging. If packet logging is on, it will be turned
148 off and the log closed. If it is off, logging to the filename
149 following the l will be enabled. Differs from simply capturing the
150 data from the GPS device in that only whole packets are logged. The
151 logfile is opened for append, so you can log more than one portion
152 of the packet stream and they will be stitched together correctly.
153 n
155 (Direct mode only.) With an argument of 0, switch device to NMEA
156 mode at current speed; with an argument of 1, change to binary
157 (native) mode. With no argument, toggle the setting. Will show an
158 error if the device doesn't have such modes.
159 After you switch a dual-protocol GPS to NMEA mode with this
161 command, it retains the information about the original type and its
162 control capabilities. That is why the device type listed before the
163 prompt doesn't change.
164 q
166 Quit gpsmon. Control-C, or whatever your current interrupt
167 character is, works as well.
168 s
170 (Direct mode only.) Change baud rate. Follow it with a number
171 interpreted as bits per second, for example "s9600". The speed
172 number may optionally be followed by a colon and a
173 wordlength-parity-stopbits specification in the traditional style,
174 e.g 8N1 (the default), 7E1, etc. Some devices don't support serial
175 modes other than their default, so this command may fail with a
176 message.
177 Use this command with caution. On USB and Bluetooth GPSes it is
179 also possible for serial mode setting to fail either because the
180 serial adaptor chip does not support non-8N1 modes or because the
181 device firmware does not properly synchronize the serial adaptor
182 chip with the UART on the GPS chipset when the speed changes. These
183 failures can hang your device, possibly requiring a GPS power cycle
184 or (in extreme cases) physically disconnecting the NVRAM backup
185 battery.
186 t
188 (Direct mode only.) Force a switch of monitoring type. Follow it
189 with a string that is unique to the name of a gpsd driver with
190 gpsmon support; gpsmon will switch to using that driver and display
191 code. Will show an error message if there is no matching gpsd
192 driver, or multiple matches, or the unique match has no display
193 support in gpsmon.
194 x
196 (Direct mode only.) Send hex payload to device. Following the
197 command letter you may type hex digit pairs; end with a newline.
198 These will become the payload of a control packet shipped to the
199 device. The packet will be wrapped with headers, trailers, and
200 checksum appropriate for the current driver type. The first one or
201 two bytes of the payload may be specially interpreted, see the
202 description of the -x of gpsctl(1).
203 X
205 (Direct mode only.) Send raw hex bytes to device. Following the
206 command letter you may type hex digit pairs; end with a newline.
207 These will be shipped to the device.
208 Ctrl-S
210 Freeze display, suspend scrolling in debug window.
211 Ctrl-Q
213 Unfreeze display, resume normal operation.
214 NMEA support
216 (These remarks apply to not just generic NMEA devices but all extended
217 NMEA devices for which gpsmon presently has support.)
218 All fields are raw data from the GPS except (a) the "Cooked PVT" window
220 near top of screen, provided as a check and (b) the "PPS offset" field.
221 There are no device-specific commands. Which generic commands are
223 available may vary by type: examine the output of gpsmon -l to learn
224 more.
225 SiRF support
227 Most information is raw from the GPS. Underlined fields are derived by
228 translation from ECEF coordinates or application of leap-second and
229 local time-zone offsets. 1PPS is the clock lag as usual.
230 The following commands are supported for SiRF GPSes only:
232 A
234 (Direct mode only.) Toggle reporting of 50BPS subframe data.
235 M
237 (Direct mode only.) Set (M1) or clear (M0) static navigation. The
238 SiRF documentation says “Static navigation is a position filter
239 designed to be used with motor vehicles. When the vehicle's
240 velocity falls below a threshold, the position and heading are
241 frozen, and velocity is set to zero. This condition will continue
242 until the computed velocity rises above 1.2 times the threshold or
243 until the computed position is at least a set distance from the
244 frozen place. The threshold velocity and set distance may vary with
245 software versions.”
246 Non-static mode is designed for use with road navigation software,
248 which often snaps the reported position to the nearest road within
249 some uncertainty radius. You probably want to turn static
250 navigation off for pedestrian use, as it is likely to report speed
251 zero and position changing in large jumps.
252 P
254 (Direct mode only.) Toggle navigation-parameter display mode.
255 Toggles between normal display and one that shows selected
256 navigation parameters from MID 19, including the Static Navigation
257 bit toggled by the 'M' command.
258 To interpret what you see, you will need a copy of the SiRF Binary
260 Protocol Reference Manual.
261 u-blox support
263 Most information is raw from the GPS. Underlined fields are derived by
264 translation from ECEF coordinates. 1PPS is the clock lag as usual.
265 There are no per-type special commands.
266
268 The PPS Offset field will never be updated when running in client mode,
269 even if you can see PPS events in the packet window. This limitation
270 may be fixed in a future release.
271
273 gpsd(8), gpsdctl(8), gps(1), libgps(3), libgpsmm(3), gpsprof(1),
274 gpsfake(1), gpsctl(1), gpscat(1). gpspipe(1).
275
277 Eric S. Raymond <esr@thyrsus.com>.
278The GPSD Project 17 Feb 2009 GPSMON(1)