[PATCH] 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 <willemfergu...@zoology.up.ac.za>
From 87666415cc92a845e4e625c2159f8f4cecbc49ac Mon Sep 17 00:00:00 2001
From: Willem Ferguson <willemfergu...@zoology.up.ac.za>
Date: Thu, 24 Sep 2015 16:14:29 +0200
Subject: [PATCH] [PATCH] 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 <willemfergu...@zoology.up.ac.za>
---
Documentation/user-manual.txt | 213 +++++++++++++++++++++++++++++++++++++++++-
1 file changed, 211 insertions(+), 2 deletions(-)
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index a7fdeab..9ebd828 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.
--
2.1.4
_______________________________________________
subsurface mailing list
subsurface@subsurface-divelog.org
http://lists.subsurface-divelog.org/cgi-bin/mailman/listinfo/subsurface
