From: Linus Torvalds Date: Thu, 15 Dec 2011 02:19:48 +0000 (-0800) Subject: Merge branch 'forlinus' of git://git.hohndel.org/subsurface X-Git-Url: http://git.tdb.fi/?a=commitdiff_plain;h=b0759feef87fcf820682cb36d65f2252c2cc12ae;hp=6245b700a4a98cc2dba8c5b8c3f4958491605755;p=ext%2Fsubsurface.git Merge branch 'forlinus' of git://git.hohndel.org/subsurface * 'forlinus' of git://git.hohndel.org/subsurface: Improve Makefile for MacOS Add reasonable default device names for divecomputer import More intuitive label for "not saving" when exiting --- diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt new file mode 100644 index 0000000..1813601 --- /dev/null +++ b/Documentation/user-manual.txt @@ -0,0 +1,357 @@ +Subsurface 1.2 + +User Manual + +Version 0.0.4 + +Autor documentation: Jacco van Koll + +Scope of this document is the usage of the program. +Please read the build manual for instructions how to build the +software and (if needed) it´s dependencies. + +Audience: Fun Divers, Tec Divers, Professional Divers + + +1. Introduction: + +Subsurface was started because of a lack of viable dive log software +on Linux. It turns out that the resulting software was easily ported +to Windows and Mac, but it clearly is a native Linux program first. +Right now, the program is under development and from version 1.1 it is +already very usable for divers with supported dive-computers. + +In this manual the Suunto Viper will be used for all examples. + + +2. Requirements + +Before you are able to import information from your divecomputer into +Subsurface, you need some preparation. Do you have the following: + + 1. Your Divecomputer - Compatible with libdivecomputer (see list in Appendix A) + 2. Communication interface - Cable to connect your divecomputer to your PC/Laptop/Netbook + 3. Working installation of Subsurface + 4. If needed, the manual of your divecomputer + + +3. Start using the program: + +When you start the program for the first time, it shows no information +at all. This is because the program does not automatically load the +already available dive-log files. + +There is a menu, containing 'File', 'Log', 'Filter' and Help. + +The screen is devided in 3 area's: + + Area with 3 tabs: Dive Notes, Equipment, Info & Stats + Area next to the 3 tabs, which will contain the dive profile + Area with the dives (usually called dive list), which can be sorted by number, date, etc. + + +4. Import new dives + +Before you start fiddeling around with your divecomputer, note that +there are divecomputers that consume more power when they are in the +PC-Communication mode. This could drain your battery. Therefor, ensure +if your computer is recharging when connecting to the USB port. The +Suunto Viper does not recharge trough the USB connection. Please +consult the manual of your divecomputer if you are unsure if it will +be recharged when connected to the USB port. + +Now it is time to hook up your divecomputer to your Linux system: + + Make sure that your OS has the required drivers installed + + On Linux this means you need to have the correct kernel + module loaded. Most distributions will do this automatically + for you. + + On Windows, the OS should offer to download the correct + driver when you connect to the USB port. + + On a Mac you at times have to manually hunt for the correct + driver. For example the correct driver for the Mares Puck + devices can be found as Mac_OSX_VCP_Driver.zip at + http://www.silabs.com/support/pages/support.aspx?ProductFamily=USB+Bridges + + Connect your interface cable to a free USB port + + Put your divecomputer into PC Communication mode. (For Suunto Viper, press Mode - 1 Memory - 3 TR-PC) + (You should consult the manual of your specific divecomputer for your brand and type) + + Go in Subsurface to 'File - Import' + Within the popup, under Dive computer, choose your brand and type. Here we choose Suunto Vyper. + Change the devicename under which your interface is connected. + On Linux, default is /dev/ttyUSB0 + On Windows, default is COM3 + On Mac, default is ... specific to the dive computer + + Click the 'OK' button. + + Now watch how your data is retrieved from your divecomputer! + Depending on your type of computer and/or number of dives, this + could take some time. Please be patient. + + +5. Viewing and completing your logs + +When all data from your divecomputer is transferred, you will see a +listing of your dives in Area 3. + +An example: + +On Sunday Oct 23, 2011 you made a dive. +In the log line of this dive, you see the following information: + + #: 12 Dive number + Date: Sun, Oct 23, 2011 10:50 Date and time of your dive + *: Your rating (none at this time) + m: 12.8 Your maximum depth in meters + min: 31:20 Your dive-time in minutes and seconds + Deg. C: 13.0 Lowest water temperature during your dive + Cyl: Your used cylinder (none at this time) + O2%: air What type of mixture + SAC: SAC (none at this time) + Location: Where you performed your dive (empty) + + As you can see, some information is already there because it is + retrieved from your divecomputer. Some information is waiting for + you to be added. By double clicking on this dive, you can view and + complete the log. + + +6. Edit the dive info + +When you double click on the dive log line, the editor window +opens. Now you can add information that is missing. Let start with +completing the example: + +You double clicked on dive #12, as described in 5. Viewing and +completing your logs. The Dive Info window pops up and you will see +the following: + + Location: An input where you can enter your new location, or you can choose with the pull-down previous locations + 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 + Buddy: An input where you can enter het name of you Buddy, or you can choose with the pull-down a previous name + Rating: A pull-down where you can rate your dive. + Notes: A free input where you can enter information about your dive. What you've seen, etc. + +In this example we use the following information: + + Location: Oostvoornse Meer + Dive Master: S. de Vries + Buddy: S. de Vries + Rating: 3 stars + Notes: First dive here. Good visibility. Did see the concrete poles, some crab and fish. Very nice and easy dive. + Made movie with 'headcam'. + +Now don't press ok yet! + + +7. Edit equipment info + +You also want to edit your Cylinder information. And in the previous +chapter, this was not edited. There is still another item to edit in +the Dive Info screen: + + Cylinder: A double-click fieldset. Here you can edit your Cylinder information + +So, when you double click on the cylinder info, you get another +popup. This popup gives you the following: + + Cylinder: Pull-down where you can choose your Cylinder, or add your own + Size: The volume if not 'filled' + Pressure: The maximum pressure of this Cylinder + Optional: + Start Pressure: What was the pressure starting the dive + End Pressure: What was the pressure ending the dive + Nitrox: What was the percentage of blend + +Now we are going to enter the data: + + Cylinder: 15.0 l + Size: 15.0 + Pressure: 220 + + Now tick the option for Start & End pressure + + Start Pressure: 180 + End Pressure: 60 + Press Ok + +Now your dive information for this dive is complete. You can now press +ok in the Dive Info screen and view the results. + + +8. Adding equipment info + +In Area with the 3 tabs there is the tab Equipment. With this tab, you +can add Cylinders. We are going to add an additional Cylinder: + + In the main screen, click on the Equipment tab. This shows your Cylinder you added in 7. + Now press the Add button and the Cylinder popup comes back. + Just like you added your Cylinder information in 7. Edit equipment info, you add your cylinder + information for the second Cylinder. Fill in all the information about this Cylinder and press OK. + + +9. View info & Stats + +After adding all the information, you can use the tab Info & +Stats. This tab will provide you with all the (statistical and +calculated) information regarding your dive. + +The information contains: + + Dive Info: + + Date: Date and time of your dive + Dive Time: Duration of your dive + Surf Intv: Interval between previous dive and this dive + Max Depth: Maximum depth of this dive + Avg Depth: The average depth of this dive + Water Temp: Lowest temperature of the water + SAC: The amount of Surface Air Consumption liters per minute + OTU: The Oxygen Toxicity Units of this dive + O2/He: Amount of Oxygen/Helium + Gas Used: The total volume of gas used during this dive + + Statistics: + + Total time: Total time of all your dives together, calculated + Avg Time: The average divetime of your dives, calculated + Max Depth: The maximum depth of all your dives + Avg Depth: The average depth of all your dives, calculated + Max SAC: Highest of Surface Air Consumption of all your dives + Min SAC: Lowest of Surface Air Consumption of all your dives + Avg SAC: Average Surface Air Consuption of all your dives, calculated + + +10. Setting up preferences + +Subsurface has the ability to modify the preferences you want. By +using menu 'File - Preferences' you will be presented a popup with the +'Units'. You are free to choose what is your preference, with other +words, use Metric or Imperial. + +You can set the following options: + Depth: Your diving depth in Meters or Feet + Pressure: The pressure of your tank(s) in Bar/Ato or PSI (Pressure Square Inch) + Volume: The volume of your tank(s) in Liter or CuFt (Cubic Feet) (At sea-level pressure) + Temperature: The temperature of the water in Celcius or Fahrenheit + +In the main screen, you did see in Area 3, some information. In the +Columns options, you can enable/disable options you would like to show +there: + Show Temp: Shows the temperature of your dive + Show Cyl: Shows the cylinder(s) of your dive + Show O2%: Shows the O2% of your dive + Show SAC: Shows the SAC of your dive (Surface Air Consumption) + Show OTU: Shows the OTU of your dive (Oxygen Toxicity Units) + +And, you can change the font usage of the program. + +I will give an example here: + +I am a diver in The Netherlands, using the Metric System. Therefor, I +go to the menu File, choose Preferences here. In the Units section, I +use the folowing: + + Depth: Meter + Pressure: Bar + Volume: Liter + Temperature: Celcius + +I would like to see the: + Temperature + Show Cyl + Show O2% + Show SAC + +As a beginning diver, I don't need to track my OTUs. So I leave this +one not enabled. + +Clicking OK on the dialog stores these settings. + + +11. How to find the Device Name + +When you connect your divecomputer by using an USB connector, most of the +time, the default of ´/dev/ttyUSB0' should work. But if you have other +Serial to USB devices, this can be different because '/dev/ttyUSB0' is +already in use. + +One of the ways to find out what your dive name is: + + Disconnect your usb cable of your dive computer + Open a terminal + Type the command: 'dmesg' and press enter + Plug in your usb cable of your divecomputer + Type the command: 'dmesg' and press enter + +Within your terminal you should see a message similair to this one: + + usb 2-1.1: new full speed USB device number 14 using ehci_hcd + usbcore: registered new interface driver usbserial + USB Serial support registered for generic + usbcore: registered new interface driver usbserial_generic + usbserial: USB Serial Driver core + USB Serial support registered for FTDI USB Serial Device + ftdi_sio 2-1.1:1.0: FTDI USB Serial Device converter detected + usb 2-1.1: Detected FT232BM + usb 2-1.1: Number of endpoints 2 + usb 2-1.1: Endpoint 1 MaxPacketSize 64 + usb 2-1.1: Endpoint 2 MaxPacketSize 64 + usb 2-1.1: Setting MaxPacketSize 64 + usb 2-1.1: FTDI USB Serial Device converter now attached to ttyUSB3 + usbcore: registered new interface driver ftdi_sio + ftdi_sio: v1.6.0:USB FTDI Serial Converters Driver + +You see that in the third line from the bottom, the usb adapter is +detected and is connected to 'ttyUSB3'. Now you use this information in +the import settings as '/dev/ttyUSB3'. Your divecomputer interface is +connected and you should be able to import your dives. + + +Appendix A + +The use of libdivecomputer provides the support for divecomputers. Within +the list of computers in the 'File - import' menu, you will see a listing +of divecomputers. This list is covering a compatible set. Please check +your users manual to check if your computer will be supported. + + Supported divecomputers: + + Atomics: + Cobalt + Cressi: + Edi + Mares: + Icon HD + Nemo + Puck + Oceanic: + Veo250 + VT Pro + OSTC: * + DR5 + 2N + Reefnet: + Sensus + Sensus Pro + Sensus Ultra + Suunto: + D9 + Eon + Solution + Viper + Viper Air + Uwatec: + Aladin + Memo Mouse + Smart + Zeagle: + N2iTiON 3 + +* OSTC computers are listed in the pull-down menu as OSTC. All 3 types are supported.