1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!-- 3This file is Copyright (c) 2010-2019 by the GPSD project 4SPDX-License-Identifier: BSD-2-clause 5--> 6<!DOCTYPE refentry PUBLIC 7 "-//OASIS//DTD DocBook XML V4.1.2//EN" 8 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> 9<refentry id='gpsmon.1'> 10<refentryinfo><date>17 Feb 2009</date></refentryinfo> 11<refmeta> 12<refentrytitle>gpsmon</refentrytitle> 13<manvolnum>1</manvolnum> 14<refmiscinfo class="source">The GPSD Project</refmiscinfo> 15<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> 16</refmeta> 17<refnamediv id='name'> 18<refname>gpsmon</refname> 19<refpurpose>real-time GPS packet monitor and control utility</refpurpose> 20</refnamediv> 21<refsynopsisdiv id='synopsis'> 22 23<cmdsynopsis> 24 <command>gpsmon</command> 25 <arg choice='opt'>-L </arg> 26 <arg choice='opt'>-V </arg> 27 <arg choice='opt'>-h </arg> 28 <arg choice='opt'>-n </arg> 29 <arg choice='opt'>-a </arg> 30 <arg choice='opt'>-l <replaceable>logfile</replaceable></arg> 31 <arg choice='opt'>-t <replaceable>driver-prefix</replaceable></arg> 32 <arg choice='opt'> 33 <group> 34 <arg choice='plain'> 35 <replaceable>server</replaceable> 36 <group> 37 <replaceable>:port</replaceable> 38 <group><replaceable>:device</replaceable></group> 39 </group> 40 </arg> 41 <arg choice='plain'><replaceable>device</replaceable></arg> 42 </group> 43 </arg> 44 <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg> 45</cmdsynopsis> 46</refsynopsisdiv> 47 48<refsect1 id='description'><title>DESCRIPTION</title> 49 50<para><application>gpsmon</application> is a monitor that watches 51packets coming from a GPS and displays them along with diagnostic 52information. It supports commands that can be used to tweak GPS 53settings in various ways; some are device-independent, some vary with 54the GPS chipset type. It will behave sanely, just dumping packets, 55when connected to a GPS type it knows nothing about.</para> 56 57<para><application>gpsmon</application> differs from a navigation 58client in that it mostly dumps raw data from the GPS, with only enough 59data-massaging to allow checks against expected output. In 60particular, this tool does not do any interpolation or modeling 61to derive climb/sink or error estimates. Nor does it discard 62altitude reports when the fix quality is too low.</para> 63 64<para>Unlike <application>gpsd</application>, 65<application>gpsmon</application> never writes control or probe 66strings to the device unless you explicitly tell it to. Thus, while 67it will auto-sync to binary packet types, it won't automatically 68recognize a device shipping an extended NMEA protocol as anything 69other than a plain NMEA device. Use the <option>-t</option> option or 70the <command>t</command> to work around this.</para> 71 72<para><application>gpsmon</application> is a designed to run in a 73terminal emulator with a minimum 25x80 size; the non-GUI interface is 74a design choice made to accommodate users operating in constrained 75environments and over telnet or ssh connections. If run in a larger 76window, the size of the packet-log window will be increased to 77fit.</para> 78 79<para><application>gpsmon</application> accepts an -h option that 80displays a usage message, or a -V option to dump the package 81version and exit.</para> 82 83<para>This program may be run in either of two modes, as a client for 84the <application>gpsd</application> daemon (and its associated control 85socket) or directly connected to a specified serial device. When run 86with no argument, it attempts to connect to the daemon. If the 87argument begins with a server:port specification it will also attempt 88to connect to the daemon. If the argument looks like a bare server 89name it will attempt to connect to a daemon running on the default 90gpsd port on that server. Only if the device argument contains 91slashes but no colons will it be treated as a serial device for direct 92connection. In direct-connect mode <application>gpsmon</application> 93will hunt for a correct baud rate and lock on to it 94automatically. Possible cases look like this:</para> 95 96<variablelist> 97<varlistentry> 98<term>localhost:/dev/ttyS1</term> 99<listitem><para>Look at the default port of localhost, trying both 100IPv4 and IPv6 and watching output from serial device 1.</para></listitem> 101</varlistentry> 102<varlistentry> 103<term>example.com:2317</term> 104<listitem><para>Look at port 2317 on example.com, trying both 105IPv4 and IPv6.</para></listitem> 106</varlistentry> 107<varlistentry> 108<term>71.162.241.5:2317:/dev/ttyS3</term> 109<listitem><para>Look at port 2317 at the specified IPv4 110address, collecting data from attached serial device 3.</para></listitem> 111</varlistentry> 112<varlistentry> 113<term>[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5</term> 114<listitem><para>Look at port 2317 at the specified IPv6 115address, collecting data from attached serial device 5.</para></listitem> 116</varlistentry> 117</variablelist> 118 119<para>Unlike <application>gpsd</application>, 120<application>gpsmon</application> run in direct mode does not do its 121own device probing. Thus, in particular, if you point it at a 122GPS with a native binary mode that happens to be emitting NMEA, it 123won't identify the actual type unless the device emits a recognizable 124NMEA trigger sentence. The -t and -i options may help you.</para> 125 126<para>The -F option is only valid in client mode; it specifies a 127control socket to which the program should send device control 128strings. You must specify a valid pathname of a Unix-domain socket on 129your local filesystem.</para> 130 131<para>The -D option enables packet-getter debugging output and is 132probably only useful to developers of the GPSD code. Consult the 133packet-getter source code for relevant values.</para> 134 135<para>The -L option lists a table showing which GPS device types 136<application>gpsmon</application> has built-in support for, and which 137generic commands can be applied to which GPS types, and then 138exits. Note that this does not list type-specific commands associated 139with individual GPS types.</para> 140 141<para>The -l option sets up logging to a specified file to start 142immediately on device open. This may be useful is, for example, 143you want to capture the startup message from a device that displays 144firmware version information there.</para> 145 146<para>The -n option forces gpsmon to request NMEA0183 packets instead of the 147raw datastream from gpsd.</para> 148 149<para>The -t option sets up a fallback type. Give it a string that 150is a distinguishing prefix of exactly one driver type name; this will 151be used for mode, speed, and rate switching if the driver selected 152by the packet type lacks those capabilities. Most useful when the 153packet type is NMEA but the device is known to have a binary mode, 154such as SiRF binary.</para> 155 156<para>The -a option enables a special debugging mode that does not 157use screen painting. Packets are dumped normally; any character 158typed suspends packet dumping and brings up a command prompt. This 159feature will mainly be of interest to GPSD developers.</para> 160 161<para>After startup (without -a), the top part of the screen reports 162the contents of several especially interesting packet types. The 163"PPS" field, if nonempty, is the delta between the last 1PPS top of 164second and the system clock at that time.</para> 165 166<para>The bottom half of the screen is a scrolling hex dump of all 167packets the GPS is issuing. If the packet type is textual, any 168trailing CR/LF is omitted. Dump lines beginning >>> represent 169control packets sent to the GPS. Lines consisting of "PPS" surrounded 170by dashes, if present, indicate 1PPS and the start of the reporting 171cycle.</para> 172 173</refsect1> 174<refsect1 id='commands'><title>COMMANDS</title> 175 176<para>The following device-independent commands are available while 177<application>gpsmon</application> is running:</para> 178 179<variablelist> 180 181<varlistentry> 182<term>i</term> 183<listitem> 184<para>(Direct mode only.) Enable/disable subtype probing and 185reinitialize the driver. In normal operation, 186<application>gpsmon</application> does not send configuration strings 187to the device (except for wakeup strings needed to get it to send 188data, if any). The command 'i1' causes it to send the same sequence of 189subtype probes that <application>gpsd</application> would. The 190command 'i0' turns off probing; 'i' alone toggles the bit. In either 191case, the current driver is re-selected; if the probe bit is enabled, 192probes will begin to be issued immediately.</para> 193 194<para>Note that enabling probing might flip the device into another 195mode; in particular, it will flip a SiRF chip into binary mode as if 196you had used the <quote>n</quote> command. This is due to a 197limitation in the SiRF firmware that we can't fix.</para> 198 199<para>This command will generally do nothing after the first time you 200use it, because the device type will already have been discovered.</para> 201</listitem> 202</varlistentry> 203 204<varlistentry> 205<term>c</term> 206<listitem> 207<para>(Direct mode only.) Change cycle time. Follow it with a number 208interpreted as a cycle time in seconds. Most devices have a fixed 209cycle time of 1 second, so this command may fail with a 210message.</para> 211</listitem> 212</varlistentry> 213 214<varlistentry> 215<term>l</term> 216<listitem> 217<para>Toggle packet logging. If packet logging is on, it will be 218turned off and the log closed. If it is off, logging to the filename 219following the l will be enabled. Differs from simply capturing the 220data from the GPS device in that only whole packets are logged. 221The logfile is opened for append, so you can log more than one 222portion of the packet stream and they will be stitched together 223correctly.</para> 224</listitem> 225</varlistentry> 226 227<varlistentry> 228<term>n</term> 229<listitem> 230<para>(Direct mode only.) With an argument of 0, switch device to NMEA 231mode at current speed; with an argument of 1, change to binary 232(native) mode. With no argument, toggle the setting. Will show an 233error if the device doesn't have such modes.</para> 234 235<para>After you switch a dual-protocol GPS to NMEA mode with this 236command, it retains the information about the original type and its 237control capabilities. That is why the device type listed before the 238prompt doesn't change.</para> 239</listitem> 240</varlistentry> 241 242<varlistentry> 243<term>q</term> 244<listitem> 245<para>Quit <application>gpsmon</application>. Control-C, or whatever 246your current interrupt character is, works as well.</para> 247</listitem> 248</varlistentry> 249 250<varlistentry> 251<term>s</term> 252<listitem> 253<para>(Direct mode only.) Change baud rate. Follow it with a number 254interpreted as bits per second, for example "s9600". The speed number 255may optionally be followed by a colon and a wordlength-parity-stopbits 256specification in the traditional style, e.g 8N1 (the default), 7E1, 257etc. Some devices don't support serial modes other than their 258default, so this command may fail with a message.</para> 259 260<para>Use this command with caution. On USB and Bluetooth GPSes it is 261also possible for serial mode setting to fail either because the 262serial adaptor chip does not support non-8N1 modes or because the 263device firmware does not properly synchronize the serial adaptor chip 264with the UART on the GPS chipset when the speed changes. These 265failures can hang your device, possibly requiring a GPS power cycle or (in 266extreme cases) physically disconnecting the NVRAM backup battery.</para> 267</listitem> 268</varlistentry> 269 270<varlistentry> 271<term>t</term> 272<listitem> 273<para>(Direct mode only.) Force a switch of monitoring type. Follow it 274with a string that is unique to the name of a gpsd driver with 275<application>gpsmon</application> support; 276<application>gpsmon</application> will switch to using that driver and 277display code. Will show an error message if there is no matching gpsd 278driver, or multiple matches, or the unique match has no display 279support in <application>gpsmon</application>.</para> 280</listitem> 281</varlistentry> 282 283<varlistentry> 284<term>x</term> 285<listitem> 286<para>(Direct mode only.) Send hex payload to device. Following the 287command letter you may type hex digit pairs; end with a newline. 288These will become the payload of a control packet shipped to the 289device. The packet will be wrapped with headers, trailers, and 290checksum appropriate for the current driver type. The first one or two 291bytes of the payload may be specially interpreted, see the description 292of the <option>-x</option> of 293<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> 294</listitem> 295</varlistentry> 296 297<varlistentry> 298<term>X</term> 299<listitem> 300<para>(Direct mode only.) Send raw hex bytes to device. Following the 301command letter you may type hex digit pairs; end with a newline. 302These will be shipped to the device.</para> 303</listitem> 304</varlistentry> 305 306<varlistentry> 307<term>Ctrl-S</term> 308<listitem> 309<para>Freeze display, suspend scrolling in debug window.</para> 310</listitem> 311</varlistentry> 312<varlistentry> 313<term>Ctrl-Q</term> 314<listitem> 315<para>Unfreeze display, resume normal operation.</para> 316</listitem> 317</varlistentry> 318</variablelist> 319 320<refsect2><title>NMEA support</title> 321 322<para>(These remarks apply to not just generic NMEA devices 323but all extended NMEA devices for which 324<application>gpsmon</application> presently has support.)</para> 325 326<para>All fields are raw data from the GPS except (a) the "Cooked PVT" 327window near top of screen, provided as a check and (b) the "PPS 328offset" field.</para> 329 330<para>There are no device-specific commands. Which generic 331commands are available may vary by type: examine the output 332of <command>gpsmon -l</command> to learn more.</para> 333</refsect2> 334 335<refsect2><title>SiRF support</title> 336<para>Most information is raw from the GPS. Underlined fields are 337derived by translation from ECEF coordinates or application of 338leap-second and local time-zone offsets. 1PPS is the clock lag as 339usual.</para> 340 341<para>The following commands are supported for SiRF GPSes only:</para> 342 343<variablelist> 344<varlistentry> 345<term>A</term> 346<listitem> 347<para>(Direct mode only.) Toggle reporting of 50BPS subframe data.</para> 348</listitem> 349</varlistentry> 350<varlistentry> 351<term>M</term> 352<listitem> 353<para>(Direct mode only.) Set (M1) or clear (M0) static 354navigation. The SiRF documentation says <quote>Static navigation is a 355position filter designed to be used with motor vehicles. When the 356vehicle's velocity falls below a threshold, the position and heading 357are frozen, and velocity is set to zero. This condition will continue 358until the computed velocity rises above 1.2 times the threshold or 359until the computed position is at least a set distance from the frozen 360place. The threshold velocity and set distance may vary with software 361versions.</quote></para> 362 363<para>Non-static mode is designed for use with road navigation 364software, which often snaps the reported position to the nearest road 365within some uncertainty radius. You probably want to turn static 366navigation off for pedestrian use, as it is likely to report speed 367zero and position changing in large jumps.</para> 368</listitem> 369</varlistentry> 370<varlistentry> 371<term>P</term> 372<listitem> 373<para>(Direct mode only.) Toggle navigation-parameter display mode. 374Toggles between normal display and one that shows selected navigation 375parameters from MID 19, including the Static Navigation bit toggled by 376the 'M' command.</para> 377</listitem> 378</varlistentry> 379</variablelist> 380 381<para>To interpret what you see, you will need a copy of the 382<citetitle>SiRF Binary Protocol Reference Manual</citetitle>.</para> 383 384</refsect2> 385<refsect2><title>u-blox support</title> 386<para>Most information is raw from the GPS. Underlined fields are 387derived by translation from ECEF coordinates. 1PPS is the clock lag as 388usual. There are no per-type special commands.</para> 389 390</refsect2> 391</refsect1> 392<refsect1 id='bugs'><title>BUGS AND LIMITATIONS</title> 393 394<para>The PPS Offset field will never be updated when running in 395client mode, even if you can see PPS events in the packet window. 396This limitation may be fixed in a future release.</para> 397 398<!-- 399Debug window dumps of control message sends to the GPS (preceded 400by '>>>') are only supported for the following drivers: NMEA, SiRF, 401EverMore, Navcom, UBX, TSIP, iTalk, Garmintxt. This feature will not 402work for Zodiacs and not always work for Garmins in binary 403mode. 404--> 405 406</refsect1> 407<refsect1 id='see_also'><title>SEE ALSO</title> 408<para> 409<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 410<citerefentry><refentrytitle>gpsdctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 411<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 412<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 413<citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 414<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 415<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 416<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 417<citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>. 418<citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry>. 419</para> 420</refsect1> 421 422<refsect1 id='maintainer'><title>AUTHOR</title> 423 424<para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para> 425</refsect1> 426 427</refentry> 428 429