Contents

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.

  1. First Try
  2. GPS Troubleshooting
  3. USB Troubleshooting
  4. General Troubleshooting
  5. Start at Boot Troubleshooting
  6. Telnet
  7. Udev Hotplug Troubleshooting

First Try

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.

GPS troubleshooting

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 troubleshooting

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 such as sudo 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.

General Troubleshooting

Make sure gpsd is not running

Before doing anything else, make sure there is no instance of gpsd running:

sudo killall gpsd

Remove any sockets gpsd might have left behind, e.g.:

sudo rm /var/run/gpsd.sock

Ensure no other programs are using your device

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.

Use gpsmon to check that your device is emitting data

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.

Launch gpsd to see its progress messages

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 /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.
#

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 /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.
#

This time, gpsd stashes the device file and waits for some outside agency, like udev, to create it. Like so:

# 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.
#

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
#

Troubleshooting Start at Boot

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).

Ubuntu/Debian

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.

Red Hat

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

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.

Udev Hotplug Troubleshooting

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 /var/run/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 /var/run/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.