gpsprof.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!--
   3 This file is Copyright (c) 2010 by the GPSD project
   4 BSD terms apply: see the file COPYING in the distribution root for details.
   5 -->
   6 <!DOCTYPE refentry PUBLIC
   7    "-//OASIS//DTD DocBook XML V4.1.2//EN"
   8    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   9 <refentry id='gpsprof.1'>
  10 <refentryinfo><date>10 Feb 2005</date></refentryinfo>
  11 <refmeta>
  12 <refentrytitle>gpsprof</refentrytitle>
  13 <manvolnum>1</manvolnum>
  14 <refmiscinfo class="source">The GPSD Project</refmiscinfo>
  15 <refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
  16 </refmeta>
  17 <refnamediv id='name'>
  18 <refname>gpsprof</refname>
  19 <refpurpose>profile a GPS and gpsd, plotting latency information</refpurpose>
  20 </refnamediv>
  21 <refsynopsisdiv id='synopsis'>
  22
  23 <cmdsynopsis>
  24   <command>gpsprof</command>
  25       <arg choice='opt'>-f <replaceable>plot_type</replaceable></arg>
  26       <arg choice='opt'>-m <replaceable>threshold</replaceable></arg>
  27       <arg choice='opt'>-n <replaceable>packetcount</replaceable></arg>
  28       <arg choice='opt'>-s <replaceable>speed</replaceable></arg>
  29       <arg choice='opt'>-t <replaceable>title</replaceable></arg>
  30       <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg>
  31       <arg choice='opt'>-h</arg>
  32 </cmdsynopsis>
  33 </refsynopsisdiv>
  34
  35 <refsect1 id='description'><title>DESCRIPTION</title>
  36
  37 <para><application>gpsprof</application> measures the various
  38 latencies between a GPS and its client. It emits to standard output a
  39 GNUPLOT program that draws an illustrative graph. It can also be told
  40 to emit the raw profile data.  The information it provides can be
  41 useful for establishing an upper bound on latency, and thus on
  42 position accuracy of a GPS in motion.</para>
  43
  44 <para><application>gpsprof</application> uses instrumentation built
  45 into <application>gpsd</application>.</para>
  46
  47 <para>To display the graph, use
  48 <citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
  49 Thus, for example, to display the default spatial scatter plot, do
  50 this:
  51
  52 <programlisting>
  53 gpsprof | gnuplot -persist
  54 </programlisting>
  55 </para>
  56
  57 </refsect1>
  58 <refsect1 id='options'><title>OPTIONS</title>
  59
  60 <para>The -f option sets the plot type. The X axis is samples
  61 (sentences with timestamps).  The Y axis is normally latency in seconds.
  62 Currently the following plot types are defined:</para>
  63
  64 <variablelist>
  65 <varlistentry>
  66 <term>space</term>
  67 <listitem>
  68 <para>Generate a scattergram of fixes and plot a probable-error
  69 circle.  This data is only meaningful if the GPS is held stationary
  70 while <application>gpsprof</application> is running.
  71 This is the default.</para>
  72 <para></para>
  73 </listitem>
  74 </varlistentry>
  75 <varlistentry>
  76 <term>uninstrumented</term>
  77 <listitem>
  78 <para>Plot total latency without instrumentation.  Useful mainly as a
  79 check that the instrumentation is not producing significant
  80 distortion.  It only plots times for sentences that contain fixes;
  81 staircase-like artifacts in the plot are created when elapsed time
  82 from sentences without fixes is lumped in.</para>
  83 </listitem>
  84 </varlistentry>
  85 <varlistentry>
  86 <term>raw</term>
  87 <listitem>
  88 <para>Plot raw data.</para>
  89 </listitem>
  90 </varlistentry>
  91 <varlistentry>
  92 <term>split</term>
  93 <listitem>
  94 <para>Each sentence has its RS232 latency time colored differently.</para>
  95 </listitem>
  96 </varlistentry>
  97 <varlistentry>
  98 <term>cycle</term>
  99 <listitem>
 100 <para>Report on the set of sentences or packets emitted by the GPS,
 101 their send intervals, and the basic cycle time. (This report is
 102 plain text rather than a gnuplot script.)</para>
 103 </listitem>
 104 </varlistentry>
 105 </variablelist>
 106
 107 <para>The instrumented time plot conveys the following information:</para>
 108
 109 <variablelist>
 110 <varlistentry>
 111 <term>RS232 time</term>
 112 <listitem>
 113 <para>Time required to send the sentence from the GPS to
 114 <application>gpsd</application>. This measured from the time of
 115 the last zero-length read before the packet to when the packet sniffer
 116 recognizes a complete sentence, so there is a small aountt of
 117 computational overhead mixed in.</para>
 118 </listitem>
 119 </varlistentry>
 120 <varlistentry>
 121 <term>Decode time</term>
 122 <listitem>
 123 <para>Elapsed time between sentence reception and the moment that
 124 <application>gpsd</application> ships the resulting update to
 125 the profiling client.</para>
 126 </listitem>
 127 </varlistentry>
 128 <varlistentry>
 129 <term>TCP/IP latency</term>
 130 <listitem>
 131 <para>Elapsed time between the moment that
 132 <application>gpsd</application> ships the update to
 133 the profiling client and the moment it is decoded and timestamped.</para>
 134 </listitem>
 135 </varlistentry>
 136 </variablelist>
 137
 138 <para>Because of RS232 buffering effects, the profiler sometimes
 139 generates reports of ridiculously high latencies right at the
 140 beginning of a session.  The -m option lets you set a latency threshold, in
 141 multiples of the cycle time, above which reports are discarded.</para>
 142
 143 <para>The -n option sets the number of packets to sample.  The default
 144 is 100.</para>
 145
 146 <para>The -s option sets the baud rate.  Note, this will only work if
 147 the chipset accepts a speed-change command (SiRFstarII and SiRFstarIII
 148 support this feature).</para>
 149
 150 <para>The -t option sets a text string to be included in the plot
 151 title.</para>
 152
 153 <para>The -h option makes <application>gpsprof</application> print
 154 a usage message and exit.</para>
 155
 156 <para>The -D sets debug level.</para>
 157
 158 </refsect1>
 159 <refsect1 id='see_also'><title>SEE ALSO</title>
 160 <para>
 161 <citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 162 <citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 163 <citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 164 <citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 165 <citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 166 <citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 167 <citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 168 <citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 169 </para>
 170 </refsect1>
 171
 172 <refsect1 id='maintainer'><title>AUTHOR</title>
 173
 174 <para>Eric S. Raymond <email>esr@thyrsus.com</email>.  There is a
 175 project page for <application>gpsd</application> <ulink
 176 url="http://gpsd.berlios.de/">here</ulink>.</para>
 177
 178 </refsect1>
 179
 180 </refentry>
 181