1GPSMON(1) GPSD Documentation GPSMON(1)
2
6 gpsmon - real-time GPS packet monitor and control utility
7
9 gpsmon [-h] [-L] [-V] [-l logfile] [-F control-socket]
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.
17 This tool used to be called 'sirfmon', and worked only on SiRF devices
19 (and the command set has changed to resemble the command switches of
20 gpsctl). It now has support for a range of NMEA devices as well;
21 support for other (binary-protocol) device types is planned. It will
22 behave sanely, just dumping packets, when connected to a GPS type it
23 knows nothing about.
24 gpsmon differs from a navigation client in that it mostly dumps raw
26 data from the GPS, with only enough data-massaging to allow checks
27 against expected output. In particular, this tool does not do any
28 interpolation or modeling to derive climb/sink or error estimates. Nor
29 does it discard altitude reports when the fix quality is too low.
30 gpsmon is a designed to run in a terminal emulator with a minimum 25x80
32 size; the non-GUI interface is a design choice made to accommodate
33 users operating in constrained environments and over telnet or ssh
34 connections. If run in a larger window, the size of the packet-log
35 window will be increased to fit.
36 gpsmon accepts an -h option that displays a usage message, or a -V
38 option to dump the package version and exit.
39 This program may be run in either of two modes, as a client for the
41 gpsd daemon (and its associated control socket) or directly connected
42 to a specified serial device. When run with no argument, it attempts to
43 connect to the daemon. If the argument looks like a server:port
44 specification it will also attempt to connect to the daemon. If the
45 argument looks like a bare server name it will attempt to connect to a
46 daemon running on the default gpsd port on that server. Only if the
47 device argument contains slashes but no colons will it be treated as a
48 serial device for direct connection. In direct-connect mode gpsmon will
49 hunt for a correct baud rate and lock on to it automatically.
50 The -F option is only valid in client mode; it specifies a control
52 socket to which the program should send device control strings. You
53 must specify a valid pathname of a Unix-domain socket on your local
54 filesystem.
55 The -D option enables packet-getter debugging output and is probably
57 only useful to developers of the GPSD code. Consult the packet-getter
58 source code for relevant values.
59 The -L option lists a table showing which GPS device types gpsmon has
61 built-in support for, and which generic commands can be applied to
62 which GPS types, and then exits. Note that this does not list
63 type-specific commands associated with individual GPS types.
64 The -l option sets up logging to a specified file to start immediately
66 on device open. This may be useful is, for example, you want to capture
67 the startup message from a device that displays firmware version
68 information there.
69 After startup, the top part of the screen reports the contents of
71 several especially interesting packet types. The bottom half of the
72 screen is a scrolling hex dump of all packets the GPS is issuing. Dump
73 lines beginning >>> represent control packets sent to the GPS.
74
76 The following device-independent comands are available while gpsmon is
77 running:
78 i
80 Enable/disable subtype probing and reinitialize the driver. In
81 normal operation, gpsmon does not send configuration strings to the
82 device (except for wakeup strings needed to get it to send data, if
83 any). The command 'i1' causes it to send the same sequence of
84 subtype probes that gpsd would. The command 'i0' turns off probing;
85 'i' alone toggles the bit. In either case, the current driver is
86 re-selected; if the probe bit is enabled, probes will begin to be
87 issued immediately.
88 Note that enabling probing might flip the device into another mode;
90 in particular, it will flip a SiRF chip into binary mode as if you
91 had used the “n” command. This is due to a limitation in the SiRF
92 firmware that we can't fix.
93 c
95 Change cycle time. Follow it with a number interpreted as a cycle
96 time in seconds. Most devices have a fixed cycle time of 1 second,
97 so this command may fail with a message.
98 l
100 Toggle packet logging. If packet logging is on, it will be turned
101 off and the log closed. If it is off, logging to the filename
102 following the l will be enabled. Differs from simply capturing the
103 data from the GPS device in that only whole packets are logged. The
104 logfile is opened for append, so you can log more than one portion
105 of the packet stream and they will be stitched together correctly.
106 n
108 With an argument of 0, switch device to NMEA mode at current speed;
109 with an argument of 1, change to binary (native) mode. With no
110 argument, toggle the setting. Will show an error if the device
111 doesn't have such modes.
112 q
114 Quit gpsmon. Control-C, or whatever your current interrupt chracter
115 is, works as well.
116 s
118 Change baud rate. Follow it with a number interpreted as bits per
119 second, for example "s9600". The speed number may optionally be
120 followed by a colon and a wordlength-parity-stopbits specification
121 in the traditional style, e.g 8N1 (the default), 7E1, etc. Some
122 devices don't support serial modes other than their default, so
123 this command may fail with a message.
124 Use this command with caution. On USB and Bluetooth GPSes it is
126 also possible for serial mode setting to fail either because the
127 serial adaptor chip does not support non-8N1 modes or because the
128 device firmware does not properly synchronize the serrial adaptor
129 chip with the UART on the GPS chipset whjen the speed changes.
130 These failures can hang your device, possibly requiring a GPS power
131 cycle or (in extreme cases) physically disconnecting the NVRAM
132 backup battery.
133 t
135 Force a switch of monitoring type. Follow it with a string that is
136 unique to the name of a gpsd driver with gpsmon support; gpsmon
137 will switch to using that driver and display code. Will show an
138 error message if there is no matching gpsd driver, or multiple
139 matches, or the unique match has no display support in gpsmon.
140 x
142 Send hex payload to device. Following the command letter you may
143 type hex digit pairs; end with a newline. These will become the
144 payload of a control packet shipped to the device. The packet will
145 be wrapped with headers, trailers, and checksum appropriate for the
146 current driver type. The first one or two bytes of the payload may
147 be specially interpreted, see the description of the -x of
148 gpsctl(1).
149 X
151 Send raw hex bytes to device. Following the command letter you may
152 type hex digit pairs; end with a newline. These will be shipped to
153 the device.
154 Ctrl-S
156 Freeze display, suspend scrolling in debug window.
157 Ctrl-Q
159 Unfreeze display, resume normal operation.
160 NMEA support
162 (These remarks apply to not just generic NMEA devices but all extended
163 NMEA devices for which gpsmon presently has support.)
164 All fields are raw data from the GPS except the "Cooked PVT" window
166 near top of screen, provided as a sheck.
167 There are no device-specific commands. Which generic commands are
169 available may vary by type: examine the output of gpsmon -l to learn
170 more.
171 SiRF support
173 Most information is raw from the GPS. Underlined fields are derived by
174 translation from ECEF coordinates or application of leap-second and
175 local time-zone offsets.
176 The following commands are supported for SiRF GPSes only:
178 A
180 Toggle reporting of 50BPS subframe data.
181 M
183 Set (M1) or clear (M0) static navigation. The SiRF documentation
184 says “Static navigation is a position filter designed to be used
185 with motor vehicles. When the vehicle's velocity falls below a
186 threshold, the position and heading are frozen, and velocity is set
187 to zero. This condition will continue until the computed velocity
188 rises above 1.2 times the threshold or until the computed position
189 is at least a set distance from the frozen place. The threshold
190 velocity and set distance may vary with software versions.”
191 Non-static mode is designed for use with road navigation software,
193 which often snaps the reported position to the nearest road within
194 some uncertainty radius. You probably want to turn static
195 navigation off for pedestrian use, as it is likely to report speed
196 zero and position changing in large jumps.
197 P
199 Toggle navigation-parameter display mode. Toggles between normal
200 display and one that shows selected navigation parameters from MID
201 19, including the Static Navigation bit toggled by the 'M' command.
202 To interpret what you see, you will need a copy of the SiRF Binary
204 Protocol Reference Manual.
205
207 /var/run/gpsd.sock
208 The default location of the control socket.
209
211 If you run gpsmon in client mode, and kill the daemon while gpsmon is
212 still running, gpsmon will hang. Don't do that...
213
215 gpsd(8), gps(1), libgps(3), libgpsd(3), gpsprof(1), gpsfake(1),
216 gpsctl(1), gpscat(1). gpspipe(1).
217
219 Eric S. Raymond esr@thyrsus.com. This code is part of the gpsd toolset;
220 there is a project page for gpsd here[1].
221
223 1. here
224 http://gpsd.berlios.de/
225The GPSD Project 17 Feb 2009 GPSMON(1)