gpsfake.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='gpsfake.1'>
  10 <refentryinfo><date>12 Feb 2005</date></refentryinfo>
  11 <refmeta>
  12 <refentrytitle>gpsfake</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>gpsfake</refname>
  19 <refpurpose>test harness for gpsd, simulating a GPS</refpurpose>
  20 </refnamediv>
  21 <refsynopsisdiv id='synopsis'>
  22
  23 <cmdsynopsis>
  24   <command>gpsfake</command>
  25       <arg choice='opt'>-1</arg>
  26       <arg choice='opt'>-h</arg>
  27       <arg choice='opt'>-b</arg>
  28       <arg choice='opt'>-c <replaceable>interval</replaceable></arg>
  29       <arg choice='opt'>-i</arg>
  30       <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg>
  31       <arg choice='opt'>-l</arg>
  32       <arg choice='opt'>-m <replaceable>monitor</replaceable></arg>
  33       <arg choice='opt'>-n</arg>
  34       <arg choice='opt'>-o <replaceable>options</replaceable></arg>
  35       <arg choice='opt'>-p</arg>
  36       <arg choice='opt'>-r <replaceable>initcmd</replaceable></arg>
  37       <arg choice='opt'>-s <replaceable>speed</replaceable></arg>
  38       <arg choice='opt'>-u</arg>
  39       <arg choice='opt'>-v</arg>
  40       <arg rep='repeat'>
  41             <arg choice='plain'><replaceable>logfile</replaceable></arg>
  42       </arg>
  43 </cmdsynopsis>
  44 </refsynopsisdiv>
  45
  46 <refsect1 id='description'><title>DESCRIPTION</title>
  47
  48 <para><application>gpsfake</application> is a test harness for
  49 <application>gpsd</application> and its clients.  It opens a pty
  50 (pseudo-TTY), launches a <application>gpsd</application> instance that
  51 thinks the slave side of the pty is its GPS device, and repeatedly
  52 feeds the contents of one or more test logfiles through the master side to the
  53 GPS. If there are multiple logfiles, sentences from them are
  54 interleaved in the order the fuiles are specified.</para>
  55
  56 <para><application>gpsfake</application> does not require root
  57 privileges, and can be run concurrently with a production
  58 <application>gpsd</application> instance without causing problems.</para>
  59
  60 <para>The logfiles may be of NMEA, SiRF packets, TSIP packets, or
  61 Zodiac packets.  Leading lines beginning with # will be treated as
  62 comments and ignored.</para>
  63
  64 <para>The <application>gpsd</application> instance is run in
  65 foreground.  The thread sending fake GPS data to the daemon
  66 is run in background.</para>
  67
  68 </refsect1>
  69 <refsect1 id='options'><title>OPTIONS</title>
  70
  71 <para>With the -1 option, the logfile is interpreted once only rather
  72 than repeatedly.  This option is intended to facilitate regression
  73 testing.</para>
  74
  75 <para>The -b option enables a twirling-baton progress indicator
  76 on standard error.  At termination, it reports elapsed time.</para>
  77
  78 <para>The -c option sets the delay between sentences in
  79 seconds. Fractional values of seconds are legal.  The default is zero
  80 (no delay).</para>
  81
  82 <para>The -l option makes the program dump a line or packet number
  83 just before each sentence is fed to the daemon. If the sentence is
  84 textual (e.g. NMEA), the text is dumped as well.  If not, the packet
  85 will be dumped in hexadecimal (except for RTCM packets, which aren't
  86 dumped at all).  This option is useful for checking that gpsfake is
  87 getting packet boundaries right.</para>
  88
  89 <para>The -i option is for single-stepping through logfiles.  It dumps
  90 the line or packet number (and the sentence if the protocol is
  91 textual) followed by "? ".  Only when the user keys Enter is the line
  92 actually fed to <application>gpsd</application>.</para>
  93
  94 <para>The -m option specifies a monitor program inside which the
  95 daemon should be run.  This option is intended to be used with
  96 <citerefentry><refentrytitle>valgrind</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  97 <citerefentry><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  98 and similar programs.</para>
  99
 100 <para>The -g option uses the monitor facility to run the
 101 <application>gpsd</application> instance within gpsfake under control
 102 of gdb.</para>
 103
 104 <para>The -o option specifies options to pass to the daemon.  The -n
 105 option passes -n to start the daemon reading the GPS without waiting
 106 for a client (equivalent to -o "-n").  The -D option passes a -D
 107 option to the daemon: thus -D 4 is shorthand for -o "-D 4".</para>
 108
 109 <para>The -p ("pipe") option sets watcher mode and dumps the NMEA and GPSD
 110 notifications generated by the log to standard output. This is useful
 111 for regression-testing.</para>
 112
 113 <para>The -r option specifies an initialization command to use in pipe mode.
 114 The default is <command>?WATCH={"enable":true,"json":true}</command>.</para>
 115
 116 <para>The -s option sets the baud rate for the slave tty.  The
 117 default is 4800.</para>
 118
 119 <para>The -u option forces the test framework to use UDP rather than
 120 pty devices. This may be useful for testing from within chroot jails
 121 where access to pty devices is locked out.</para>
 122
 123 <para>The -v option enables verbose progress reports to stderr.  It is
 124 mainly useful for debugging <application>gpsfake</application>
 125 itself.</para>
 126
 127 <para>The -x option dumps packets as
 128 <application>gpsfake</application> gathers them.  It is mainly useful
 129 for debugging <application>gpsfake</application> itself.</para>
 130
 131 <para>The -h option makes <application>gpsfake</application> print
 132 a usage message and exit.</para>
 133
 134 <para>The argument must be the name of a file containing the
 135 data to be cycled at the device. <application>gpsfake</application>
 136 will print a notification each time it cycles.</para>
 137
 138 <para>Normally, gpsfake creates a pty for each logfile and passes the
 139 slave side of the debice to the daemon.  If the header comment in the
 140 logfile contains the string "UDP", packets are instead shipped via UDP
 141 port 5000 to the addess 192.168.0.1.255.  You can monitoer them with
 142 this: <command>tcpdump -s0 -n -A -i lo udp and port 5000</command>.</para>
 143
 144 </refsect1>
 145 <refsect1 id='custom'><title>CUSTOM TESTS</title>
 146
 147 <para><application>gpsfake</application> is a trivial wrapper around a
 148 Python module, also named gpsfake, that can be used to fully script
 149 sessions involving a <application>gpsd</application> instance, any
 150 number of client sessions, and any number of fake GPSes feeding the
 151 daemon instance with data from specified sentence logs.</para>
 152
 153 <para>Source and embedded documentation for this module is shipped with the
 154 <application>gpsd</application> development tools.  You can use it to
 155 torture-test either <application>gpsd</application> itself or any
 156 <application>gpsd</application>-aware client application.</para>
 157
 158 <para>Logfiles for the use with <application>gpsfake</application> can
 159 be retrieved using <application>gpspipe</application>,
 160 <application>gpscat</application>, or
 161 <application>gpsmon</application> from the gpsd distribution, or any
 162 other application which is able to create a compatible output.</para>
 163
 164 <para>If <application>gpsfake</application> exits with "Cannot execute
 165 gpsd: executable not found." the environment variable GPSD_HOME can be
 166 set to the path where gpsd can be found. (instead of adding that folder
 167 to the PATH envirnment variable</para>
 168
 169 </refsect1>
 170 <refsect1 id='see_also'><title>SEE ALSO</title>
 171 <para>
 172 <citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 173 <citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 174 <citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 175 <citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 176 <citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 177 <citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 178 <citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 179 <citerefentry><refentrytitle>gpsmon</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 180 </para>
 181 </refsect1>
 182
 183 <refsect1 id='maintainer'><title>AUTHOR</title>
 184
 185 <para>Eric S. Raymond <email>esr@thyrsus.com</email>.  There is a
 186 project page for <application>gpsd</application> <ulink
 187 url="http://gpsd.berlios.de/">here</ulink>.</para>
 188
 189 </refsect1>
 190
 191 </refentry>
 192