manpagez: man pages & more
man gpsprof(1)
Home | html | info | man
gpsprof(1)                    GPSD Documentation                    gpsprof(1)




NAME

       gpsprof - profile a GPS and gpsd, plotting latency information


SYNOPSIS

       gpsprof [-?] [--debug LVL] [--device DEV] [--dumpfile FILE]
               [--formatter TYPE] [--help] [--host HOST] [--logfile FILE]
               [--port PORT] [--redo] [--subtitle SUBTITLE]
               [--terminal TERMINAL] [--threshold THRESHOLD] [--title TITLE]
               [--wait SECONDS] [--version] [-D LVL] [-d FILE] [-f TYPE] [-h]
               [-l FILE] [-m THRESHOLD] [-n SECONDS] [-r] [-S SUBTITLE]
               [-T TERMINAL] [-t TITLE] [-V] [[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, --formatter 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
           fixes 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.

       instrumented
           Plot instrumented profile. Plots various components of the total
           latency between the GPS's fix time and when the client receives the
           fix.

           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 axis 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.

       -?, -h, --help
           Print a usage message and exit.

       -d FILE, --dumpfile FILE
           Dump the plot data, without attached gnuplot code, to a specified
           file for post-analysis.

       -d LVL, --debug LVL
           Sets debug level.

       -l FILE, --logfile FILE
           Dump the raw JSON reports collected from the device to the
           specified FILE.

       -n SEC, --wait SEC
           Sets the number of seconds to sample. The default is 100. Most GPS
           are configured to emit one fix per second, so 100 samples would
           then span 100 seconds.

       -r, --redo
           Replot from a JSON logfile (such as -l, logfile produces) on
           standard input. Both -n, --wait and -l, --logfile options are
           ignored when this one is selected.

       -S STR, --subtitle STR
           Sets a text string to be included in the plot as a subtitle. This
           will be below the title.

       -t STR, --title STR
           Sets a text string to be the plot title. This will replace the
           default title.

       -T TERM, --terminal TERM
           Add 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. The same terminal type may work very
           differently on different distributions.

           To see which terminal types your copy of gnuplot supports:

               gnuplot -e "set terminal"



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 gnuplot(1). 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

       gpsd(8), gps(1), libgps(3), libgpsmm(3), gpsfake(1), gpsctl(1),
       gpscat(1), gnuplot(1).


AUTHOR

       Eric S. Raymond <esr@thyrsus.com>.



The GPSD Project                6 December 2020                     gpsprof(1)

gpsd 3.22 - Generated Sat Jan 16 09:33:00 CST 2021
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.