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