diff options
Diffstat (limited to 'man/gpsfake.xml')
| -rw-r--r-- | man/gpsfake.xml | 264 |
1 files changed, 264 insertions, 0 deletions
diff --git a/man/gpsfake.xml b/man/gpsfake.xml new file mode 100644 index 00000000..e8331d47 --- /dev/null +++ b/man/gpsfake.xml @@ -0,0 +1,264 @@ +<?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='gpsfake.1'> +<refentryinfo><date>12 Feb 2005</date></refentryinfo> +<refmeta> +<refentrytitle>gpsfake</refentrytitle> +<manvolnum>1</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>gpsfake</refname> +<refpurpose>test harness for gpsd, simulating a GPS</refpurpose> +</refnamediv> +<refsynopsisdiv id='synopsis'> + +<cmdsynopsis> + <command>gpsfake</command> + <arg choice='opt'>-1</arg> + <arg choice='opt'>-h</arg> + <arg choice='opt'>-b</arg> + <arg choice='opt'>-c <replaceable>interval</replaceable></arg> + <arg choice='opt'>-i</arg> + <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg> + <arg choice='opt'>-l</arg> + <arg choice='opt'>-m <replaceable>monitor</replaceable></arg> + <arg choice='opt'>-g</arg> + <arg choice='opt'>-n</arg> + <arg choice='opt'>-o <replaceable>options</replaceable></arg> + <arg choice='opt'>-p</arg> + <arg choice='opt'>-P <replaceable>port</replaceable></arg> + <arg choice='opt'>-q</arg> + <arg choice='opt'>-r <replaceable>initcmd</replaceable></arg> + <arg choice='opt'>-s <replaceable>speed</replaceable></arg> + <arg choice='opt'>-S</arg> + <arg choice='opt'>-u</arg> + <arg choice='opt'>-t</arg> + <arg choice='opt'>-T</arg> + <arg choice='opt'>-v</arg> + <arg rep='repeat'> + <arg choice='plain'><replaceable>logfile</replaceable></arg> + </arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1 id='description'><title>DESCRIPTION</title> + +<para><application>gpsfake</application> is a test harness for +<application>gpsd</application> and its clients. It opens a pty +(pseudo-TTY), launches a <application>gpsd</application> instance that +thinks the slave side of the pty is its GPS device, and repeatedly +feeds the contents of one or more test logfiles through the master side to the +GPS. If there are multiple logfiles, sentences from them are +interleaved in the order the files are specified.</para> + +<para><application>gpsfake</application> does not require root +privileges, and can be run concurrently with a production +<application>gpsd</application> instance without causing problems.</para> + +<para>The logfiles may contain packets in any supported format, +including in particular NMEA, SiRF, TSIP, or Zodiac. Leading lines +beginning with # will be treated as comments and ignored, except in +the following special cases:</para> + +<itemizedlist> +<listitem><para> +a comment of the form #Date: yyyy-mm-dd (ISO8601 date format) may be +used to set the initial date for the log. +</para></listitem> + +<listitem><para> +a comment of the form #Serial: [0-9]* [78][NOE][12] may be used to set +serial parameters for the log - baud rate, word length, stop bits. +</para></listitem> + +<listitem><para> +a comment of the form #Transport: UDP may be used to fake a UDP source +rather than the normal pty. +</para></listitem> +</itemizedlist> + +<para>The <application>gpsd</application> instance is run in +foreground. The thread sending fake GPS data to the daemon +is run in background.</para> + +</refsect1> +<refsect1 id='options'><title>OPTIONS</title> + +<para>With the -1 option, the logfile is interpreted once only rather +than repeatedly. This option is intended to facilitate regression +testing.</para> + +<para>The <option>-b</option> enables a twirling-baton progress indicator +on standard error. At termination, it reports elapsed time.</para> + +<para>The <option>-c</option> sets the delay between sentences in +seconds. Fractional values of seconds are legal. The default is zero +(no delay).</para> + +<para>The <option>-l</option> makes the program dump a line or packet number +just before each sentence is fed to the daemon. If the sentence is +textual (e.g. NMEA), the text is dumped as well. If not, the packet +will be dumped in hexadecimal (except for RTCM packets, which aren't +dumped at all). This option is useful for checking that gpsfake is +getting packet boundaries right.</para> + +<para>The <option>-i</option> is for single-stepping through logfiles. It dumps +the line or packet number (and the sentence if the protocol is +textual) followed by "? ". Only when the user keys Enter is the line +actually fed to <application>gpsd</application>.</para> + +<para>The <option>-m</option> specifies a monitor program inside which the +daemon should be run. This option is intended to be used with +<citerefentry><refentrytitle>valgrind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry> +and similar programs.</para> + +<para>The <option>-g</option> uses the monitor facility to run the +<application>gpsd</application> instance within gpsfake under control +of gdb.</para> + +<para>The <option>-o</option> specifies options to pass to the daemon. The -n +option passes -n to start the daemon reading the GPS without waiting +for a client (equivalent to -o "-n"). The <option>-D</option> passes a -D +option to the daemon: thus -D 4 is shorthand for -o "-D 4".</para> + +<para>The -p ("pipe") option sets watcher mode and dumps the NMEA and GPSD +notifications generated by the log to standard output. This is useful +for regression-testing.</para> + +<para>The -P ("port") option sets the daemon's listening port.</para> + +<para>The <option>-q</option> tells gpsfake to suppress normal progress +output and thus act in a quiet manner.</para> + +<para>The <option>-r</option> specifies an initialization command to use in pipe mode. +The default is <command>?WATCH={"enable":true,"json":true}</command>.</para> + +<para>The <option>-s</option> sets the baud rate for the slave tty. The +default is 4800.</para> + +<para>The option -S tells gpsfake to insert realistic delays in the +test input rather than trying to stuff it through the daemon as fast +as possible. This will make the test(s) run much slower, but avoids +flaky failures due to machine lode and possible race conditions in +the pty layer.</para> + +<para>The <option>-t</option> forces the test framework to use TCP +rather than pty devices. Besides being a test of TCP source handling, +this may be useful for testing from within chroot jails where access +to pty devices is locked out.</para> + +<para>The <option>-T</option> makes <application>gpsfake</application> print +some system information and then exits.</para> + +<para>The <option>-u</option> forces the test framework to use UDP +rather than pty devices. Besides being a test of UDP source handling, +this may be useful for testing from within chroot jails where access +to pty devices is locked out.</para> + +<para>The <option>-v</option> enables verbose progress reports to stderr. It is +mainly useful for debugging <application>gpsfake</application> +itself.</para> + +<para>The <option>-x</option> dumps packets as +<application>gpsfake</application> gathers them. It is mainly useful +for debugging <application>gpsfake</application> itself.</para> + +<para>The <option>-h</option> makes <application>gpsfake</application> print +a usage message and exit.</para> + +<para>The argument must be the name of a file containing the +data to be cycled at the device. <application>gpsfake</application> +will print a notification each time it cycles.</para> + +<para>Normally, gpsfake creates a pty for each logfile and passes the +slave side of the device to the daemon. If the header comment in the +logfile contains the string "UDP", packets are instead shipped via UDP +port 5000 to the address 192.168.0.1.255. You can monitor them with +this: <command>tcpdump -s0 -n -A -i lo udp and port 5000</command>.</para> + +</refsect1> +<refsect1 id='magic'><title>MAGIC COMMENTS</title> + +<para>Certain magic comments in test load headers can change the +conditions of the test. These are:</para> + +<variablelist> +<varlistentry> +<term>Serial:</term> +<listitem><para>May contain a serial-port setting such as 4800 7N2 - +baud rate followed by 7 or 8 for byte length, N or O or E for parity +and 1 or 2 for stop bits. The test is run with those settings on the +slave port that the daemon sees.</para></listitem> +</varlistentry> +<varlistentry> +<term>Transport:</term> +<listitem><para>Values 'TCP' and 'UDP' force the use of TCP and +UDP feeds respectively (the default is a pty).</para></listitem> +</varlistentry> +<varlistentry> +<term>Delay-Cookie:</term> +<listitem><para>Must be followed by two whitespace-separated fields, a +delimiter character and a numeric delay in seconds. Instead of being +broken up by packet boundaries, the test load is split on the +delimiters. The delay is performed after each feed. Can be useful +for imposing write boundaries in the middle of packets. +</para></listitem> +</varlistentry> +</variablelist> + +</refsect1> +<refsect1 id='custom'><title>CUSTOM TESTS</title> + +<para><application>gpsfake</application> is a trivial wrapper around a +Python module, also named gpsfake, that can be used to fully script +sessions involving a <application>gpsd</application> instance, any +number of client sessions, and any number of fake GPSes feeding the +daemon instance with data from specified sentence logs.</para> + +<para>Source and embedded documentation for this module is shipped with the +<application>gpsd</application> development tools. You can use it to +torture-test either <application>gpsd</application> itself or any +<application>gpsd</application>-aware client application.</para> + +<para>Logfiles for the use with <application>gpsfake</application> can +be retrieved using <application>gpspipe</application>, +<application>gpscat</application>, or +<application>gpsmon</application> from the gpsd distribution, or any +other application which is able to create a compatible output.</para> + +<para>If <application>gpsfake</application> exits with "Cannot execute +gpsd: executable not found." the environment variable GPSD_HOME can be +set to the path where gpsd can be found. (instead of adding that folder +to the PATH environment variable</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>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry> +<citerefentry><refentrytitle>gpsmon</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> + |