= GPSD Installation Instructions = :title: GPSD Installation Instructions :description: Steps for installing GPSD and verifying its performance. :keywords: GPSD, GPS, installation :author: Eric S. Raymond :robots:index,follow Here are the steps for installing GPSD and verifying its performance. They assume you have GPSD available as an installable binary package, Instructions for building GPSD from source (including cross-building) are in the file "build.txt" in the source distribution. Most of these installation instructions are generic to Linux (inc There are some special notes on installation for OS X and the Raspberry Pi near the end of this file. == Check that your GPS is live and you can get data from it == Start by making sure you can get data from your GPS, otherwise the later steps will be very frustrating. In this command stty -F /dev/ttyXXX ispeed 4800 && cat =6) or 3.y(y>=2) | required for various clients and utilities |python-GI bindings | the test clients xgps and xgpsspeed, need this |pyserial | for ubxtool and zerk in direct-serial mode |=============================================================================== Some ncurses packages contain the terminfo library; some break it out separately as libtinfo5 or libtinfo. == Installing gpsd == === Install your distributions package(s) === Up-to-date gpsd packages are generally available for Linux distributions including Debian and derivatives (including Ubuntu and Mint), Fedora and derivatives (including CentOS), openSUSE, PCLinuxOS, Mageia, Gentoo, and Slackware. In the embedded space, CeroWRT and Yocto carry GPSD. The GPSD package in the FreeBSD ports tree is also reliably up to date. Even if your distribution is not on this list, it is quite likely GPSD has already been packaged for it. Whatever distribution you are running, the name of the core GPSD package containing the service daemon is almost certainly "gpsd". However, many distributions break up GPSD into separate installable packages for the core daemon and clients; you should search your repository index for anything with gpsd as a prefix. === Install from source code === Directions for installing from source are in the file build.txt found in the source distribution. == How to test the software == 1. Start gpsd. You'll need to give it as an argument a path to a serial or USB port with a GPS attached to it. Your test command should look something like this: gpsd -D 5 -N -n /dev/ttyUSB0 2. Once gpsd is running, telnet to port 2947. You should see a greeting line that's a JSON object describing GPSD's version. Now plug in your GPS (or AIS receiver, or RTCM2 receiver). 3. Type '?WATCH={"enable":true,"json":true};' to start raw and watcher modes. You should see lines beginning with '{' that are JSON objects representing reports from your GPS; these are reports in GPSD protocol. 4. Start the xgps or cgps client. Calling it with no arguments should do the right thing. You should see a display panel with position/velocity-time information, and a satellite display. The displays won't look very interesting until the GPS acquires satellite lock. 5. Have patience. If you are cold-starting a new GPS, it may take 15-20 minutes after it gets a skyview for it to download an ephemeris and begin delivering fixes. 6. A FAQ and troubleshooting instructions can be found at the GPSD project site. == Once you have verified correct operation == 1. If you installed from a .deb under Debian or a Debian-derived system, you may need to `dpkg-reconfigure -plow gpsd' to enable the hotplug magic ("Start gpsd automatically"). 2. Check out the list of supported hardware at the Hardware page on the GPSD project's website. If your GPS isn't on the list, please send us information to add a new line to the table. Directions are included on that page. We can also use updates of the latest version number known to work with hardware already supported. 3. GPSD includes gpsd.php, a PHP script, that you can use to generate a PHP status page for your GPS if you wish. (It may not be in the core package.) It should be manually copied to your HTTP document directory. The first time it's invoked, it will generate a file called 'gpsd_config.inc' in that directory containing configuration information; edit to taste. 4. There are other non-essential scripts that may be useful; these are in the contrib/ directory of the source. They may not be available in the packages available from distributions. For special instructions related to using GPSD for time service, see the GPSD Time Service HOWTO in the distribution or on the web. == Special Notes for OS X Installation == gpsd will build, install and run on OS X. The easiest way to do so is to first install the MacPorts package. Follow their install procedure at: http://www.macports.org/install.php Then use their port command to install scons, and optionally git if you want to access the development source. -------------------------------------------------------------- # port install scons # port install git -------------------------------------------------------------- While running gpsd, or scons check, you may run out of shared memory segments. If so, you will see this error message: -------------------------------------------------------------- gpsd:ERROR: shmat failed: Too many open files -------------------------------------------------------------- By default OS X allows a very small number of shared segments. You can check your allowed maximum number of shared segments, then increase the maximum number, with these commands: -------------------------------------------------------------- # sysctl kern.sysv.shmseg=8 kern.sysv.shmseg: 32 -> 8 # sysctl -a | fgrep shmseg kern.sysv.shmseg: 8 # sysctl kern.sysv.shmseg=16 kern.sysv.shmseg: 8 -> 16 # sysctl -a | fgrep shmseg kern.sysv.shmseg: 16 -------------------------------------------------------------- If you are using a USB based GPS you will likely need the Prolific PL2303 driver. You can find it here: http://www.prolific.com.tw/US/ShowProduct.aspx?p_id=229&pcid=41 == Special Notes for Raspberry Pi Installation == gpsd will build, install and run on the Raspberry Pi (RasPi) and Pi 2 using Debian jessie. Other distributions based on Debian (raspbian, etc) will work fine as well. The gpsd package in Debian Wheezy is known to be flaky, be sure to update to a new version of gpsd from source. === Raspbian === Before compiling gpsd from source, you will need to update your system as root. Switching to the latest raspbian distribution (jessie) is strongly recommended. -------------------------------------------------------------- # apt-get update # apt-get dist-upgrade # rpi-update # reboot -------------------------------------------------------------- -------------------------------------------------------------- # apt-get install scons libncurses5-dev python-dev pps-tools # apt-get install git-core -------------------------------------------------------------- Git-core is only required to build from a git repository. pps-tools is for testing PPS inputs. The rest of the installation is just as for any other source based install, as noted in the file *build.txt* . === Other Debian derivatives (including stock) === ==== Jessie ==== -------------------------------------------------------------- # apt-get install scons libncurses5-dev python-dev pps-tools # apt-get install git-core -------------------------------------------------------------- Git-core is only required to build from a git repository. pps-tools is for testing PPS inputs. The rest of the installation is just as for any other source based install, as noted in the file *build.txt* . ==== Wheezy ==== Wheezy, being older, requires updating the tools for compiling and testing gpsd: You need scons at 2.3.0 or higher to build. If your scons is less than 2.3.0 you will need to get a newer scons from wheezy-backport. Partial instructions are detailed here: http://backports.debian.org/Instructions/ Basically you need to add this line to /etc/apt/sources.list: -------------------------------------------------------------- deb http://http.debian.net/debian wheezy-backports main -------------------------------------------------------------- Then do another update: -------------------------------------------------------------- apt-get update -------------------------------------------------------------- Which may lead you to this error if you lack a full set of debian keys: -------------------------------------------------------------- W: GPG error: http://http.debian.net wheezy-backports Release: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 8B48AD6246925553 -------------------------------------------------------------- Partial but detailed instructions to fix that are here: -------------------------------------------------------------- https://wiki.debian.org/SecureApt -------------------------------------------------------------- Use either of the following code blocks. The first is more robust: -------------------------------------------------------------- apt-get install debian-archive-keyring -------------------------------------------------------------- -------------------------------------------------------------- gpg --keyserver pgpkeys.mit.edu --recv 8B48AD6246925553 gpg -a --export 46925553 | apt-key add - apt-get update -------------------------------------------------------------- You can now install scons from the wheezy-backports repository: -------------------------------------------------------------- apt-get -t wheezy-backports install scons -------------------------------------------------------------- and other tools: -------------------------------------------------------------- # apt-get install scons libncurses5-dev python-dev pps-tools # apt-get install git-core -------------------------------------------------------------- Git-core is only required to build from a git repository. pps-tools is for testing PPS inputs. The rest of the installation is just as for any other source based install, as noted in the file *build.txt* . === Other Raspberry Pi tips === 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: -------------------------------------------------------------- ~ # gpsd -D 5 -N -n /dev/ttyAMA0 /dev/pps0 -------------------------------------------------------------- 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: -------------------------------------------------------------- ~ # gpsd -D 5 -N -n /dev/ttyAMA0 -------------------------------------------------------------- You can verify gpsd is using the PPS by running ntpshmmon: -------------------------------------------------------------- ~ # ntpshmmon # Name Seen@ Clock Real L Prec sample NTP0 1461619703.641899335 1461619703.445224418 1461619703.000000000 0 -1 sample NTP2 1461619703.642203397 1461619702.999262204 1461619703.000000000 0 -20 sample NTP0 1461619704.142097363 1461619703.445224418 1461619703.000000000 0 -1 sample NTP2 1461619704.142204134 1461619703.999258157 1461619704.000000000 0 -20 -------------------------------------------------------------- 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: -------------------------------------------------------------- # GPS PPS reference (NTP1) server 127.127.28.1 prefer fudge 127.127.28.1 refid PPS -------------------------------------------------------------- To: -------------------------------------------------------------- # GPS PPS reference (NTP2) server 127.127.28.2 prefer fudge 127.127.28.2 refid PPS -------------------------------------------------------------- Now proceed as for any other operating system to use gpsd. Warning, the pps_gpio driver in all linux kernels up to the current 3.19 only reports one edge. Be sure to validate that your PPS signal is not offset by the pulse width. Detailed instructions are available from their web site: 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