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 Bluetooth dive computer (e.g. Shearwater, OSTC) on Linux?"]

Downloading 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="https://subsurface-divelog.org/documentation/subsurface-4-user-manual/">Subsurface User Manual</a>.

Previous 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.

[/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]
[expand title="How do I fix permission errors when trying to download from my Suunto EON Steel under 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 an EON Steel 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 EON Steel).

<pre><code style="font-size: 8pt;">echo 'SUBSYSTEM=="usb",ATTR{idVendor}=="1493",ATTR{idProduct}=="0030", MODE="0666"' |
sudo tee /etc/udev/rules.d/99-cobalt.rules </code></pre>

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

[/expand]
[expand title="Why is my IRDA based dive computer not working on a MAC?"]

Subsurface on the Mac does not currently support IRDA based dive computers. This is an issue of missing support libraries for us to use - other dive log software may have implemented their own IRDA stack on the Mac, we have not. Subsurface on Windows and Linux does support IRDA based dive computers just fine.

[/expand]