1GPSPROF(1) GPSD Documentation GPSPROF(1)
2
6 gpsprof - profile a GPS and gpsd, plotting latency information
7
9 gpsprof [-D debuglevel] [-d dumpfile] [-f plot_type] [-h] [-l logfile]
10 [-m threshold] [-n samplecount] [-r] [-S subtitle]
11 [-T terminal] [-t title] [[server[:port[:device]]]]
12
14 gpsprof performs accuracy, latency, skyview, and time drift profiling
15 on a GPS. It emits to standard output a GNUPLOT program that draws one
16 of several illustrative graphs. It can also be told to emit the raw
17 profile data.
18 Information from the default spatial plot it provides can be useful for
20 characterizing position accuracy of a GPS.
21 gpsprof uses instrumentation built into gpsd. It can read data from a
23 local or remote running gpsd. Or it can read data from a saved logfile.
24 gpsprof is designed to be lightweight and use minimal host resources.
26 No graphics subsystem needs to be installed on the host running
27 gpsprof. Simply copy the resultant plot file to another host to be
28 rendered with gnuplot.
29
31 The -f option sets the plot type. Currently the following plot types
32 are defined:
33 space
35 Generate a scatterplot of fixes and plot probable error circles.
36 This data is only meaningful if the GPS is held stationary while
37 gpsprof is running. Various statistics about the fixes are listed
38 at the bottom. This is the default plot type.
39 polar
41 Generate a heat map of reported satellite Signal to Noise Ratio
42 (SNR) using polar coordinates. A colored dot is plotted for each
43 satellite seen by the GPS. The color of dot corresponds to the SNR
44 of the satellite. The dots are plotted by azimuth and elevation.
45 North, azimuth 0 degrees, is at the top of the plot. Directly
46 overhead, elevation of 90 degrees, is plotted at the center. Useful
47 for analyzing the quality of the skyview as seen by the GPS.
48 polarunused
50 Similar to the polar plot, but only unused satellites are plotted.
51 Useful for seeing which parts of the antenna skyview are
52 obstructed, degraded, below the GPS elevation mask, or otherwise
53 rejected.
54 polarused
56 Similar to the polar plot, but only satellites used to compute fixs
57 are plotted. Useful for seeing which parts of the antenna skyview
58 are being used in fixes.
59 time
61 Plot delta of system clock (NTP corrected time) against GPS time as
62 reported in PPS messages. The X axis is sample time in seconds from
63 the start of the plot. The Y axis is the system clock delta from
64 GPS time. This plot only works if gpsd was built with the timing
65 (latency timing support) configure option enabled.
66 instrumented
68 Plot instrumented profile. Plots various components of the total
69 latency between the GPS's fix time and when the client receives the
70 fix. This plot only works if gpsd was built with the timing
71 (latency timing support) configuration option enabled.
72 For purposes of the description, below, start-of-reporting-cycle
74 (SORC) is when a device's reporting cycle begins. This time is
75 detected by watching to see when data availability follows a long
76 enough amount of quiet time that we can be sure we've seen the gap
77 at the end of the sensor's previous report-transmission cycle.
78 Detecting this gap requires a device running at 9600bps or faster.
79 Similarly, EORC is end-of-reporting-cycle; when the daemon has seen
81 the last sentence it needs in the reporting cycle and ready to ship
82 a fix to the client.
83 The components of the instrumented plot are as follows:
85 Fix latency
87 Delta between GPS time and SORC.
88 RS232 time
90 RS232 transmission time for data shipped during the cycle
91 (computed from character volume and baud rate).
92 Analysis time
94 EORC, minus SORC, minus RS232 time. The amount of real time the
95 daemon spent on computation rather than I/O.
96 Reception time
98 Shipping time from the daemon to when it was received by
99 gpsprof.
100 Because of RS232 buffering effects, the profiler sometimes
102 generates reports of ridiculously high latencies right at the
103 beginning of a session. The -m option lets you set a latency
104 threshold, in multiples of the cycle time, above which reports are
105 discarded.
106 uninstrumented
108 Plot total latency without instrumentation. Useful mainly as a
109 check that the instrumentation is not producing significant
110 distortion. The X axis is sample time in seconds from the start of
111 the plot. The Y axs is latency in seconds.It only plots times for
112 reports that contain fixes; staircase-like artifacts in the plot
113 are created when elapsed time from reports without fixes is lumped
114 in.
115 The -d option dumps the plot data, without attached gnuplot code, to a
117 specified file for post-analysis.
118 The -D sets debug level.
120 The -h option makes gpsprof print a usage message and exit.
122 The -l option dumps the raw JSON reports collected from the device to a
124 specified file.
125 The -n option sets the number of packets to sample. The default is 100.
127 Most GPS are configured to emit one fix per second, so 100 samples
128 would then span 100 seconds.
129 The -r option replots from a JSON logfile (such as -l produces) on
131 standard input. Both -n and -l options are ignored when this one is
132 selected.
133 The -S option sets a text string to be included in the plot as a
135 subtitle. This will be below the title.
136 The -t option sets a text string to be the plot title. This will
138 replace the default title.
139 The -T option generates a terminal type setting into the gnuplot code.
141 Typical usage is "-T png", or "-T pngcairo" telling gnuplot to write a
142 PNG file. Without this option gnuplot will call its X11 display code.
143 Different installations of gnuplot will support different terminal
145 types. Different terminal types may work better for you than other
146 ones. "-T png" will generate PNG images. Use "-T jpeg" to generate JPEG
147 images. "-T pngcairo" often works best, but is not supported by some
148 distributions.
149
151 Sending SIGUSR1 to a running instance causes it to write a completion
152 message to standard error and resume processing. The first number in
153 the startup message is the process ID to signal.
154
156 To display the graph, use gnuplot(1). Thus, for example, to display the
157 default spatial scatter plot, do this:
158 gpsprof | gnuplot -persist
160 To generate an image file:
162 gpsprof -T png | gnuplot > image.png
164 To generate a polar plot, and save the GPS data for further plots:
166 gpsprof -f polar -T jpeg -l polar.json | gnuplot > polar.png
168 Then to make the matching polarused and polarunused plots and pngs from
170 the just saved the GPS data:
171 gpsprof -f polarused -T jpeg -r < polar.json > polarused.plot
173 gnuplot < polarused.plot > polarused.png
174 gpsprof -f polarunused -T jpeg -r < polar.json > polarunused.plot
175 gnuplot < polarunused.plot > polarunused.png
176
179 gpsd(8), gps(1), libgps(3), libgpsmm(3), gpsfake(1), gpsctl(1),
180 gpscat(1), gnuplot(1).
181
183 Eric S. Raymond <esr@thyrsus.com>.
184The GPSD Project 30 May 2018 GPSPROF(1)