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

NAME

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

SYNOPSIS

9       gpsmon [-L] [-V] [-h] [-n] [-a] [-l logfile] [-t driver-prefix]
10              [[ server [:port [:device]] | device]] [-D debuglevel]
11

DESCRIPTION

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
20       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
26       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
32       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
38       gpsmon accepts an -h option that displays a usage message, or a -V
39       option to dump the package version and exit.
40
41       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
53       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
57       example.com:2317
58           Look at port 2317 on example.com, trying both IPv4 and IPv6.
59
60       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
64       [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
68       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
74       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
79       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
83       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
88       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
93       The -n option forces gpsmon to request NMEA0183 packets instead of the
94       raw datastream from gpsd.
95
96       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
103       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
108       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
113       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

COMMANDS

120       The following device-independent commands are available while gpsmon is
121       running:
122
123       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
133           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
138           This command will generally do nothing after the first time you use
139           it, because the device type will already have been discovered.
140
141       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
146       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
154       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
160           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
165       q
166           Quit gpsmon. Control-C, or whatever your current interrupt
167           character is, works as well.
168
169       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
178           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
187       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
195       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
204       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
209       Ctrl-S
210           Freeze display, suspend scrolling in debug window.
211
212       Ctrl-Q
213           Unfreeze display, resume normal operation.
214
215   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
219       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
222       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
226   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
231       The following commands are supported for SiRF GPSes only:
232
233       A
234           (Direct mode only.) Toggle reporting of 50BPS subframe data.
235
236       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
247           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
253       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
259       To interpret what you see, you will need a copy of the SiRF Binary
260       Protocol Reference Manual.
261
262   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

BUGS AND LIMITATIONS

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

SEE ALSO

273       gpsd(8), gpsdctl(8), gps(1), libgps(3), libgpsmm(3), gpsprof(1),
274       gpsfake(1), gpsctl(1), gpscat(1).  gpspipe(1).
275

AUTHOR

277       Eric S. Raymond <esr@thyrsus.com>.
278
279
280
281The GPSD Project                  17 Feb 2009                        GPSMON(1)
Impressum