diff options
| -rw-r--r-- | CHANGELOG.md | 2 | ||||
| -rw-r--r-- | Documentation/mobile-manual.txt | 139 |
2 files changed, 79 insertions, 62 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md index 34fe32b8d..4295ae29a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/Documentation/mobile-manual.txt b/Documentation/mobile-manual.txt index d003c9850..f5a7b9c3d 100644 --- a/Documentation/mobile-manual.txt +++ b/Documentation/mobile-manual.txt @@ -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. |