Document Collect/XLSForm start-geopoint feature

odk1-src/form-audit-log.rst

@@ -38,6 +38,8 @@ To enable logging for a form, add a row of :th:`type` :tc:`audit` and :th:`name`
 
 A form may contain at most one row of :th:`type` :tc:`audit`.
 
+.. _audit-geolocation-tracking:
+
 Location tracking
 ~~~~~~~~~~~~~~~~~
 

odk1-src/form-question-types.rst

@@ -2167,18 +2167,16 @@ and available in Aggregate and other data analysis tools.
 Metadata 
 ~~~~~~~~~~
 
-Metadata questions capture information about 
-the device or the survey collection event
-and are not visible to the user. 
-A more complete record of user behavior within a form 
-can be generated by enabling :doc:`form audit logging <form-audit-log>`.
+Metadata questions capture information about the device or a survey collection event and are not visible to the user.
 
+A more complete record of user behavior within a form can be generated by enabling :doc:`form audit logging <form-audit-log>`.
 
 These items are dependent on the survey collection event:
 
 - :tc:`start` --- The time the survey was started.
 - :tc:`end` --- The last time the survey was saved.
 - :tc:`today` --- The current date, according to the device, when the survey is collected.
+- :tc:`start-geopoint` --- The geolocation when the survey was started. :ref:`Read more <metadata-start-geopoint>`.
 
 These items are defined by the device and cannot be changed:
 
@@ -2205,6 +2203,30 @@ and :ref:`can be edited in Settings <form-metadata-settings>`:
   simserial,simserial
   username,username
   phonenumber,phonenumber
+  start-geopoint,start-geopoint
+
+.. _metadata-start-geopoint:
+
+Geolocation at survey start
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. seealso::
+  :ref:`Audit log geolocation tracking <audit-geolocation-tracking>`
+
+.. note::
+  Geolocation tracking was added in Collect v1.23. Form conversion requires XLSForm Online ≥ v1.6.1, XLSForm Offline ≥ v1.11.1 or pyxform ≥ v0.15.1.
+
+The :tc:`start-geopoint` question type is used to capture a single geolocation in :ref:`geopoint format <location-widgets>` when the survey is first started. Questions of type :tc:`start-geopoint` may be given any allowable name. Although it is possible to have more than one :tc:`start-geopoint` question in a form, all will have the same value.
+
+Any time a survey with a `start-geopoint` question is opened in Collect, the enumerator will see a warning that the form tracks device location. If the device battery is low, or if location tracking needs to be turned off for any reason, you can tap :menuselection:`⋮ --> Track location` or turn off location providers in Android.
+
+The first time that a survey with a `start-geopoint` question is opened, Collect will attempt to read the device's geolocation. The geolocation reading with the highest accuracy received in a 20-second window will be recorded. A location icon will be displayed in the Android status bar while the geolocation is being requested by Collect.
+
+Geolocation is read using data from GPS, WiFi and possibly other signals so this feature should work in most environments.
+
+If geolocation information is unavailable, the question will be left blank. Reasons for a blank value may include the enumerator turning off location providers, Collect not having location permissions, Google Play Services not being installed, the GPS not having satellite lock and more. No troubleshooting information is provided in the form submission.
+
+Including a `start-geopoint` question may make it faster to get high-accuracy geolocation readings for other :ref:`location question types <location-widgets>` by "warming" the GPS.
 
 .. _calculate-question: