diff --git a/Documentation/user-manual.html.git b/Documentation/user-manual.html.git index 133509f2d..daff41257 100644 --- a/Documentation/user-manual.html.git +++ b/Documentation/user-manual.html.git @@ -410,7 +410,7 @@ asciidoc.install(3);

USER MANUAL

Manual authors: Willem Ferguson, Jacco van Koll, Dirk Hohndel, Reinout Hoornweg, Linus Torvalds, Miika Turkia, Amit Chaudhuri, Jan Schubert, Salvador Cuñat

-

Version 4.1, April 2014

+

Version 4.1, May 2014

Welcome as a user of Subsurface, an advanced dive logging programme with extensive infrastructure to describe, organise, interpret and print scuba and free dives. Subsurface offers many advantages above other similar @@ -465,19 +465,37 @@ Divers

The Subsurface window is usually divided into four panels with a Main Menu (File Import Log View Filter Help) at the top of the window (for Windows and Linux) or the top of the screen (for Mac and Ubuntu Unity). The four panels are:

-

1) The Dive List to the bottom left containing a list of all the dives in the +

    +
  1. +

    +The Dive List to the bottom left containing a list of all the dives in the user’s dive log. A dive can be selected and highlighted on the dive list by clicking on it. In most situations the up/down keys can be used to switch -between dives. The Dive List is an important tool for manipulating a dive log.

-

2) The Dive Map to the bottom right, showing the user’s dive sites on a world +between dives. The Dive List is an important tool for manipulating a dive log. +

+ +
  • +

    +The Dive Map to the bottom right, showing the user’s dive sites on a world map -and centred on the site of the last dive selected in the Dive List.

    • -

    3) The Dive Info to the top left, giving more detailed information on the +and centred on the site of the last dive selected in the Dive List. +

    + +
  • +

    +The Dive Info to the top left, giving more detailed information on the dive selected in the Dive List, including some statistics for the selected dive or for all -highlighted dive(s).

    • -

    4) The Dive Profile to the top right, showing a graphical dive profile of the -selected dive in the Dive List.

    +highlighted dive(s). +

    + +
  • +

    +The Dive Profile to the top right, showing a graphical dive profile of the +selected dive in the Dive List. +

    +
    • +

    The dividers can be dragged between panels in order to change the size of any of the panels. Subsurface remembers the position of the dividers, so the next time Subsurface starts it uses the positions of the dividers when the program @@ -871,13 +889,16 @@ involves setting up the communications port (or mount point) of the computer with Subsurface that communicates with the dive computer. In order to set up this communication, one needs to find the appropriate information to instruct -Subsurface where and how to import the dive information. Appendix A provides -the technical information to help the user achieving this for different +Subsurface where and how to import the dive information. +Appendix A +provides the technical information to help the user achieving this for different operating -systems and Appendix B has dive computer specific information.

    +systems and +Appendix B +has dive computer specific information.

    After this, the dive computer can be hooked up to the user’s PC, which can be achieved by following these steps:

    -
    +
    FIGURE: Download dialogue 1 @@ -926,9 +947,11 @@ the dive computer must be selected, e.g. D4 (Suunto), Veo200 (Oceanic), or Puck

    The Device or Mount Point drop-down list contains the USB or Bluetooth port name that Subsurface needs in order to communicate with the dive computer. -The appropriate port name must be selected. Consult Appendix A -and Appendix B for -technical details on how to find the appropriate port information for a +The appropriate port name must be selected. Consult +Appendix A +and +Appendix B +for technical details on how to find the appropriate port information for a particular dive computer and, in some cases, how to do the correct settings to the operating system of the computer on which Subsurface is running. @@ -1003,18 +1026,44 @@ message will be shown, similar to this text: "Unable to open /dev/ttyUSB0 Mares Important -Check the following: 1) Is the dive computer still in PC-communication or -Upload mode? -2) Is the battery of the dive computer fully charged? If not then the battery -must be charged or replaced. -3) Is the connecting cable faulty? Does the cable work perfectly using other -software? Has it worked before, or is this the first time the cable is being used? -4) Consult Appendix A and make sure that the correct Mount Point -was specified (see above). -5) On Unix-like operating systems, does the user have write permission to the -USB port? If not, consult Appendix A. +Check the following:

    +

    If the Subsurface computer does not recognise the USB adaptor by showing an appropriate device name next to the Mount Point, then there is a possibility that the cable or USB adaptor is faulty. A faulty cable is the most @@ -1351,7 +1400,7 @@ multi-platform applications, these dive logs cannot be directly imported into Subsurface. Mares dive logs need to be imported using a three-step process, using www.divelogs.de as a mechanism to extract the dive log information.

    -
    +

    3.3.3. Importing dives from divelogs.de

    @@ -1555,18 +1604,19 @@ appear in the Dive List area of Subsurface.

    -

    3.4. Importing GPS coordinates with the Subsurface Companion App for mobile phones

    -

    If the user has an Android device with GPS, the coordinates for the diving -location can be obtained and automatically passed to the Subsurface -divelog. This takes place when the Companion App stores the dive locations on +

    3.4. Importing GPS coordinates with the Subsurface Companion App for mobile phones

    +

    Using the Subsurface Companion App on an Android device with a GPS, the coordinates +for the diving +location can be automatically passed to the Subsurface +divelog. The Companion App stores the dive locations on a dedicated Internet-based file server. Subsurface, in turn, can collect the localities from the file server.

    -

    To do this, one needs to:

    +

    To do this:

    • -Register on the Subsurface companion web page. -A confirmation mail with instructions and a personal DIVERID will be send together with +Register on the Subsurface companion web page. +A confirmation email with instructions and a personal DIVERID will be send together with a long number that gives access to the file server and Companion App capabilities.

      • @@ -1587,7 +1637,7 @@ from

    • Create a new account. Equivalent to registering in Subsurface companion -page. +page using an Internet browser.

    • @@ -1606,13 +1656,13 @@ option (see below).

    Now one is ready to get a dive position and send it to the server. The Android display will look like the left hand image (A) below, but without any dive.

    -

    Touch the "+" icon on the top right to add a new dive site. Users will be -prompted for a place name (or asked to activate the GPS if it is turned off). +

    Touch the "+" icon on the top right to add a new dive site, resulting in a prompt +for a place name (or a request to activate the GPS if it is turned off). The main screen shows a list of dive locations, each with a name, date and -time. Some dives may have an arrow-up icon on the selection box to the left (see +time. Some locations may have an arrow-up icon on the selection box to the left (see image B in the middle, below) indicating that they require upload to the server.

    -

    There are several ways to send dives to the server; the easiest is by simply -selecting the dive. See middle image below (B):

    +

    There are several ways to send locationd to the server; the easiest is by simply +selecting the location. See middle image below (B):

    FIGURE: Screen shots (A-C) of companion app @@ -1624,14 +1674,32 @@ selecting the dive. See middle image below (B):

    Important -Users must be careful, as the trash icon on the right means exactly what it is supposed to mean, +Users must be careful, as the trash icon on the right means exactly what it should mean: it deletes the dive location(s).
    -

    The new dive points are now stored on the server and can be downloaded to the +

    New dive locations are now stored on the server and can be downloaded to the Subsurface dive log whenever users upload or add dives to Subsurface. -After a dive trip using the Companion app, all dive locations are ready to be +After a dive trip using the Companion App, all dive locations are ready to be saved on a Subsurface dive log (see below).

    +

    When you click on a dive (not selecting the check button as shown in the images above), the +name given to it, date/time and GPS coordinates will be shown, with two options:

    +
      +
    • +

      +Edit: Change the text name of the dive location. +

      +
      • +
    • +

      +Maps: Display a map showing the dive location (you’ll be prompted to +choose which helper app use from your installed apps). Currently this feature is +non fully functional, but is under active development. +

      +
      • +
    +

    After editing and saving a dive location, one needs to upload it to the web +service, as explained above.

    Settings on the Companion app

    Selecting the Settings menu option results in the right hand image above (C).

    @@ -1646,8 +1714,8 @@ saved on a Subsurface dive log (see below).

  • -User ID. Obtained by registering as indicated above. The easiest way to -obtain it is simply to copy and paste from the confirmation mail but, of +User ID. The DIVERID obtained by registering as described above. The easiest way to +obtain it is simply to copy and paste from the confirmation email but, of course, users can also type this information.

    • @@ -1658,14 +1726,14 @@ course, users can also type this information.

    • -Synchronize on startup. If selected, dives in the Android device and those -on the web service will synchronize each time the app is started. +Synchronize on startup. If selected, dive locations in the Android device and those +on the web service synchronize each time the app is started.

    • -Upload new dives. If selected, each time the user adds a dive location it will -automatically be sent to the server. +Upload new dives. If selected, each time the user adds a dive location it is +automatically sent to the server.

    @@ -1673,23 +1741,23 @@ automatically be sent to the server.
    Background service

    Instead of entering a unique dive location, users can leave the service running -in the background of their device, thus allowing the continuous collection of GPS locations.

    +in the background of their Android device, allowing the continuous collection of GPS locations.

    The settings below define the behaviour of the service:

    • -Min duration. In minutes. The app will try to get a position each X minutes -until it’s stopped by the user. +Min duration. In minutes. The app will try to get a location every X minutes +until stopped by the user.

    • -Min distance. In meters. Minimum distance between two position fixes. +Min distance. In meters. Minimum distance between two locations.

    • -Name template. The name the app will use when saving the position fixes. +Name template. The name the app will use when saving the locations.

    @@ -1698,13 +1766,14 @@ until it’s stopped by the user. Tip -How does the background service work? Assuming that the user set 5 minutes and 50 -meters in the settings above, the app will start by taking a fix at the current location, -followed by another one -at every 5 minutes. If this 2nd (3rd, 4th …) location is within a radius of 50 -meters from the previous one, then this new fix is not saved. If the user is not moving, -only one fix is saved, but if the user is moving, then a trace of the journey is obtained, -by saving each new position at every 5 minutes. +How does the background service work? Assuming the user sets 5 minutes and 50 +meters in the settings above, the app will start by recording a location at the current +location, followed by another one at every 5 minutes or every time one moves 50m +from previous location. +If subsequent locations are within a radius of 50 meters from the previous one, +a new location is not saved. If the user is not moving, only one location is saved, +but if the user is moving, a trace of the route is obtained by saving a +location every 50 meters.
    @@ -1724,26 +1793,26 @@ Subsurface mailing list.

  • -Version. Displays the current version of the companion app. +Version. Displays the current version of the Companion App.

    • Search
    -

    Here one can search one’s saved dive locations by the name or by date and hour.

    +

    Search the saved dive locations by name or by date and time.

    Start service
    -

    Initiates the background service depending on the previously defined settings.

    +

    Initiates the background service following the previously defined settings.

    Disconnect
    -

    This is a badly named option. It disconnects the app from the server by +

    This is a badly named option that disconnects the app from the server by resetting the user ID in the app, showing the first screen where an account can be created, retrieve the ID for an existing account or use the users own ID. The disconnect option -is useful if a user’s Android device was used to download the dive positions +is useful if a user’s Android device was used to download the dive locations of another registered diver.

    @@ -1757,9 +1826,9 @@ of another registered diver.

    Subsurface before obtaining the GPS coordinates from the server. The download dialog can be reached via Ctrl+G or from the Subsurface Main Menu Import → Import GPS data from Subsurface Service, resulting in the image on the -left (A), below. On first use the DIVERID text box will be blank. Users must provide their -DIVERID and then select the Download button to initiate the download process. When this -is completed, users will see the screen on the right (B), below:

    +left (A), below. On first use the DIVERID text box is blank. Provide a +DIVERID, then select the Download button to initiate the download process, after +which the screen on the right (B) below appears:

    FIGURE: Downloading Companion app GPS data @@ -1768,24 +1837,49 @@ is completed, users will see the screen on the right (B), below

    Note that the Apply button is now active. By clicking on it, users can update the locations of the newly entered or uploaded dives in Subsurface which applies the coordinates and names entered on the app for all the new dives that match the -date-times of the uploaded GPS localities.

    +date-times of the uploaded GPS localities. If one has entered the name of the dive +location in Subsurface before downloading the GPS coordinates, this name will take +precedence over downloaded one.

    +

    Since Subsurface matches GPS locations from the Android device and dive information from the +dive computer based on date-time data, automatic assignment of GPS data to dives is dependent +on agreement of the date-time information between these two devices. Although Subsurface has +a wide range tolerance, it may be unable to identify the appropriate dive if there is +a large difference between the time in the dive computer and that of the Android device, +resulting in no updates.

    +

    Similar date-times may not always be possible and there may be many reasons for this (e.g. time zones), or +Subsurface may be unable to decide which is the correct position for a dive (e.g. on repetitive +dives while running background service there may be several locations that would be +included in the time range that fit not only the first dive, but one or more subsequent dives as well). +A workaround for this situation to manually edit the date-time of a dive in the Subsurface +Dive List before downloading the GPS data and then to change the date-time back again after +downloading GPS data.

    - +
    Note Features, issues and tips. Since Subsurface matches GPS locations from the -Android device and dive information from the dive computer based on date-time -data, automatic assignment of GPS data to dives is dependent on agreement of -date and time between these two devices. If there is a large difference between -the time in the dive computer and the time in the Android device, -Subsurface is unable to identify the dive matching a location and nothing -happens. Similar date-times may be not always be possible. A dirty hack is -manually editing the date-time of a dive in Subsurface’s Dive List before -downloading the GPS data and then to edit the date-time back again after -downloading GPS data.TIPS:
    +
    @@ -1827,7 +1921,7 @@ water temperature and surface air consumption (SAC).

    4.3. The Dive Profile

    -Typical dive profile +Typical dive profile

    Of all the panels in Subsurface, the Dive Profile contains the most detailed @@ -1937,9 +2031,16 @@ coding is not relative to some absolute values but relative to the average normalised air consumption during the dive. So areas that are red or orange indicate times of increased normalized air consumption while dark green reflects times -when the diver was using less gas than average. The colour coding is obviously -only possible when a tank sensor is connected and tank pressure readings during -the dive are available.

    +when the diver was using less gas than average.

    +
    + + + +
    +Note +Clicking on the heartrate button will allow the display of heart rate information +during the dive if the dive computer was attached to a heart rate sensor.
    +

    It is possible to zoom into the profile graph. This is done either by using the scroll wheel / scroll gesture of your mouse or trackpad. By default Subsurface always shows a profile area large enough for at least 30 minutes @@ -1966,8 +2067,11 @@ two red dots.

    The profile can also include the dive computer reported ceiling (more -precisely, the deepest deco stop that the dive computer calculated for each particular moment in time) as a red overlay on the dive profile. Ascent ceilings arise when a direct ascent to the surface increases -the risk of a diver suffering from decompression sickness (DCS) and it is necessary to either ascend +precisely, the deepest deco stop that the dive computer calculated for each +particular moment in time) as a red overlay on the dive profile. Ascent ceilings +arise when a direct ascent to the surface increases +the risk of a diver suffering from decompression sickness (DCS) and it is necessary +to either ascend slower or to perform decompression stop(s) before ascending to the surface. Not all dive computers record this information and make it available for download; for example all of the Suunto dive computers fail to make this very useful data @@ -1975,7 +2079,8 @@ available to divelog software. Subsurface also calculates ceilings inde shown as a green overlay on the dive profile. Because of the differences in algorithms used and amount of data available (and other factors taken into consideration at the time -of the calculation) it is unlikely that ceilings from dive computers and from Subsurface are the same, even if the same algorithm and gradient factors (see below) are used. +of the calculation) it is unlikely that ceilings from dive computers and from Subsurface +are the same, even if the same algorithm and gradient factors (see below) are used. It is also quite common that Subsurface calculates a ceiling for non-decompression dives when the dive computer stayed in non-deco mode during the whole dive (represented by the dark green section in the profile @@ -2003,7 +2108,8 @@ shown as a red area by checking Dive computer reported ceiling Note -If the Calculated ceiling button on the Profile Panel is clicked, then a ceiling, calculated by Subsurface, is shown in green if it exists for +If the Calculated ceiling button on the Profile Panel is clicked, then a ceiling, +calculated by Subsurface, is shown in green if it exists for a particular dive (A in figure below). This setting can be modified in two ways:

    @@ -3095,7 +3201,7 @@ already provides for communication using the IrDA protocol. However, the user additionally needs to load a driver for the IrDA interface with the dive computer. The easiest way is to load the irda-tools package from the Linux IrDA Project. -After the installation of the irda-tools, the root user can specify a device name +After the installation of the irda-tools, the root user can specify a device name from the console as follows: irattach irda0 @@ -3172,7 +3278,7 @@ the dialogue found by selecting Import from the Main Menu, then clickin can be found here. However, in some cases, a two-step process may be required:

    -
    +

    This appendix provides some information about approaches to export dive log data from foreign dive log software. The procedures below mostly apply to Linux and/or Windows.

    @@ -3202,7 +3308,7 @@ conventions to export dive log data.

    Divemanager 3 (DM3):

    -

    Backing up Suunto DM4:

    -
    +

    12.2. Exporting from Mares Dive Organiser V2.1

    @@ -3376,7 +3477,7 @@ of the dive data base is to export the information to another compatible format which can be imported into Subsurface.
    -
    +

    12.3. Exporting dives from DivingLog 5.0

    @@ -3415,7 +3516,7 @@ selecting File → Preferences → Units and Language by clicki button). Then do the following:
    -
    + @@ -3486,7 +3587,7 @@ you may stay in the water for a long time, but spend most of it at the surface.