path: root/gpsprof.xml

<?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>