Much more detailed instructions for installing and testing.

1 files changed, 44 insertions, 20 deletions

diff --git a/INSTALL b/INSTALL
index ff0bce2c..ae300b5e 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,38 +1,62 @@
-Start by making sure you can get data from your GPS, otherwise the later
+Here are the steps for installing gpsd and verifying its performance:
+
+1. 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 </dev/ttyUSB0
 
 replace ttyXXX with the filename of the port.  This will probably be
 either /dev/ttyUSB0 or /dev/ttyS0.  When you run this command, you
-should see text lines come to stdout (possibly after a short initial
-burst of bnary 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.
+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.
+
+2. Make a symlink named /dev/gps to your GPS port; the command will be
+
+     ln -s /dev/ttyXXX /dev/gps
+
+where ttyXXX is as in step 1.
+
+3. Build gpsd from source (skip this step if you have installed a gpsd
+binary package).
 
 You will need to have either Motif or LessTif installed in order for
 gps and xgpsspeed to build.  If you're on a Linux system, you probably
-already have LessTif.  Source code is available from <http://www.lesstif.org/>.
+already have LessTif.  Source code is available from
+<http://www.lesstif.org/>.
+
+To build from source, run ./autogen.sh (or sh autogen.sh if the
+script does not have execute permission).  Then run make: libgps.so,
+gpsd, gps, and xgpsspeed will be built. Copy the app-defaults files
+gps.ad and xgpsspeed.ad to your home directory or to the system-wide X
+app-defaults directory.
+
+4. Start gpsd on a serial or USB port that has the GPS connected to it.
+If you made a /dev/gps symlink, just invoking "gpsd" as root should do it.
+If you installed from an RPM, gpsd will be started for you automatically 
+at boot time.
 
-Run ./autogen.sh (or sh autogen.sh if the script does not have execute
-permission).  
+5. Once gpsd is running, telnet to port 2947.  Type "r" to start raw
+and watcher modes.  You should see NMEA data (text lines beginning
+with $) spewing out.  You will also see lines with a GPSD prefix;
+these are sentence translations in GPSD protocol.
 
-Check the Makefile.
+Note that until your GPS has acquired a fix, typing "p" to get position
+will only return this:
 
-Run make:  libgps.so, gpsd, gps, and xgpsspeed will be built.
-Copy the applications wherever you want them to live.
+GPSD,P=?
 
-Copy the app-defaults files gps.ad and xgpsspeed.ad to your home
-directory or to the system-wide X app-defaults directory.
+This response does not mean that gpsd is broken or that the GPS is not
+sending data, merely that gpsd has not yet seen any *valid* position data.
+You will have to wait for the GPS to acquire satellite lock.  If you have 
+raw or watcher mode on it should be obvious when you get a lock.
 
-The right thing to do is to start gpsd on a serial or USB port that
-has the GPS connected to it.
+6. Start the gps 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.
 
-Then start gps.  Calling it with no arguments will do the right thing
-if you have gpsd running on the default port (2947).
 
-You can also telnet to port 2947 for testing. When doing that, type a 'WR'
-followed by <cr>. This should display both the raw NMEA sentences the daemon
-receives from the GPS and their translations in GPSD protocol.