Changeset c7a4bb1 in subsurface


Ignore:
Timestamp:
Dec 6, 2013, 9:22:13 AM (4 years ago)
Author:
Dirk Hohndel <dirk@…>
Branches:
Mtest, android_test, dcDownload, foratdotde, gitMerge, gitdebug, gitpictures, ios, master, mergeKirigamiPort, pictimeshift, resolutionIndependence, spinner, testTomaz, testing, v4.0-branch, v4.0.3-branch, v4.2-branch, v4.4-branch, v4.5-branch
Children:
5506fa4
Parents:
07e1e41
git-author:
Salvador Cuñat <salvador.cunat@…> (12/06/13 07:47:05)
git-committer:
Dirk Hohndel <dirk@…> (12/06/13 09:22:13)
Message:

Companion app and downloading GPS coordinates from web service

A first try on documenting the companion app and explanation on how to use
it combined with Subsurface.

Signed-off-by: Salvador Cuñat <salvador.cunat@…>
Signed-off-by: Dirk Hohndel <dirk@…>

Location:
Documentation
Files:
5 added
1 edited

Legend:

Unmodified
Added
Removed
  • Documentation/user-manual.txt

    rfb169db rc7a4bb1  
    742742  ** http://www.tek-dive.com/portal/upload/M-Values.pdf[Understanding M-values by Erik Baker, , _Immersed_ Vol. 3, No. 3.]
    743743
     744[[S_Companion]]
     745== Importing GPS coordinates with Subsurface companion.
     746If you have an Android device with GPS, you can achieve the coordinates of the point where you are diving and automatically pass them to your Subsurface divelog. You only need:
     747
     748- [red]#Register in Subsurface companion page.# http://api.hohndel.org/login/ You'll receive a confirmation mail with instructions and your *DIVERID*, this id will give you access to the companion app capabilities.
     749
     750- [red]#Download the app.# You can download it from https://play.google.com/store/apps/details?id=org.subsurface or http://f-droid.org/repository/browse/?fdfilter=subsurface&fdid=org.subsurface .
     751
     752=== Using Subsurface companion app.
     753
     754On first use the app has three options:
     755
     756* +Create a new account.+  Equivalent to register in Subsurface companion page.
     757
     758* +Retrieve an account.+  This is the option you would use if someway have forgot your DIVERID. You should receive an email whith it.
     759
     760* +Use an existing account.+ You'll be prompted to introduce your DIVERID.
     761
     762The app stores your ID and don't ask for it again unless you use the _Disconnect_ menu option commented below.
     763
     764Now you're ready to get a dive position and send it to the server.  The android display will look like next image, but without any dive.
     765
     766image::images/companion_1.png["Entry display for companion app",align="center"]
     767
     768Typing the "+" icon on the right you will be prompted for a name for the dive point (or asked first for the GPS activation if this was turned off), and you will get a register in the display with the name of the dive point, date and time.   As you can see in the image above, there are two kind of register, those with a little arrow up and those without it.  The arrow up means the dive is stored in the device, but hasn't been sent to the server.
     769
     770Now we want to send the dive to the server. There are several ways of doing this. Easiest is simply selecting the dive as seen in this image
     771
     772image::images/companion_2.png["Selecting dive points",align="center"]
     773
     774and typing the right arrow will send it to the server.  Be careful, the trash on the right means exactly what it's supossed to mean, it would delete de dive point.
     775
     776Well, the new dive point is stored in the server and can be downloaded to Subsurface divinglog whenever you register your dive in it.  If returning from a dive trip, and you have been lucky, there can be lots of dive points coordinates ready to be saved on your divelog.  We will see how to do this later.
     777
     778Next step would be adjust your preferences in the _Settings_ menu option.  Let's see the options we would get by opening the menu.
     779
     780image::images/companion_3.png["Menu options displayed",align="center"]
     781
     782
     783==== Settings
     784
     785===== Server and account
     786
     787- +Web-service URL.+ Predefined. It's actually http://api.hohndel.org/
     788
     789- +User ID.+ Obtained by registering as indicated above. The easiest way to introduce it is simply copy+paste from the confirmation mail but, off course, you can type it char by char.
     790
     791===== Synchronization
     792
     793- +Synchronize on startup.+ If selected, dives in android device and those on the web service will synchronize each time you start the app.
     794
     795- +Upload new dives.+ If selected, each time you add a dive it'll automatically be sent to the server.
     796
     797===== Background service
     798Instead of take a unique position, you can leave the service running on background on your device. This setting will define the behaviour of the service.
     799
     800- +Min duration.+ In minutes. The app'll try to get a position each X minutes until you stop it.
     801
     802- +Min distance.+ In meters. Minimum distance between two position fixes.
     803
     804- +Name template.+ Te name the app'll use when saving the position fixes.
     805
     806[NOTE]
     807_How background service works?_ Let's asume we've set 5 minutes and 50 meters in the parameters above, the app will fix a position, then another one each 5 minutes. If this 2nd (3rd, 4th ...) is in a radius of 50 meters from the previous one, the position won't be saved. After another 5 minutes there will be a new try, and so on.  This way, if we are in a static position, we'll only get a fix, but if we're moving we can have a nice trace of our journey.
     808
     809===== Other
     810
     811- +Mailing List.+ The mail box for Subsurface. You can send an email to the subsurface mailing list.
     812
     813- +Subsurface website.+ A link to the URL of subsurface web
     814
     815- +Version.+ Displays the current version of the companion app.
     816
     817==== Search
     818
     819Here you can search your saved dive points by the name you gave them or by date and hour.
     820
     821==== Start service
     822
     823Initiates the _background service_. It'll work depending on the previously fixed settings.
     824
     825==== Disconect
     826
     827Badly named option. It disconects your app from the server by reseting your ID in the app. It will send you to the first display where can create an account, retrive the ID for an existing one or use your own ID. Useful if you are downloading the dive positions for another registered user with your android device.
     828
     829==== Send all locations
     830
     831As expected, this option will send all locations stored in the android device to the server.
     832
     833=== Downloading dive locations to your Subsurface divelog
     834
     835First you will have downloaded your dive/s from your DC or created them manually.  Now you want to get the GPS coordinates from the server. The download dialog can be reached via _Ctrl+G_ or from Subsurface's main menu _Import -> Import GPS data from Subsurface Service_
     836
     837image::images/Downloading_GPS.png["Initial downloading GPS dialog ",align="center"]
     838
     839On first use the DIVERID will be blanked, so you'll have to put it here as usual.  Then simply clik on the _Download_ button and the download begins.  When ended you'll get the next
     840
     841image::images/Downloading_GPS_2.png["After downloading",align="center"]
     842
     843Note the _Apply_ button now active, click on it and, luckily, you'll be done.  Subsurface's logic should apply the coordinates and names you gave them for all the new dives.
     844
     845[NOTE]
     846_Features, issues and tips._  Automatically applying of GPS data to the dives is a task very dependent on a correct time.  Note that there might be a difference between time in your DC and time in your android device, if you have a little one there'll be no problem and the logic will work fine, but if it's big Subsurface will be unable to identify the dive which matches the coordinates, and nothing will happen. The ideal is have a correct time in your DC (or in the android device, whichever is wrong)  but this may be not possible.  A dirty hack is editing manually the time in Subsurface's log _before_ downloading the GPS data. If the correct time was the erased one, then simply edit it back manually again _after_ downloading.
     847
     848
    744849== APPENDIX A: Operating system specific information for importing dive information from dive computer.
    745850
Note: See TracChangeset for help on using the changeset viewer.