'\" t
.\"     Title: gpsprof
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 6 December 2020
.\"    Manual: GPSD Documentation
.\"    Source: The GPSD Project
.\"  Language: English
.\"
.TH "GPSPROF" "1" "6 December 2020" "The GPSD Project" "GPSD Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
gpsprof \- profile a GPS and gpsd, plotting latency information
.SH "SYNOPSIS"
.HP \w'\fBgpsprof\fR\ 'u
\fBgpsprof\fR [\-?] [\-\-debug\ \fILVL\fR] [\-\-device\ \fIDEV\fR] [\-\-dumpfile\ \fIFILE\fR] [\-\-formatter\ \fITYPE\fR] [\-\-help] [\-\-host\ \fIHOST\fR] [\-\-logfile\ \fIFILE\fR] [\-\-port\ \fIPORT\fR] [\-\-redo] [\-\-subtitle\ \fISUBTITLE\fR] [\-\-terminal\ \fITERMINAL\fR] [\-\-threshold\ \fITHRESHOLD\fR] [\-\-title\ \fITITLE\fR] [\-\-wait\ \fISECONDS\fR] [\-\-version] [\-D\ \fILVL\fR] [\-d\ \fIFILE\fR] [\-f\ \fITYPE\fR] [\-h] [\-l\ \fIFILE\fR] [\-m\ \fITHRESHOLD\fR] [\-n\ \fISECONDS\fR] [\-r] [\-S\ \fISUBTITLE\fR] [\-T\ \fITERMINAL\fR] [\-t\ \fITITLE\fR] [\-V] [[server[:port[:device]]]]
.SH "DESCRIPTION"
.PP
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\&.
.PP
Information from the default spatial plot it provides can be useful for characterizing position accuracy of a GPS\&.
.PP
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\&.
.PP
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\&.
.SH "OPTIONS"
.PP
The
\fB\-f, \-\-formatter\fR
option sets the plot type\&. Currently the following plot types are defined:
.PP
\fBspace\fR
.RS 4
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\&.
.RE
.PP
\fBpolar\fR
.RS 4
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\&.
.RE
.PP
\fBpolarunused\fR
.RS 4
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\&.
.RE
.PP
\fBpolarused\fR
.RS 4
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\&.
.RE
.PP
\fBtime\fR
.RS 4
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\&.
.RE
.PP
\fBinstrumented\fR
.RS 4
Plot instrumented profile\&. Plots various components of the total latency between the GPS\*(Aqs fix time and when the client receives the fix\&.
.sp
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\&.
.sp
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\&.
.sp
The components of the instrumented plot are as follows:
.PP
\fBFix latency\fR
.RS 4
Delta between GPS time and SORC\&.
.RE
.PP
\fBRS232 time\fR
.RS 4
RS232 transmission time for data shipped during the cycle (computed from character volume and baud rate)\&.
.RE
.PP
\fBAnalysis time\fR
.RS 4
EORC, minus SORC, minus RS232 time\&. The amount of real time the daemon spent on computation rather than I/O\&.
.RE
.PP
\fBReception time\fR
.RS 4
Shipping time from the daemon to when it was received by
gpsprof\&.
.RE
.sp
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\&.
.RE
.PP
\fBuninstrumented\fR
.RS 4
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\&.
.RE
.PP
\fB\-?\fR, \fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a usage message and exit\&.
.RE
.PP
\fB\-d FILE\fR, \fB\-\-dumpfile FILE\fR
.RS 4
Dump the plot data, without attached gnuplot code, to a specified file for post\-analysis\&.
.RE
.PP
\fB\-d LVL\fR, \fB\-\-debug LVL\fR
.RS 4
Sets debug level\&.
.RE
.PP
\fB\-l FILE\fR, \fB\-\-logfile FILE\fR
.RS 4
Dump the raw JSON reports collected from the device to the specified FILE\&.
.RE
.PP
\fB\-n SEC\fR, \fB\-\-wait SEC\fR
.RS 4
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\&.
.RE
.PP
\fB\-r\fR, \fB\-\-redo\fR
.RS 4
Replot from a JSON logfile (such as
\fB\-l, logfile\fR
produces) on standard input\&. Both
\fB\-n, \-\-wait\fR
and
\fB\-l, \-\-logfile\fR
options are ignored when this one is selected\&.
.RE
.PP
\fB\-S STR\fR, \fB\-\-subtitle STR\fR
.RS 4
Sets a text string to be included in the plot as a subtitle\&. This will be below the title\&.
.RE
.PP
\fB\-t STR\fR, \fB\-\-title STR\fR
.RS 4
Sets a text string to be the plot title\&. This will replace the default title\&.
.RE
.PP
\fB\-T TERM\fR, \fB\-\-terminal TERM\fR
.RS 4
Add a terminal type setting into the gnuplot code\&. Typical usage is "\fB\-T png\fR", or "\fB\-T pngcairo\fR" telling gnuplot to write a PNG file\&. Without this option gnuplot will call its X11 display code\&.
.sp
Different installations of
gnuplot
will support different terminal types\&. Different terminal types may work better for you than other ones\&. "\fB\-T png\fR" will generate PNG images\&. Use "\fB\-T jpeg\fR" to generate JPEG images\&. "\fB\-T pngcairo\fR" often works best, but is not supported by some distributions\&. The same terminal type may work very differently on different distributions\&.
.sp
To see which terminal types your copy of
gnuplot
supports:
.sp
.if n \{\
.RS 4
.\}
.nf
gnuplot \-e "set terminal"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.SH "SIGNALS"
.PP
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\&.
.SH "EXAMPLES"
.PP
To display the graph, use
\fBgnuplot\fR(1)\&. Thus, for example, to display the default spatial scatter plot, do this:
.sp
.if n \{\
.RS 4
.\}
.nf
gpsprof | gnuplot \-persist
.fi
.if n \{\
.RE
.\}
.PP
To generate an image file:
.sp
.if n \{\
.RS 4
.\}
.nf
gpsprof \-T png | gnuplot > image\&.png
.fi
.if n \{\
.RE
.\}
.PP
To generate a polar plot, and save the GPS data for further plots:
.sp
.if n \{\
.RS 4
.\}
.nf
gpsprof \-f polar \-T jpeg \-l polar\&.json | gnuplot > polar\&.png
.fi
.if n \{\
.RE
.\}
.sp
Then to make the matching polarused and polarunused plots and pngs from the just saved the GPS data:
.sp
.if n \{\
.RS 4
.\}
.nf
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
.fi
.if n \{\
.RE
.\}
.sp
.SH "SEE ALSO"
.PP
\fBgpsd\fR(8),
\fBgps\fR(1),
\fBlibgps\fR(3),
\fBlibgpsmm\fR(3),
\fBgpsfake\fR(1),
\fBgpsctl\fR(1),
\fBgpscat\fR(1),
\fBgnuplot\fR(1)\&.
.SH "AUTHOR"
.PP
Eric S\&. Raymond
<esr@thyrsus\&.com>\&.