1 Subsurface 1.2 User Manual
2 ==========================
3 Jacco van_Koll <jko@haringstad.com>
9 :website: http://subsurface.hohndel.org
11 Scope of this document is the usage of the program.
12 Please read the build manual for instructions how to build the
13 software and (if needed) its dependencies.
15 Audience: Fun Divers, Tec Divers, Professional Divers
22 Subsurface was started because of a lack of viable dive log software
23 on Linux. It turns out that the resulting software was easily ported
24 to Windows and Mac, but it clearly is a native Linux program first.
25 Right now, the program is under development and from version 1.1 it is
26 already very usable for divers with supported dive-computers.
28 In this manual the Suunto Viper will be used for all examples.
35 Before you are able to import information from your divecomputer into
36 Subsurface, you need some preparation. Do you have the following:
38 1. Your Divecomputer - Compatible with libdivecomputer (see list in <<AppendixA,Appendix A>>)
39 2. Communication interface - Cable to connect your divecomputer to your PC/Laptop/Netbook
40 3. Working installation of Subsurface
41 4. If needed, the manual of your divecomputer
45 Start using the program
46 -----------------------
48 When you start the program for the first time, it shows no information
49 at all. This is because the program does not automatically load the
50 already available dive-log files.
52 There is a menu, containing 'File', 'Log', 'Filter' and Help.
54 The screen is devided in 3 area's:
56 - Area with 3 tabs: Dive Notes, Equipment, Info & Stats
57 - Area next to the 3 tabs which will contain the dive profile
58 - Area with the dives (usually called dive list) which can be sorted by number, date, etc.
62 Import new dives from your divecomputer
63 ---------------------------------------
65 Before you start fiddeling around with your divecomputer, note that
66 there are divecomputers that consume more power when they are in the
67 PC-Communication mode. This could drain your battery. Therefor, ensure
68 if your computer is recharging when connecting to the USB port. The
69 Suunto Viper does not recharge trough the USB connection. Please
70 consult the manual of your divecomputer if you are unsure if it will
71 be recharged when connected to the USB port.
73 Now it is time to hook up your divecomputer to your Linux system:
75 - Make sure that your OS has the required drivers installed
77 * On Linux this means you need to have the correct kernel
78 module loaded. Most distributions will do this automatically
81 * On Windows, the OS should offer to download the correct
82 driver when you connect to the USB port.
84 * On a Mac you at times have to manually hunt for the correct
85 driver. For example the correct driver for the Mares Puck
86 devices can be found as Mac_OSX_VCP_Driver.zip at
87 http://www.silabs.com/support/pages/support.aspx?ProductFamily=USB+Bridges
89 - Connect your interface cable to a free USB port
91 - Put your divecomputer into PC Communication mode. (For Suunto Viper, press Mode - 1 Memory - 3 TR-PC)
92 (You should consult the manual of your specific divecomputer for your brand and type)
94 - Go in Subsurface to 'File - Import'
95 * Within the popup, under Dive computer, choose your brand and type. Here we choose Suunto Vyper.
96 * Change the devicename under which your interface is connected.
97 ** On Linux, default is /dev/ttyUSB0
98 ** On Windows, default is COM3
99 ** On Mac, default is ... specific to the dive computer
101 * Click the 'OK' button.
103 - Now watch how your data is retrieved from your divecomputer!
104 Depending on your type of computer and/or number of dives, this
105 could take some time. Please be patient.
109 Viewing and completing your logs
110 --------------------------------
112 When all data from your divecomputer is transferred, you will see a
113 listing of your dives in Area 3.
117 On Sunday Oct 23, 2011 you made a dive.
118 In the log line of this dive, you see the following information:
123 Sun, Oct 23, 2011 10:50 Date and time of your dive
125 Your rating (none at this time)
127 12.8 Your maximum depth in meters
129 31:20 Your dive-time in minutes and seconds
131 13.0 Lowest water temperature during your dive
133 Your used cylinder (none at this time)
135 air What type of mixture
137 SAC (none at this time)
139 Where you performed your dive (empty)
141 As you can see, some information is already there because it is
142 retrieved from your divecomputer. Some information is waiting for
143 you to be added. By double clicking on this dive, you can view and
151 When you double click on the dive log line, the editor window
152 opens. Now you can add information that is missing. Let start with
153 completing the example:
155 You double clicked on dive #12, as described in 5. Viewing and
156 completing your logs. The Dive Info window pops up and you will see
159 - Location: An input where you can enter your new location, or you can choose with the pull-down previous locations
160 - Dive Master: An input where you can enter the name of your Dive Master, or you can choose with the pull-down a previous name
161 - Buddy: An input where you can enter het name of you Buddy, or you can choose with the pull-down a previous name
162 - Rating: A pull-down where you can rate your dive.
163 - Notes: A free input where you can enter information about your dive. What you've seen, etc.
165 In this example we use the following information:
167 - Location: Oostvoornse Meer
168 - Dive Master: S. de Vries
171 - Notes: First dive here. Good visibility. Did see the concrete poles, some crab and fish. Very nice and easy dive.
172 Made movie with 'headcam'.
174 Now don't press ok yet!
176 [[S_EditEquipmentInfo]]
180 You also want to edit your Cylinder information. And in the
181 <<S_EditDiveInfo, previous chapter>>, this was not edited. There is
182 still another item to edit in the Dive Info screen:
184 - Cylinder: A double-click fieldset. Here you can edit your Cylinder information
186 So, when you double click on the cylinder info, you get another
187 popup. This popup gives you the following:
189 - Cylinder: Pull-down where you can choose your Cylinder, or add your own
190 - Size: The volume if not 'filled'
191 - Pressure: The maximum pressure of this Cylinder
193 * Start Pressure: What was the pressure starting the dive
194 * End Pressure: What was the pressure ending the dive
195 * Nitrox: What was the percentage of blend
197 Now we are going to enter the data:
203 Now tick the option for Start & End pressure
205 - Start Pressure: 180
209 Now your dive information for this dive is complete. You can now press
210 ok in the Dive Info screen and view the results.
212 [[S_AddingEquipment]]
213 Adding equipment info
214 ---------------------
216 In Area with the 3 tabs there is the tab Equipment. With this tab, you
217 can add Cylinders. We are going to add an additional Cylinder:
219 - In the main screen, click on the Equipment tab. This shows your
220 Cylinder you added in 7.
222 - Now press the Add button and the Cylinder popup comes back.
224 - Just like you added your Cylinder information in 7. Edit equipment
225 info, you add your cylinder information for the second Cylinder.
226 Fill in all the information about this Cylinder and press OK.
232 After adding all the information, you can use the tab Info &
233 Stats. This tab will provide you with all the (statistical and
234 calculated) information regarding your dive.
236 The information contains:
240 ** Date: Date and time of your dive
241 ** Dive Time: Duration of your dive
242 ** Surf Intv: Interval between previous dive and this dive
243 ** Max Depth: Maximum depth of this dive
244 ** Avg Depth: The average depth of this dive
245 ** Water Temp: Lowest temperature of the water
246 ** SAC: The amount of Surface Air Consumption liters per minute
247 ** OTU: The Oxygen Toxicity Units of this dive
248 ** O2/He: Amount of Oxygen/Helium
249 ** Gas Used: The total volume of gas used during this dive
253 ** Total time: Total time of all your dives together, calculated
254 ** Avg Time: The average divetime of your dives, calculated
255 ** Max Depth: The maximum depth of all your dives
256 ** Avg Depth: The average depth of all your dives, calculated
257 ** Max SAC: Highest of Surface Air Consumption of all your dives
258 ** Min SAC: Lowest of Surface Air Consumption of all your dives
259 ** Avg SAC: Average Surface Air Consuption of all your dives, calculated
261 [[S_SettingUpPreferences]]
262 Setting up preferences
263 ----------------------
265 Subsurface has the ability to modify the preferences you want. By
266 using menu 'File - Preferences' you will be presented a popup with the
267 'Units'. You are free to choose what is your preference, with other
268 words, use Metric or Imperial.
270 You can set the following options:
271 - Depth: Your diving depth in Meters or Feet
272 - Pressure: The pressure of your tank(s) in Bar/Ato or PSI (Pressure Square Inch)
273 - Volume: The volume of your tank(s) in Liter or CuFt (Cubic Feet) (At sea-level pressure)
274 - Temperature: The temperature of the water in Celcius or Fahrenheit
276 In the main screen, you did see in Area 3, some information. In the
277 Columns options, you can enable/disable options you would like to show
279 - Show Temp: Shows the temperature of your dive
280 - Show Cyl: Shows the cylinder(s) of your dive
281 - Show O2%: Shows the O2% of your dive
282 - Show SAC: Shows the SAC of your dive (Surface Air Consumption)
283 - Show OTU: Shows the OTU of your dive (Oxygen Toxicity Units)
285 And, you can change the font usage of the program.
287 I will give an example here:
289 I am a diver in The Netherlands, using the Metric System. Therefor, I
290 go to the menu File, choose Preferences here. In the Units section, I
296 - Temperature: Celcius
298 I would like to see the:
305 As a beginning diver, I don't need to track my OTUs. So I leave this
308 Clicking OK on the dialog stores these settings.
310 [[S_HowFindDeviceName]]
311 How to find the Device Name
312 ---------------------------
314 When you connect your divecomputer by using an USB connector, most of the
315 time, the default of '/dev/ttyUSB0' should work. But if you have other
316 Serial to USB devices, this can be different because '/dev/ttyUSB0' is
319 One of the ways to find out what your dive name is:
321 - Disconnect your usb cable of your dive computer
323 - Type the command: 'dmesg' and press enter
324 - Plug in your usb cable of your divecomputer
325 - Type the command: 'dmesg' and press enter
327 Within your terminal you should see a message similair to this one:
329 usb 2-1.1: new full speed USB device number 14 using ehci_hcd
330 usbcore: registered new interface driver usbserial
331 USB Serial support registered for generic
332 usbcore: registered new interface driver usbserial_generic
333 usbserial: USB Serial Driver core
334 USB Serial support registered for FTDI USB Serial Device
335 ftdi_sio 2-1.1:1.0: FTDI USB Serial Device converter detected
336 usb 2-1.1: Detected FT232BM
337 usb 2-1.1: Number of endpoints 2
338 usb 2-1.1: Endpoint 1 MaxPacketSize 64
339 usb 2-1.1: Endpoint 2 MaxPacketSize 64
340 usb 2-1.1: Setting MaxPacketSize 64
341 usb 2-1.1: FTDI USB Serial Device converter now attached to ttyUSB3
342 usbcore: registered new interface driver ftdi_sio
343 ftdi_sio: v1.6.0:USB FTDI Serial Converters Driver
345 You see that in the third line from the bottom, the usb adapter is
346 detected and is connected to 'ttyUSB3'. Now you use this information in
347 the import settings as '/dev/ttyUSB3'. Your divecomputer interface is
348 connected and you should be able to import your dives.
350 [[S_ImportingDivesJDivelog]]
351 Importing dives from JDivelog
352 -----------------------------
354 Maybe you have been using JDivelog and you have a lot of dives logged in
355 this program. You don't have to type all information by hand into
356 Subsurface, because you can import your divelogs from JDivelog.
358 JDivelog stores its information into files with the extention of .jlb.
359 These .jlb contain all the information that has been stored, except your
360 images in xml format.
362 By using the menu 'File - Import' you get the popup, like described in
363 <<S_ImportNewDives, chapter 4>>, Importing new dives. Within this
364 popup there is the option to import existing files which are already
365 on your computer. To import your JDivelog file(s) do the following:
367 - Open 'File - Import' on the menu
368 - Use the file locator under XML file name
369 - Browse your directories to the location where your *.jlb file is
370 - Select your existing *.jlb file and click 'open'
371 - Click the OK button in the popup
373 After a few moments, you see your existing logs in Subsurface. Now you can
374 edit your dives like explained in <<S_EditDiveInfo, chapter 6>>.
376 Information that is imported from JDivelog into the location field:
378 - Extended dive location information
380 Information that is merged into the location or notes field:
382 - Used amount of weight
384 - Used type of gloves
388 Alternatively, you can start subsurface with the --import comand line
389 which will have the same effect:
391 subsurface MyDives.xml --import JDivelogDives.jlb
393 will open your divelog (assuming that's called MyDives.xml) and then
394 import the dives from JdivelogDives.jlb. You can now save the combined
395 divelog back as MyDives.xml.
397 Subsurface will similarly import xml exports from DivingLog as well as
400 When importing dives subsurface tries to detect multiple records for
401 the same dive and merges the information as best as it can. So as long
402 as there are no time zone issues (or other reasons that would cause the
403 beginning time of the dives to be substantially different) subsurface
404 will not create duplicate entries.
406 [[S_ImportingDivesSuunto]]
407 Importing dives from Suunto Divemanager 3.*
408 -------------------------------------------
410 Before you can start importing dives from Suunto Divemanager, you first
411 have to export the dives you want to import. Subsurface does not import
412 directly from the Suunto Divemanager log files. The following procedures
413 unpacking instructions for Linux and Windows.
415 Export from Suunto Divemanager
416 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
418 - Start Suunto Divemanager and login with the name containing the logs
419 - Do not start the import wizard to import dives from your computer.
420 - In the navigation tree on the left side of the program-window, select your dives.
421 - Within the list of dives, select the dives you would like to import later:
422 * To select certain dives: hold ctrl and point & click the dive
423 * To select all dives: Select the first dive, hold down shift and select the last dive
424 - With the dives marked, use the program menu 'File - Export'
425 - The export popup will show
426 - Within this popup, there is one field called Export Path.
427 * Click the button browse next to the field Export Path
428 ** A file-manager like window pops up
429 ** Navigate to the directory where you want to store the Divelog.SDE file
430 ** Optional change the name of the file you want to save
432 * You are back in the Export popup. Press the button 'Export'
433 - Your dives are now exported to the file Divelogs.SDE.
435 Unpacking the Divelogs.SDE on Windows
436 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
438 Renaming your file to a .zip:
440 - Use the filemanager (explorer) and navigate to your Divelogs.SDE file
441 - Right click on the Divelogs.SDE file and choose 'Rename'
442 * Change the name into Divelogs.SDE.zip
443 * Press enter when done. A warning popup shows:
445 The file could be unusable when changing the extension. Are you sure:
448 * Your filemanager will show now the filename Divelogs.SDE.zip
450 When you double click your Divelogs.SDE.zip file, your preferred archiving
451 tool will start and show you the list of xml files that are in the zip
452 archive. Select all the xml files and extract them to a place where you
453 can find them later in the process.
455 Unpacking the Divelogs.SDE on Linux
456 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
458 The assumption is that you have exported your Divelogs.SDE on a Windows
459 system. You have to transfer the file to a location where you can read it
460 from within your Linux environment. You can use file-tranfer, shared
461 storage or an USB storage device to do this.
462 The example uses an USB storage:
464 - Insert your USB storage into your Windows computer
465 - Use the filemanager (explorer) to navigate to the location where your Divelogs.SDE file is located
466 - Copy the file to your USB storage:
467 * Select the file by 1 click
469 * Navigate to your USB Storage
471 - Disconnect your USB storage by right clicking your USB storage in the explorer and choose Eject
472 - Insert your USB storage into your Linux computer
473 - Use your favourite filemanager to navigate to your USB storage
474 - Copy the file to /tmp by:
475 * Right click on the file
478 * press Ctrl+v or use the menu 'Edit - Paste'
479 - The file is now transfered to /tmp
481 Now the file is in /tmp, we can extract the xml files from it. You can do
482 this by hand, or use the example script in <<AppendixB,Appendix B>>.
484 To extract the xml files, we need to open a terminal and use the following
490 unzip ../Divelogs.SDE
492 Your divelogs have now been extracted from the Divelogs.SDE file and you
493 can import them with the command:
497 And with the menu 'File - Save' you can save your dives into the
501 The menu and sub-menus
502 ----------------------
504 Within Subsurface, there are several menu and sub-menu options. All of
505 those will be described here with their function.
510 The file menu is used for the following menu options:
512 - Open:: Open your saved Subsurface xml file(s)
513 - Save:: Save your current divelogs or changes you made to your divelogs
514 - Print:: Print your current divelog profiles and information about the dive
515 - Import:: Import your dives from your divecomputer, JDivelogs or Suunto Divemanager
516 - Preferences:: Set your preferences as described in chapter 10
517 - Quit:: Quit the program
522 Within the Log menu, there are only 2 sub-items:
524 - Renumber:: This option provides you with a popup. Within this
525 popup you can choose what the first number of your dives should be
526 for this set of dives.
527 - View:: This is a submenu containing:
528 * List:: Show only the list of dives you have made
529 * Profile:: Show only the dive profile of the selected dive
530 * Info:: Show only the 3 tab information screen
531 * Three:: Show the 'default' 3 screen setup
536 This menu gives you the choice to enable or disable Events for the
537 selected divelog(s). At this time, you can enable or disable ascent.
538 When you enable ascent for your dives, within the dive profile, a yellow
539 marker with exclamation sign (!) will show on the points where you have
545 The Help menu shows only the About, which contains the version and author
546 information and License button.
550 Appendix A: Supported Dive Computers
551 ------------------------------------
553 The use of libdivecomputer provides the support for divecomputers. Within
554 the list of computers in the 'File - import' menu, you will see a listing
555 of divecomputers. This list is covering a compatible set. Please check
556 your users manual to check if your computer will be supported.
558 Supported divecomputers::
619 * OSTC computers are listed in the pull-down menu as OSTC. All 3 types are supported.
623 Appendix B: Suunto Export Unpacking Script
624 ------------------------------------------
628 # Small basic example script to unpack Suunto Export files
629 # for the use with Subsurface
632 echo -n "Enter the directory where you stored your Suunto Divemanager export file: "
635 echo -n "Enter the name of your Suunto Divemanager export file: "
636 read SuuntoExportFile
638 echo "You have entered: $SuuntoExportDir/$SuuntoExportFile"
642 if [ -e ./$SuuntoExportFile ]; then
645 unzip ../$SuuntoExportFile
648 echo "Nothing found! Try again!"