mifr/subsurface
1
0
Fork 0
mirror of https://github.com/subsurface/subsurface.git synced 2024-11-30 22:20:21 +00:00
Code Issues Projects Releases Packages Wiki Activity

Mobile user manual: some updates for Subsurface-mobile 3.0

Browse source 
This needs more work and especially new screen shots, but for now this
covers at least some of the most important changes.

Signed-off-by: Dirk Hohndel <dirk@hohndel.org>
This commit is contained in:
Dirk Hohndel 2020-03-15 17:58:08 -07:00
parent 91a97e09e5
commit fe9a2ab5c3
2 changed files with 79 additions and 62 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
CHANGELOG.md
View file

@ -1,3 +1,5 @@
Mobile-android: remove libusb/FTDI support (largely non-functional)
Mobile-android: Continue download after obtaining USB permission
Mobile-android: Add usb-serial-for-android driver support
Mobile: fix missing download info on retry
Mobile: enable profile zoom and pan

139
Documentation/mobile-manual.txt
View file

@ -2,8 +2,8 @@
// Subsurface-mobile User Manual
// =============================
// :author: Manual authors: Willem Ferguson, Dirk Hohndel
// :revnumber: 2.1.5
// :revdate: December 2018
// :revnumber: 3.0.0
// :revdate: March 2020
:icons:
:toc:
:toc-placement: manual
@ -18,7 +18,7 @@ image::mobile-images/Banner.jpg["Banner",align="center"]
// toc::[]
[blue]#_Version 2.1.5, December 2018_#
[blue]#_Version 3.0.0, March 2020_#
Welcome as a user of _Subsurface_ and _Subsurface-mobile_, advanced dive logging
software with extensive infrastructure to describe, organize, and interpret scuba
@ -50,7 +50,7 @@ _Subsurface-mobile_ allows:
- Download and storage of dive log information using the _Subsurface_ cloud.
- Viewing this information on a mobile device.
- Manually creating and adding new dive records to your dive log.
- Download dive data directly from many dive computers.
- Download dive data directly from some dive computers.
- Editing many of the dive log data fields, e.g. dive-master, buddy,
equipment or notes relating to a dive.
- Recording, storing and applying GPS positions of dives.
@ -62,14 +62,15 @@ _Subsurface-mobile_ does not support download of dive data from all the
dive computers that the desktop/laptop version can. This limitation is
mainly caused by the inability of accessing some types of devices on the
two mobile platforms. On Android, a subset of
dive computers that use a FTDI USB interface or a Bluetooth / Bluetooth LE interface
dive computers that use USB serial cables or a Bluetooth / Bluetooth LE interface
are accessible by _Subsurface-mobile_. On iOS, only Bluetooth LE based
dive computers are supported.
== Installing _Subsurface-mobile_ on your mobile device
Find _Subsurface-mobile_ in the _Google Play Store_ or the _iTunes Store_
and install it. Please note that both stores also contain the older _Subsurface_ companion app (used only for tracking GPS positions) - make sure you actually install _Subsurface-mobile_.
and install it. For Android devices without access to the _Google Play Store_
APKs can be found in the downloads folder on the Subsurface website.
== Using _Subsurface-mobile_ for the first time
@ -96,7 +97,13 @@ do full maintenance of a dive log from _Subsurface-mobile_ alone. By using the s
credentials with _Subsurface-mobile_ and _Subsurface_ for desktop, the _Subsurface_ cloud storage allows sharing of a dive
log between both (or even more than two) devices.
The dive data on the cloud are cached locally both on the mobile device as well as on the desktop - it is easy to create backups of the data (for example in XML format) on the desktop: both mobile device and desktop keep a local copy of the data so that the dive log is always accessible, even without Internet connection. The Subsurface team never accesses a user's dive data without explicit permission to do so, the data are not used for any purpose other than providing them to the user who created them. There are no ads and no harvesting / analysis of the data stored in the Subsurface cloud storage.
The dive data in the cloud are cached locally both on the mobile device as well as on the desktop -
it is easy to create backups of the data (for example in XML format) on the desktop: both mobile
device and desktop keep a local copy of the data so that the dive log is always accessible, even
without Internet connection. The Subsurface team never accesses a user's dive data without explicit
permission to do so, the data are not used for any purpose other than providing them to the user who
created them. There are no ads and no harvesting / analysis of the data stored in the Subsurface
cloud storage.
1) Enter an e-mail address and a password in the fields indicated on the screen (see image above).
The e-mail address should be in lower case and the password should contain a combination of
@ -105,14 +112,18 @@ Tap the "Sign-in or Register" button. If you have already set
up an account from the _Subsurface_ desktop application, enter the same credentials here.
Once the dive
list has been downloaded from the cloud, _Subsurface-mobile_ usually works only with the the local
copy on the mobile device. This avoids long delays or even failure of operations if there is a bad (or no) internet connection, a situation fairly common at many dive sites. Once registered, _Subsurface-mobile_ remembers the cloud credentials and it is not necessary to provide these again when launching the program.
copy on the mobile device. This avoids long delays or even failure of operations if there is a bad
(or no) internet connection, a situation fairly common at many dive sites. Once registered,
_Subsurface-mobile_ remembers the cloud credentials and it is not necessary to provide these again
when launching the program.
2) If this is a new cloud account, a PIN screen will open (see image on right, above). A PIN is e-mailed
to the email address entered in the previous step. Enter this PIN into the field indicated
and tap the _Register_ button. The user
information is stored on the cloud server and access to the cloud is enabled. In this case
the dive list is initially empty. Start entering dives in the dive
log or download dive information from a supported dive computer.
log or download dive information from a supported dive computer. After the PIN has been entered it
is no longer needed - it just proves that this is indeed your email account.
****
[icon="images/icons/important.png"]
@ -145,12 +156,18 @@ multiple accounts. See the section on xref:S_ChangeCloudAccount[Changing to a di
== Getting Support
The best place to get support is the Subsurface User Forum. Additionally, Subsurface-mobile allows you to send a support email by tapping on _Ask for support_ in the main menu. This will open an email to our in app support address in the native email client, including the relevant logs.
The best place to get support is the Subsurface User Forum. Additionally, Subsurface-mobile allows
you to send a support email by tapping on _Ask for support_ in the main menu. This will open an
email to our in app support address in the native email client, including the relevant logs.
== Menu Structure and User Interface
At the bottom of many _Subsurface-mobile_ screens is a round button that provides for
several actions (see image below). The most common choice is indicated in a round colored _action button_ (in the case below, edit a dive). Alternative actions are indicated in a white _action bar_.
On some screen a context menu is available by tapping on the three dots in the lower right corner
of the screen. In the dive list this can also be opened by tapping and holding a dive ot trip
header.
On Android devices, use the Android Back
button for "cancel", "discard" or "back" actions. For example, when
editing dive information, tapping the action button saves the changes while the
@ -166,7 +183,7 @@ _Subsurface-mobile_ on Android does not use the traditional "hamburger"
menu button in the top left or right corner of the screen to open menus.
Instead, _Subsurface-mobile_ uses a
different user interaction philosophy based on the Kirigami framework
developed by the Plasma developers. There are three ways to open the main menu:
developed by the Plasma developers. There are two ways to open the main menu:
- Tap the "hamburger" symbol in the lower left corner of the screen
(easy to reach for hand held devices)
@ -200,6 +217,8 @@ Using the Action Bar, it is also possible to delete the dive (tap the dustbin
on the Action Bar) or to view the dive
location on a map viewer (Google Maps on Android, the Google Maps web site
on iOS; tap the GPS icon on the Action Bar.).
The context menu (accessible by tapping on the vertical three dots in the lower right corner of the
screen) offers additional options to move dives between trips and to undo and redo previous actions.
== Filter the dive list
@ -211,7 +230,15 @@ at the bottom of the dive list to perform filtering of the dive list (see image
image::mobile-images/Filter.jpg["FIGURE: Filter tool",align="center"]
By default, all the dives in the dive log are shown in the dive list. After several years your dive log can become quite long and, sometimes, you might like to list only the dives of a particular type, e.g. those at a particular dive site or those with a specific buddy or dive master. Use the Filter to achieve this. The filter mechanism searches through all the information for each dive, looking for one or more key words. Only the dives containing these key words are listed in the dive list. In the xref:S_Settings[_Settings_] screen there two options that affect the way the filter searches for appropriate information. Firstly, you can select _Match filter case sensitive_ which causes the search of key words to be case sensitive. Secondly, you can select _Include notes in full text filtering_. If this option is not selected, the filter does not search through the dive notes for key words. Selecting the _Filter_ action button brings up a text box at the top of the dive list. Type the key words to be searched for. In the image on the left, the dive list has been filtered for the word "Nitrox" and 265 dives were found containing this word as a tag. For each trip in the dive list the number of dives containing "Nitrox" as a tag is shown. To clear the filter, remove the key words from the text box and select the Filter action button to switch off filtering.
By default, all the dives in the dive log are shown in the dive list. After several years your dive
log can become quite long and, sometimes, you might like to list only the dives of a particular
type, e.g. those at a particular dive site or those with a specific buddy or dive master. Use the
Filter to achieve this. The filter mechanism searches through all the information for each dive,
looking for one or more key words. Only the dives containing these key words are listed in the dive
list. Three filter modes exist. Fulltext searches all text strings, People only looks at buddies and
dive masters, and tags only filters for tags containing the given text.
To clear the filter, remove the key words from the text box and select the Filter action button to
switch off filtering.
== Viewing the locations of all dives in the dive list
@ -271,41 +298,34 @@ the same dive in _Details View_.
image::mobile-images/Manualdive.jpg["FIGURE: Manual dive entry screen",align="center"]
== Copy dive information from one dive to another
When editing dives it is possible to transfer information from one dive to another. For instance,
when diving with the same buddy and the same equipment configuration during a particular dive trip
it can be efficient to simply copy all this information from the previous dive into the dive that
is being edited. Currently a standard list of dive information is copied to the clipboard:
Divemaster, Buddy, Suit, Tags, Cylinders, Weights.
Copy and paste dive information is performed on the Dive List. Long-press on a dive. A panel
with three icons appears on top the selected dive :
image::mobile-images/CopyDeleteDive.jpg["FIGURE: Copy/Delete dive information",align="center"]
To copy the above information to the clipboard, select the leftmost of the three icons. A "Copy"
notification briefly appears on the screen. Now long-press the dive into which the copied information
needs to be pasted. The same three icons appear on the target dive. Select the middle icon. A "Paste"
notification briefly appears on the screen. This completes the copy-and-paste action. Continue by
reviewing this new (pasted) information by manually editing the target dive.
To choose what dive details to copy, long-press the copy button. This will open
up a configuration page where you can toggle the details you want to copy over
to the destination.
// == Copy dive information from one dive to another
//
// When editing dives it is possible to transfer information from one dive to another. For instance,
// when diving with the same buddy and the same equipment configuration during a particular dive trip
// it can be efficient to simply copy all this information from the previous dive into the dive that
// is being edited. Currently a standard list of dive information is copied to the clipboard:
//
// Divemaster, Buddy, Suit, Tags, Cylinders, Weights.
//
// Copy and paste dive information is performed on the Dive List. Long-press on a dive. A panel
// with three icons appears on top the selected dive :
//
// image::mobile-images/CopyDeleteDive.jpg["FIGURE: Copy/Delete dive information",align="center"]
//
// To copy the above information to the clipboard, select the leftmost of the three icons. A "Copy"
// notification briefly appears on the screen. Now long-press the dive into which the copied information
// needs to be pasted. The same three icons appear on the target dive. Select the middle icon. A "Paste"
// notification briefly appears on the screen. This completes the copy-and-paste action. Continue by
// reviewing this new (pasted) information by manually editing the target dive.
//
// To choose what dive details to copy, long-press the copy button. This will open
// up a configuration page where you can toggle the details you want to copy over
// to the destination.
== Deleting a dive
Delete a dive from the dive list by long-pressing a dive
until a red dustbin appears on the right-hand side (see image above). Tap the dustbin.
The dive is deleted without asking any confirmation because _Subsurface-mobile_ assumes that the
combination of a long tap on the dive with another tap on the red dustbin is an unambiguous
instruction to delete the dive.
To choose what dive details to copy, long-press the copy button. This will open
up a configuration page where you can toggle the details you want to copy over
to the destination. By default, the following fields are copied:
Delete a dive from the dive list by long-pressing a dive and selecting delete in the context menu.
If the wrong dive was deleted by mistake you can easily undo the operation in the context menu.
image::mobile-images/Delete_undo.jpg["FIGURE: Undo delete dive",align="center"]
@ -317,9 +337,9 @@ tap _Manage dives -> Download from DC_. A screen is shown requiring that the us
the names of the vendor and model of the dive computer. For instance, when using a Shearwater Petrel dive
computer, the vendor is _Shearwater_ and the Dive computer name is _Petrel_(see image on the left, below).
*Caveats:* The download feature in smartphones supports only a limited number of dive computers. On
Android devices these are typically dive computers using an FTDI interface
using a USB OTG cable (but this is blocked on some Android devices by OS
settings). Android devices also support Bluetooth dive computers that
Android devices these are typically dive computers using a serial USB interface
using a USB OTG cable or a simple USB C-A adapter on newer devices.
Android devices also support Bluetooth dive computers that
are supported in _Subsurface_ on the desktop. Both Android and iOS devices allow direct
download of dive data from a handful of Bluetooth LE enabled dive
computers. Use the _Vendor name_ and _Dive Computer_ drop-downs to pick the correct
@ -330,14 +350,8 @@ computers that are not used any more. Achieve this by selecting the option
_Forget remembered dive computers_ in the xref:S_Settings[_Settings_] menu.
After all these caveats, let us proceed with download.
*For USB FTDI dive computers:*
This feature is not supported on iOS and on most newer Android devices. It still works on some older
Android devices (typically Android 7 and older) and is kept enabled for this
reason. Note: USB cables "normally" used for uploading dives to a
desktop/laptop computer do NOT work; these
cables usually have a full-sized ("Type A") male USB plug
on one end which plugs into the USB port of a desktop/laptop computer. For downloads to a mobile device
one needs a USB OTG (USB On-The-Go) cable.
*For USB serial dive computers:*
This feature is not supported on iOS.
[width="100%", frame="None"]
|=======
@ -350,8 +364,7 @@ OTG cable usually has a full-size ("Type A") female receptacle at one end which
accommodates the full-sized male plug
of the USB cable "normally" used (see image below). This means that two cables are used to connect
the dive computer to the mobile device. *Not all Android devices support OTG cables*
and even on some devices that do support those cables in general, as mentioned above _Subsurface-mobile_
does usually not support cable based downloads, except on some older Android devices.
but usually all modern Android devices with a USB C plug can be used with a USB A-C adapter.
|=======
_Subsurface_ remembers the settings for dive computers that
@ -359,7 +372,13 @@ have been successfully used (image on right, below). These appear
as buttons under a heading "_Previously used dive computers_".
Select the appropriate button. Having connected the USB dive computer to the
_Subsurface_ computer and having selected the appropriate vendor and dive computer,
ensure that the Connection text box shows "FTDI".
ensure that the Connection text box shows the corresponding connection. For a small number of dive
computers the connection name shows the dive computer vendor, for most only the cable chipset vendor
(and USB connection number) is shown. Most users of course only connect one USB dive computer to
their Android device and then things are fairly straight forward. A dialog will pop up and ask if
you want to use Subsurface-mobile to connect to the device. If you confirm, then Subsurface will
open to the dive computer download screen with the correct connection selected (and if it can deduce
the correct dive computer based on the cable used, even that information is already pre-filled).
*For BLUETOOTH/BTLE dive computers:* The process for Bluetooth download is slightly different between Android and iOS.
In our testing we got the best results on iOS when the dive computer was
@ -528,10 +547,6 @@ Select the appropriate color theme by dragging the appropriate slider on the rig
On the left is the dive list after selecting the Pink theme.
|=======
=== Configuring the GPS webservice
The Settings screen allows one to set up the way in which GPS positions are collected during dives. See the section on xref:S_ConfigureGPS[Configuring the GPS service].
=== Activating the Developer sub-menu
The information in the subsurface.log generated while running _Subsurface-mobile_, plus some additional information for understanding the screen rendering of dive information as well as the way in which _Subsurface-mobile_ processed information during a specific occasion while running the app (see section below) is available through a _Developer_ menu at run time. Activate (or deactivate) this menu item on the Main Menu by dragging the slider switch in the Settings screen.