diff options
| -rw-r--r-- | Documentation/user-manual.txt | 201 |
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]] |