Home
News
Installation & Building
Downloads
Mailing lists
Documentation
FAQ
Screenshots
Recipes
Other GPSDs
Hardware
For GPS Vendors
Wish List
Hall of Shame
Troubleshooting
Hacker's Guide
Application Compatibility References
History
Future
References like foobar(n) are a Unix convention meaning you should look up the program foobar using the man utility for browsing manual pages. Numeric section 1 refers to general commands and section 8 to administrative commands.
If you have a USB GPS and have installed from a binary package,
plug your GPS into a USB port and run xgps or
cgps. Very likely you will see fix data appear in the
client. If so, you're done.
If you have a Bluetooth GPS, follow our Bluetooth
instructions and run xgps or cgps. Very
likely you will see fix data appear in the client. If so, you're
done.
If you have a serial (RS232) GPS, plug it into a serial port connector and jump to General Troubleshooting
We do not yet have troubleshooting instructions for GPSes using CF (Compact Flash) interfaces. Please contribute some if you can.
If your test client does not show data, keep reading.
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.
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.
USB GPSes actually emulate RS232 serial using converter chips.
Under Linux, the usbserial 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 lsmod(8).
On Linux systems with module autoloading disabled or misconfigured,
it is possible you may need to load the module manually with a command,
while running as root, such as modprobe usbserial vendor=0x1a86
product=0x7523. 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.
Run lsusb(8) 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 dmesg(8),
looking near the end for a message indicating a new USB device of
that kind and giving you the device path - /dev/ttyUSBn
for some number n.
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 cgps or
xgps) and watch it report fixes. If this works, you are
done and can skip the rest of this guide.
Before doing anything else, make sure there is no instance of gpsd running, as root, do:
# killall gpsd # killall -9 gpsd
Remove any sockets gpsd might have left behind, as root, do:
# rm /run/gpsd.sock
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 lsof(8)
and search the output for your GPS device path (for example
lsof -n | grep /dev/ttyUSB0). If something is
listed in the output you'll have to stop these processes and
reconfigure them to ignore your GPS device.
Try running gpsmon(1), giving it your GPS device path as an
argument (for example. "gpsmon /dev/ttyUSB0"). 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.
If gpsmon(1) reports no data at all, you may have the device
path wrong; check that using dmesg(8) 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 gpsd will operate. Check your cabling, power, and
kernel configuration.
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:
# gpsd -N -D3 -F @RUNDIR/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. #
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.
Here we give it a device file. But the device file isn't there, and there is no receiver.
# gpsd -N -D3 -F @RUNDIR/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. #
This time, gpsd stashes the device file and waits for some outside agency, like udev, to create it. Like so:
# gpsd -N -D3 -F @RUNDIR/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. #
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 udev is working correctly.
If you pull the plug on the receiver, gpsd will note the change.
With the receiver plugged in and gpsd running as above, you can
launch a client. xgps 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:
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}
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.
Another way to verify that gpsd can open the device file is with lsof(8) ("list open files"):
# lsof | grep ttyU gpsd 20895 nobody 7u CHR 188,0 0t0 851138 /dev/ttyUSB0 #
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). service gpsd
start, etc. works on some Linuxes. sysv-rc-conf(8) is a handy
curses utility for the job. Watch the output.
You can also look at your boot messages with dmesg(1).
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
/etc/init.d/gpsd. However, both are governed by a control
file, /etc/default/gpsd. If necessary, edit the control
file as root.
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 /etc/systemd/system/gpsd.service
with the following content:
[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
To ask systemd to reload its config run
systemctl daemon-reload; systemctl reenable gpsd.service.
Instead of using the EnvironmentFile(s) you could just edit the command
line as necessary for your system. Don't forget to run
systemctl daemon-reload after changing the file.
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.
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.
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 apt-get remove the
prior installation. You must apt-get purge them. This
removes some configuration files left behind by remove.
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.
One culprit is packages like
tangogps, which recommendd gpsd.
Fortunately, since it recommends gpsd, you can install it using
apt-get install --no-install-recommends or disable the
installation of recommended packages permanently. Put the following in
a file with a high leading number in /etc/apt/apt.conf.d,
e.g. 90no.recommendations:
APT::Install-Recommends "false";
Other client packages may not be so lenient, but you can use the tool equivs to create an empty fake package which provides gpsd.
The rpm package made from the gpsd distribution will launch at boot
from the script /etc/init/rc.d/gpsd. It is governed by
the file /etc/sysconfig/gpsd, although it it doesn't find
that file, it will provide its own defaults.
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.
Telnet provides a quick and dirty acceptance test for gpsd. Other
clients (cgps, xgps, and other)
are preferable, so consider telnet a last ditch tool. You can telnet
into gpsd:
$ 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}
Note that the release strings will be different in
your case.
To see data from the receiver in JSON (if any), enter the command ?WATCH={"enable":true,"json":true}. To end JSON output, ?WATCH={"enable":false}. Then control-] and "exit" to exit the telnet client.
For more information, see How the GPSD wire protocol works in the GPSD Client HOWTO.
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.
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.
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 6-pin mini-DIN connector, 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 entire cable 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.
The next thing to try is watching the hotplug events in your system
logs. Do tail -f /var/log/syslog; 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.
Now we involve the udev system. Unplug the receiver. If you are
compiling gpsd, run make udev-install from the source
directory to install the required udev rules. (There is a make
udev-uninstall for cleaning up after this test.) If you are
using a package, your package manager will install these files for
you. Do tail -f /var/log/syslog. Now plug in the
receiver.
You should see messages that include something like the following text (the USB device may vary):
gpsd.hotplug: gpsd_control(action=add, arg=/dev/ttyUSB0) gpsd.hotplug: launching gpsd -F @RUNDIR/gpsd.sock
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.
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.
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.
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 make
udev-test and plug in the receiver. (For those using packages,
this is the equivalent of "gpsd -N -n -F @RUNDIR/gpsd.sock
-D 5".)
You can also launch the hotplug code manually: cd /lib/udev
&& ./gpsd.hotplug add /dev/ttyUSB0 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.
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.
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.
If you do see these device file opens and closes logged, the udev end of the configuration is working.
Sometimes it is best to debug gpsd without it interactioning with systemd. Once gpsd is working, you can try to get systemd to work with gpsd. To disable systemd, do this as root:
systemctl stop gpsd.socket gpsd.service systemctl disable gpsd.socket gpsd.service reboot
gpsd must be installed. We want gpsd itself and, for testing, the gpsd clients, at least cgps and possibly xgps.
gpsd must running and reading from the GPS receiver. For general gpsd debugging, it is helpful to know that gpsd is running, and that the GPS receiver device file is present. For a u-blox receiver:
root@orca:~# ps aux | grep -i gpsd | grep -v grep ; ls /dev/ttyA* gpsd 14547 0.5 0.0 18092 3504 ? S<sl 15:44 0:00 /usr/sbin/gpsd /dev/ttyACM0 root@orca:~#
(Devices file names vary. /dev/ttyU* is typical.)
If gpsd isn't running, check other parts of this document, and INSTALL in the root of the git repo.
The next question is, is gpsd controlled by systemd?
Your problem lies elsewhere.
You can use systemd's tools to check. systemctl status gpsd should tell you what systemd thinks gpsd's status is.
root@orca:~# systemctl status gpsd gpsd.service - GPS (Global Positioning System) Daemon Loaded: loaded (/lib/systemd/system/gpsd.service; enabled; vendor preset: enabled) Active: active (running) since Thu 2019-10-03 15:07:01 MDT; 1 weeks 2 days ago Main PID: 32454 (gpsd) Tasks: 1 (limit: 4915) Memory: 924.0K CGroup: /system.slice/gpsd.service 32454 /usr/sbin/gpsd Oct 03 15:07:01 orca systemd[1]: Starting GPS (Global Positioning System) Daemon... Oct 03 15:07:01 orca systemd[1]: Started GPS (Global Positioning System) Daemon. root@orca:~#
This example shows that systemd clearly does control gpsd. If systemd replies something like Unit gpsd.service could not be found., systemd is present but does not control gpsd.
Alternatively, see if any of the files gpsd.* are present under systemd's directories. That location is system dependent, but /lib/systemd/system/ is typical. Or use locate or your package manager to check.
If systemd is present but does not control gpsd, your problem lies elsewhere.
Your tool for interacting with systemd is systemctl. The typical syntax is
systemctl [OPTIONS...] COMMAND [UNIT...]
For the gory details, see the systemctl man page. Generally useful commands include: daemon-reload, disable, enable, reload, restart, show, start, status, and stop. Note that daemon-reload and reload are not the same command. reload tells a unit to reload its configuration file (if it can do so). daemon-reload has systemd reload all unit files and its own configuration file.
If you want to shut gpsd down, you have to shut down both units. Shutting down gpsd.service alone is not sufficient because gpsd.socket could fire it up again.
systemctl stop gpsd.socket gpsd.service
Note: issuing the stop command may not actually stop the service. On a Debian system out of the box, systemd starts gpsd up again.
For security, gpsd by default is shipped set up to listen only on the loopback interface, thereby restricting its audience to clients on the same computer. We'd like to allow other computers to listen in as well. This means:
Once we know gpsd is running, we modify /etc/default/gpsd to provide the options we want. One to listen on all the interfaces (-G), and one to tell gpsd not to wait for a client to connect before polling (-n). The GPSD_OPTIONS stanza now looks like:
# Other options you want to pass to gpsd # GPSD_OPTIONS="" GPSD_OPTIONS="-Gn"
We can stop gpsd. Systemd will restart it for us, this time with the options in place. We then verify that the options are there:
root@orca:~# systemctl stop gpsd.socket gpsd.service root@orca:~# ps aux | grep -i gpsd | grep -v grep gpsd 14547 0.5 0.0 18092 3504 ? S<sl 15:44 0:00 /usr/sbin/gpsd -Gn root@orca:~#
But we aren't there yet. gpsd may be listening on all interfaces, but systemd's hold on the socket means gpsd can't hear anything on interfaces other than the loopback. We have to tell systemd to allow gpsd to hear other interfaces. We run systemctl edit --full gpsd.socket. Then we can edit it. After editing, the [Socket] stanza looks like so:
[Socket] ListenStream=@RUNDIR/gpsd.sock ListenStream=[::1]:2947 # ListenStream=127.0.0.1:2947 ListenStream=0.0.0.0:2947 SocketMode=0600
When you are done editing, systemctl does what it needs to do internally to preserve your changes from being over-written during upgrades. It also does the equivalent of a systemctl daemon-reload for you.
We now restart both gpsd units like so:
systemctl restart gpsd.socket gpsd.service
Now check with a local client, and a client on the remote computer:
xgps <host>
Where <host> in our example is orca. As usual, if you see data in the client, you're done.