1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!-- 3This file is Copyright (c) 2010 by the GPSD project 4SPDX-License-Identifier: BSD-2-clause 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>30 May 2018</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'>-D <replaceable>debuglevel</replaceable></arg> 26 <arg choice='opt'>-d <replaceable>dumpfile</replaceable></arg> 27 <arg choice='opt'>-f <replaceable>plot_type</replaceable></arg> 28 <arg choice='opt'>-h </arg> 29 <arg choice='opt'>-l <replaceable>logfile</replaceable></arg> 30 <arg choice='opt'>-m <replaceable>threshold</replaceable></arg> 31 <arg choice='opt'>-n <replaceable>samplecount</replaceable></arg> 32 <arg choice='opt'>-r </arg> 33 <arg choice='opt'>-S <replaceable>subtitle</replaceable></arg> 34 <arg choice='opt'>-T <replaceable>terminal</replaceable></arg> 35 <arg choice='opt'>-t <replaceable>title</replaceable></arg> 36 <arg choice='opt'>[server[:port[:device]]]</arg> 37</cmdsynopsis> 38</refsynopsisdiv> 39 40<refsect1 id='description'><title>DESCRIPTION</title> 41 42<para><application>gpsprof</application> performs accuracy, latency, 43skyview, and time drift profiling on a GPS. It emits to standard output 44a GNUPLOT program that draws one of several illustrative graphs. It can 45also be told to emit the raw profile data.</para> 46 47<para>Information from the default spatial plot it provides can be 48useful for characterizing position accuracy of a GPS.</para> 49 50<para><application>gpsprof</application> uses instrumentation built 51into <application>gpsd</application>. It can read data from a local 52or remote running <application>gpsd</application>. Or it can read 53data from a saved logfile.</para> 54 55<para><application>gpsprof</application> is designed to be lightweight 56and use minimal host resources. No graphics subsystem needs to be 57installed on the host running <application>gpsprof</application>. Simply 58copy the resultant plot file to another host to be rendered 59with <application>gnuplot</application>. 60</para> 61 62</refsect1> 63<refsect1 id='options'><title>OPTIONS</title> 64 65<para>The -f option sets the plot type. Currently the following plot 66types are defined:</para> 67 68<variablelist> 69<varlistentry> 70<term>space</term> 71<listitem> 72<para>Generate a scatterplot of fixes and plot probable error circles. 73This data is only meaningful if the GPS is held stationary while 74<application>gpsprof</application> is running. Various statistics about 75the fixes are listed at the bottom. This is the default plot type.</para> 76</listitem> 77</varlistentry> 78<varlistentry> 79<term>polar</term> 80<listitem> 81<para>Generate a heat map of reported satellite Signal to Noise Ratio 82(SNR) using polar coordinates. A colored dot is plotted for 83each satellite seen by the GPS. The color of dot corresponds to the 84SNR of the satellite. The dots are plotted by azimuth and 85elevation. North, azimuth 0 degrees, is at the top of the plot. 86Directly overhead, elevation of 90 degrees, is plotted at the center. 87Useful for analyzing the quality of the skyview as seen by the GPS. 88</para> 89</listitem> 90</varlistentry> 91 92<varlistentry> 93<term>polarunused</term> 94<listitem> 95<para>Similar to the polar plot, but only unused satellites 96are plotted. Useful for seeing which parts of the antenna skyview 97are obstructed, degraded, below the GPS elevation mask, or otherwise 98rejected.</para> 99</listitem> 100</varlistentry> 101 102<varlistentry> 103<term>polarused</term> 104<listitem> 105<para>Similar to the polar plot, but only satellites used to compute 106fixs are plotted. Useful for seeing which parts of the antenna 107skyview are being used in fixes.</para> 108</listitem> 109</varlistentry> 110 111<varlistentry> 112<term>time</term> 113<listitem> 114<para>Plot delta of system clock (NTP corrected time) against GPS time 115as reported in PPS messages. The X axis is sample time in seconds 116from the start of the plot. The Y axis is the system clock delta from 117GPS time. This plot only works if <application>gpsd</application> was 118built with the timing (latency timing support) configure option 119enabled.</para> 120</listitem> 121</varlistentry> 122 123<varlistentry> 124<term>instrumented</term> 125<listitem> 126<para>Plot instrumented profile. Plots various components of the total 127latency between the GPS's fix time and when the client receives the 128fix. This plot only works if <application>gpsd</application> was built 129with the timing (latency timing support) configuration option enabled. 130</para> 131<para>For purposes of the description, below, start-of-reporting-cycle 132(SORC) is when a device's reporting cycle begins. This time is 133detected by watching to see when data availability follows a long 134enough amount of quiet time that we can be sure we've seen the gap at 135the end of the sensor's previous report-transmission cycle. Detecting 136this gap requires a device running at 9600bps or faster.</para> 137 138<para>Similarly, EORC is end-of-reporting-cycle; when the daemon has 139seen the last sentence it needs in the reporting cycle and ready to ship 140a fix to the client.</para> 141 142<para>The components of the instrumented plot are as follows:</para> 143 144<variablelist> 145<varlistentry> 146<term>Fix latency</term> 147<listitem> 148<para>Delta between GPS time and SORC.</para> 149</listitem> 150</varlistentry> 151<varlistentry> 152<term>RS232 time</term> 153<listitem> 154<para>RS232 transmission time for data shipped during the cycle 155(computed from character volume and baud rate).</para> 156</listitem> 157</varlistentry> 158<varlistentry> 159<term>Analysis time</term> 160<listitem> 161<para>EORC, minus SORC, minus RS232 time. The amount of real time the daemon 162spent on computation rather than I/O.</para> 163</listitem> 164</varlistentry> 165<varlistentry> 166<term>Reception time</term> 167<listitem> 168<para>Shipping time from 169the daemon to when it was received by <application>gpsprof</application>.</para> 170</listitem> 171</varlistentry> 172</variablelist> 173 174<para>Because of RS232 buffering effects, the profiler sometimes 175generates reports of ridiculously high latencies right at the 176beginning of a session. The -m option lets you set a latency 177threshold, in multiples of the cycle time, above which reports are 178discarded.</para> 179 180</listitem> 181</varlistentry> 182<varlistentry> 183<term>uninstrumented</term> 184<listitem> 185<para>Plot total latency without instrumentation. Useful mainly as a 186check that the instrumentation is not producing significant distortion. 187The X axis is sample time in seconds from the start of the plot. The Y 188axs is latency in seconds.It only plots times for reports that contain 189fixes; staircase-like artifacts in the plot are created when elapsed 190time from reports without fixes is lumped in.</para> 191</listitem> 192</varlistentry> 193</variablelist> 194 195 196<para>The -d option dumps the plot data, without attached gnuplot 197code, to a specified file for post-analysis.</para> 198 199<para>The -D sets debug level.</para> 200 201<para>The -h option makes <application>gpsprof</application> print 202a usage message and exit.</para> 203 204<para>The -l option dumps the raw JSON reports collected from the device 205to a specified file.</para> 206 207<para>The -n option sets the number of packets to sample. The default 208is 100. Most GPS are configured to emit one fix per second, so 100 209samples would then span 100 seconds.</para> 210 211<para>The -r option replots from a JSON logfile (such as -l produces) 212on standard input. Both -n and -l options are ignored when this 213one is selected.</para> 214 215<para>The -S option sets a text string to be included in the plot 216as a subtitle. This will be below the title.</para> 217 218<para>The -t option sets a text string to be the plot title. This 219will replace the default title.</para> 220 221<para>The -T option generates a terminal type setting into the gnuplot 222code. Typical usage is "-T png", or "-T pngcairo" telling gnuplot to 223write a PNG file. Without this option gnuplot will call its X11 display 224code.</para> 225<para> Different installations of <application>gnuplot</application> will 226support different terminal types. Different terminal types may work better 227for you than other ones. "-T png" will generate PNG images. Use "-T jpeg" 228to generate JPEG images. "-T pngcairo" often works best, but is not 229supported by some distributions.</para> 230 231</refsect1> 232<refsect1 id='signals'><title>SIGNALS</title> 233<para>Sending SIGUSR1 to a running instance causes it to write a 234completion message to standard error and resume processing. The 235first number in the startup message is the process ID to signal.</para> 236</refsect1> 237 238<refsect1 id='examples'><title>EXAMPLES</title> 239<para>To display the graph, use 240<citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>. 241Thus, for example, to display the default spatial scatter plot, do 242this: 243 244<programlisting> 245gpsprof | gnuplot -persist 246</programlisting> 247</para> 248 249<para>To generate an image file: 250 251<programlisting> 252gpsprof -T png | gnuplot > image.png 253</programlisting> 254</para> 255<para> 256To generate a polar plot, and save the GPS data for further plots: 257<programlisting> 258gpsprof -f polar -T jpeg -l polar.json | gnuplot > polar.png 259</programlisting> 260Then to make the matching polarused and polarunused plots and pngs from 261the just saved the GPS data: 262<programlisting> 263gpsprof -f polarused -T jpeg -r < polar.json > polarused.plot 264gnuplot < polarused.plot > polarused.png 265gpsprof -f polarunused -T jpeg -r < polar.json > polarunused.plot 266gnuplot < polarunused.plot > polarunused.png 267</programlisting> 268</para> 269 270</refsect1> 271<refsect1 id='see_also'><title>SEE ALSO</title> 272<para> 273<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 274<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 275<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 276<citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 277<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 278<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 279<citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 280<citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>. 281</para> 282</refsect1> 283 284<refsect1 id='maintainer'><title>AUTHOR</title> 285 286<para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para> 287 288</refsect1> 289 290</refentry> 291 292
