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.

250 lines
14 KiB

  1. '\" t
  2. .\" Title: gpsmon
  3. .\" Author: [see the "AUTHOR" section]
  4. .\" Generator: DocBook XSL Stylesheets v1.79.1 <>
  5. .\" Date: 17 Feb 2009
  6. .\" Manual: GPSD Documentation
  7. .\" Source: The GPSD Project
  8. .\" Language: English
  9. .\"
  10. .TH "GPSMON" "1" "17 Feb 2009" "The GPSD Project" "GPSD Documentation"
  11. .\" -----------------------------------------------------------------
  12. .\" * Define some portability stuff
  13. .\" -----------------------------------------------------------------
  14. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15. .\"
  16. .\"
  17. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18. .ie \n(.g .ds Aq \(aq
  19. .el .ds Aq '
  20. .\" -----------------------------------------------------------------
  21. .\" * set default formatting
  22. .\" -----------------------------------------------------------------
  23. .\" disable hyphenation
  24. .nh
  25. .\" disable justification (adjust text to left margin only)
  26. .ad l
  27. .\" -----------------------------------------------------------------
  29. .\" -----------------------------------------------------------------
  30. .SH "NAME"
  31. gpsmon \- real\-time GPS packet monitor and control utility
  32. .SH "SYNOPSIS"
  33. .HP \w'\fBgpsmon\fR\ 'u
  34. \fBgpsmon\fR [\-L] [\-V] [\-h] [\-n] [\-a] [\-l\ \fIlogfile\fR] [\-t\ \fIdriver\-prefix\fR] [[\ \fIserver\fR\ [\fI:port\fR\ [\fI:device\fR]]\ |\ \fIdevice\fR]] [\-D\ \fIdebuglevel\fR]
  36. .PP
  37. gpsmon
  38. 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\&.
  39. .PP
  40. gpsmon
  41. 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\&.
  42. .PP
  43. Unlike
  44. gpsd,
  45. gpsmon
  46. 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\*(Aqt automatically recognize a device shipping an extended NMEA protocol as anything other than a plain NMEA device\&. Use the
  47. \fB\-t\fR
  48. option or the
  49. \fBt\fR
  50. to work around this\&.
  51. .PP
  52. gpsmon
  53. 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\&.
  54. .PP
  55. gpsmon
  56. accepts an \-h option that displays a usage message, or a \-V option to dump the package version and exit\&.
  57. .PP
  58. This program may be run in either of two modes, as a client for the
  59. gpsd
  60. 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
  61. gpsmon
  62. will hunt for a correct baud rate and lock on to it automatically\&. Possible cases look like this:
  63. .PP
  64. localhost:/dev/ttyS1
  65. .RS 4
  66. Look at the default port of localhost, trying both IPv4 and IPv6 and watching output from serial device 1\&.
  67. .RE
  68. .PP
  69. example\&.com:2317
  70. .RS 4
  71. Look at port 2317 on example\&.com, trying both IPv4 and IPv6\&.
  72. .RE
  73. .PP
  74. 71\&.162\&.241\&.5:2317:/dev/ttyS3
  75. .RS 4
  76. Look at port 2317 at the specified IPv4 address, collecting data from attached serial device 3\&.
  77. .RE
  78. .PP
  79. [FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5
  80. .RS 4
  81. Look at port 2317 at the specified IPv6 address, collecting data from attached serial device 5\&.
  82. .RE
  83. .PP
  84. Unlike
  85. gpsd,
  86. gpsmon
  87. 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\*(Aqt identify the actual type unless the device emits a recognizable NMEA trigger sentence\&. The \-t and \-i options may help you\&.
  88. .PP
  89. 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\&.
  90. .PP
  91. 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\&.
  92. .PP
  93. The \-L option lists a table showing which GPS device types
  94. gpsmon
  95. 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\&.
  96. .PP
  97. 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\&.
  98. .PP
  99. The \-n option forces gpsmon to request NMEA0183 packets instead of the raw datastream from gpsd\&.
  100. .PP
  101. 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\&.
  102. .PP
  103. 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\&.
  104. .PP
  105. 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\&.
  106. .PP
  107. 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\&.
  108. .SH "COMMANDS"
  109. .PP
  110. The following device\-independent commands are available while
  111. gpsmon
  112. is running:
  113. .PP
  114. i
  115. .RS 4
  116. (Direct mode only\&.) Enable/disable subtype probing and reinitialize the driver\&. In normal operation,
  117. gpsmon
  118. does not send configuration strings to the device (except for wakeup strings needed to get it to send data, if any)\&. The command \*(Aqi1\*(Aq causes it to send the same sequence of subtype probes that
  119. gpsd
  120. would\&. The command \*(Aqi0\*(Aq turns off probing; \*(Aqi\*(Aq 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\&.
  121. .sp
  122. 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
  123. \(lqn\(rq
  124. command\&. This is due to a limitation in the SiRF firmware that we can\*(Aqt fix\&.
  125. .sp
  126. This command will generally do nothing after the first time you use it, because the device type will already have been discovered\&.
  127. .RE
  128. .PP
  129. c
  130. .RS 4
  131. (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\&.
  132. .RE
  133. .PP
  134. l
  135. .RS 4
  136. 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\&.
  137. .RE
  138. .PP
  139. n
  140. .RS 4
  141. (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\*(Aqt have such modes\&.
  142. .sp
  143. 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\*(Aqt change\&.
  144. .RE
  145. .PP
  146. q
  147. .RS 4
  148. Quit
  149. gpsmon\&. Control\-C, or whatever your current interrupt character is, works as well\&.
  150. .RE
  151. .PP
  152. s
  153. .RS 4
  154. (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\*(Aqt support serial modes other than their default, so this command may fail with a message\&.
  155. .sp
  156. 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\&.
  157. .RE
  158. .PP
  159. t
  160. .RS 4
  161. (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
  162. gpsmon
  163. support;
  164. gpsmon
  165. 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
  166. gpsmon\&.
  167. .RE
  168. .PP
  169. x
  170. .RS 4
  171. (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
  172. \fB\-x\fR
  173. of
  174. \fBgpsctl\fR(1)\&.
  175. .RE
  176. .PP
  177. X
  178. .RS 4
  179. (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\&.
  180. .RE
  181. .PP
  182. Ctrl\-S
  183. .RS 4
  184. Freeze display, suspend scrolling in debug window\&.
  185. .RE
  186. .PP
  187. Ctrl\-Q
  188. .RS 4
  189. Unfreeze display, resume normal operation\&.
  190. .RE
  191. .SS "NMEA support"
  192. .PP
  193. (These remarks apply to not just generic NMEA devices but all extended NMEA devices for which
  194. gpsmon
  195. presently has support\&.)
  196. .PP
  197. 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\&.
  198. .PP
  199. There are no device\-specific commands\&. Which generic commands are available may vary by type: examine the output of
  200. \fBgpsmon \-l\fR
  201. to learn more\&.
  202. .SS "SiRF support"
  203. .PP
  204. 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\&.
  205. .PP
  206. The following commands are supported for SiRF GPSes only:
  207. .PP
  208. A
  209. .RS 4
  210. (Direct mode only\&.) Toggle reporting of 50BPS subframe data\&.
  211. .RE
  212. .PP
  213. M
  214. .RS 4
  215. (Direct mode only\&.) Set (M1) or clear (M0) static navigation\&. The SiRF documentation says
  216. \(lqStatic navigation is a position filter designed to be used with motor vehicles\&. When the vehicle\*(Aqs 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\&.\(rq
  217. .sp
  218. 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\&.
  219. .RE
  220. .PP
  221. P
  222. .RS 4
  223. (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 \*(AqM\*(Aq command\&.
  224. .RE
  225. .PP
  226. To interpret what you see, you will need a copy of the
  227. SiRF Binary Protocol Reference Manual\&.
  228. .SS "u\-blox support"
  229. .PP
  230. 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\&.
  232. .PP
  233. 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\&.
  234. .SH "SEE ALSO"
  235. .PP
  236. \fBgpsd\fR(8),
  237. \fBgpsdctl\fR(8),
  238. \fBgps\fR(1),
  239. \fBlibgps\fR(3),
  240. \fBlibgpsmm\fR(3),
  241. \fBgpsprof\fR(1),
  242. \fBgpsfake\fR(1),
  243. \fBgpsctl\fR(1),
  244. \fBgpscat\fR(1)\&.
  245. \fBgpspipe\fR(1)\&.
  246. .SH "AUTHOR"
  247. .PP
  248. Eric S\&. Raymond
  249. <esr@thyrsus\&.com>\&.