Changeset 541b86e in subsurface

Apr 18, 2017, 9:15:52 PM (6 days ago)
Dirk Hohndel <dirk@…>
Rick Walsh <rickmwalsh@…> (04/05/17 15:28:30)
Dirk Hohndel <dirk@…> (04/18/17 21:15:52)

FAQ: update section on Bluetooth on Linux

Setting up an RFCOMM connection has not been required for a long time.

Reported-by: Stephen Hemminger <stephen@…>
Signed-off-by: Rick Walsh <rickmwalsh@…>
Signed-off-by: Dirk Hohndel <dirk@…>

1 edited


  • Documentation/FAQ.wordpress

    r0f63b52 r541b86e  
    127 [expand title="How do I download dives from my Shearwater Petrel 2 (or other Bluetooth dive computer) on Linux?"]
     127[expand title="How do I download dives from my Bluetooth dive computer (e.g. Shearwater, OSTC) on Linux?"]
    129 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.
     129Downloading dives over Bluetooth on all platforms is done using the "Choose Bluetooth download mode" option when downloading dives, and pairing with the detected dive computer. This is further explained in the <a href="">Subsurface User Manual</a>.
    131 <ol>
    132 <li>Enable Bluetooth controller and pair your dive computer</li>
    133 <li>Establish an RFCOMM connection</li>
    134 <li>Download the dives with Subsurface</li>
    135 </ol>
    137 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.
    139 Make sure you know how to put your dive computer into upload mode.  On the Shearwater Petrel, Petrel 2 and Nerd, 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'.
    141 To establish the connection you need to have root access through sudo or su, and you will need to have the correct permissions on your system to download the dives.  On Fedora 22 and probably most other systems, this means becoming a member of the dialout group if you are not already.  This can be done graphically, or on the command terminal, enter:
    142 <pre><code style="font-size: 8pt;">sudo usermod -a -G dialout username</code></pre>
    143 Log out and log in for the change to take effect.
    145 <em>Enabling the Bluetooth controller and pairing your dive computer</em>
    146 You may be able to set up the Bluetooth controller and pair your dive computer using your distros graphical environment.  Once you've set your dive computer to upload mode, click the Bluetooth icon in the system tray and selecting 'Add new device'.  Your dive computer should appear.  If asked for a password, enter 0000.  Write down or copy the MAC address of your dive computer - you'll need this later.  It should be in the form 00:11:22:33:44:55.
    148 If the graphical method didn't work, you need to pair the device from the command line.  Open a terminal and use hciconfig to check the Bluetooth controller status
    149 <pre><code style="font-size: 8pt;">hciconfig
    150 hci0:   Type: BR/EDR  Bus: USB
    151         BD Address: 01:23:45:67:89:AB  ACL MTU: 310:10  SCO MTU: 64:8
    152         DOWN
    153         RX bytes:504 acl:0 sco:0 events:22 errors:0
    154         TX bytes:92 acl:0 sco:0 commands:21 errors:0</code></pre>
    155 This tells you you have one 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 you didn't have a Bluetooth dongle plugged in when you booted your computer, hci0 is probably the onboard.  We need to power on the controller and enable authentication:
    156 <pre><code style="font-size: 8pt;">sudo hciconfig hci0 up auth
    157 (enter password when prompted)
    158 hciconfig
    159 hci0:   Type: BR/EDR  Bus: USB
    160         BD Address: 01:23:45:67:89:AB  ACL MTU: 310:10  SCO MTU: 64:8
    161         UP RUNNING PSCAN AUTH
    162         RX bytes:1026 acl:0 sco:0 events:47 errors:0
    163         TX bytes:449 acl:0 sco:0 commands:46 errors:0</code></pre>
    164 Check that the status now includes 'UP', 'RUNNING' AND 'AUTH'
    166 If there are multiple controllers running, it's easiest if you turn off the controller(s) you don't plan to use. E.g.
    167 <pre><code style="font-size: 8pt;">sudo hciconfig hci1 down</code></pre>
    168 Next step is to 'trust' and 'pair' the dive computer.  On distros with Bluez 5, such as Fedora 22, you can use a tool called blutootctl, which will bring up its own command prompt.
    169 <pre><code style="font-size: 8pt;">bluetoothctl
    170 [NEW] Controller 01:23:45:67:89:AB localhost.localdomain [default]
    171 [bluetooth]# agent on
    172 Agent registered
    173 [bluetooth]# default-agent
    174 Default agent request successful
    175 [bluetooth]# scan on                        <----now set your dive computer to upload mode
    176 Discovery started
    177 [CHG] Controller 01:23:45:67:89:AB Discovering: yes
    178 [NEW] Device 00:11:22:33:44:55 Petrel
    179 [bluetooth]# trust 00:11:22:33:44:55        <----you can use the tab key to autocomplete the MAC address
    180 [CHG] Device 00:11:22:33:44:55 Trusted: yes
    181 Changing 00:11:22:33:44:55 trust succeeded
    182 [bluetooth]# pair 00:11:22:33:44:55
    183 Attempting to pair with 00:11:22:33:44:55
    184 [CHG] Device 00:11:22:33:44:55 Connected: yes
    185 [CHG] Device 00:11:22:33:44:55 UUIDs: 00001101-0000-1000-8000-0089abc12345
    186 [CHG] Device 00:11:22:33:44:55 Paired: yes
    187 Pairing successful
    188 [CHG] Device 00:11:22:33:44:55 Connected: no</code></pre>
    189 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'.
    191 If your system has Bluez version 4 (e.g. Ubuntu 12.04 through to 15.04), you probably don't have bluetoothctl, but do have a script called bluez-simple-agent or just simple-agent.
    192 <pre><code style="font-size: 8pt;">hcitool -i hci0 scanning
    193 Scanning ...
    194         00:11:22:33:44:55       Petrel
    195 bluez-simple-agent hci0 00:11:22:33:44:55</code></pre>
    196 Once you have paired your dive computer, you are ready to set up the RFCOMM connection
    198 <em>Establishing the RFCOMM connection</em>
    199 The command to establish an RFCOMM connection is:
    200 <pre><code style="font-size: 8pt;">sudo rfcomm -i &lt;controller&gt; connect &lt;dev&gt; &lt;bdaddr&gt; [channel]</code></pre>
    201 &lt;controller&gt; is the Bluetooth controller, hci0
    202 &lt;dev&gt; is the RFCOMM device file, rfcomm0
    203 &lt;bdaddr&gt; is the dive computer's MAC address, 00:11:22:33:44:55
    204 [channel] is the dive computer's Bluetooth channel we need to connect to.  If you omit it, channel 1 will be assumed.  Based on a limited number of user reports, the channel for different dive computers is probably:
    205 <ul>
    206 <li>Shearwater Petrel 2: channel 5
    207 <li>Shearwater Nerd: channel 5
    208 <li>Shearwater Petrel 1: channel 1
    209 <li>OSTC Sport: Channel 1
    210 </ul>
    211 E.g. to connect a Shearwater Petrel 2, set the dive computer to upload mode and enter:
    212 <pre><code style="font-size: 8pt;">sudo rfcomm -i hci0 connect rfcomm0 00:11:22:33:44:55 5
    213 (enter password when prompted)
    214 Connected /dev/rfcomm0 to 00:11:22:33:44:55 on channel 5
    215 Press CTRL-C for hangup</code></pre>
    216 To connect a Shearwater Petrel 1 or OSTC Sport, set the dive computer to upload mode and enter:
    217 <pre><code style="font-size: 8pt;">sudo rfcomm -i hci0 connect rfcomm0 00:11:22:33:44:55
    218 (enter password when prompted)
    219 Connected /dev/rfcomm0 to 00:11:22:33:44:55 on channel 1
    220 Press CTRL-C for hangup</code></pre>
    221 If you don't know what channel your dive computer uses, or the channel in the list above doesn't work, the command 'sdptool records' should help determine the appropriate channel.  The output below is from a Shearwater Petrel 2.
    222 <pre><code style="font-size: 8pt;">sdptool -i hci0 records 00:11:22:33:44:55
    223 Service Name: Serial Port
    224 Service RecHandle: 0x10000
    225 Service Class ID List:
    226   "Serial Port" (0x1101)
    227 Protocol Descriptor List:
    228   "L2CAP" (0x0100)
    229   "RFCOMM" (0x0003)
    230     Channel: 5</code></pre>
    231 If you have 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
    233 <em>Download the dives with Subsurface</em>
    234 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'.
    236 If you get a permissions error, you probably need to add yourself to the dialout group, logout and login again.
     131Previous versions of Subsurface required setting up an RFCOMM connection from the command line before downloading dives from a Bluetooth enabled dive computer. This is no longer the case.
Note: See TracChangeset for help on using the changeset viewer.