MAN-J
Man PagesPricing
LoginGet Started
gpsprof(1)
Original
English • 242 lines
GPSPROF(1)		      GPSD Documentation		    GPSPROF(1)

NAME
       gpsprof - profile a GPS and gpsd, plotting latency information

SYNOPSIS
       gpsprof [OPTIONS] [server[:port[:device]]]

       gpsprof -h

       gpsprof -V

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

       gpsprof does not require root privileges, but it will run fine as root.

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(1) 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
	   Specify the terminal type setting in the gnuplot(1) code. Typical
	   usage is "-T png", or "-T pngcairo" telling gnuplot(1) to write a
	   PNG file.  The default terminal is "x11".

	   Different installations of gnuplot(1) 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(1) supports:

	   gnuplot -e "set terminal"

ARGUMENTS
       By default, clients collect data from the local gpsd daemon running on
       localhost, using the default GPSD port 2947. The optional argument to
       any client may override this behavior: [server[:port[:device]]]

       For further explanation, and examples, see the ARGUMENTS section in the
       gps(1) man page

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 on your x11 display, 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

       You can split the pieces up, so you do not need to run the entire chain
       at once.	 To allow tweaking settings without recollecting all the data.
       Like this:

	   gpspipe -w -x 3600 ::/dev/ttyS0 > MY.raw
	   gpsdecode  < MY.raw > MY.json
	   gpsprof -r -T pngcairo -t "MY Title" < MY.json > MY.plt
	   gnuplot MY.plt > MY.png
	   display MY.png

       The gpspipe saves one hour of raw data from the local gpsd device
       /dev/ttyS0 into MY.raw.	It will take one hour to complete.

       The gpsdecode converts the raw data in MY.raw into a gpsd JSON file
       called MY.json.

       The gpsprof reads MY.json and creates a gnuplot program in MY.plt.

       The gnuplot executes the program in MY.plt and creates the image file
       MY.png.

       The display program paints MY.png on your desktop.

RETURN VALUES
       0
	   on success.

       1
	   on failure

SEE ALSO
       gpsd(8), display(1), gnuplot(1), gpsctl(1), gps(1), libgps(3),
       libgpsmm(3), gpsprof(1), gpsfake(1).

RESOURCES
       Project web site:  <https://gpsd.io/>

COPYING
       This file is Copyright 2013 by the GPSD project
       SPDX-License-Identifier: BSD-2-clause

AUTHOR
       Eric S. Raymond

GPSD, Version 3.26.1		  2025-05-06			    GPSPROF(1)

gpsprof(1)

gpsprof \- profile a GPS and gpsd, plotting latency information

0popularity

System Information

GPSD, Version 3.26.1 1.0.0
Updated 2025-05-06
Maintained by Unknown

Actions