subsurface/Documentation/FAQ.wordpress

<!-- when editing please don't break the formatting... WordPress is a bit silly about this
     - I need the empty lines after the [expand...] and before the [/expand]
     - Every paragraph is a single line (how stupid is that!) with an empty line in between -->
<h2>Here are some Frequently Asked Questions by our users</h2>
<span class="expandall">Expand All</span> --- <span class="collapseall">Collapse All</span>
[expand title="Which operating system does Subsurface support?"]

Subsurface runs on Windows (32 and 64bit, Windows XP and newer), MacOS (Intel, 10.7 and newer) and many flavors of Linux. We provide Linux packages for Ubuntu, Linux Mint, Debian, openSUSE and Fedora. Details on where to find Subsurface for your OS are on our <a title="Downloads" href="http://subsurface-divelog.org/download/">Downloads</a> page.

[/expand]
[expand title="How do I install Subsurface on Windows?"]

<a href="http://subsurface-divelog.org/download/">Download the installer</a> and double-click on it. You will get a warning that the installer is from an unknown publisher. Please click Yes to allow installation. Next you are presented with the license for Subsurface, after that you can choose where you would like to install Subsurface (the default should be reasonable in most cases) and the <em>Start Menu Folder</em> where a shortcut to call Subsurface and an entry to uninstall Subsurface will be installed.

[/expand]
[expand title="How do I install Subsurface on MacOS?"]

<a href="http://subsurface-divelog.org/download/">Download the installer DMG</a> and open it. Drag the Subsurface icon on to the Applications icon.

[/expand]
[expand title="How do I install Subsurface on Ubuntu?"]

Simply add the following PPA to your system:
<pre><code style="font-size: 8pt;">ppa:subsurface/subsurface</code></pre>
[/expand]
[expand title="How do I install Subsurface on Debian?"]

We currently only support Debian Jessie; you need to add the Ubuntu repository:
<pre><code style="font-size: 8pt;">echo "deb http://ppa.launchpad.net/subsurface/subsurface/ubuntu trusty main" \
        | sudo tee /etc/apt/sources.lists.d/subsurface.list
gpg --keyserver subkeys.pgp.net --recv-keys A8BC9756EE61D9C6
gpg -a --export A8BC9756EE61D9C6 | sudo apt-key add -
sudo apt-get update</code></pre>
Now you can install Subsurface from that repository:
<pre><code style="font-size: 8pt;">sudo apt-get install subsurface</code></pre>
Make sure you are getting a current version with all its Qt5 dependencies.

[/expand]
[expand title="How do I install Subsurface on openSUSE?"]

Go to <a href="http://software.opensuse.org/download.html?project=home:Subsurface-Divelog&amp;package=subsurface">our build service project page</a> and follow the simple instructions there -- it’s as easy as two clicks.

[/expand]
[expand title="The shortcut keys don't work on Ubuntu"]

Please uninstall <code style="font-size: 9pt;">appmenu-qt5</code> and the
shortcuts will work.

[/expand]
[expand title="How can I post my dive on Facebook?"]

Go to the preferences and select the Facebook section. There you can log in to your Facebook account. You have to do this every time you want to post to Facebook, for privacy reasons Subsurface does not stay logged in to Facebook between sessions.

Once you are logged into Facebook you can close the preferences. You will now see a Facebook button next to the Notes section towards the center of the Subsurface window. Clicking on that opens a dialog that allows you to control which parts of the current dive are posted to your timeline. The post is always "private" - you need to connect to Facebook and change the audience for that post in order for others to see it (we do this so you get to review what is posted before it becomes public).

[/expand]
[expand title="How can I post my dives on the web?"]

Currently Subsurface integrates with two different online logbooks: <a href="http://divelogs.de">divelogs.de</a> and <a href="http://dive-share.appspot.com/">DiveShare</a>. You can export dives to either of those two services from the File➝Export menu.

[/expand]
[expand title="How do I use the companion apps?"]

There are companion apps available for both Android and IOS. You can find them in the respective stores. Once you install them on your mobile device you can either mark dive sites and name them (e.g., right before or after a dive), or you can run a "service" in the background that periodically records your position. Don't forget to turn the service off when you are done as it may increase your battery consumption.

Once you have uploaded the dive site data from the companion app to our web service, you can then download the data from within Subsurface. Do this <em>after</em> you have downloaded the dives from that day from your divecomputer (or manually added the dives) so that Subsurface can match the dive data (and their time stamps) with the data stored by the companion app. Subsurface will then add GPS data to those dives that didn't have GPS information and are reasonably close in time to to markers saved by the companion app.

Please note that the companion apps by themselves do <em>not</em> add dives to your dive list. The dive needs to exist before GPS data is added to it.

[/expand]
[expand title="How can I use more than one tank with the same gas?"]

This is a typical question for side mount divers or some tec divers. Subsurface supports having more than one tank with the same gas, even if some dive computers don't. Simply add a gas change to your second tank of the same gas as both tanks will be included in the gas use calculations. In order to add gas changes simply right-click on the profile at the appropriate spot and you will be offered to add such an event.

[/expand]
[expand title="Why is Subsurface not able to download my dives?"]

Clean the contacts. Clean the contacts again. Make sure the connector is firmly connected. Wiggle it. Seriously. Make sure the dive computer is in transfer mode (this isn't necessary for all dive computers but for many common ones). Check with other software that the download works in general. Try another cable. See our user manual for pairing with BT and the general use case.

[/expand]
[expand title="Why is the CSV import failing?"]

The CSV import has a couple of caveats. You should avoid some special characters like ampersand (&), less than (<), greater than (>) and double quotes ("), the latter if quoting text cells. The file should use UTF-8 character set, if having non-ASCII characters. Also the size of the CSV file might cause problems. Importing 100 dives at a time (without dive profile) has worked previously, but larger files might exceed limits of the parser used. When having problems with CSV imports, try first with a smaller sample to make sure everything works.

[/expand]
[expand title="How can I use Subsurface for multiple users?"]

Store logs of different users to separate log files. From Subsurface, you can open individual files for different divers and multiple users are supported quite well.

[/expand]
[expand title="How can I load pictures and associate them with my dive?"]

Select the dives you want to load and associate the pictures with. Then right click on one of the selected dives and select "Load images" from the
popup menu. This will bring in a file selection dialog where you can select one or multiple pictures. When the selection is done and you hit Open, you get a new dialog where you can shift the times of the images. This is described in more detail in our user manual.

If you are having trouble with loading the images, check that you have at least one of the following tags in the Exif headers DateTimeOriginal or
DateTime. We take the time from these fields to detect if the image was shot during the dive or not. If the picture is edited, you should store the original Exif information on the new/edited image for it to be loaded properly.

[/expand]
[expand title="Can I import my dives from my old log software?"]

Many common programs are already supported and we are always happy to try to add new ones. If your old log software supports exporting the log book, we might well be able to import that (for example via CSV files or UDDF). However, usually support for importing the native format will help you to get more complete information into Subsurface. To implement support for the log format, we will need a sample log file. It would be great to have also a screenshot from the original log software or description of the dive that is shown on the sample log. Preferably we would like to have a reasonably simple dive to get basic support and another dive that has as many features enabled as possible (e.g. gas changes during the dive). Please post this information to the user forum or send it to the developer mailing list subsurface@subsurface-divelog.org. Unfortunately some of the log formats we have not been able to decipher (as some vendors have decided to encrypt their log files to increase the degree of lock-in of their customers), so there are no guarantees that this will bring support for your old log software, but it is worth a try.

[/expand]
[expand title="Can you add support for dive computer X?"]

We support a large number of dive computers already and are always happy to add support for more. Please contact us via the user forums so we can try to help. Some vendors have actively helped us in our work and adding support for new models from those vendors is usually easy. Other vendors are more neutral, some are actively hostile. Without help from the vendor it can be rather challenging to reverse engineer the transfer protocol and the dive encoding, but with sufficient help from you it is often possible to do so.

A good starting point is often to send us a libdivecomputer log and dump (you can pick those in the dive computer download dialog) when connecting to the dive computer using a similar existing model (if possible).

[/expand]
[expand title="Is there a virus in the Subsurface installer?"]

If you get a warning message or if Subsurface is blocked by your anti virus software, that is almost certainly a false positive. Subsurface is not built on a Windows machine, it is cross built from source on Linux on a well maintained and clean server.

Most/all Windows AV software packages support an "add exception" feature, which skips an executable from being scanned. Try adding Subsurface to the list of non-harmful software. If the Subsurface installer download is detected as malware, please temporary disable your AV software until Subsurface is installed

In either case, please inform your AV software vendor of a "false positive" as we assure your that Subsurface is not malware

[/expand]
[expand title="I cannot download all my dives, only the most recent ones even though my dive computer's manual states that it records history of e.g. 999 dives.]

Dive history is different than the dive profiles on the log. The history only keeps track of the total number of dives and total amount of time spent below surface. The logs, on the other hand, store the dive profile, but they have limited amount of memory to do so. The exact amount of dive profiles that can be stored on the device depend on sample interval and duration of the dives. Once the memory is full the oldest dives get overwritten with new dives. Thus we are only able to download the last 13, 30 or 199 dives.

If you have downloaded your dives to different dive logging software before they were overwritten, there is a high change that Subsurface can import these. However, if the logs are only on your dive computer, they cannot be salvaged after being over written by new dives.

[/expand]
[expand title="How do I download dives from my Shearwater Petrel 2 (or other Bluetooth dive computer) on Linux?"]

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.

<ol>
<li>Enable Bluetooth controller and pair your dive computer</li>
<li>Establish an RFCOMM connection</li>
<li>Download the dives with Subsurface</li>
</ol>

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.

Make sure you know how to put your dive computer into 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 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:
<pre><code style="font-size: 8pt;">sudo usermod -a -G dialout username</code></pre>
Log out and log in for the change to take effect.

<em>Enabling the Bluetooth controller and pairing your dive computer</em>
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.

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
<pre><code style="font-size: 8pt;">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</code></pre>
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:
<pre><code style="font-size: 8pt;">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</code></pre>
Check that the status now includes 'UP', 'RUNNING' AND 'AUTH'

If there are multiple controllers running, it's easiest if you turn off the controller(s) you don't plan to use. E.g.
<pre><code style="font-size: 8pt;">sudo hciconfig hci1 down</code></pre>
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.
<pre><code style="font-size: 8pt;">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</code></pre>
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 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.
<pre><code style="font-size: 8pt;">hcitool -i hci0 scanning
Scanning ...
        00:11:22:33:44:55       Petrel
bluez-simple-agent hci0 00:11:22:33:44:55</code></pre>
Once you have paired your dive computer, you are ready to set up the RFCOMM connection

<em>Establishing the RFCOMM connection</em>
The command to establish an RFCOMM connection is:
<pre><code style="font-size: 8pt;">sudo rfcomm -i &lt;controller&gt; connect &lt;dev&gt; &lt;bdaddr&gt; [channel]</code></pre>
&lt;controller&gt; is the Bluetooth controller, hci0
&lt;dev&gt; is the RFCOMM device file, rfcomm0
&lt;bdaddr&gt; 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 you omit it, channel 1 will be assumed.  Based on a limited number of user reports, the channel for different dive computers is probably:
<ul>
<li>Shearwater Petrel 2: channel 5
<li>Shearwater Petrel 1: channel 1
<li>OSTC Sport: Channel 1
</ul>
E.g. to connect a Shearwater Petrel 2, set the dive computer to upload mode and enter:
<pre><code style="font-size: 8pt;">sudo rfcomm -i hci0 connect rfcomm0 00:11:22:33:44:55 5
(enter password when prompted)
Connected /dev/rfcomm0 to 00:11:22:33:44:55 on channel 5
Press CTRL-C for hangup</code></pre>
To connect a Shearwater Petrel 1 or OSTC Sport, set the dive computer to upload mode and enter:
<pre><code style="font-size: 8pt;">sudo rfcomm -i hci0 connect rfcomm0 00:11:22:33:44:55
(enter password when prompted)
Connected /dev/rfcomm0 to 00:11:22:33:44:55 on channel 1
Press CTRL-C for hangup</code></pre>
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.
<pre><code style="font-size: 8pt;">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</code></pre>
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 subsurface@subsurface-divelog.org.

<em>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'.

If you get a permissions error, you probably need to add yourself to the dialout group, logout and login again.

[/expand]
[expand title="How do I fix permission errors when trying to download from my Atomics Aquatics Cobalt under Linux?"]

Sadly this is a somewhat difficult process on some versions of Linux. By default new devices are sometimes given permissions that prevent a regular user from accessing them. If you get a permission error when trying to download from a Cobalt or Cobalt 2 under Linux, please try these steps.

This should work on most Linux flavors. We'd appreciate feedback if this doesn't work for you. Open a terminal window and cut and paste the following command. It may ask you to enter your password in order to allow access as super user (which is required to set up the udev rule that changes the device permissions as you plug in your Cobalt).

<pre><code style="font-size: 8pt;">(MYGRP=$(id | sed "s/^.*gid=.*(\(.*\)) .*$/\1/") ; \
echo -n 'SUBSYSTEM=="usb", ATTR{idVendor}=="0471", ATTR{idProduct}=="0888", MODE="0660", GROUP="' ; \
echo -n $MYGRP ; echo '"') | sudo tee /etc/udev/rules.d/99-cobalt.rules </code></pre>

If you disconnect and reconnect your Cobalt it should now get the correct access permissions.

[/expand]