Subject: [PATCH] User manual: update section on Bluetooth
User manual: update section dealing with Bluetooth communication
to reflect Rick Walsh'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 <willemfergu...@zoology.up.ac.za>
---
>From 9bb7ade613ecfc8acd53b87bcb0e060fdb904f2c Mon Sep 17 00:00:00 2001
From: willem ferguson <willemfergu...@zoology.up.ac.za>
Date: Sat, 23 May 2015 20:55:48 +0200
Subject: [PATCH] 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 <willemfergu...@zoology.up.ac.za>
---
Documentation/user-manual.txt | 189 ++++++++++++++++++++++++++++++++++--------
1 file changed, 154 insertions(+), 35 deletions(-)
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index bcfb7d8..1a92921 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'.
+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+.
-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+.
+ hcitool -i hci0 scanning
+ Scanning ...
+ 00:11:22:33:44:55 Petrel
+ bluez-simple-agent hci0 00:11:22:33:44:55
-One may also use a manual approach by using such commands:
+Once ther dive computer is pired, set up the RFCOMM connection
- * +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.
+===== Establishing the RFCOMM connection
- * +hcitool scanning+ gets a list of bluetooth enabled
- client devices, look for the dive computer and remember the MAC
- address are shown there
+The command to establish an RFCOMM connection is:
- * +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'
++sudo rfcomm -i <controller> connect <dev> <bdaddr> [channel]+
-Unfortunately on Linux binding to a communication device has to be done
-manually by running:
+- <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.
- * +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.
+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:
-For downloading dives in _Subsurface_ specify the device name connected to the MAC
-address in the last step above, e.g. _/dev/rfcomm0_.
+- _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]]
@@ -3951,3 +4066,7 @@ It's even more noticeable if you do things like divemastering the initial OW div
you may stay in the water for a long time, but spend most of it at the surface. And then
you don't want that to count as some kind of long diveâ.
+
+
+
+
--
1.9.1
_______________________________________________
subsurface mailing list
subsurface@subsurface-divelog.org
http://lists.subsurface-divelog.org/cgi-bin/mailman/listinfo/subsurface
