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.

219 lines
8.6 KiB

  1. '\" t
  2. .\" Title: gpsprof
  3. .\" Author: [see the "AUTHOR" section]
  4. .\" Generator: DocBook XSL Stylesheets v1.79.1 <>
  5. .\" Date: 30 May 2018
  6. .\" Manual: GPSD Documentation
  7. .\" Source: The GPSD Project
  8. .\" Language: English
  9. .\"
  10. .TH "GPSPROF" "1" "30 May 2018" "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. gpsprof \- profile a GPS and gpsd, plotting latency information
  32. .SH "SYNOPSIS"
  33. .HP \w'\fBgpsprof\fR\ 'u
  34. \fBgpsprof\fR [\-D\ \fIdebuglevel\fR] [\-d\ \fIdumpfile\fR] [\-f\ \fIplot_type\fR] [\-h] [\-l\ \fIlogfile\fR] [\-m\ \fIthreshold\fR] [\-n\ \fIsamplecount\fR] [\-r] [\-S\ \fIsubtitle\fR] [\-T\ \fIterminal\fR] [\-t\ \fItitle\fR] [[server[:port[:device]]]]
  36. .PP
  37. gpsprof
  38. performs accuracy, latency, skyview, and time drift profiling on a GPS\&. It emits to standard output a GNUPLOT program that draws one of several illustrative graphs\&. It can also be told to emit the raw profile data\&.
  39. .PP
  40. Information from the default spatial plot it provides can be useful for characterizing position accuracy of a GPS\&.
  41. .PP
  42. gpsprof
  43. uses instrumentation built into
  44. gpsd\&. It can read data from a local or remote running
  45. gpsd\&. Or it can read data from a saved logfile\&.
  46. .PP
  47. gpsprof
  48. is designed to be lightweight and use minimal host resources\&. No graphics subsystem needs to be installed on the host running
  49. gpsprof\&. Simply copy the resultant plot file to another host to be rendered with
  50. gnuplot\&.
  51. .SH "OPTIONS"
  52. .PP
  53. The \-f option sets the plot type\&. Currently the following plot types are defined:
  54. .PP
  55. space
  56. .RS 4
  57. Generate a scatterplot of fixes and plot probable error circles\&. This data is only meaningful if the GPS is held stationary while
  58. gpsprof
  59. is running\&. Various statistics about the fixes are listed at the bottom\&. This is the default plot type\&.
  60. .RE
  61. .PP
  62. polar
  63. .RS 4
  64. Generate a heat map of reported satellite Signal to Noise Ratio (SNR) using polar coordinates\&. A colored dot is plotted for each satellite seen by the GPS\&. The color of dot corresponds to the SNR of the satellite\&. The dots are plotted by azimuth and elevation\&. North, azimuth 0 degrees, is at the top of the plot\&. Directly overhead, elevation of 90 degrees, is plotted at the center\&. Useful for analyzing the quality of the skyview as seen by the GPS\&.
  65. .RE
  66. .PP
  67. polarunused
  68. .RS 4
  69. Similar to the polar plot, but only unused satellites are plotted\&. Useful for seeing which parts of the antenna skyview are obstructed, degraded, below the GPS elevation mask, or otherwise rejected\&.
  70. .RE
  71. .PP
  72. polarused
  73. .RS 4
  74. Similar to the polar plot, but only satellites used to compute fixs are plotted\&. Useful for seeing which parts of the antenna skyview are being used in fixes\&.
  75. .RE
  76. .PP
  77. time
  78. .RS 4
  79. Plot delta of system clock (NTP corrected time) against GPS time as reported in PPS messages\&. The X axis is sample time in seconds from the start of the plot\&. The Y axis is the system clock delta from GPS time\&. This plot only works if
  80. gpsd
  81. was built with the timing (latency timing support) configure option enabled\&.
  82. .RE
  83. .PP
  84. instrumented
  85. .RS 4
  86. Plot instrumented profile\&. Plots various components of the total latency between the GPS\*(Aqs fix time and when the client receives the fix\&. This plot only works if
  87. gpsd
  88. was built with the timing (latency timing support) configuration option enabled\&.
  89. .sp
  90. For purposes of the description, below, start\-of\-reporting\-cycle (SORC) is when a device\*(Aqs reporting cycle begins\&. This time is detected by watching to see when data availability follows a long enough amount of quiet time that we can be sure we\*(Aqve seen the gap at the end of the sensor\*(Aqs previous report\-transmission cycle\&. Detecting this gap requires a device running at 9600bps or faster\&.
  91. .sp
  92. Similarly, EORC is end\-of\-reporting\-cycle; when the daemon has seen the last sentence it needs in the reporting cycle and ready to ship a fix to the client\&.
  93. .sp
  94. The components of the instrumented plot are as follows:
  95. .PP
  96. Fix latency
  97. .RS 4
  98. Delta between GPS time and SORC\&.
  99. .RE
  100. .PP
  101. RS232 time
  102. .RS 4
  103. RS232 transmission time for data shipped during the cycle (computed from character volume and baud rate)\&.
  104. .RE
  105. .PP
  106. Analysis time
  107. .RS 4
  108. EORC, minus SORC, minus RS232 time\&. The amount of real time the daemon spent on computation rather than I/O\&.
  109. .RE
  110. .PP
  111. Reception time
  112. .RS 4
  113. Shipping time from the daemon to when it was received by
  114. gpsprof\&.
  115. .RE
  116. .sp
  117. Because of RS232 buffering effects, the profiler sometimes generates reports of ridiculously high latencies right at the beginning of a session\&. The \-m option lets you set a latency threshold, in multiples of the cycle time, above which reports are discarded\&.
  118. .RE
  119. .PP
  120. uninstrumented
  121. .RS 4
  122. Plot total latency without instrumentation\&. Useful mainly as a check that the instrumentation is not producing significant distortion\&. The X axis is sample time in seconds from the start of the plot\&. The Y axs is latency in seconds\&.It only plots times for reports that contain fixes; staircase\-like artifacts in the plot are created when elapsed time from reports without fixes is lumped in\&.
  123. .RE
  124. .PP
  125. The \-d option dumps the plot data, without attached gnuplot code, to a specified file for post\-analysis\&.
  126. .PP
  127. The \-D sets debug level\&.
  128. .PP
  129. The \-h option makes
  130. gpsprof
  131. print a usage message and exit\&.
  132. .PP
  133. The \-l option dumps the raw JSON reports collected from the device to a specified file\&.
  134. .PP
  135. The \-n option sets the number of packets to sample\&. The default is 100\&. Most GPS are configured to emit one fix per second, so 100 samples would then span 100 seconds\&.
  136. .PP
  137. The \-r option replots from a JSON logfile (such as \-l produces) on standard input\&. Both \-n and \-l options are ignored when this one is selected\&.
  138. .PP
  139. The \-S option sets a text string to be included in the plot as a subtitle\&. This will be below the title\&.
  140. .PP
  141. The \-t option sets a text string to be the plot title\&. This will replace the default title\&.
  142. .PP
  143. The \-T option generates a terminal type setting into the gnuplot code\&. Typical usage is "\-T png", or "\-T pngcairo" telling gnuplot to write a PNG file\&. Without this option gnuplot will call its X11 display code\&.
  144. .PP
  145. Different installations of
  146. gnuplot
  147. will support different terminal types\&. Different terminal types may work better for you than other ones\&. "\-T png" will generate PNG images\&. Use "\-T jpeg" to generate JPEG images\&. "\-T pngcairo" often works best, but is not supported by some distributions\&.
  148. .SH "SIGNALS"
  149. .PP
  150. Sending SIGUSR1 to a running instance causes it to write a completion message to standard error and resume processing\&. The first number in the startup message is the process ID to signal\&.
  151. .SH "EXAMPLES"
  152. .PP
  153. To display the graph, use
  154. \fBgnuplot\fR(1)\&. Thus, for example, to display the default spatial scatter plot, do this:
  155. .sp
  156. .if n \{\
  157. .RS 4
  158. .\}
  159. .nf
  160. gpsprof | gnuplot \-persist
  161. .fi
  162. .if n \{\
  163. .RE
  164. .\}
  165. .PP
  166. To generate an image file:
  167. .sp
  168. .if n \{\
  169. .RS 4
  170. .\}
  171. .nf
  172. gpsprof \-T png | gnuplot > image\&.png
  173. .fi
  174. .if n \{\
  175. .RE
  176. .\}
  177. .PP
  178. To generate a polar plot, and save the GPS data for further plots:
  179. .sp
  180. .if n \{\
  181. .RS 4
  182. .\}
  183. .nf
  184. gpsprof \-f polar \-T jpeg \-l polar\&.json | gnuplot > polar\&.png
  185. .fi
  186. .if n \{\
  187. .RE
  188. .\}
  189. .sp
  190. Then to make the matching polarused and polarunused plots and pngs from the just saved the GPS data:
  191. .sp
  192. .if n \{\
  193. .RS 4
  194. .\}
  195. .nf
  196. gpsprof \-f polarused \-T jpeg \-r < polar\&.json > polarused\&.plot
  197. gnuplot < polarused\&.plot > polarused\&.png
  198. gpsprof \-f polarunused \-T jpeg \-r < polar\&.json > polarunused\&.plot
  199. gnuplot < polarunused\&.plot > polarunused\&.png
  200. .fi
  201. .if n \{\
  202. .RE
  203. .\}
  204. .sp
  205. .SH "SEE ALSO"
  206. .PP
  207. \fBgpsd\fR(8),
  208. \fBgps\fR(1),
  209. \fBlibgps\fR(3),
  210. \fBlibgpsmm\fR(3),
  211. \fBgpsfake\fR(1),
  212. \fBgpsctl\fR(1),
  213. \fBgpscat\fR(1),
  214. \fBgnuplot\fR(1)\&.
  215. .SH "AUTHOR"
  216. .PP
  217. Eric S\&. Raymond
  218. <esr@thyrsus\&.com>\&.