diff options
author | Eric S. Raymond <esr@thyrsus.com> | 2011-09-25 11:34:21 -0400 |
---|---|---|
committer | Eric S. Raymond <esr@thyrsus.com> | 2011-09-25 11:34:21 -0400 |
commit | 05f83412bce5c114f72d4c85da0b5a26b5254c83 (patch) | |
tree | 4c689386865fbe88c816187f6c5ca00a1075dede /INSTALL | |
parent | 898d32d48c71029e1c8654c38f9f70f525e90a43 (diff) | |
download | gpsd-05f83412bce5c114f72d4c85da0b5a26b5254c83.tar.gz |
More documentation updates.
Diffstat (limited to 'INSTALL')
-rw-r--r-- | INSTALL | 98 |
1 files changed, 47 insertions, 51 deletions
@@ -1,9 +1,16 @@ = GPSD Installation Instructions = -Here are the steps for installing GPSD and verifying its performance: +Here are the steps for installing GPSD and verifying its performance. +They assume you have GPSD available as an installable binary package, + +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. Instructions for building GPSD from source (including cross-building) -are in the file "build.txt" +are in the file "build.txt" in the source distribution. == Check that your GPS is live and you can get data from it == @@ -29,21 +36,9 @@ 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 akll be loaded on demand when +Under a stock Linux kernel these will all be loaded on demand when the USB system sees the appropriate vendor/product ID combinations. -If you have or are custom-building a Linux kernel for embedded -deployment, you will need some subset of the following modules: - -pl2303 Prolific Technology, Inc. PL2303 Serial Port -ftdi_sio FTDI 8U232AM / FT232 -cypress_m8 M8/CY7C64013 -cp210x Cygnal Integrated Products devices -garmin_gps Garmin USB mice including GPS-18 -cdc_am USB Communication Device Class Abstract Control Model interface - -These are listed in rough order of devices covered as of 2011; the -PL23203 by itself accounts for over 70% of deployed USB mice. We -recommend building with pl2303, ftdi_sio, cypress_m8, and cp210x. +See build.txt for instructions relating to custom kernels. == Check that your system configuration will allow GPSD to work == @@ -85,13 +80,15 @@ 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: -pthreads library -> support for PPS timekeeping on serial GPSes -DBUS -> gpsd will issue DBUS notifications -ncurses -> a test client and the GPS monitor depend on this -libusb-1.0.x or later -> better USB device discovery -Qt + qmake -> libQgpsmm depends on this -python2.6+ -> required for various clients and utilities -pgtk-2/cairo bindings -> the main test client, xgps, needs this +|========================================================================== +|pthreads library | support for PPS timekeeping on serial GPSes +|DBUS | gpsd will issue DBUS notifications +|ncurses | a test client and the GPS monitor depend on this +|libusb-1.0.x or later | better USB device discovery +|Qt + qmake | libQgpsmm depends on this +|python2.6+ | required for various clients and utilities +|pgtk-2/cairo bindings | the main test client, xgps, needs this +|========================================================================== Note that while Python is required to *build* GPSD from source (the build uses some code generators in Python), it is not required to run @@ -102,19 +99,13 @@ The Python code in GPSD is actually compatible back to Python 2.4 except that you need either the json library module from 2.6 or the functionally equivalent simplejson backport. -== Building and installing the software == - -If you have GPSD available as a binary package, its name 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. - -Instructions for building from source are in the file "build.txt". - == 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. +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. @@ -125,19 +116,26 @@ 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 client. Calling it with no arguments should do the right -thing. You should see a GUI panel with position/velocity-time information, -and a satellite display. The displays won't look very interesting until -the GPS acquires satellite lock. +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. To enable hotplugging of USB GPSes under Linux, do a 'scons udev-install' or -equivalent to put the appropriate udev rules and wrapper files in place. +6. A FAQ and troubleshooting instructions can be found at +http://gpsd.berlios.de/faq.html -7. Check out the list of supported hardware at +== 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 http://gpsd.berlios.de/hardware.html @@ -147,19 +145,17 @@ 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. -8. The distribution includes a PHP script that you can use to -generate a PHP status page for your GPS. You will need php and php-gd -installed. To install it, copy the file 'gpsd.php' to your HTTP -document directory. The first time it's invoked, it will generate a -file called 'gpsd_config.inc' containing configuration information; -edit to taste. Note that for the Google Maps feature work you need -to set a valid Google API key in your config file. +3. GPSD includes 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.) -9. 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"). +It will be installed in 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. Note +that for the Google Maps feature work you need to set a valid Google +API key in gpsd_config.inc. -10. Note for people using gpsd as time source for ntpd: In case you're +4. Note for people using gpsd as time source for ntpd: In case you're using dhcp3-client to configure your system, make sure you disable /etc/dhcp3/dhclient-exit-hooks.d/ntp, as dhclient would restart ntpd with an automatically created ntp.conf otherwise - and gpsd |