Document the Bluetooth troubleshooting procedure.

1 files changed, 34 insertions, 13 deletions

diff --git a/www/upstream-bugs.html b/www/upstream-bugs.html
index 0fd47883..886280d5 100644
--- a/www/upstream-bugs.html
+++ b/www/upstream-bugs.html
@@ -126,19 +126,40 @@ baud rate so tcsetattr is never called.</p>
 <h2 id="bluetooth">Firmware problems in some Bluetooth and USB devices can hang them</h2>
 
 <p>The baudrate-hunting code in <code>gpsd</code> tickles a serious
-firmware bug on some some Bluetooth devices, notably those shipped by
-Holux and including the GPSlim-236.  This bug may render these GPSes
-catatonic.  The problem seems to be that buggy firmware inside these
-receivers doesn't necessarily keep the Bluetooth serial-port emulation
-and the GPS chip talking at the same baud rate. This problem is not
-unique to <code>gpsd</code> &mdash; Windows users are warned against using
-SiRFdemo's "Synchronize Protocol/Baud Rate" option on Bluetooth devices.</p>
+firmware bug on some some Bluetooth devices; these are flagged on our
+<a href="hardware.html">Hardware</a> page.  This bug may render these
+GPSes catatonic.  The problem seems to be that buggy firmware inside
+these receivers doesn't necessarily keep the Bluetooth serial-port
+emulation and the GPS chip talking at the same baud rate. This problem
+is not unique to <code>gpsd</code> &mdash; Windows users are warned
+against using SiRFdemo's "Synchronize Protocol/Baud Rate" option on
+Bluetooth devices.</p>
 
 <p>If this happens, you can sometimes recover by repeatedly sending
-reset messages using <code>gpsctl</code>.  The only guaranteed fix is to
-drain the battery backing up the GPS's settings; in extreme cases, you
-may have to open the case and unsolder the backup battery so the chip
-forgets its configuration settings.</p>
+reset messages using <code>gpsctl</code>. Otherwise, power-cycling the
+GPS The only guaranteed fix is to drain the battery backing up the
+GPS's settings; in extreme cases, you may have to open the case and
+unsolder the backup battery so the chip forgets its configuration
+settings.</p>
+
+<p>To check whether you have this bug:</p>
+
+<ol>
+<li><p>Reset your GPS to a usable state.</p></li>
+
+<li><p>Launch gpsd with the Bluetooth device on the command line and
+the -b option to prevent autobauding.</p></li>
+
+<li><p>Observe it operating.</p></li>
+
+<li><p>Power down the device and terminate gpsd.</p></li>
+
+<li><p>Launch with -b again and see if it still works.</p></li>
+</ol>
+
+<p>If you find the device comes up on the last step, then you know
+that -b is an effective workaround and can finger bad Bluetooth
+firmware as the cause of the problem.</p>
 
 <p>A separate bug with less severe symptoms afflicts some USB devices.
 The probe strings <tt>gpsd</tt> sends in order to determine device
@@ -148,8 +169,8 @@ break up the probe writes into smaller pieces, interleaving them with
 the first few packet reads, so they are far less likely to trigger
 this bug.</p>
 
-<p>Use the -b option of gpsd to prevent it from trying to reconfigure
-your GPS; this will avoid both problems.</p>
+<p>You can use the -b option of gpsd to prevent it from trying to
+reconfigure your GPS; this will avoid both problems.</p>
 
 <h2 id="pl2303">Linux pl2303 driver on openwrt 2.4 kernel can hang when device is read at unexpected speed</h2>