GPSD Installation Instructions

Start by making sure you can get data from your GPS, otherwise the later steps will be very frustrating. In this command:

replace ttyXXX with the filename of the port, and 4800 with the correct speed. This will probably be either /dev/ttyUSB0 or /dev/ttyS0. If you are on a *BSD Unix or MacOS X, replace -F with -f.

When you run this command, you should see text lines beginning with $ come to stdout (possibly after a short initial burst of binary garbage). If you don’t see this, you may have OS-level problems with your serial support, but more likely have the wrong device. Look again.

If you have trouble with the preceding step, check your cabling first. Verify that the device is connected and that its power LED (if it has one) is lit.

If you seem to have some sort of serial-device problem, check that your kernel properly supports the device you are using. For GPSes using an RS-232 port (which is no longer common) you will need serial-port support compiled into your kernel. Various USB-to-serial adapter chips found in GPSes require specific drivers.

Under a stock Linux kernel these will all be loaded on demand when the USB system sees the appropriate vendor/product ID combinations. See build.adoc for instructions relating to custom kernels.

Ensure that device permissions will enable gpsd to read from and write to GPS devices even after it drops root privileges. If you are running Fedora Core, Ubuntu, or stock Debian you can skip this step, as the stock configuration has the right properties.

gpsd requires two things: (1) that GPS devices have group read and write enabled, and (2) all of them have the same group ID as a prototypical device, typically /dev/ttyS0 under Linux or /dev/tty00 under *BSD. It does not actually matter what the owning group is, as gpsd will look this up on startup. Alternatively, (3), you can set a fallback group with the gpsd-group option in case the prototype is not found: this should be the group that has write access to serial devices. On Debian and derivatives including Ubuntu this is "dialout"; on Gentoo/Fedora/openSuse it is "uucp".

Before dropping privileges, gpsd will ensure that it has access to devices given to it on the command line by forcing their group read and write permissions on.

On a Linux with udev, check the files in /etc/udev/permissions.d to ensure that /dev/tty* devices are all created with the same group and with 0660 permissions.

When gpsd drops privileges, its default is to set uid to 'nobody' and group to the owning group of the prototype device (the configure option gpsd_user=foo will cause gpsd to change to 'foo' instead).

If your system has the Linux hotplug facility installed you can skip the permission-setting part; the hotplug scripts will force the permissions for you. You still have to make sure all the tty devices are in the same group.

A minimum build of GPSD can run pretty close to the metal; all it absolutely needs is the C runtime support. The test clients and various additional features have additional prerequisites:

Some ncurses packages contain the terminfo library; some break it out separately as libtinfo5 or libtinfo.

The PyGObject package goes by several names, and is split up into sub packages different ways, depending on the distribution. Sometimes python-gi, python-gobject, python-cairo, etc. The packages also need the underlying system libraries (GTK, GLib, etc.)

The asynchronous python module (gps/aiogps.py) and its example client (example_aiogps.py) require Python 3.6+.

See below for more specific module requirements in the individual distribution instructions.

Before installing gpsd on your system, make sure that all parts of any previous installation have been removed. Do not mix gpsd parts from different sources. The gpsd clients and the server must be of the same version.

For special instructions related to using GPSD for time service, see the GPSD Time Service HOWTO in the distribution or on the web.

Any USB connected GPS that is known to work with gpsd will work fine on the RasPi. No special instructions apply.

A very popular option is to install the AdaFruit Ultimate GPS HAT. With this GPS you also get a good 1PPS signal. This works as any other GPS with gpsd, but there are two things to note. The GPS takes over the serial console: /dev/ttyAMA0. The PPS signal will be on GPIO Pin #4.

Only three specific changes need to be made to make the HAT work. First in the file /boot/cmdline.txt, remove this part "console=ttyAMA0,115200 kgdboc=ttyAMA0,115200". That frees the serial port from console use so the GPS can use it.

Second you need to tell the boot process to load the pps_gpio module and attach /dev/pps0 to GPIO pin 4. Do that by adding this line to the bottom of /boot/config.txt: dtoverlay=pps-gpio,gpiopin=4

Reboot so those changes take effect.

Run gpsd like this:

If you are on the RasPi with gpsd version 3.17, or above, /dev/pps0 can be autodetected, and used for PPS if available.

gpsd 3.17 and up only:

You can verify gpsd is using the PPS by running ntpshmmon:

If you do not see NTP2 then you misconfigured the pps_gpio driver.

The serial time is provided to ntpd on NTP0, the PPS time is on NTP2, not on NTP1 like described earlier. So your ntp.conf will need to be adjusted from:

To:

Now proceed as for any other operating system to use gpsd.

Be sure to validate that your PPS signal is not offset by the pulse width. That would mean gpsd is using the wrong edge.

Detailed instructions are available from their website: https://learn.adafruit.com/adafruit-ultimate-gps-hat-for-raspberry-pi/

You will need to dig deeper to make the PPS work, here is a good reference: http://www.satsignal.eu/ntp/Raspberry-Pi-NTP.html

Only Windows Subsystem for Linux 1 provides a reasonable means of running gpsd at this time. WSL2 lacks a GUI, USB and serial support making it unsuitable at this time.