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
9.1 KiB

  1. '\" t
  2. .\" Title: gpsfake
  3. .\" Author: [see the "AUTHOR" section]
  4. .\" Generator: DocBook XSL Stylesheets v1.79.1 <>
  5. .\" Date: 12 Feb 2005
  6. .\" Manual: GPSD Documentation
  7. .\" Source: The GPSD Project
  8. .\" Language: English
  9. .\"
  10. .TH "GPSFAKE" "1" "12 Feb 2005" "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. gpsfake \- test harness for gpsd, simulating a GPS
  32. .SH "SYNOPSIS"
  33. .HP \w'\fBgpsfake\fR\ 'u
  34. \fBgpsfake\fR [\-1] [\-h] [\-b] [\-c\ \fIinterval\fR] [\-i] [\-D\ \fIdebuglevel\fR] [\-l] [\-m\ \fImonitor\fR] [\-g] [\-G] [\-n] [\-o\ \fIoptions\fR] [\-p] [\-P\ \fIport\fR] [\-q] [\-r\ \fIinitcmd\fR] [\-s\ \fIspeed\fR] [\-S] [\-u] [\-t] [\-T] [\-v] [\-W\ \fItimeout\fR] [\fIlogfile\fR...]
  36. .PP
  37. gpsfake
  38. is a test harness for
  39. gpsd
  40. and its clients\&. It opens a pty (pseudo\-TTY), launches a
  41. gpsd
  42. instance that thinks the slave side of the pty is its GPS device, and repeatedly feeds the contents of one or more test logfiles through the master side to the GPS\&. If there are multiple logfiles, sentences from them are interleaved in the order the files are specified\&.
  43. .PP
  44. gpsfake
  45. does not require root privileges, and can be run concurrently with a production
  46. gpsd
  47. instance without causing problems\&.
  48. .PP
  49. The logfiles may contain packets in any supported format, including in particular NMEA, SiRF, TSIP, or Zodiac\&. Leading lines beginning with # will be treated as comments and ignored, except in the following special cases:
  50. .sp
  51. .RS 4
  52. .ie n \{\
  53. \h'-04'\(bu\h'+03'\c
  54. .\}
  55. .el \{\
  56. .sp -1
  57. .IP \(bu 2.3
  58. .\}
  59. a comment of the form #Date: yyyy\-mm\-dd (ISO8601 date format) may be used to set the initial date for the log\&.
  60. .RE
  61. .sp
  62. .RS 4
  63. .ie n \{\
  64. \h'-04'\(bu\h'+03'\c
  65. .\}
  66. .el \{\
  67. .sp -1
  68. .IP \(bu 2.3
  69. .\}
  70. a comment of the form #Serial: [0\-9]* [78][NOE][12] may be used to set serial parameters for the log \- baud rate, word length, stop bits\&.
  71. .RE
  72. .sp
  73. .RS 4
  74. .ie n \{\
  75. \h'-04'\(bu\h'+03'\c
  76. .\}
  77. .el \{\
  78. .sp -1
  79. .IP \(bu 2.3
  80. .\}
  81. a comment of the form #Transport: UDP may be used to fake a UDP source rather than the normal pty\&.
  82. .RE
  83. .PP
  84. The
  85. gpsd
  86. instance is run in foreground\&. The thread sending fake GPS data to the daemon is run in background\&.
  87. .SH "OPTIONS"
  88. .PP
  89. With the \-1 option, the logfile is interpreted once only rather than repeatedly\&. This option is intended to facilitate regression testing\&.
  90. .PP
  91. The
  92. \fB\-b\fR
  93. enables a twirling\-baton progress indicator on standard error\&. At termination, it reports elapsed time\&.
  94. .PP
  95. The
  96. \fB\-c\fR
  97. sets the delay between sentences in seconds\&. Fractional values of seconds are legal\&. The default is zero (no delay)\&.
  98. .PP
  99. The
  100. \fB\-l\fR
  101. makes the program dump a line or packet number just before each sentence is fed to the daemon\&. If the sentence is textual (e\&.g\&. NMEA), the text is dumped as well\&. If not, the packet will be dumped in hexadecimal (except for RTCM packets, which aren\*(Aqt dumped at all)\&. This option is useful for checking that gpsfake is getting packet boundaries right\&.
  102. .PP
  103. The
  104. \fB\-i\fR
  105. is for single\-stepping through logfiles\&. It dumps the line or packet number (and the sentence if the protocol is textual) followed by "? "\&. Only when the user keys Enter is the line actually fed to
  106. gpsd\&.
  107. .PP
  108. The
  109. \fB\-m\fR
  110. specifies a monitor program inside which the daemon should be run\&. This option is intended to be used with
  111. \fBvalgrind\fR(1),
  112. \fBgdb\fR(1)
  113. and similar programs\&.
  114. .PP
  115. The
  116. \fB\-g\fR
  117. and
  118. \fB\-G\fR
  119. options use the monitor facility to run the
  120. gpsd
  121. instance within gpsfake under control of gdb or lldb, respectively\&. They also disable the timeout on daemon inactivity, to allow for breakpointing\&. If necessary, the timeout can be reenabled by a subsequent
  122. \fB\-W\fR\&.
  123. .PP
  124. The
  125. \fB\-o\fR
  126. specifies options to pass to the daemon\&. The \-n option passes \-n to start the daemon reading the GPS without waiting for a client (equivalent to \-o "\-n")\&. The
  127. \fB\-D\fR
  128. passes a \-D option to the daemon: thus \-D 4 is shorthand for \-o "\-D 4"\&.
  129. .PP
  130. The \-p ("pipe") option sets watcher mode and dumps the NMEA and GPSD notifications generated by the log to standard output\&. This is useful for regression\-testing\&.
  131. .PP
  132. The \-P ("port") option sets the daemon\*(Aqs listening port\&.
  133. .PP
  134. The
  135. \fB\-q\fR
  136. tells gpsfake to suppress normal progress output and thus act in a quiet manner\&.
  137. .PP
  138. The
  139. \fB\-r\fR
  140. specifies an initialization command to use in pipe mode\&. The default is
  141. \fB?WATCH={"enable":true,"json":true}\fR\&.
  142. .PP
  143. The
  144. \fB\-s\fR
  145. sets the baud rate for the slave tty\&. The default is 4800\&.
  146. .PP
  147. The option \-S tells gpsfake to insert realistic delays in the test input rather than trying to stuff it through the daemon as fast as possible\&. This will make the test(s) run much slower, but avoids flaky failures due to machine lode and possible race conditions in the pty layer\&.
  148. .PP
  149. The
  150. \fB\-t\fR
  151. forces the test framework to use TCP rather than pty devices\&. Besides being a test of TCP source handling, this may be useful for testing from within chroot jails where access to pty devices is locked out\&.
  152. .PP
  153. The
  154. \fB\-T\fR
  155. makes
  156. gpsfake
  157. print some system information and then exits\&.
  158. .PP
  159. The
  160. \fB\-u\fR
  161. forces the test framework to use UDP rather than pty devices\&. Besides being a test of UDP source handling, this may be useful for testing from within chroot jails where access to pty devices is locked out\&.
  162. .PP
  163. The
  164. \fB\-v\fR
  165. enables verbose progress reports to stderr\&. It is mainly useful for debugging
  166. gpsfake
  167. itself\&.
  168. .PP
  169. The
  170. \fB\-W\fR
  171. ("wait") option sets the timeout on daemon inactivity, in seconds\&. The default timeout is 60 seconds, and a value of 0 suppresses the timeout altogether\&. Note that the actual timeout is longer due to internal delays, typically by about 20 seconds\&.
  172. .PP
  173. The
  174. \fB\-x\fR
  175. dumps packets as
  176. gpsfake
  177. gathers them\&. It is mainly useful for debugging
  178. gpsfake
  179. itself\&.
  180. .PP
  181. The
  182. \fB\-h\fR
  183. makes
  184. gpsfake
  185. print a usage message and exit\&.
  186. .PP
  187. The argument must be the name of a file containing the data to be cycled at the device\&.
  188. gpsfake
  189. will print a notification each time it cycles\&.
  190. .PP
  191. Normally, gpsfake creates a pty for each logfile and passes the slave side of the device to the daemon\&. If the header comment in the logfile contains the string "UDP", packets are instead shipped via UDP port 5000 to the address 192\&.168\&.0\&.1\&.255\&. You can monitor them with this:
  192. \fBtcpdump \-s0 \-n \-A \-i lo udp and port 5000\fR\&.
  194. .PP
  195. Certain magic comments in test load headers can change the conditions of the test\&. These are:
  196. .PP
  197. Serial:
  198. .RS 4
  199. May contain a serial\-port setting such as 4800 7N2 \- baud rate followed by 7 or 8 for byte length, N or O or E for parity and 1 or 2 for stop bits\&. The test is run with those settings on the slave port that the daemon sees\&.
  200. .RE
  201. .PP
  202. Transport:
  203. .RS 4
  204. Values \*(AqTCP\*(Aq and \*(AqUDP\*(Aq force the use of TCP and UDP feeds respectively (the default is a pty)\&.
  205. .RE
  206. .PP
  207. Delay\-Cookie:
  208. .RS 4
  209. Must be followed by two whitespace\-separated fields, a delimiter character and a numeric delay in seconds\&. Instead of being broken up by packet boundaries, the test load is split on the delimiters\&. The delay is performed after each feed\&. Can be useful for imposing write boundaries in the middle of packets\&.
  210. .RE
  212. .PP
  213. gpsfake
  214. is a trivial wrapper around a Python module, also named gpsfake, that can be used to fully script sessions involving a
  215. gpsd
  216. instance, any number of client sessions, and any number of fake GPSes feeding the daemon instance with data from specified sentence logs\&.
  217. .PP
  218. Source and embedded documentation for this module is shipped with the
  219. gpsd
  220. development tools\&. You can use it to torture\-test either
  221. gpsd
  222. itself or any
  223. gpsd\-aware client application\&.
  224. .PP
  225. Logfiles for the use with
  226. gpsfake
  227. can be retrieved using
  228. gpspipe,
  229. gpscat, or
  230. gpsmon
  231. from the gpsd distribution, or any other application which is able to create a compatible output\&.
  232. .PP
  233. If
  234. gpsfake
  235. exits with "Cannot execute gpsd: executable not found\&." the environment variable GPSD_HOME can be set to the path where gpsd can be found\&. (instead of adding that folder to the PATH environment variable
  236. .SH "SEE ALSO"
  237. .PP
  238. \fBgpsd\fR(8),
  239. \fBgps\fR(1),
  240. \fBlibgps\fR(3),
  241. \fBlibgpsmm\fR(3),
  242. \fBgpsctl\fR(1),
  243. \fBgpspipe\fR(1),
  244. \fBgpsprof\fR(1)
  245. \fBgpsmon\fR(1)\&.
  246. .SH "AUTHOR"
  247. .PP
  248. Eric S\&. Raymond
  249. <esr@thyrsus\&.com>\&.