1GPSPROF(1) GPSD Documentation GPSPROF(1)
2
6 gpsprof - profile a GPS and gpsd, plotting latency information
7
9 gpsprof [OPTIONS] [server[:port[:device]]]
10 gpsprof -h
12 gpsprof -V
14
16 gpsprof performs accuracy, latency, skyview, and time drift profiling
17 on a GPS. It emits to standard output a GNUPLOT program that draws one
18 of several illustrative graphs. It can also be told to emit the raw
19 profile data.
20 Information from the default spatial plot it provides can be useful for
22 characterizing position accuracy of a GPS.
23 gpsprof uses instrumentation built into gpsd. It can read data from a
25 local or remote running gpsd. Or it can read data from a saved logfile.
26 gpsprof is designed to be lightweight and use minimal host resources.
28 No graphics subsystem needs to be installed on the host running
29 gpsprof. Simply copy the resultant plot file to another host to be
30 rendered with gnuplot(1).
31 gpsprof does not require root privileges, but it will run fine as root.
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 (SORC)
76 is when a device’s reporting cycle begins. This time is detected by
77 watching to see when data availability follows a long enough amount of
78 quiet time that we can be sure we’ve seen the gap at the end of the
79 sensor’s previous report-transmission cycle. Detecting this gap
80 requires a device running at 9600bps or faster.
81 Similarly, EORC is end-of-reporting-cycle; when the daemon has seen the
83 last sentence it needs in the reporting cycle and ready to ship a fix
84 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 (computed
93 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 gpsprof.
101 Because of RS232 buffering effects, the profiler sometimes generates
103 reports of ridiculously high latencies right at the beginning of a
104 session. The -m option lets you set a latency threshold, in multiples
105 of the cycle time, above which reports are 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 axis 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 -?, -h, --help
117 Print a usage message and exit.
118 -d FILE, --dumpfile FILE
120 Dump the plot data, without attached gnuplot(1) code, to a
121 specified file for post-analysis.
122 -d LVL, --debug LVL
124 Sets debug level.
125 -l FILE, --logfile FILE
127 Dump the raw JSON reports collected from the device to the
128 specified FILE.
129 -n SEC, --wait SEC
131 Sets the number of seconds to sample. The default is 100. Most GPS
132 are configured to emit one fix per second, so 100 samples would
133 then span 100 seconds.
134 -r, --redo
136 Replot from a JSON logfile (such as -l, logfile produces) on
137 standard input. Both -n, --wait and -l, --logfile options are
138 ignored when this one is selected.
139 -S STR, --subtitle STR
141 Sets a text string to be included in the plot as a subtitle. This
142 will be below the title.
143 -t STR, --title STR
145 Sets a text string to be the plot title. This will replace the
146 default title.
147 -T TERM, --terminal TERM
149 Specify the terminal type setting in the gnuplot(1) code. Typical
150 usage is "-T png", or "-T pngcairo" telling gnuplot(1) to write a
151 PNG file. The default terminal is "x11".
152 Different installations of gnuplot(1) will support different
154 terminal types. Different terminal types may work better for you
155 than other ones. "-T png" will generate PNG images. Use "-T jpeg"
156 to generate JPEG images. "-T pngcairo" often works best, but is not
157 supported by some distributions. The same terminal type may work
158 very differently on different distributions.
159 To see which terminal types your copy of gnuplot(1) supports:
161 gnuplot -e "set terminal"
163
165 By default, clients collect data from the local gpsd daemon running on
166 localhost, using the default GPSD port 2947. The optional argument to
167 any client may override this behavior: [server[:port[:device]]]
168 For further explanation, and examples, see the ARGUMENTS section in the
170 gps(1) man page
171
173 Sending SIGUSR1 to a running instance causes it to write a completion
174 message to standard error and resume processing. The first number in
175 the startup message is the process ID to signal.
176
178 To display the graph, use gnuplot(1) . Thus, for example, to display
179 the default spatial scatter plot on your x11 display, do this:
180 gpsprof | gnuplot -persist
182 To generate an image file:
184 gpsprof -T png | gnuplot > image.png
186 To generate a polar plot, and save the GPS data for further plots:
188 gpsprof -f polar -T jpeg -l polar.json | gnuplot > polar.png
190 Then to make the matching polarused and polarunused plots and pngs from
192 the just saved the GPS data:
193 gpsprof -f polarused -T jpeg -r < polar.json > polarused.plot
195 gnuplot < polarused.plot > polarused.png
196 gpsprof -f polarunused -T jpeg -r < polar.json > polarunused.plot
197 gnuplot < polarunused.plot > polarunused.png
198 You can split the pieces up, so you do not need to run the entire chain
200 at once. To allow tweaking settings without recollecting all the data.
201 Like this:
202 gpspipe -w -x 3600 ::/dev/ttyS0 > MY.raw
204 gpsdecode < MY.raw > MY.json
205 gpsprof -r -T pngcairo -t "MY Title" < MY.json > MY.plt
206 gnuplot MY.plt > MY.png
207 display MY.png
208 The gpspipe saves one hour of raw data from the local gpsd device
210 /dev/ttyS0 into MY.raw. It will take one hour to complete.
211 The gpsdecode converts the raw data in MY.raw into a gpsd JSON file
213 called MY.json.
214 The gpsprof reads MY.json and creates a gnuplot program in MY.plt.
216 The gnuplot executes the program in MY.plt and creates the image file
218 MY.png.
219 The display program paints MY.png on your desktop.
221
223 0
224 on success.
225 1
227 on failure
228
230 gpsd(8), display(1), gnuplot(1), gpsctl(1), gps(1), libgps(3),
231 libgpsmm(3), gpsprof(1), gpsfake(1).
232
234 Project web site: https://gpsd.io/
235
237 This file is Copyright 2013 by the GPSD project
238 SPDX-License-Identifier: BSD-2-clause
239
241 Eric S. Raymond
242GPSD, Version 3.25 2023-01-10 GPSPROF(1)