diff options
Diffstat (limited to 'Documentation/user-manual.txt')
| -rw-r--r-- | Documentation/user-manual.txt | 213 |
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. |