diff options
Diffstat (limited to 'man/gpsmon.xml')
| -rw-r--r-- | man/gpsmon.xml | 428 |
1 files changed, 428 insertions, 0 deletions
diff --git a/man/gpsmon.xml b/man/gpsmon.xml new file mode 100644 index 00000000..f33b5f15 --- /dev/null +++ b/man/gpsmon.xml @@ -0,0 +1,428 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2010-2019 by the GPSD project +SPDX-License-Identifier: BSD-2-clause +--> +<!DOCTYPE refentry PUBLIC + "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<refentry id='gpsmon.1'> +<refentryinfo><date>17 Feb 2009</date></refentryinfo> +<refmeta> +<refentrytitle>gpsmon</refentrytitle> +<manvolnum>1</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>gpsmon</refname> +<refpurpose>real-time GPS packet monitor and control utility</refpurpose> +</refnamediv> +<refsynopsisdiv id='synopsis'> + +<cmdsynopsis> + <command>gpsmon</command> + <arg choice='opt'>-L </arg> + <arg choice='opt'>-V </arg> + <arg choice='opt'>-h </arg> + <arg choice='opt'>-n </arg> + <arg choice='opt'>-a </arg> + <arg choice='opt'>-l <replaceable>logfile</replaceable></arg> + <arg choice='opt'>-t <replaceable>driver-prefix</replaceable></arg> + <arg choice='opt'> + <group> + <arg choice='plain'> + <replaceable>server</replaceable> + <group> + <replaceable>:port</replaceable> + <group><replaceable>:device</replaceable></group> + </group> + </arg> + <arg choice='plain'><replaceable>device</replaceable></arg> + </group> + </arg> + <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1 id='description'><title>DESCRIPTION</title> + +<para><application>gpsmon</application> is a monitor that watches +packets coming from a GPS and displays them along with diagnostic +information. It supports commands that can be used to tweak GPS +settings in various ways; some are device-independent, some vary with +the GPS chipset type. It will behave sanely, just dumping packets, +when connected to a GPS type it knows nothing about.</para> + +<para><application>gpsmon</application> differs from a navigation +client in that it mostly dumps raw data from the GPS, with only enough +data-massaging to allow checks against expected output. In +particular, this tool does not do any interpolation or modeling +to derive climb/sink or error estimates. Nor does it discard +altitude reports when the fix quality is too low.</para> + +<para>Unlike <application>gpsd</application>, +<application>gpsmon</application> never writes control or probe +strings to the device unless you explicitly tell it to. Thus, while +it will auto-sync to binary packet types, it won't automatically +recognize a device shipping an extended NMEA protocol as anything +other than a plain NMEA device. Use the <option>-t</option> option or +the <command>t</command> to work around this.</para> + +<para><application>gpsmon</application> is a designed to run in a +terminal emulator with a minimum 25x80 size; the non-GUI interface is +a design choice made to accommodate users operating in constrained +environments and over telnet or ssh connections. If run in a larger +window, the size of the packet-log window will be increased to +fit.</para> + +<para><application>gpsmon</application> accepts an -h option that +displays a usage message, or a -V option to dump the package +version and exit.</para> + +<para>This program may be run in either of two modes, as a client for +the <application>gpsd</application> daemon (and its associated control +socket) or directly connected to a specified serial device. When run +with no argument, it attempts to connect to the daemon. If the +argument begins with a server:port specification it will also attempt +to connect to the daemon. If the argument looks like a bare server +name it will attempt to connect to a daemon running on the default +gpsd port on that server. Only if the device argument contains +slashes but no colons will it be treated as a serial device for direct +connection. In direct-connect mode <application>gpsmon</application> +will hunt for a correct baud rate and lock on to it +automatically. Possible cases look like this:</para> + +<variablelist> +<varlistentry> +<term>localhost:/dev/ttyS1</term> +<listitem><para>Look at the default port of localhost, trying both +IPv4 and IPv6 and watching output from serial device 1.</para></listitem> +</varlistentry> +<varlistentry> +<term>example.com:2317</term> +<listitem><para>Look at port 2317 on example.com, trying both +IPv4 and IPv6.</para></listitem> +</varlistentry> +<varlistentry> +<term>71.162.241.5:2317:/dev/ttyS3</term> +<listitem><para>Look at port 2317 at the specified IPv4 +address, collecting data from attached serial device 3.</para></listitem> +</varlistentry> +<varlistentry> +<term>[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5</term> +<listitem><para>Look at port 2317 at the specified IPv6 +address, collecting data from attached serial device 5.</para></listitem> +</varlistentry> +</variablelist> + +<para>Unlike <application>gpsd</application>, +<application>gpsmon</application> run in direct mode does not do its +own device probing. Thus, in particular, if you point it at a +GPS with a native binary mode that happens to be emitting NMEA, it +won't identify the actual type unless the device emits a recognizable +NMEA trigger sentence. The -t and -i options may help you.</para> + +<para>The -F option is only valid in client mode; it specifies a +control socket to which the program should send device control +strings. You must specify a valid pathname of a Unix-domain socket on +your local filesystem.</para> + +<para>The -D option enables packet-getter debugging output and is +probably only useful to developers of the GPSD code. Consult the +packet-getter source code for relevant values.</para> + +<para>The -L option lists a table showing which GPS device types +<application>gpsmon</application> has built-in support for, and which +generic commands can be applied to which GPS types, and then +exits. Note that this does not list type-specific commands associated +with individual GPS types.</para> + +<para>The -l option sets up logging to a specified file to start +immediately on device open. This may be useful is, for example, +you want to capture the startup message from a device that displays +firmware version information there.</para> + +<para>The -n option forces gpsmon to request NMEA0183 packets instead of the +raw datastream from gpsd.</para> + +<para>The -t option sets up a fallback type. Give it a string that +is a distinguishing prefix of exactly one driver type name; this will +be used for mode, speed, and rate switching if the driver selected +by the packet type lacks those capabilities. Most useful when the +packet type is NMEA but the device is known to have a binary mode, +such as SiRF binary.</para> + +<para>The -a option enables a special debugging mode that does not +use screen painting. Packets are dumped normally; any character +typed suspends packet dumping and brings up a command prompt. This +feature will mainly be of interest to GPSD developers.</para> + +<para>After startup (without -a), the top part of the screen reports +the contents of several especially interesting packet types. The +"PPS" field, if nonempty, is the delta between the last 1PPS top of +second and the system clock at that time.</para> + +<para>The bottom half of the screen is a scrolling hex dump of all +packets the GPS is issuing. If the packet type is textual, any +trailing CR/LF is omitted. Dump lines beginning >>> represent +control packets sent to the GPS. Lines consisting of "PPS" surrounded +by dashes, if present, indicate 1PPS and the start of the reporting +cycle.</para> + +</refsect1> +<refsect1 id='commands'><title>COMMANDS</title> + +<para>The following device-independent commands are available while +<application>gpsmon</application> is running:</para> + +<variablelist> + +<varlistentry> +<term>i</term> +<listitem> +<para>(Direct mode only.) Enable/disable subtype probing and +reinitialize the driver. In normal operation, +<application>gpsmon</application> does not send configuration strings +to the device (except for wakeup strings needed to get it to send +data, if any). The command 'i1' causes it to send the same sequence of +subtype probes that <application>gpsd</application> would. The +command 'i0' turns off probing; 'i' alone toggles the bit. In either +case, the current driver is re-selected; if the probe bit is enabled, +probes will begin to be issued immediately.</para> + +<para>Note that enabling probing might flip the device into another +mode; in particular, it will flip a SiRF chip into binary mode as if +you had used the <quote>n</quote> command. This is due to a +limitation in the SiRF firmware that we can't fix.</para> + +<para>This command will generally do nothing after the first time you +use it, because the device type will already have been discovered.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>c</term> +<listitem> +<para>(Direct mode only.) Change cycle time. Follow it with a number +interpreted as a cycle time in seconds. Most devices have a fixed +cycle time of 1 second, so this command may fail with a +message.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>l</term> +<listitem> +<para>Toggle packet logging. If packet logging is on, it will be +turned off and the log closed. If it is off, logging to the filename +following the l will be enabled. Differs from simply capturing the +data from the GPS device in that only whole packets are logged. +The logfile is opened for append, so you can log more than one +portion of the packet stream and they will be stitched together +correctly.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>n</term> +<listitem> +<para>(Direct mode only.) With an argument of 0, switch device to NMEA +mode at current speed; with an argument of 1, change to binary +(native) mode. With no argument, toggle the setting. Will show an +error if the device doesn't have such modes.</para> + +<para>After you switch a dual-protocol GPS to NMEA mode with this +command, it retains the information about the original type and its +control capabilities. That is why the device type listed before the +prompt doesn't change.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>q</term> +<listitem> +<para>Quit <application>gpsmon</application>. Control-C, or whatever +your current interrupt character is, works as well.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>s</term> +<listitem> +<para>(Direct mode only.) Change baud rate. Follow it with a number +interpreted as bits per second, for example "s9600". The speed number +may optionally be followed by a colon and a wordlength-parity-stopbits +specification in the traditional style, e.g 8N1 (the default), 7E1, +etc. Some devices don't support serial modes other than their +default, so this command may fail with a message.</para> + +<para>Use this command with caution. On USB and Bluetooth GPSes it is +also possible for serial mode setting to fail either because the +serial adaptor chip does not support non-8N1 modes or because the +device firmware does not properly synchronize the serial adaptor chip +with the UART on the GPS chipset when the speed changes. These +failures can hang your device, possibly requiring a GPS power cycle or (in +extreme cases) physically disconnecting the NVRAM backup battery.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>t</term> +<listitem> +<para>(Direct mode only.) Force a switch of monitoring type. Follow it +with a string that is unique to the name of a gpsd driver with +<application>gpsmon</application> support; +<application>gpsmon</application> will switch to using that driver and +display code. Will show an error message if there is no matching gpsd +driver, or multiple matches, or the unique match has no display +support in <application>gpsmon</application>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>x</term> +<listitem> +<para>(Direct mode only.) Send hex payload to device. Following the +command letter you may type hex digit pairs; end with a newline. +These will become the payload of a control packet shipped to the +device. The packet will be wrapped with headers, trailers, and +checksum appropriate for the current driver type. The first one or two +bytes of the payload may be specially interpreted, see the description +of the <option>-x</option> of +<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>X</term> +<listitem> +<para>(Direct mode only.) Send raw hex bytes to device. Following the +command letter you may type hex digit pairs; end with a newline. +These will be shipped to the device.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Ctrl-S</term> +<listitem> +<para>Freeze display, suspend scrolling in debug window.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Ctrl-Q</term> +<listitem> +<para>Unfreeze display, resume normal operation.</para> +</listitem> +</varlistentry> +</variablelist> + +<refsect2><title>NMEA support</title> + +<para>(These remarks apply to not just generic NMEA devices +but all extended NMEA devices for which +<application>gpsmon</application> presently has support.)</para> + +<para>All fields are raw data from the GPS except (a) the "Cooked PVT" +window near top of screen, provided as a check and (b) the "PPS +offset" field.</para> + +<para>There are no device-specific commands. Which generic +commands are available may vary by type: examine the output +of <command>gpsmon -l</command> to learn more.</para> +</refsect2> + +<refsect2><title>SiRF support</title> +<para>Most information is raw from the GPS. Underlined fields are +derived by translation from ECEF coordinates or application of +leap-second and local time-zone offsets. 1PPS is the clock lag as +usual.</para> + +<para>The following commands are supported for SiRF GPSes only:</para> + +<variablelist> +<varlistentry> +<term>A</term> +<listitem> +<para>(Direct mode only.) Toggle reporting of 50BPS subframe data.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>M</term> +<listitem> +<para>(Direct mode only.) Set (M1) or clear (M0) static +navigation. The SiRF documentation says <quote>Static navigation is a +position filter designed to be used with motor vehicles. When the +vehicle's velocity falls below a threshold, the position and heading +are frozen, and velocity is set to zero. This condition will continue +until the computed velocity rises above 1.2 times the threshold or +until the computed position is at least a set distance from the frozen +place. The threshold velocity and set distance may vary with software +versions.</quote></para> + +<para>Non-static mode is designed for use with road navigation +software, which often snaps the reported position to the nearest road +within some uncertainty radius. You probably want to turn static +navigation off for pedestrian use, as it is likely to report speed +zero and position changing in large jumps.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>P</term> +<listitem> +<para>(Direct mode only.) Toggle navigation-parameter display mode. +Toggles between normal display and one that shows selected navigation +parameters from MID 19, including the Static Navigation bit toggled by +the 'M' command.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>To interpret what you see, you will need a copy of the +<citetitle>SiRF Binary Protocol Reference Manual</citetitle>.</para> + +</refsect2> +<refsect2><title>u-blox support</title> +<para>Most information is raw from the GPS. Underlined fields are +derived by translation from ECEF coordinates. 1PPS is the clock lag as +usual. There are no per-type special commands.</para> + +</refsect2> +</refsect1> +<refsect1 id='bugs'><title>BUGS AND LIMITATIONS</title> + +<para>The PPS Offset field will never be updated when running in +client mode, even if you can see PPS events in the packet window. +This limitation may be fixed in a future release.</para> + +<!-- +Debug window dumps of control message sends to the GPS (preceded +by '>>>') are only supported for the following drivers: NMEA, SiRF, +EverMore, Navcom, UBX, TSIP, iTalk, Garmintxt. This feature will not +work for Zodiacs and not always work for Garmins in binary +mode. +--> + +</refsect1> +<refsect1 id='see_also'><title>SEE ALSO</title> +<para> +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsdctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +<citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +</para> +</refsect1> + +<refsect1 id='maintainer'><title>AUTHOR</title> + +<para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para> +</refsect1> + +</refentry> + |