1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
|
<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Author" content="Eric S. Raymond">
<meta name="Description" content="How to bring up a GPS under GPSD">
<meta name="Keywords" content="GPS, gpsd, troubleshooting">
<meta name="Revised" content="9 April 2015">
<meta name="robots" content="index,follow">
<title>Troubleshooting GPSD</title>
<link rel="stylesheet" href="main.css" type="text/css">
</head>
<body>
<div id="Header">Troubleshooting GPSD</div>
<div id="Menu">
<img src="gpsd-logo-small.png" alt="Small gpsd Logo"><br>
<a href="index.html">Home</a><br>
<a href="index.html#news">News</a><br>
<a href="index.html#downloads">Downloads</a><br>
<a href="index.html#mailing-lists">Mailing lists</a><br>
<a href="index.html#documentation">Documentation</a><br>
<a href="faq.html">FAQ</a><br>
<a href="xgps-sample.html">Screenshots</a><br>
<a href="index.html#recipes">Recipes</a><br>
<a href="index.html#others">Other GPSDs</a><br>
<a href="hardware.html">Hardware</a><br>
<a href="for-vendors.html">For GPS Vendors</a><br>
<a href="wishlist.html">Wish List</a><br>
<a href="hall-of-shame.html">Hall of Shame</a><br>
Troubleshooting<br>
<a href="hacking.html">Hacker's Guide</a><br>
<a href="protocol-transition.html">Application Compatibility</a>
<a href="references.html">References</a><br>
<a href="history.html">History</a><br>
<a href="future.html">Future</a><br>
<div> </div>
<a href='http://www.catb.org/hacker-emblem/'><img
src='http://www.catb.org/hacker-emblem/glider.png'
alt='hacker emblem'></a><br>
<script type="text/javascript" src="https://www.openhub.net/p/3944/widgets/project_thin_badge.js"></script>
<hr>
<script type="text/javascript"><!--
google_ad_client = "pub-1458586455084261";
google_ad_width = 160;
google_ad_height = 600;
google_ad_format = "160x600_as";
google_ad_type = "text";
google_ad_channel = "";
//--></script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
<hr>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401"
alt="Valid HTML 4.01!" height="31" width="88"></a>
</div>
<div id="Content">
<h1>Contents</h1>
<p>References like <b>foobar(n)</b> are a Unix convention meaning you
should look up the program <b>foobar</b> using the <b>man</b> utility
for browsing manual pages. Numeric section 1 refers to general
commands and section 8 to administrative commands.</p>
<ol class="ToC">
<li><a href="#firsttry">First Try</a></li>
<li><a href="#gpstroubleshooting">GPS Troubleshooting</a></li>
<li><a href="#usbtroubleshooting">USB Troubleshooting</a></li>
<li><a href="#generaltroubleshooting">General Troubleshooting</a></li>
<li><a href="#startuptroubleshooting">Start at Boot Troubleshooting</a></li>
<li><a href="#telnet" >Telnet</a></li>
<li><a href="#hotplugtroubleshooting">Udev Hotplug Troubleshooting</a></li>
</ol>
<h1 id='firsttry'>First Try</h1>
<p>If you have a USB GPS and have installed from a binary package,
plug your GPS into a USB port and run <code>xgps</code> or
<code>cgps</code>. Very likely you will see fix data appear in the
client. If so, you're done.</p>
<p>If you have a Bluetooth GPS, follow our <a href="bt.html">Bluetooth
instructions</a> and run <code>xgps</code> or <code>cgps</code>. Very
likely you will see fix data appear in the client. If so, you're
done.</p>
<p>If you have a serial (RS232) GPS, plug it into a serial port
connector and jump to <a href="#generaltroubleshooting">General
Troubleshooting</a></p>
<p>We do not yet have troubleshooting instructions for GPSes using
CF (Compact Flash) interfaces. Please contribute some if you can.</p>
<p>If your test client does not show data, keep reading.</p>
<h1 id='gpstroubleshooting'>GPS troubleshooting</h1>
<p>Check that the GPS has power. If it is a USB device, it
needs to be cabled to a USB port to have power. All Bluetooth GPSes
and some serial GPSes are powered by an on-board battery; check that
the battery is present and charged. The GPS may have an on-off switch
which needs to be in the 'on' position.</p>
<p>Most GPSes have a power-on LED; it should be continuously on
or blinking once a second. If it is continuously off, your GPS is dead
or disconnected. Check that it has power.</p>
<h1 id='usbtroubleshooting'>USB troubleshooting</h1>
<p>USB GPSes actually emulate RS232 serial using converter chips.
Under Linux, the <code>usbserial</code> kernel module must be loaded
for correct operation of this class of device. Normally this module
load should happen automatically when the device activates, but if you
don't receive data check for it with <b>lsmod(8)</b>.</p>
<p>On Linux systems with module autoloading disabled or misconfigured,
it is possible you may need to load the module manually with a command
such as <code>sudo modprobe usbserial vendor=0x1a86
product=0x7523</code>. Do not copy those hex numbers slavishly, they
are examples. To get the right numbers, you will need to dig up the
vendor and product ID of your USB-serial converter device.</p>
<p>Run <b>lsusb(8)</b> before and after connecting your GPS; after,
you should see an additional line indicating a new device. Expect the
new line to describe a serial-to-USB adapter chip, often (but not
always) the Prolific Technology PL2303. Then run <b>dmesg(8)</b>,
looking near the end for a message indicating a new USB device of
that kind and giving you the device path - <code>/dev/ttyUSBn</code>
for some number n.</p>
<p>If you have installed a GPSD binary package on a Linux system and
are using a USB GPS, you should not need to start gpsd manually,
because the hotplug system will have done it for you. You should be
able to start a test client (such as <code>cgps</code> or
<code>xgps</code>) and watch it report fixes. If this works, you are
done and can skip the rest of this guide.</p>
<h1 id="generaltroubleshooting">General Troubleshooting</h1>
<h2>Make sure gpsd is not running</h2>
<p>Before doing anything else, make sure there is no instance of gpsd
running:</p>
<pre>sudo killall gpsd</pre>
<p>Remove any sockets gpsd might have left behind, e.g.:</p>
<pre>sudo rm /var/run/gpsd.sock</pre>
<h2>Ensure no other programs are using your device</h2>
<p>Tools like modemmanager might be using your device, probably
automatically attached to it by udev or systemd. To check if your
device is ready to be used by gpsd try running <b>lsof(8)</b>
and search the output for your GPS device path (for example
<code>lsof -n | grep /dev/ttyUSB0</code>). If something is
listed in the output you'll have to stop these processes and
reconfigure them to ignore your GPS device.
<h2>Use gpsmon to check that your device is emitting data</h2>
<p>Try running <b>gpsmon(1)</b>, giving it your GPS device path as an
argument (for example. <code>"gpsmon /dev/ttyUSB0"</code>). After a
few moments to sync up, it should display a screen full of data on the
device, including displaying the raw packet data streaming from it.</p>
<p>If <b>gpsmon(1)</b> reports no data at all, you may have the device
path wrong; check that using <b>dmesg(8)</b> or by whatever means you
have available. If you have the right device, you may have some
low-level system problem with serial or USB that you'll need to fix
before <code>gpsd</code> will operate. Check your cabling, power, and
kernel configuration.</p>
<h2>Launch gpsd to see its progress messages</h2>
<p>You can launch gpsd with the options -N (don't daemonize) and -D
[0-8] (debug and level). This will let it run and send output,
including traffic from the GPS receiver, to the terminal. This is a
recommended first step because it avoids client issues. For example,
here we give gpsd a control socket but no device:</p>
<pre># gpsd -N -D3 -F /var/run/gpsd.sock
gpsd: launching (Version 2.96~dev)
gpsd: listening on port gpsd
gpsd: running with effective group ID 0
gpsd: running with effective user ID 0
^Cgpsd: received terminating signal 2.
gpsd: exiting.
#</pre>
<p>If you get something like this error message: "gpsd: error while
loading shared libraries: libgpsd.so.0: cannot open shared object
file: No such file or directory" then run ldconfig(8) and try again.</p>
<p>Here we give it a device file. But the device file isn't there, and
there is no receiver.</p>
<pre># gpsd -N -D3 -F /var/run/gpsd.sock /dev/ttyUSB0
gpsd: launching (Version 2.96~dev)
gpsd: listening on port gpsd
gpsd: running with effective group ID 0
gpsd: running with effective user ID 0
gpsd: stashing device /dev/ttyUSB0 at slot 0
^Cgpsd: received terminating signal 2.
gpsd: exiting.
#</pre>
<p>This time, gpsd stashes the device file and waits for some outside
agency, like udev, to create it. Like so:</p>
<pre># gpsd -N -D3 -F /var/run/gpsd.sock /dev/ttyUSB0
gpsd: launching (Version 2.96~dev)
gpsd: listening on port gpsd
gpsd: running with effective group ID 0
gpsd: running with effective user ID 0
gpsd: stashing device /dev/ttyUSB0 at slot 0
gpsd: control socket connect on fd 6
gpsd: <= control(6): /dev/ttyUSB0 already active
^Cgpsd: received terminating signal 2.
gpsd: exiting.
#</pre>
<p>If you have udev on your computer, and you don't see gpsd notice
the device ("control socket connect on fd 6"), check to be
sure <a href="#hotplugtroubleshooting">udev is working correctly</a>.</p>
<p>If you pull the plug on the receiver, gpsd will note the change.</p>
<p>With the receiver plugged in and gpsd running as above, you can
launch a client. <code>xgps</code> comes with the distribution.
On some Linuxes, it may be in a separate package, e.g. gpsd-clients.
You should then see a lot of traffic between gpsd and the client in
the gpsd terminal window. For example, here's a fix as reported by
gpsd:</p>
<pre>gpsd: SiRF: MND 0x02: time=1293859466.85 lat=42.64 lon=-118.21 alt=1315.15 track=0.00 speed=0.00 mode=1 status=0 hdop=0.00 used=0 mask={TIME|LATLON|ALTITUDE|SPEED|TRACK|STATUS|MODE|DOP|USED}</pre>
<p>Note that gpsd doesn't try to activate the receiver until it has a
client, and the client asks for data with a ?WATCH request. It also
shuts down its connection to the receiver when it has no clients. This
is a power saving feature.</p>
<p>Another way to verify that gpsd can open the device file is with
lsof(8) ("list open files"):</p>
<pre># lsof | grep ttyU
gpsd 20895 nobody 7u CHR 188,0 0t0 851138 /dev/ttyUSB0
#</pre>
<h1 id="startuptroubleshooting">Troubleshooting Start at Boot</h1>
<p>If gpsd launches at boot, you should be able to start it up or shut
it down with one of the many utilities that manipulate system-V like
startup environments, e.g. service(8). <code>service gpsd
start</code>, etc. works on some Linuxes. sysv-rc-conf(8) is a handy
curses utility for the job. Watch the output.</p>
<p>You can also look at your boot messages with dmesg(1).</p>
<h2>Ubuntu/Debian</h2>
<p>The .deb package supplied for the Debian and Ubuntu Linux
distributions launch at boot either using systemd with gpsd.socket
and gpsd.service, or on older releases from the system V-like script
<code>/etc/init.d/gpsd</code>. However, both are governed by a control
file, <code>/etc/default/gpsd</code>. If necessary, edit the control
file as root.</p>
<p>Please note that systemd will only start gpsd on request
by clients connecting to the unix or tcp socket. In case you need
gpsd to run always, you'll need to configure systemd to start it.
One way would be to create <code>/etc/systemd/system/gpsd.service</code>
with the following content:
<pre>
[Unit]
Description=GPS (Global Positioning System) Daemon
Requires=gpsd.socket
# Needed with chrony SOCK refclock
After=chronyd.service
[Service]
EnvironmentFile=-/etc/default/gpsd
EnvironmentFile=-/etc/sysconfig/gpsd
ExecStart=/usr/sbin/gpsd -N $GPSD_OPTIONS $DEVICES
[Install]
WantedBy=multi-user.target
Also=gpsd.socket
</pre>
To ask systemd to reload its config run
<code>systemctl daemon-reload; systemctl reenable gpsd.service</code>.
Instead of using the EnvironmentFile(s) you could just edit the command
line as necessary for your system. Don't forget to run
<code>systemctl daemon-reload</code> after changing the file.
</p>
<p>You will likely want the gpsd-clients package as a debugging
tool. These are the clients maintained as part of the gpsd
project. Other clients may or may not use the right libgpsd or the
right protocol, or something. So make sure gpsd is working correctly
with the gpsd clients. You can always purge them later.</p>
<p>In case you need to debug the gpsd or its clients using gdb or
the python debugger the gpsd-dbg package is provided. It should
contain all necessary debug symbols to create useful backtraces.</p>
<p>If you have a prior installation of gpsd from a deb package, and
are switching to compiling your own, from a recent tarball or from the
git repository, it is not enough to <code>apt-get remove</code> the
prior installation. You must <code>apt-get purge</code> them. This
removes some configuration files left behind by remove.</p>
<p>If you do compile your own gpsd, be aware that installing gpsd
client packages can force installation of gpsd as well. This can also
happen on debian systems when apt is set up to install recommended
packages as dependencies.</p>
<p>One culprit is packages like
<a href="http://www.tangogps.org/">tangogps</a>, which recommendd gpsd.
Fortunately, since it recommends gpsd, you can install it using
<code>apt-get install --no-install-recommends</code> or disable the
installation of recommended packages permanently. Put the following in
a file with a high leading number in <code>/etc/apt/apt.conf.d</code>,
e.g. <code>90no.recommendations</code>:</p>
<pre>APT::Install-Recommends "false";
</pre>
Other client packages may not be so lenient, but you can use the tool
<b>equivs</b> to create an empty fake package which provides gpsd.</p>
<h2>Red Hat</h2>
<p>The rpm package made from the gpsd distribution will launch at boot
from the script <code>/etc/init/rc.d/gpsd</code>. It is governed by
the file <code>/etc/sysconfig/gpsd</code>, although it it doesn't find
that file, it will provide its own defaults.</p>
<p>You will likely want the gpsd-clients package as a debugging
tool. These are the clients maintained by the gpsd developers. Other
clients may or may not use the right libgpsd or the right protocol, or
something. So make sure gpsd is working correctly with the gpsd
clients. You can always purge them later.</p>
<h1 id="telnet">Telnet</h1>
<p>Telnet provides a quick and dirty acceptance test for gpsd. Other
clients (<code>cgps</code>, <code>xgps</code>, and other)
are preferable, so consider telnet a last ditch tool. You can telnet
into gpsd:</p>
<pre>$ telnet localhost 2947
Trying ::1...
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
{"class":"VERSION","release":"2.96~dev","rev":"2011-03-15T03:05:33","proto_major":3,"proto_minor":4}
</pre>
<p>Note that the <code>release</code> strings will be different in
your case.</p>
<p>To see data from the receiver in JSON (if any), enter the command
<samp>?WATCH={"enable":true,"json":true}</samp>. To
end JSON output, <samp>?WATCH={"enable":false}</samp>. Then
control-] and "exit" to exit the telnet client.</p>
<p>For more information, see <a
href="client-howto.html#_how_the_gpsd_wire_protocol_works" >How the
GPSD wire protocol works</a> in the <a href="client-howto.html" >GPSD
Client HOWTO</a>.</p>
<h1 id="hotplugtroubleshooting">Udev Hotplug Troubleshooting</h1>
<p>The Linux udev system has been prone to change out from under us,
breaking our hotplug support for USB receivers. Accordingly, here's a
short guide to verifying that the different pieces are working
correctly, with indications of where to troubleshoot on failure.</p>
<p>First, verify that your USB subsystem can see your receiver. Run
lsusb(1). Plug the receiver in and run lsusb(1) again, looking for
the extra line - it will be identified by a serial-to-USB converter
chip type such as a PL2303. Unplug the receiver and verify that the
line describing the device is gone.</p>
<p>If this test fails, something very basic is wrong at hardware
level. If your receiver has a two-section cable joined by something
like a <a
href="https://en.wikipedia.org/wiki/Mini-DIN_connector">6-pin
mini-DIN connector</a>, with a component housing between that and the
USB plug, be aware that the serial converter may live in that housing
and you have to unplug the <b>entire cable</b> from your computer, not
just separate the halves of the mini-DIN connector. If there is no
such joint, it may be that your receiver is defective or dead. See
your vendor documentation for help in diagnosis. The least likely
failure is for the USB hardware on the PC side to be buggy.</p>
<p>The next thing to try is watching the hotplug events in your system
logs. Do <code>tail -f /var/log/syslog</code>; plug in and unplug the
receiver. You should see messages indicating from the USB subsystem
in the kernel indicating device connect and disconnect. If you don't,
check your kernel configuration; USB support may be absent or
misconfigured.</p>
<p>Now we involve the udev system. Unplug the receiver. If you are
compiling gpsd, run <code>make udev-install</code> from the source
directory to install the required udev rules. (There is a <code>make
udev-uninstall</code> for cleaning up after this test.) If you are
using a package, your package manager will install these files for
you. Do <code>tail -f /var/log/syslog</code>. Now plug in the
receiver.</p>
<p>You should see messages that include something like the following
text (the USB device may vary):</p>
<pre>
gpsd.hotplug: gpsd_control(action=add, arg=/dev/ttyUSB0)
gpsd.hotplug: launching gpsd -F /var/run/gpsd.sock
</pre>
<p>These are from the gpsd.hotplug handler called by udev on a hotplug
event matching one of the known udev types for a USB GPS, and indicating
the launch of a gpsd instance.</p>
<p>If you don't see this, several things could be going wrong. The
udev rules may not be installed correctly. Or the handler they call
may be unable to run for some reason; it has two layers, a shell script
wrapper around a little Python program that does the real work. You
may have to figure out where the udev log messages go on your system
and use udevadm(8) to crank up the log level until you can see what's
going on.</p>
<p>If your GPS uses an unusual serial-to-USB converter, the GPSD rules
may not recognize it as a probable GPS. You'll need to look at the
converter type indicated in the lsusb(1) listing and match it against
the rules in the gpsd.rules file. If it's not known, please report
this as a bug to the GPSD developers.</p>
<p>Once you know that udev can launch gpsd, you'll want to watch what
it's doing with the hotplug notifications. Unplug the receiver and
kill the running gpsd instance, if there is one. Now run <code>make
udev-test</code> and plug in the receiver. (For those using packages,
this is the equivalent of "<code>gpsd -N -n -F /var/run/gpsd.sock
-D 5</code>".) </p>
<p>You can also launch the hotplug code manually: <code>cd /lib/udev
&& ./gpsd.hotplug add /dev/ttyUSB0</code> If this fails, there is
something wrong with the hotplug code. If it succeeds, the problem may
be in how udev is calling gpsd.hotplug, or udev may never call
gpsd.hotplug.</p>
<p>You should see log messages from gpsd indicating that the control
socket has received a command to add the device, and then data
from the device. When you unplug and replug the device, gpsd
should emit messages about the device closes and opens.</p>
<p>If you don't see this, there's a bug or misconfiguration
somewhere. Check to make sure the hotplug handler and gpsd have
matching expectations about the location of the control socket.</p>
<p>If you do see these device file opens and closes logged, the
udev end of the configuration is working.</p>
<hr>
<script src="datestamp.js" type='text/javascript'></script>
</div>
</body>
</html>
<!--
Local Variables:
compile-command: "./upload hacking.html"
End:
-->
|
