From e5548e974f42f2080a74ed2a30d1e2927fe0ad9f Mon Sep 17 00:00:00 2001 From: "Gary E. Miller" Date: Mon, 19 Nov 2018 19:56:24 -0800 Subject: man: Move man pages, source and result, into main/ part of cleaning up the root directory. --- man/gpsprof.xml | 291 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 291 insertions(+) create mode 100644 man/gpsprof.xml (limited to 'man/gpsprof.xml') diff --git a/man/gpsprof.xml b/man/gpsprof.xml new file mode 100644 index 00000000..bdc22691 --- /dev/null +++ b/man/gpsprof.xml @@ -0,0 +1,291 @@ + + + + +30 May 2018 + +gpsprof +1 +The GPSD Project +GPSD Documentation + + +gpsprof +profile a GPS and gpsd, plotting latency information + + + + + gpsprof + -D debuglevel + -d dumpfile + -f plot_type + -h + -l logfile + -m threshold + -n samplecount + -r + -S subtitle + -T terminal + -t title + [server[:port[:device]]] + + + +DESCRIPTION + +gpsprof 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. + +Information from the default spatial plot it provides can be +useful for characterizing position accuracy of a GPS. + +gpsprof uses instrumentation built +into gpsd. It can read data from a local +or remote running gpsd. Or it can read +data from a saved logfile. + +gpsprof is designed to be lightweight +and use minimal host resources. No graphics subsystem needs to be +installed on the host running gpsprof. Simply +copy the resultant plot file to another host to be rendered +with gnuplot. + + + +OPTIONS + +The -f option sets the plot type. Currently the following plot +types are defined: + + + +space + +Generate a scatterplot of fixes and plot probable error circles. +This data is only meaningful if the GPS is held stationary while +gpsprof is running. Various statistics about +the fixes are listed at the bottom. This is the default plot type. + + + +polar + +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. + + + + + +polarunused + +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. + + + + +polarused + +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. + + + + +time + +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 gpsd was +built with the timing (latency timing support) configure option +enabled. + + + + +instrumented + +Plot instrumented profile. Plots various components of the total +latency between the GPS's fix time and when the client receives the +fix. This plot only works if gpsd was built +with the timing (latency timing support) configuration option enabled. + +For purposes of the description, below, start-of-reporting-cycle +(SORC) is when a device's 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've seen the gap at +the end of the sensor's previous report-transmission cycle. Detecting +this gap requires a device running at 9600bps or faster. + +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. + +The components of the instrumented plot are as follows: + + + +Fix latency + +Delta between GPS time and SORC. + + + +RS232 time + +RS232 transmission time for data shipped during the cycle +(computed from character volume and baud rate). + + + +Analysis time + +EORC, minus SORC, minus RS232 time. The amount of real time the daemon +spent on computation rather than I/O. + + + +Reception time + +Shipping time from +the daemon to when it was received by gpsprof. + + + + +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. + + + + +uninstrumented + +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. + + + + + +The -d option dumps the plot data, without attached gnuplot +code, to a specified file for post-analysis. + +The -D sets debug level. + +The -h option makes gpsprof print +a usage message and exit. + +The -l option dumps the raw JSON reports collected from the device +to a specified file. + +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. + +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. + +The -S option sets a text string to be included in the plot +as a subtitle. This will be below the title. + +The -t option sets a text string to be the plot title. This +will replace the default title. + +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. + Different installations of gnuplot 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. + + +SIGNALS +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. + + +EXAMPLES +To display the graph, use +gnuplot1. +Thus, for example, to display the default spatial scatter plot, do +this: + + +gpsprof | gnuplot -persist + + + +To generate an image file: + + +gpsprof -T png | gnuplot > image.png + + + +To generate a polar plot, and save the GPS data for further plots: + +gpsprof -f polar -T jpeg -l polar.json | gnuplot > polar.png + +Then to make the matching polarused and polarunused plots and pngs from +the just saved the GPS data: + +gpsprof -f polarused -T jpeg -r < polar.json > polarused.plot +gnuplot < polarused.plot > polarused.png +gpsprof -f polarunused -T jpeg -r < polar.json > polarunused.plot +gnuplot < polarunused.plot > polarunused.png + + + + +SEE ALSO + +gpsd8, +gps1, +libgps3, +libgpsmm3, +gpsfake1, +gpsctl1, +gpscat1, +gnuplot1. + + + +AUTHOR + +Eric S. Raymond esr@thyrsus.com. + + + + + -- cgit v1.2.1