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
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.1.2//EN"
"docbook/docbookx.dtd">
<refentry id='gpsprof.1'>
<refmeta>
<refentrytitle>gpsprof</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class='date'>10 Feb 2005</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'>-o <replaceable>outfile</replaceable></arg>
<arg choice='opt'>-r </arg>
<arg choice='opt'>-s <replaceable>speed</replaceable></arg>
<arg choice='opt'>-t <replaceable>title</replaceable></arg>
<arg choice='opt'>-T <replaceable>terminal type</replaceable></arg>
<arg choice='opt'>-h</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id='description'><title>DESCRIPTION</title>
<para><application>gpsprof</application> measures the various
latencies between a GPS and its client. It draws an illustrative
graph. It can also be told to save the raw profile data. The
information it provides can be useful for establishing an upper bound
on latency, and thus on position accuracy of a GPS in motion,
especially in combination with the static-precision reports from
<citerefentry><refentrytitle>gpsprobe</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>
<para><application>gpsprof</application> uses instrumentation built
into <application>gpsd</application> that will only be present if
it was configured to support profiling.</para>
<para>Graphs are generated using
<citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
</refsect1>
<refsect1 id='options'><title>OPTIONS</title>
<para>The -f option sets the plot type. The X axis is samples
(sentences with timestamps). The Y axis is latency in seconds.
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.</para>
<para></para>
</listitem>
</varlistentry>
<varlistentry>
<term>raw</term>
<listitem>
<para>Plot raw data.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>split</term>
<listitem>
<para>Plot filtered data. Sentences with an apparent latency larger
than 1 second are discarded. Each sentence has its RS232 latency
time colored differently. This is the default.</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.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Each plot conveys the following information:</para>
<variablelist>
<varlistentry>
<term>RS232 time</term>
<listitem>
<para>Minimum time required to send the sentence from the GPS to
<application>gpsd</application>. This is computed, not measured,
and may be an underestimate.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Other line latency</term>
<listitem>
<para>The transmission latency between the GPS and
<application>gpsd</application> not accounted for by RS232 time.
Total line latency (the sum of this bar and RS232 time)
is measured; it begins with the GPS sentence's timestamp and ends with
a timestamp that <application>gpsd</application> generates at
sentence-reading time, before it is decoded.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Decode time</term>
<listitem>
<para>Elapsed time between sentence reception and the moment that
<application>gpsd</application> ships the resulting update to
the profiling client.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>TCP/IP latency</term>
<listitem>
<para>Elapsed time between the moment that
<application>gpsd</application> ships the update to
the profiling client and the moment it is decoded and timestamped.</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 -o option specifies the name of a file in which to dump the
profiling data;
<citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
will read out from there. If this option is not specified, the data
will be written to a tempfile and discarded after the plot id made</para>
<para>The -s option sets the baud rate. Note, this will only work if
the chipset accepts a speed-change command (SiRF-II supports this
feature).</para>
<para>The -t option sets a text string to be included in the plot
title. Specifying the GPS make and model is a good use for it.</para>
<para>The -T option sets a terminal type for
<citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
. It will normally default to "x11" at produce a display immediately,
but (for example) specifying "-T png" will instead cause a PNG image
of the graphic to be shipped to standard output.</para>
<para>The -h option makes <application>gpsprof</application> print
a usage message and exit.</para>
</refsect1>
<refsect1 id='bugs'><title>BUGS AND LIMITAIONS</title>
<para>Probably overestimates TCP/IP latency somewhat, as that includes the
Python interpreter's decode time. A C client would be faster.</para>
</refsect1>
<refsect1 id='see_also'><title>SEE ALSO</title>
<para>
<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<citerefentry><refentrytitle>gpsprobe</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>. There is a
project page for <application>gpsd</application> <ulink
url="http://gpsd.berlios.de/">here</ulink>.</para>
</refsect1>
</refentry>
|
