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='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'>-g</arg> 34 <arg choice='opt'>-G</arg> 35 <arg choice='opt'>-n</arg> 36 <arg choice='opt'>-o <replaceable>options</replaceable></arg> 37 <arg choice='opt'>-p</arg> 38 <arg choice='opt'>-P <replaceable>port</replaceable></arg> 39 <arg choice='opt'>-q</arg> 40 <arg choice='opt'>-r <replaceable>initcmd</replaceable></arg> 41 <arg choice='opt'>-s <replaceable>speed</replaceable></arg> 42 <arg choice='opt'>-S</arg> 43 <arg choice='opt'>-u</arg> 44 <arg choice='opt'>-t</arg> 45 <arg choice='opt'>-T</arg> 46 <arg choice='opt'>-v</arg> 47 <arg choice='opt'>-W <replaceable>timeout</replaceable></arg> 48 <arg rep='repeat'> 49 <arg choice='plain'><replaceable>logfile</replaceable></arg> 50 </arg> 51</cmdsynopsis> 52</refsynopsisdiv> 53 54<refsect1 id='description'><title>DESCRIPTION</title> 55 56<para><application>gpsfake</application> is a test harness for 57<application>gpsd</application> and its clients. It opens a pty 58(pseudo-TTY), launches a <application>gpsd</application> instance that 59thinks the slave side of the pty is its GPS device, and repeatedly 60feeds the contents of one or more test logfiles through the master side to the 61GPS. If there are multiple logfiles, sentences from them are 62interleaved in the order the files are specified.</para> 63 64<para><application>gpsfake</application> does not require root 65privileges, and can be run concurrently with a production 66<application>gpsd</application> instance without causing problems.</para> 67 68<para>The logfiles may contain packets in any supported format, 69including in particular NMEA, SiRF, TSIP, or Zodiac. Leading lines 70beginning with # will be treated as comments and ignored, except in 71the following special cases:</para> 72 73<itemizedlist> 74<listitem><para> 75a comment of the form #Date: yyyy-mm-dd (ISO8601 date format) may be 76used to set the initial date for the log. 77</para></listitem> 78 79<listitem><para> 80a comment of the form #Serial: [0-9]* [78][NOE][12] may be used to set 81serial parameters for the log - baud rate, word length, stop bits. 82</para></listitem> 83 84<listitem><para> 85a comment of the form #Transport: UDP may be used to fake a UDP source 86rather than the normal pty. 87</para></listitem> 88</itemizedlist> 89 90<para>The <application>gpsd</application> instance is run in 91foreground. The thread sending fake GPS data to the daemon 92is run in background.</para> 93 94</refsect1> 95<refsect1 id='options'><title>OPTIONS</title> 96 97<para>With the -1 option, the logfile is interpreted once only rather 98than repeatedly. This option is intended to facilitate regression 99testing.</para> 100 101<para>The <option>-b</option> enables a twirling-baton progress indicator 102on standard error. At termination, it reports elapsed time.</para> 103 104<para>The <option>-c</option> sets the delay between sentences in 105seconds. Fractional values of seconds are legal. The default is zero 106(no delay).</para> 107 108<para>The <option>-l</option> makes the program dump a line or packet number 109just before each sentence is fed to the daemon. If the sentence is 110textual (e.g. NMEA), the text is dumped as well. If not, the packet 111will be dumped in hexadecimal (except for RTCM packets, which aren't 112dumped at all). This option is useful for checking that gpsfake is 113getting packet boundaries right.</para> 114 115<para>The <option>-i</option> is for single-stepping through logfiles. It dumps 116the line or packet number (and the sentence if the protocol is 117textual) followed by "? ". Only when the user keys Enter is the line 118actually fed to <application>gpsd</application>.</para> 119 120<para>The <option>-m</option> specifies a monitor program inside which the 121daemon should be run. This option is intended to be used with 122<citerefentry><refentrytitle>valgrind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 123<citerefentry><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry> 124and similar programs.</para> 125 126<para>The <option>-g</option> and <option>-G</option> options use the 127monitor facility to run the <application>gpsd</application> instance 128within gpsfake under control of gdb or lldb, respectively. They also 129disable the timeout on daemon inactivity, to allow for breakpointing. If 130necessary, the timeout can be reenabled by a subsequent 131<option>-W</option>.</para> 132 133<para>The <option>-o</option> specifies options to pass to the daemon. The -n 134option passes -n to start the daemon reading the GPS without waiting 135for a client (equivalent to -o "-n"). The <option>-D</option> passes a -D 136option to the daemon: thus -D 4 is shorthand for -o "-D 4".</para> 137 138<para>The -p ("pipe") option sets watcher mode and dumps the NMEA and GPSD 139notifications generated by the log to standard output. This is useful 140for regression-testing.</para> 141 142<para>The -P ("port") option sets the daemon's listening port.</para> 143 144<para>The <option>-q</option> tells gpsfake to suppress normal progress 145output and thus act in a quiet manner.</para> 146 147<para>The <option>-r</option> specifies an initialization command to use in pipe mode. 148The default is <command>?WATCH={"enable":true,"json":true}</command>.</para> 149 150<para>The <option>-s</option> sets the baud rate for the slave tty. The 151default is 4800.</para> 152 153<para>The option -S tells gpsfake to insert realistic delays in the 154test input rather than trying to stuff it through the daemon as fast 155as possible. This will make the test(s) run much slower, but avoids 156flaky failures due to machine lode and possible race conditions in 157the pty layer.</para> 158 159<para>The <option>-t</option> forces the test framework to use TCP 160rather than pty devices. Besides being a test of TCP source handling, 161this may be useful for testing from within chroot jails where access 162to pty devices is locked out.</para> 163 164<para>The <option>-T</option> makes <application>gpsfake</application> print 165some system information and then exits.</para> 166 167<para>The <option>-u</option> forces the test framework to use UDP 168rather than pty devices. Besides being a test of UDP source handling, 169this may be useful for testing from within chroot jails where access 170to pty devices is locked out.</para> 171 172<para>The <option>-v</option> enables verbose progress reports to stderr. It is 173mainly useful for debugging <application>gpsfake</application> 174itself.</para> 175 176<para>The <option>-W</option> ("wait") option sets the timeout on daemon 177inactivity, in seconds. The default timeout is 60 seconds, and a value 178of 0 suppresses the timeout altogether. Note that the actual timeout is 179longer due to internal delays, typically by about 20 seconds.</para> 180 181<para>The <option>-x</option> dumps packets as 182<application>gpsfake</application> gathers them. It is mainly useful 183for debugging <application>gpsfake</application> itself.</para> 184 185<para>The <option>-h</option> makes <application>gpsfake</application> print 186a usage message and exit.</para> 187 188<para>The argument must be the name of a file containing the 189data to be cycled at the device. <application>gpsfake</application> 190will print a notification each time it cycles.</para> 191 192<para>Normally, gpsfake creates a pty for each logfile and passes the 193slave side of the device to the daemon. If the header comment in the 194logfile contains the string "UDP", packets are instead shipped via UDP 195port 5000 to the address 192.168.0.1.255. You can monitor them with 196this: <command>tcpdump -s0 -n -A -i lo udp and port 5000</command>.</para> 197 198</refsect1> 199<refsect1 id='magic'><title>MAGIC COMMENTS</title> 200 201<para>Certain magic comments in test load headers can change the 202conditions of the test. These are:</para> 203 204<variablelist> 205<varlistentry> 206<term>Serial:</term> 207<listitem><para>May contain a serial-port setting such as 4800 7N2 - 208baud rate followed by 7 or 8 for byte length, N or O or E for parity 209and 1 or 2 for stop bits. The test is run with those settings on the 210slave port that the daemon sees.</para></listitem> 211</varlistentry> 212<varlistentry> 213<term>Transport:</term> 214<listitem><para>Values 'TCP' and 'UDP' force the use of TCP and 215UDP feeds respectively (the default is a pty).</para></listitem> 216</varlistentry> 217<varlistentry> 218<term>Delay-Cookie:</term> 219<listitem><para>Must be followed by two whitespace-separated fields, a 220delimiter character and a numeric delay in seconds. Instead of being 221broken up by packet boundaries, the test load is split on the 222delimiters. The delay is performed after each feed. Can be useful 223for imposing write boundaries in the middle of packets. 224</para></listitem> 225</varlistentry> 226</variablelist> 227 228</refsect1> 229<refsect1 id='custom'><title>CUSTOM TESTS</title> 230 231<para><application>gpsfake</application> is a trivial wrapper around a 232Python module, also named gpsfake, that can be used to fully script 233sessions involving a <application>gpsd</application> instance, any 234number of client sessions, and any number of fake GPSes feeding the 235daemon instance with data from specified sentence logs.</para> 236 237<para>Source and embedded documentation for this module is shipped with the 238<application>gpsd</application> development tools. You can use it to 239torture-test either <application>gpsd</application> itself or any 240<application>gpsd</application>-aware client application.</para> 241 242<para>Logfiles for the use with <application>gpsfake</application> can 243be retrieved using <application>gpspipe</application>, 244<application>gpscat</application>, or 245<application>gpsmon</application> from the gpsd distribution, or any 246other application which is able to create a compatible output.</para> 247 248<para>If <application>gpsfake</application> exits with "Cannot execute 249gpsd: executable not found." the environment variable GPSD_HOME can be 250set to the path where gpsd can be found. (instead of adding that folder 251to the PATH environment variable</para> 252 253</refsect1> 254<refsect1 id='see_also'><title>SEE ALSO</title> 255<para> 256<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 257<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 258<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 259<citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 260<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 261<citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 262<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry> 263<citerefentry><refentrytitle>gpsmon</refentrytitle><manvolnum>1</manvolnum></citerefentry>. 264</para> 265</refsect1> 266 267<refsect1 id='maintainer'><title>AUTHOR</title> 268 269<para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para> 270 271</refsect1> 272 273</refentry> 274 275