Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GPSPROF(1)		      GPSD Documentation		    GPSPROF(1)

       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]]]]

       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.

       The -f option sets the plot type. Currently the following plot types
       are defined:

	   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.

	   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.

	   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

	   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.

	   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.

	   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

	   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

	   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

       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

       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

       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.

       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

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

       Eric S. Raymond <>.

The GPSD Project		  30 May 2018			    GPSPROF(1)


Want to link to this manual page? Use this URL:

home | help