FAQ

General

What operating systems does Subsurface support?

Subsurface runs on Windows (32 and 64bit, Windows 7 and newer), MacOS (Intel, 10.7 and newer) and many flavors of Linux. Mobile versions of Subsurface are available for Android and iOS allow a portable platform for viewing your dive log and performing minor edits.

We provide Linux packages for Ubuntu, Linux Mint, Debian, openSUSE and Fedora. Details on where to find Subsurface for your OS are on our Downloads page. As of version 4.6, Windows XP is not supported anymore.

Subsurface-mobile is available on Google Play and the iTunes App Store.

Why Should I Use Subsurface?
 
Subsurface profiles recreational scuba divers, tech divers, and diving professionals with an easy to use interface for planning and logging and organizing dives. Dives can be entered manually, via spreadsheets, directly from some other dive logging software, and most importantly from many dive computers. What if you change dive computers? This is no problem with Subsurface as it is not tied to a specific dive computer manufacturer. Tech divers will appreciate the dive planner which allows you to plan using VPM-B or Bühlmann ZH-L16. Testing bailout gases, comparing different gas mixes and gradient factors, and finally printing the plan is made easy. Subsurface is free and available on multiple platforms making it the perfect software for a wide range of scuba divers.

Installation

How do I install Subsurface on Windows?

Download the installer 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 Start Menu Folder where a shortcut to call Subsurface and an entry to uninstall Subsurface will be installed.

How do I install Subsurface on MacOS?

Download the installer DMG and open it. Drag the Subsurface icon on to the Applications icon.

How do I install Subsurface on Ubuntu?

Simply add the following PPA to your system:

ppa:subsurface/subsurface
How do I install Subsurface on Debian?

We currently only support Debian Jessie; you need to add the Ubuntu repository:

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

Now you can install Subsurface from that repository:

sudo apt-get install subsurface

Make sure you are getting a current version with all its Qt5 dependencies.

How do I install Subsurface on openSUSE?

Go to our build service project page and follow the simple instructions there — it’s as easy as two clicks.

How do I install Subsurface-mobile on my phone / tablet?

For Android and iOS you can simply install the Subsurface-mobile apps that are available in the respective app stores. Enable cloud storage in Subsurface from your PC and store your dive information in the Subsurface cloud. The dives will now be available on your mobile device as well. Subsurface-mobile does not support all the features of the desktop version Subsurface. For example dive planning is not available in Subsurface-mobile. Dives cannot be downloaded directly from dive computers into Subsurface-mobile, however dives can be manually added to your dive log.

From all other devices (including tablets and phones with OSs that we don’t support with Subsurface-mobile), you can open our cloud website and log in with the same email address / password. This allows you to access your dive data from any device with a web browser.

Usage

How do I know I have the latest version of Subsurface?

From the Help menu, select “Check for updates”.
Also refer to the News section on the Subsurface website for announcements about new releases.

How can I import my dives into Subsurface?

There are multiple ways to import into Subsurface. From the User Manual,

For manually logged dives:

To add a dive to a dive log, select Log → Add Dive from the Main Menu. The program then shows three panels on which to enter information for a dive: two tabs in the Info panel (Notes and Equipment), as well as the Dive Profile panel that displays a graphical profile of each dive.

To import from a dive computer:

A dive computer can be hooked up to the user’s PC using these steps:

  1. The interface cable should be connected to a free USB port (or the Infra-red or Bluetooth connection set up as described later in this manual).
  2. The dive computer should be placed into PC Communication mode. (Refer to the manual of the specific dive computer).
  3. In Subsurface, from the Main Menu, select Import → Import From Dive Computer.

Then, follow the prompts to select your particular dive computer. More detailed information can be found in the User Manual.

There is also the possiblity of adding dives from other software or websites. See the User Manual for the most up to date information on this – it can be found in Section 5.3.

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

How can I post my dives on the web?

Currently Subsurface integrates with two different online logbooks: divelogs.de and DiveShare. You can export dives to either of those two services from the File➝Export menu.

How do I use the companion apps for recording dive sites?

There are companion apps available for both Android and IOS which help the user record dive site locations. You can find them in the respective app 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 after 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 not add dives to your dive list. The dive needs to exist before GPS data is added to it. The companion apps are different than the Subsurface-mobile apps. The Subsurface-mobile apps are for viewing your dive log. The companion apps are solely for managing and recording dive locations. Many users will choose to have both the Subsurface companion app and the Subsurface-mobile app on their phone/tablet.

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.

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 (BlueTooth) and the general use case.

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.

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.

We are considering more complete multi user support for a future version. If you would like to provide input into the features for that, please contact us through the user forum or our developer mailing list.

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.

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.

How do I download dives from my Bluetooth dive computer (e.g., Shearwater, OSTC)?

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 Subsurface User Manual.

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.

How do I download dives from my Bluetooth LowEnergy, BLE, Bluetooth Smart dive computer (e.g., Shearwater Perdix AI, Shearwater Perdix (latest models), Suunto EON Steel)?

At this point (September 2017, Subsurface 4.6.4) the release versions of Subsurface and Subsurface-mobile don’t support connecting to dive computers over BLE. We are actively working on this support and have test binaries for Mac (Subsurface) and Android (Subsurface-mobile) that support a hand full of BLE based dive computers. Windows support is a lot further away. While we have plans for a 4.7 version of Subsurface which includes this support, we have no expected release time frame, yet.

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

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

What to do when authentication to cloud storage fails?

If you have configured your correct user credentials to Subsurface and cloud authentication still fails, try to change the password on Subsurface preferences. There has been a change in the cloud service that can cause an error on sync, but password change with correct credentials fixes the issue.

If your credentials are still not working or there is something else wrong, contact Dirk to sort it out.

When printing, line breaks in the notes are shown as <br />

This is likely caused by an earlier install of Subsurface on the same computer. For some reason Subsurface may have decided to store a personal copy of the print template and is using that instead of the one shipped with Subsurface.

If you intentionally made specific changes to the templates, re-edit the templates and ensure that dive.notes is referenced as dive.notes|secure).

For most users who never edited the templates, however, the easiest fix is to just delete the local copies.

For macOS,In a terminal window execute
mv ~/Library/Application Support/Subsurface/printing_templates
~/Library/Application Support/Subsurface/printing_templates.bak

For Linux,
mv ~/.subsurface/printing_templates
~/.subsurface/printing_templates.bak

Operating System Specific Questions

Linux

The shortcut keys don't work on Ubuntu

Please uninstall appmenu-qt5 and the shortcuts will work.

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

(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 

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

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

echo 'SUBSYSTEM=="usb",ATTR{idVendor}=="1493",ATTR{idProduct}=="0030", MODE="0666"' |
sudo tee /etc/udev/rules.d/99-suunto.rules 

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

macOS

Why is my IRDA (infrared) 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.

Mobile

What is the difference between the Subsurface-mobile and Subsurface apps?

There are two versions of Subsurface in the app store. The Subsurface-mobile app is the port of the desktop application to Android and iOS. It allows you to connect to the Subsurface Cloud and view dives, or manually add dives. The Subsurface app is a companion app, designed to allow the logging of GPS data while on your dive. It is now unnecessary for use on Android (and no longer supported), as that functionality has been added to the Subsurface-mobile app. On iOS, the Subsurface companion app is still necessary to log GPS data.

Subsurface-mobile crashes when starting on my Samsung Android device

One of the underlying libraries that we use contains a known bug that appears to cause crashes in a certain scenario when “Accessibility” services like LastPass or Bixby Remapper are installed. There is currently no way for us to fix this in Subsurface-mobile, but an easy workaround is to temporarily disable such helper services when running Subsurface-mobile.

Windows

Is there a virus in the Subsurface installer?

If you get a warning message or if Subsurface is blocked by your anti virus (AV) 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 Anti-Virus 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.