1GPSFAKE(1) GPSD Documentation GPSFAKE(1)
2
6 gpsfake - test harness for gpsd, simulating a GNSS receiver
7
9 gpsfake [OPTIONS] infile
10 gpsfake -h
12 gpsfake -V
14
16 gpsfake is a test harness for gpsd and its clients. It opens a pty
17 (pseudo-TTY), launches a gpsd instance that thinks the slave side of
18 the pty is its GNSS device, and repeatedly feeds the contents of one or
19 more test logfiles through the master side to the GNSS receiver. If
20 there are multiple logfiles, sentences from them are interleaved in the
21 order the files are specified.
22 gpsfake does not require root privileges, but will run fine as root. It
24 can be run concurrently with a production gpsd instance without causing
25 problems, as long as you use the -P option. Runing under sudo will
26 cause minor loss of functionality.
27 The logfiles may contain packets in any supported format, including in
29 particular NMEA, SiRF, TSIP, or Zodiac. Leading lines beginning with #
30 will be treated as comments and ignored, except in the following
31 special cases.
32 Thse are interpreted directly by gpsfake:
34 • a comment of the form #Serial: [0-9] [78][NOE][12] may be used to
36 set serial parameters for the log - baud rate, word length, stop
37 bits.
38 • a comment of the form #Transport: UDP may be used to fake a UDP
40 source rather than the normal pty.
41 • a comment of the form #Transport: TCP may be used to fake a TCP
43 source rather than the normal pty.
44 Thse are interpreted directly by gpsd:
46 • a comment of the form # Date: yyyy-mm-dd (ISO8601 date format) may
48 be used to set the initial date for the log.
49 The gpsd instance is run in foreground. The thread sending fake GNSS
51 data to the daemon is run in background.
52
54 -?, -h, --help
55 Print a usage message and exit.
56 -1, --singleshot
58 The logfile is interpreted once only rather than repeatedly. This
59 option is intended to facilitate regression testing.
60 -b, --baton
62 Enable a twirling-baton progress indicator on standard error. At
63 termination, it reports elapsed time.
64 -c COUNT, --cycle COUNT
66 Sets the delay between sentences in seconds. Fractional values of
67 seconds are legal. The default is zero (no delay).
68 -d LVL, --debug LVL
70 Pass a -D option to the daemon: thus -D 4 is shorthand for -o="-D
71 4".
72 -g, -G, --gdb, --lldb
74 Use the monitor facility to run the gpsd instance within gpsfake
75 under control of gdb or lldb, respectively. They also disable the
76 timeout on daemon inactivity, to allow for breakpointing. If
77 necessary, the timeout can be reenabled by a subsequent -W or
78 --wait . If xterm and $DISPLAY are available, these options launch
79 the debugger in a separate xterm window, to separate the debugger
80 dialog from the program output, but otherwise run it directly. In
81 the gdb case, -tui is used with xterm but not otherwise, since
82 curses and program output don’t play nicely together. Although lldb
83 lacks an equivalent option, some versions have a 'gui' command.
84 -i, --promptme
86 Single-step through logfiles. It dumps the line or packet number
87 (and the sentence if the protocol is textual) followed by "? ".
88 Only when the user keys Enter is the line actually fed to gpsd.
89 -l, --linedump
91 Print a line or packet number just before each sentence is fed to
92 the daemon. If the sentence is textual (e.g. NMEA), the text is
93 printed as well. If not, the packet will be printed in hexadecimal
94 (except for RTCM packets, which aren’t dumped at all). This option
95 is useful for checking that gpsfake is getting packet boundaries
96 right.
97 -m PROG, --monitor PROG
99 Specify a monitor program (PROG) inside which the daemon should be
100 run. This option is intended to be used with valgrind(1) , gdb(1)
101 and similar programs.
102 -n, --nowait
104 Pass -n to the daemon to start the daemon reading the GNSS receiver
105 without waiting for a client (equivalent to -o="-n").
106 -o="OPTS", --option="OPTS"
108 Specify options to pass to the daemon. The equal sign (=) and
109 quotes are required so that gpsd options are not confused with
110 gpsfake options. To start the daemon reading the GNSS receiver
111 without waiting for a client use -o="-n" (equivalent to the -n)
112 which passes -n to the gpsd daemon. The option -o="-D 4" passes a
113 -D 4 to the daemon, equivalent to the using -D 4.
114 -p, --pipe
116 Sets watcher mode and dump the NMEA and GPSD notifications
117 generated by the log to standard output. This is useful for
118 regression testing.
119 -p PORT, --port PORT
121 Sets the daemon’s listening port to PORT.
122 -q, --quiet
124 Tell gpsfake to suppress normal progress output and thus act in a
125 quiet manner.
126 -r STR, --clientinit STR
128 Specify an initialization command to use in pipe mode. The default
129 is ?WATCH={"enable":true,"json":true}.
130 -s SPEED, --speed SPEED
132 Sets the baud rate for the slave tty. The default is 4800.
133 -S, --slow
135 Tells gpsfake to insert realistic delays in the test input rather
136 than trying to stuff it through the daemon as fast as possible.
137 This will make the test(s) run much slower, but avoids flaky
138 failures due to machine load and possible race conditions in the
139 pty layer.
140 -t, --tcp
142 Forces the test framework to use TCP rather than pty devices.
143 Besides being a test of TCP source handling, this may be useful for
144 testing from within chroot jails where access to pty devices is
145 locked out.
146 -T, --sysinfo
148 Makes gpsfake print some system information and then exit.
149 -u, --udp
151 Forces the test framework to use UDP rather than pty devices.
152 Besides being a test of UDP source handling, this may be useful for
153 testing from within chroot jails where access to pty devices is
154 locked out.
155 -v, --verbose
157 Enable verbose progress reports to stderr. Use multiple times to
158 increase verbosity. It is mainly useful for debugging gpsfake
159 itself.
160 -w SEC, --wait SEC
162 Set the timeout on daemon inactivity, in seconds. The default
163 timeout is 60 seconds, and a value of 0 suppresses the timeout
164 altogether. Note that the actual timeout is longer due to internal
165 delays, typically by about 20 seconds.
166 -x, --predump
168 Dump packets as gpsfake gathers them. It is mainly useful for
169 debugging gpsfake itself.
170 The last argument(s) must be the name of a file or files containing the
172 data to be cycled at the device. gpsfake will print a notification each
173 time it cycles.
174 Normally, gpsfake creates a pty for each logfile and passes the slave
176 side of the device to the daemon. If the header comment in the logfile
177 contains the string "UDP", packets are instead shipped via UDP port
178 5000 to the address 192.168.0.1.255. You can monitor the packet with
179 tcpdump this way:
180 tcpdump -s0 -n -A -i lo udp and port 5000
182
184 Certain magic comments in test load headers can change the conditions
185 of the test. These are:
186 Serial
188 May contain a serial-port setting such as 4800 7N2 - baud rate
189 followed by 7 or 8 for byte length, N or O or E for parity and 1 or
190 2 for stop bits. The test is run with those settings on the slave
191 port that the daemon sees.
192 Transport
194 Values 'TCP' and 'UDP' force the use of TCP and UDP feeds
195 respectively (the default is a pty).
196 Delay-Cookie
198 Must be followed by two whitespace-separated fields, a delimiter
199 character and a numeric delay in seconds. Instead of being broken
200 up by packet boundaries, the test load is split on the delimiters.
201 The delay is performed after each feed. Can be useful for imposing
202 write boundaries in the middle of packets.
203
205 gpsfake is a trivial wrapper around a Python module, also named
206 gpsfake, that can be used to fully script sessions involving a gpsd
207 instance, any number of client sessions, and any number of fake GPSes
208 feeding the daemon instance with data from specified sentence logs.
209 Source and embedded documentation for this module is shipped with the
211 gpsd development tools. You can use it to torture test either gpsd
212 itself or any gpsd-aware client application.
213 Logfiles for the use with gpsfake can be retrieved using gpspipe,
215 gpscat, or cgps from the gpsd distribution, or any other application
216 which is able to create a compatible output.
217
219 WRITE_PAD
220 For unknown reasons gpsfake may sometimes time out and fail. Set the
221 WRITE_PAD environment value to a larger value to avoid this issue. A
222 starting point might be "WRITE_PAD = 0.005". Values as large os 0.200
223 may be required.
224 GPSD_HOME
226 If gpsfake exits with "Cannot execute gpsd: executable not found." the
227 environment variable GPSD_HOME can be set to the path where gpsd can be
228 found. (instead of adding that folder to the PATH environment variable
229
231 0
232 on success.
233 1
235 on failure
236
238 gpsd(8), gps(1), gpspipe(1), gpscat(1), cgps(1), tcpdump(1), gdb(1),
239 lldb(1), valgrind(1)
240
242 Project web site: https://gpsd.io/
243
245 This file is Copyright 2013 by the GPSD project
246 SPDX-License-Identifier: BSD-2-clause
247
249 Eric S. Raymond
250GPSD, Version 3.25 2023-01-10 GPSFAKE(1)