User manual: update section on Bluetooth

User manual: update section dealing with Bluetooth communication
to reflect Rick's recent contribution. Some editing of the text
was performed to conform to Manual style. This section looks MUCH better now.

Signed-off-by: willem ferguson <willemferguson@zoology.up.ac.za>
Signed-off-by: Dirk Hohndel <dirk@hohndel.org>

1 files changed, 158 insertions, 43 deletions

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index bcfb7d8d0..349b19a39 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -3469,12 +3469,12 @@ _Dive Log ->  Upload Log_ and wait for the _Wait PC_ message.
 
  * *Pair the _Subsurface_ computer with the dive computer.*
 
-.On Windows:
+==== On Windows:
 
 Bluetooth is most likely already enabled. For pairing with the dive computer choose
 _Control Panel ->  Bluetooth Devices ->  Add Wireless Device_.
-This should bring up a dialog showing your dive computer (in Bluetooth mode) and
-allowing pairing. Right click on it and choose _Propertie s->  COM
+This should bring up a dialog showing your dive computer (which should be in Bluetooth mode) and
+allowing pairing. Right click on it and choose _Properties->  COM
 Ports_ to identify the port used for your dive computer. If there are several
 ports listed, use the one saying "Outgoing" instead of "Incoming".
 
@@ -3484,7 +3484,7 @@ this COM port already. If not, enter it manually.
 Note: If there are issues afterwards when downloading from the dive computer using
 other software, remove the existing pairing with the dive computer.
 
-.On MacOS:
+==== On MacOS:
 
 Click on the Bluetooth symbol in the menu bar and select _Set up
 Bluetooth Device..._. The dive computer should then show up in the list of devices. Select it and go
@@ -3494,48 +3494,163 @@ initial setup.
 Once the pairing is completed the correct device is shown in the
 'Device or Mount Point' drop-down in the _Subsurface_ *Import* dialog.
 
-.On Linux
+==== On Linux
 Ensure Bluetooth is enabled on the _Subsurface_ computer.
 On most common distributions this should be true out of the box and
 pairing should be straight forward. For instance, Gnome3 shows a
-Bluetooth icon in the upper right corner of the desktop where one selects 'Set
-up New Device'. This should show a dialog where one can select the
-dive computer (which already should be in Bluetooth mode) and pair it.
-If a PIN is required, try manually setting '0000'.
-
-In the rare cases where the above is not true, then
-depending on your system, try +initd+ or +systemd+. This might be different
-and also involve loading modules specific to your hardware. In case your system
-is running +systemd+, manually run +systemctl start bluetooth.service+ to
-enable it, in case of +initd+, run something like +rc.config start bluetoothd+ or
-+/etc/init.d/bluetooth start+.
-
-One may also use a manual approach by using such commands:
-
- * +hciconfig+ shows the Bluetooth devices available on your
-   computer (not dive computer), most likely one will see a hci0, if not
-   try +hcitool -a+ to see inactive devices and  run +sudo
-   hciconfig hci0 up+ to bring them up.
-
- * +hcitool scanning+ gets a list of bluetooth enabled
-   client devices, look for the dive computer and remember the MAC
-   address are shown there
-
- * +bluez-simple-agent hci0 10:00:E8:C4:BE:C4+  pairs
-   the dive computer with the bluetooth stack of the _Subsurface_ computer, copy/paste
-   the MAC address from the output of 'hcitool scanning'
-
-Unfortunately on Linux binding to a communication device has to be done
-manually by running:
-
- * +rfcomm bind /dev/rfcomm0 10:00:E8:C4:BE:C4+ binds the dive
-   computer to a communication device in the desktop computer, in case rfcomm is
-   already taken use rfcomm1 or up. IMPORTANT: Copy/paste the MAC address
-   from the output of +hcitool scanning+, the MAC address shown above will not
-   work.
-
-For downloading dives in _Subsurface_ specify the device name connected to the MAC
-address in the last step above, e.g. _/dev/rfcomm0_.
+Bluetooth icon on the right of the toolbar at the top of the screen.
+Users have reported difficulties with some Bluetooth controllers.  If you have an onboard controller,
+try that first.  It is simplest if you remove any USB Bluetooth dongles.  If you have a USB dongle that
+came with your dive computer, try that before any others.
+
+Setting up a connection to download dives from your Bluetooth-enabled device, such as the
+_Shearwater Petrel_, is not yet an automated process and will generally require the command prompt.
+It is essentially a three step process.
+
+ - Enable the Bluetooth controller and pair your dive computer</li>
+ - Establish an RFCOMM connection
+ - Download the dives with Subsurface
+
+Ensure the dive computer is in upload mode. On the _Shearwater Petrel_ and _Petrel 2_,
+cycle through the menu, select 'Dive Log', then 'Upload Log'.  The display will read 'Initializing', then
+'Wait PC 3:00' and will countdown.  Once the connection is established, the display reads 'Wait CMD ...'
+and the countdown continues. When downloading the dive from Subsurface, the display reads 'Sending' then
+'Sent Dive'.
+
+To establish the connection, establish root access through +sudo+ or +su+.
+The correct permission is required to download the dives in the computer. On most Linux systems this means becoming
+a member of the dialout group (This is identical as for many dive computers using a Linux USB port, descibed
+in the previous section). On the command terminal, enter:
+
++sudo usermod -a -G dialout username+
+
+Then log out and log in for the change to take effect.
+
+===== Enabling the Bluetooth controller and pairing your dive computer
+
+Attempt to set up the Bluetooth controller and pair your dive computer using the graphical
+environment of the operating system. After setting the dive computer to upload mode, click the Bluetooth icon in the system tray
+and select 'Add new device'. The dive computer should appear. If asked for a password, enter 0000.
+Write down or copy the MAC address of your dive computer - this needed later and should be in the form 	00:11:22:33:44:55.
+
+If the graphical method didn't work, pair the device from the command line. Open a terminal
+and use +hciconfig+ to check the Bluetooth controller status
+
+	$ hciconfig
+	hci0:	Type: BR/EDR  Bus: USB
+		BD Address: 01:23:45:67:89:AB  ACL MTU: 310:10  SCO MTU: 64:8
+		*DOWN*
+		RX bytes:504 acl:0 sco:0 events:22 errors:0
+		TX bytes:92 acl:0 sco:0 commands:21 errors:0
+
+This indicates a Bluetooth controller with MAC address 01:23:45:67:89:AB, connected as hci0.
+Its status is 'DOWN', i.e. not powered.  Additional controllers will appear as hci1, etc.
+If there is not a Bluetooth dongle plugged in upon booting the computer, hci0 is probably the onboard.
+Now power on the controller and enable authentication:
+
+	sudo hciconfig hci0 up auth+  (enter password when prompted)
+	hciconfig
+	hci0:  Type: BR/EDR  Bus: USB
+		BD Address: 01:23:45:67:89:AB  ACL MTU: 310:10  SCO MTU: 64:8
+		*UP RUNNING PSCAN AUTH*
+		RX bytes:1026 acl:0 sco:0 events:47 errors:0
+		TX bytes:449 acl:0 sco:0 commands:46 errors:0
+
++Check that the status now includes +'UP', 'RUNNING' AND 'AUTH'+.
+
+If there are multiple controllers running, it's easiest to off the unused controller(s). For example, for +hci1+:
+
+	sudo hciconfig hci1 down
+
+Next step is to 'trust' and 'pair' the dive computer. On distros with Bluez 5, such as Fedora 22,
+one can use a tool called +blutootctl+, which will bring up its own command prompt.
+
+	bluetoothctl
+	[NEW] Controller 01:23:45:67:89:AB localhost.localdomain [default]
+	[bluetooth]# agent on
+	Agent registered
+	[bluetooth]# default-agent
+	Default agent request successful
+	[bluetooth]# scan on                        <----now set your dive computer to upload mode
+	Discovery started
+	[CHG] Controller 01:23:45:67:89:AB Discovering: yes
+	[NEW] Device 00:11:22:33:44:55 Petrel
+	[bluetooth]# trust 00:11:22:33:44:55        <----you can use the tab key to autocomplete the MAC address
+	[CHG] Device 00:11:22:33:44:55 Trusted: yes
+	Changing 00:11:22:33:44:55 trust succeeded
+	[bluetooth]# pair 00:11:22:33:44:55
+	Attempting to pair with 00:11:22:33:44:55
+	[CHG] Device 00:11:22:33:44:55 Connected: yes
+	[CHG] Device 00:11:22:33:44:55 UUIDs: 00001101-0000-1000-8000-0089abc12345
+	[CHG] Device 00:11:22:33:44:55 Paired: yes
+	Pairing successful
+	[CHG] Device 00:11:22:33:44:55 Connected: no
+
+If asked for a password, enter 0000. It's ok if the last line says 'Connected: no'. The important part
+is the line above, +Pairing successful+.
+
+If the system has Bluez version 4 (e.g. Ubuntu 12.04 through to 15.04), there is probably not a
++bluetoothctl+, but  a script called +bluez-simple-agent+ or just +simple-agent+.
+
+	hcitool -i hci0 scanning
+	Scanning ...
+		00:11:22:33:44:55       Petrel
+		bluez-simple-agent hci0 00:11:22:33:44:55
+
+Once ther dive computer is pired, set up the RFCOMM connection
+
+===== Establishing the RFCOMM connection
+
+The command to establish an RFCOMM connection is:
+
++sudo rfcomm -i <controller> connect <dev> <bdaddr> [channel]+
+
+- <controller>+ is the Bluetooth controller, +hci0+.
+- <dev> is the RFCOMM device file, +rfcomm0+
+- <bdaddr> is the dive computer's MAC address, +00:11:22:33:44:55+
+- [channel] is the dive computer's Bluetooth channel we need to connect to.
+
+If one omits it, channel 0 is assumed.  Based on a limited number of user reports,
+the appropriate channel for the dive computer is probably:
+
+- _Shearwater Petrel 2_: channel 5
+- _Shearwater Petrel 1_: channel 0
+- _Heinrichs-Weikamp OSTC Sport_: channel 0
+
+E.g. to connect a _Shearwater Petrel 2_, set the dive computer to upload mode and enter:
+
+	sudo rfcomm -i hci0 connect rfcomm0 00:11:22:33:44:55 5 (enter a password, probably 0000, when prompted)
+
+This gives the response:
+
+	Connected /dev/rfcomm0 to 00:11:22:33:44:55 on channel 5
+	Press CTRL-C for hangup
+
+To connect a _Shearwater Petrel 1+ or + HW OSTC Sport+, set the dive computer to upload mode and enter:
+
+	sudo rfcomm -i hci0 connect rfcomm0 00:11:22:33:44:55   (enter a password, probably 0000, when prompted)
+	Connected /dev/rfcomm0 to 00:11:22:33:44:55 on channel 0
+	Press CTRL-C for hangup
+
+If the specific channel the dive computer needs is not known, or the channel in the list above doesn't
+work, the command +sdptool records+ should help determine the appropriate channel. The output
+below is for a _Shearwater Petrel 2_.
+
+	sdptool -i hci0 records 00:11:22:33:44:55
+	Service Name: Serial Port
+	Service RecHandle: 0x10000
+	Service Class ID List:
+		"Serial Port" (0x1101)
+		Protocol Descriptor List:
+		"L2CAP" (0x0100)
+		"RFCOMM" (0x0003)
+		Channel: 5
+
+For a Bluetooth dive computer not in the list above, or if the channel listed is not correct, please
+let the Subsurface developers know on the user forum or the developer mailing list _subsurface@subsurface-divelog.org_.
+
+===== Download the dives with Subsurface</em>
+After establishing the RFCOMM connection and while the dive computer's upload mode countdown is still running, go to_Subsurface_, select _Import->Import from dive computer_ and enter appropriate Vendor (e.g. _Shearwater_), Dive Computer (_Petrel_), Device or Mount Point (_/dev/rfcomm0_) and click _Download_.
 
 [[_appendix_b_dive_computer_specific_information_for_importing_dive_information]]