Add a FAQ entry describing the lossage on sleep/wakeup.

2 files changed, 68 insertions, 0 deletions

diff --git a/www/70-persistent-usb-gps.rules b/www/70-persistent-usb-gps.rules
new file mode 100644
index 00000000..0964df7b
--- /dev/null
+++ b/www/70-persistent-usb-gps.rules
@@ -0,0 +1,44 @@
+# 
+# Author: Fulup Ar Foll
+# Date:   26-jun-09
+# Object: make sure GPS dev (ex: /dev/gps-usb) dont change name on sleep/wakeup
+# -----------------------------------------------------------------------------
+#
+# 1) place this file in /etc/udev/rules.d
+# 2) use default config or update with your own vendor:product ID (use "lsusb" to find them)
+# 3) reload udev with "/etc/init.d/udev reload"
+#
+# Device alias can be:
+#  (default) - by path  ==> SYMLINK="serial-$env(ID_PATH)"   /dev/gps-pci-0000:00:1d.1-usb-0:1:1.0
+#            - static   ==> SYMLINK="gps-usb"                /dev/gps-usb
+#            - custom   ==> RUN+="/usr/local/bin/myscript"   /dev/any-thingk-you-want
+#
+# DEFAULT CONFIG: you can use this file "as it is", you should then see a /dev/gps-pci* 
+# that will be created for any of the serial/usb you hot-plug. The name is fixed but
+# depend on the USB port you use. As a result the name is fixed until you keep the same socket.
+#
+# -----------------------------------------------------------------------
+# check "man 7 udev" for forther syntax. (search for %n)
+# -----------------------------------------------------------------------
+
+# Examples
+# -----------------------------------------------------------------------
+# Your own script:     SUBSYSTEM=="tty", SYSFS{idVendor}=="xxxx", SYSFS{idProduct}=="yyyy", RUN+="/usr/local/bin/myscript"
+# Static device name:  SUBSYSTEM=="tty", SYSFS{idVendor}=="xxxx", SYSFS{idProduct}=="yyyy", SYMLINK="gps-usb"
+# Path dependent name: SUBSYSTEM=="tty", SYSFS{idVendor}=="xxxx", SYSFS{idProduct}=="yyyy", SYMLINK="gps-$env{ID_PATH}"
+# In first case you do what ever you want, script received the information about context in environement variables
+# In second case you name is fixe (ex: /dev/gps-usb) this is working if your usb/serial ID(vendor:product) is unique
+# In third case your device name depend on the port it is plugged in.
+
+
+# ========================================================================================
+#                          update YOUR CONFIG here after
+# ========================================================================================
+
+# Default rules is applied for any unspecified vendor:product devices
+# -----------------------------------------------------------------------------------------
+SUBSYSTEM=="tty", SYSFS{idVendor}=="?*", SYSFS{idProduct}=="?*", SYMLINK="gps-$env{ID_PATH}"
+
+# Well known device may get a static device name 
+# -----------------------------------------------------------------------
+SUBSYSTEM=="tty", SYSFS{idVendor}=="10c4", SYSFS{idProduct}=="ea60", SYMLINK="gps-usb"
diff --git a/www/faq.html b/www/faq.html
index dc872e5e..fc968370 100644
--- a/www/faq.html
+++ b/www/faq.html
@@ -77,6 +77,7 @@ GPSD Frequently Asked Questions
 <li><a href='#interfacing'>How should  I interface my application with <code>gpsd</code>?</a><br/>
 <li><a href='#agps'>Can GPSD work use Assisted GPS data from cellphone networks?</code>?</a><br/>
 <li><a href='#accuracy'>How can I improve fix and PPS time accuracy from my GPS</a><br/>
+<li><a href='#sleep'>Why does my GPS get lost when I sleep/wake my laptop?</a><br/>
 <li><a href='#web'>How do I get gpsd data into a web page?</a><br/>
 </ul>
 
@@ -489,6 +490,29 @@ buildings as possible, and on the ground./<p>
 signal bounce and reduced accuracy. That's just how the physics
 works.</p>
 
+<h1 id='sleep'>Why does my GPS get lost when I sleep/wake my laptop?</h1>
+
+<p>This is not a GPSD problem, but a result of the way Linux handles
+USB serial devices.  In a default Linux configuration, USB serial
+device name do not depend on which physical port you plug the
+USB/serial adaptor, but on what order you plug devices in: 1st device
+gets /dev/ttyUSB0, 2nd gets /dev/ttyUSB1, etc....
+
+<p>This collides with what happens during a suspend/resume. If you
+suspensd while <tt>gpsd</tt> has a device active, it will hold the
+device open while your laptop is asleep - but, meanwhile, the suspend
+logic is shutting down hotpluggable devices to be recreated at
+resume time. On resume, Linux will see that the old device is open
+<em>and recreate one with a different name</em>, leaving <tt>gpsd</tt>
+kooking at a bad file descriptor.</p>
+
+<p>There is a solution to this problem: create a stable gps-usb device
+that is actually a symlink which gets modified by hotplug events, and
+give <tt>gpsd</tt> that device when you invoke it.  You'll need <a
+href="70-persistent-usb-gps.rules">these replacement udev rules</a>,
+and the experience required to patch them so the vendor ID in the last
+one matches your GPS hardware (look in your lsusb output).
+
 <h1 id='web'>How do I get gpsd data into a web page?</h1>
 
 <p>The <code>gpsd</code> source-code distribution now includes a PHP