User manual update: Put back manual Bluetooth procedures

Put back the procedures for manually achieving a Bluetooth connection
into APPENDIX A.
Refer to the manual procedures from the text that described the new
built-in Subsurface Bluetooth interface.

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

1 files changed, 211 insertions, 2 deletions

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index a7fdeab90..9ebd828ca 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -4,7 +4,7 @@
 // Linus Torvalds, Miika Turkia, Amit Chaudhuri, Jan Schubert, Willem
 // Ferguson, Salvador Cuñat, Pedro Neves
 // :revnumber: 4.5
-// :revdate: September 2015
+// :revdate: October 2015
 :icons:
 :toc:
 :toc-placement: manual
@@ -507,6 +507,11 @@ Select the _Save_ button of the dialogue. This closes the Bluetooth dialogue. No
 _Download_ in the _Download from  dive computer_ dialogue which should still be open.
 The downloaded dives are shown on the righthand side of the download dialogue.
 
+*IN CASE OF PROBLEMS*: When encountering problems with
+Bluetooth download, xref:S_HowFindBluetoothDeviceName[_Appendix A_] contains
+information for manually setting up and inspecting the Bluetooth connection
+with _Subsurface_.
+
 
 [[S_DeviceNames]]
 ==== Changing the name of a dive computer
@@ -3284,7 +3289,7 @@ dealing with the appropriate operations.
   clear all dive information.
 - _Open logbook_ - This opens the file manager in order to select a dive
   logbook to open.
-- _Open cloud storage_ - Open the log book previously saved in <<S_Cloud_storage,_Cloud storage_>>.
+- _Open cloud storage_ - Open the dive log previously saved in <<S_Cloud_storage,_Cloud storage_>>.
 - _Save_ - Save the dive logbook that is currently open.
 - _Save to cloud storage_ - Save the current dive log to <<S_Cloud_storage,_Cloud storage_>>.
 - _Save as_ - Save the current logbook under a different file name.
@@ -3457,6 +3462,210 @@ to the USB
 port, the dive computer interface can connect and one should be able to import
 dives.
 
+
+[[S_HowFindBluetoothDeviceName]]
+=== Manually setting up Bluetooth enabled devices
+[icon="images/icons/bluetooth.jpg"]
+[NOTE]
+For dive computers communicating through bluetooth like the Heinrichs
+Weikamp Frog or the Shearwater Predator and Petrel there is a
+different procedure to get the devices name to communicate with
+_Subsurface_. Follow these steps:
+
+ * *For the dive computer, after enabling Bluetooth, ensure it is in Upload mode.*
+
+For Bluetooth pairing of the dive computer, refer to the
+manufacturer's user guide. When using a Shearwater Predator/Petrel, select
+_Dive Log ->  Upload Log_ and wait for the _Wait PC_ message.
+
+ * *Pair the _Subsurface_ computer with the dive computer.*
+
+==== 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 (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".
+
+For downloading to _Subsurface_, the _Subsurface_ drop-down list should contain
+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:
+
+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
+through the pairing process. This step should only be needed once for
+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
+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 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 1 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 1
+- _Heinrichs-Weikamp OSTC Sport_: channel 1
+
+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 1
+	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]]
 
 == APPENDIX B: Dive Computer specific information for importing dive data.