diff options
Diffstat (limited to 'man/gpsprof.xml')
| -rw-r--r-- | man/gpsprof.xml | 291 |
1 files changed, 291 insertions, 0 deletions
diff --git a/man/gpsprof.xml b/man/gpsprof.xml new file mode 100644 index 00000000..bdc22691 --- /dev/null +++ b/man/gpsprof.xml @@ -0,0 +1,291 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2010 by the GPSD project +SPDX-License-Identifier: BSD-2-clause +--> +<!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>30 May 2018</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'>-D <replaceable>debuglevel</replaceable></arg> + <arg choice='opt'>-d <replaceable>dumpfile</replaceable></arg> + <arg choice='opt'>-f <replaceable>plot_type</replaceable></arg> + <arg choice='opt'>-h </arg> + <arg choice='opt'>-l <replaceable>logfile</replaceable></arg> + <arg choice='opt'>-m <replaceable>threshold</replaceable></arg> + <arg choice='opt'>-n <replaceable>samplecount</replaceable></arg> + <arg choice='opt'>-r </arg> + <arg choice='opt'>-S <replaceable>subtitle</replaceable></arg> + <arg choice='opt'>-T <replaceable>terminal</replaceable></arg> + <arg choice='opt'>-t <replaceable>title</replaceable></arg> + <arg choice='opt'>[server[:port[:device]]]</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1 id='description'><title>DESCRIPTION</title> + +<para><application>gpsprof</application> performs accuracy, latency, +skyview, 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 characterizing position accuracy of a GPS.</para> + +<para><application>gpsprof</application> uses instrumentation built +into <application>gpsd</application>. It can read data from a local +or remote running <application>gpsd</application>. Or it can read +data from a saved logfile.</para> + +<para><application>gpsprof</application> is designed to be lightweight +and use minimal host resources. No graphics subsystem needs to be +installed on the host running <application>gpsprof</application>. Simply +copy the resultant plot file to another host to be rendered +with <application>gnuplot</application>. +</para> + +</refsect1> +<refsect1 id='options'><title>OPTIONS</title> + +<para>The -f option sets the plot type. Currently the following plot +types are defined:</para> + +<variablelist> +<varlistentry> +<term>space</term> +<listitem> +<para>Generate a scatterplot of fixes and plot probable error circles. +This data is only meaningful if the GPS is held stationary while +<application>gpsprof</application> is running. Various statistics about +the fixes are listed at the bottom. This is the default plot type.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>polar</term> +<listitem> +<para>Generate a heat map of reported satellite Signal to Noise Ratio +(SNR) using polar coordinates. A colored dot is plotted for +each satellite seen by the GPS. The color of dot corresponds to the +SNR of the satellite. The dots are plotted by azimuth and +elevation. North, azimuth 0 degrees, is at the top of the plot. +Directly overhead, elevation of 90 degrees, is plotted at the center. +Useful for analyzing the quality of the skyview as seen by the GPS. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>polarunused</term> +<listitem> +<para>Similar to the polar plot, but only unused satellites +are plotted. Useful for seeing which parts of the antenna skyview +are obstructed, degraded, below the GPS elevation mask, or otherwise +rejected.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>polarused</term> +<listitem> +<para>Similar to the polar plot, but only satellites used to compute +fixs are plotted. Useful for seeing which parts of the antenna +skyview are being used in fixes.</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. The X axis is sample time in seconds +from the start of the plot. The Y axis is the system clock delta from +GPS time. This plot only works if <application>gpsd</application> was +built with the timing (latency timing support) configure option +enabled.</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 and when the client receives the +fix. This plot only works if <application>gpsd</application> was built +with the timing (latency timing support) configuration option enabled. +</para> +<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> + +</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. +The X axis is sample time in seconds from the start of the plot. The Y +axs is latency in seconds.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> +</variablelist> + + +<para>The -d option dumps the plot data, without attached gnuplot +code, to a specified file for post-analysis.</para> + +<para>The -D sets debug level.</para> + +<para>The -h option makes <application>gpsprof</application> print +a usage message and exit.</para> + +<para>The -l option dumps the raw JSON reports collected from the device +to a specified file.</para> + +<para>The -n option sets the number of packets to sample. The default +is 100. Most GPS are configured to emit one fix per second, so 100 +samples would then span 100 seconds.</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 -S option sets a text string to be included in the plot +as a subtitle. This will be below the title.</para> + +<para>The -t option sets a text string to be the plot title. This +will replace the default title.</para> + +<para>The -T option generates a terminal type setting into the gnuplot +code. Typical usage is "-T png", or "-T pngcairo" telling gnuplot to +write a PNG file. Without this option gnuplot will call its X11 display +code.</para> +<para> Different installations of <application>gnuplot</application> will +support different terminal types. Different terminal types may work better +for you than other ones. "-T png" will generate PNG images. Use "-T jpeg" +to generate JPEG images. "-T pngcairo" often works best, but is not +supported by some distributions.</para> + +</refsect1> +<refsect1 id='signals'><title>SIGNALS</title> +<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='examples'><title>EXAMPLES</title> +<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> +<para> +To generate a polar plot, and save the GPS data for further plots: +<programlisting> +gpsprof -f polar -T jpeg -l polar.json | gnuplot > polar.png +</programlisting> +Then to make the matching polarused and polarunused plots and pngs from +the just saved the GPS data: +<programlisting> +gpsprof -f polarused -T jpeg -r < polar.json > polarused.plot +gnuplot < polarused.plot > polarused.png +gpsprof -f polarunused -T jpeg -r < polar.json > polarunused.plot +gnuplot < polarunused.plot > polarunused.png +</programlisting> +</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>libgpsmm</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> + |