summaryrefslogtreecommitdiff
path: root/gpsprof.xml
blob: 4beb6c0005d1646208b4facbf676ddef69c185f9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
This file is Copyright (c) 2010 by the GPSD project
BSD terms apply: see the file COPYING in the distribution root for details.
-->
<!DOCTYPE refentry PUBLIC 
   "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id='gpsprof.1'>
<refentryinfo><date>10 Feb 2005</date></refentryinfo>
<refmeta>
<refentrytitle>gpsprof</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source">The GPSD Project</refmiscinfo>
<refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>gpsprof</refname>
<refpurpose>profile a GPS and gpsd, plotting latency information</refpurpose>
</refnamediv>
<refsynopsisdiv id='synopsis'>

<cmdsynopsis>
  <command>gpsprof</command>  
      <arg choice='opt'>-f <replaceable>plot_type</replaceable></arg>
      <arg choice='opt'>-m <replaceable>threshold</replaceable></arg>
      <arg choice='opt'>-n <replaceable>packetcount</replaceable></arg>
      <arg choice='opt'>-t <replaceable>title</replaceable></arg>
      <arg choice='opt'>-T <replaceable>terminal</replaceable></arg>
      <arg choice='opt'>-d <replaceable>dumpfile</replaceable></arg>
      <arg choice='opt'>-l <replaceable>logfile</replaceable></arg>
      <arg choice='opt'>-r </arg>
      <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg>
      <arg choice='opt'>-h </arg>
      <arg choice='opt'>[server[:port[:device]]]</arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1 id='description'><title>DESCRIPTION</title>

<para><application>gpsprof</application> performs accuracy, latency,
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.</para>

<para>Information from the default spatial plot it provides can be
useful for establishing an upper bound on latency, and thus on
position accuracy of a GPS in motion.</para>

<para><application>gpsprof</application> uses instrumentation built
into <application>gpsd</application>.</para>

<para>To display the graph, use
<citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
Thus, for example, to display the default spatial scatter plot, do
this:

<programlisting>
gpsprof | gnuplot -persist
</programlisting>
</para>

<para>To generate an image file:

<programlisting>
gpsprof -T png | gnuplot >image.png
</programlisting>
</para>

</refsect1>
<refsect1 id='options'><title>OPTIONS</title>

<para>The -f option sets the plot type. The X axis is samples (either
sentences with timestamps or PPS time drift messages).  The Y axis is
normally latency in seconds, except for the spatial plot.  Currently the
following plot types are defined:</para>

<variablelist>
<varlistentry>
<term>space</term>
<listitem>
<para>Generate a scattergram of fixes and plot a probable-error
circle.  This data is only meaningful if the GPS is held stationary
while <application>gpsprof</application> is running. 
This is the default.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>time</term>
<listitem>
<para>Plot delta of system clock (NTP corrected time) against GPS time
as reported in PPS messages.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>uninstrumented</term>
<listitem>
<para>Plot total latency without instrumentation.  Useful mainly as a
check that the instrumentation is not producing significant
distortion.  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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>instrumented</term>
<listitem>
<para>Plot instrumented profile. 
Plots various components of the total latency between the GPS's fix time 
fix and when the client receives the fix.</para>
</listitem>
</varlistentry>
</variablelist>

<para>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.</para>

<para>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.</para>

<para>The components of the instrumented plot are as follows:</para>

<variablelist>
<varlistentry>
<term>Fix latency</term>
<listitem>
<para>Delta between GPS time and SORC.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RS232 time</term>
<listitem>
<para>RS232 transmission time for data shipped during the cycle 
(computed from character volume and baud rate).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Analysis time</term>
<listitem>
<para>EORC, minus SORC, minus RS232 time.  The amount of real time the daemon
spent on computation rather than I/O.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Reception time</term>
<listitem>
<para>Shipping time from
the daemon to when it was received by <application>gpsprof</application>.</para>
</listitem>
</varlistentry>
</variablelist>

<para>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.</para>

<para>The -n option sets the number of packets to sample.  The default
is 100.</para>

<para>The -t option sets a text string to be included in the plot
title.</para>

<para>The -T option generates a terminal type setting into the gnuplot code.
Typical usage is "-T png" telling gnuplot to write a PNG file.  Without
this option gnuplot will call its X11 display code.</para>

<para>The -d option dumps the plot data, without attached gnuplot
code, to a specified file for post-analysis.</para>

<para>The -l option dumps the raw JSON reports collected from the device
to a specified file.</para>

<para>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 selected.</para>

<para>The -h option makes <application>gpsprof</application> print 
a usage message and exit.</para>

<para>The -D sets debug level.</para>

<para>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.</para>

</refsect1>
<refsect1 id='see_also'><title>SEE ALSO</title>
<para>
<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>
</refsect1>

<refsect1 id='maintainer'><title>AUTHOR</title> 

<para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para>

</refsect1>

</refentry>