Devuan fork of gpsd
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

429 lines
17 KiB

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