Detail the GPS toolbar functions and live tracking operation

docs/user_manual/introduction/qgis_gui.rst

@@ -1922,6 +1922,7 @@ Available toolbars are:
    ":guilabel:`Data Source Manager`", ":ref:`manage_data_source`"
    ":guilabel:`Database`", ":ref:`dbmanager`"
    ":guilabel:`Digitizing`", ":ref:`sec_edit_existing_layer`"
+   ":guilabel:`GPS`", ":ref:`sec_gpstracking`"
    ":guilabel:`GRASS`", ":ref:`sec_grass`"
    ":guilabel:`Help`"
    ":guilabel:`Label`", ":ref:`label_toolbar`"

docs/user_manual/working_with_gps/live_GPS_tracking.rst

@@ -9,44 +9,118 @@ Live GPS tracking
    .. contents::
       :local:
 
+QGIS can help you do field mapping with a GPS receiver.
+Such a live tracking operation is done using the :guilabel:`GPS` toolbar.
+Some :ref:`device configuration <gps_options>` may be needed before
+connecting QGIS and the GPS receiver.
 
 
+.. Anything else people need to know here for starting with live tracking ???????
 
 
+.. _gps_toolbar:
 
+GPS toolbar
+-----------
 
+The :guilabel:`GPS Toolbar` provides the main tools to control a live tracking session.
+It can be activated from :menuselection:`View --> Toolbars --> GPS`.
+It follows the state of the project, GPS, and current GPS track, and enable the actions
+only when they make sense.
+Once a device is detected by QGIS, you will be able to interact with it:
 
+* |gpsConnect| :sup:`Connect to GPS`
+* |gpsDisconnect| :sup:`Disconnect from GPS`
+* |recenter| :sup:`Recenter map on GPS location`: the map will jump to the current GPS position
+  regardless of the :ref:`automatic recentering parameter <gps_recenter>`.
 
+* |gpsDestinationLayer| :sup:`Set destination layer for GPS digitized features`:
+  By default, QGIS will :guilabel:`Follow active layer` for feature digitizing,
+  meaning that GPS digitizing tools will adapt to the layer selected in :guilabel:`Layers` panel
+  and created features will be stored in it accordingly.
+  While this may be comfortable in some contexts, it also implies careful interaction
+  with other layers to avoid storing inadvertently features in undesired layers.
+  This option allows you to explicitly indicate a layer for the data storage
+  during the live tracking session, and you could switch depending on your needs.
+  Exposed tools will adapt as well to the selected layer type.
 
+  The GPS destination layer is made automatically editable when a feature is being created,
+  and the user is notified accordingly.
 
+* actions for feature creation:
 
+  * |addTrackPoint| :sup:`Add vertex to GPS track using GPS current location`
+  * |captureLine| :sup:`Create feature from track`
+  * |capturePoint| :sup:`Create a new point feature at current GPS location`
+  * |reset| :sup:`Reset track`
 
+* |metadata| :sup:`Show GPS information`: opens the :guilabel:`GPS Information` panel
 
+  .. todo: replace guilabel with a ref to the section when available, i.e
+     * |metadata| :sup:`Show GPS information`: opens the :ref:`GPS Information``
+     <gps_information_panel>` panel
 
+* a display box for quick access to some GPS information components you may need:
 
+  * |unchecked| :sup:`Show location`
+  * |unchecked| :sup:`Show altitude (Geoid)`
+  * |unchecked| :sup:`Show altitude (WGS 84 ellipsoid)`
+  * |unchecked| :sup:`Show ground speed`
+  * |unchecked| :sup:`Show bearing`
+  * |unchecked| :sup:`Show total track length`
+  * |unchecked| :sup:`Show distance from start of track`
 
+.. _tracking_settings:
 
+* The |options| :sup:`Settings` button opens a drop-down menu with settings
+  which are expected to be modified mid-session:
 
+  * |unchecked| :guilabel:`Show location marker`
+  * |unchecked| :guilabel:`Show bearing line`
+  * |unchecked| :guilabel:`Rotate map to match GPS direction`
 
+  .. _gps_recenter:
 
+  * Options to control map recentering:
 
+    * |radioButtonOff| :guilabel:`Always recenter map` when the GPS position is offset
+      from the map canvas center by a certain distance (as a ratio of the map canvas extent)
+    * |radioButtonOn| :guilabel:`Recenter map when leaving extent`
+    * |radioButtonOff| :guilabel:`Never recenter`
 
+  * |unchecked| :guilabel:`Automatically add track vertices`
+    whenever new locations are received from the GPS device.
+  * |unchecked| :guilabel:`Automatically save added features`:
+    features created from GPS locations are immediately committed to their target layers
+    (skipping the usual layer edit buffer)
+  * :guilabel:`Time stamp destination` to adjust the field for time fix storage
 
+  .. _gps_logging:
 
+  * |unchecked| :guilabel:`Log to GeoPackage/SpatiaLite...`: When activated,
+    the user will be prompted to select an existing GeoPackage/SpatiaLite file
+    or enter a new file name.
+    A ``gps_points`` and ``gps_tracks`` table will be created in the file
+    with a predefined structure.
 
+    All incoming GPS messages will be logged to the ``gps_points`` layer,
+    along with speed, bearing, altitude and accuracy information from the GPS.
 
+    When the GPS is disconnected (or QGIS closed), the entire recorded GPS track
+    will be added to the ``gps_tracks`` table
+    (along with some calculated information like track length, start and end times).
 
+  * |unchecked| :guilabel:`Log NMEA sentences...`
+  * |options| :guilabel:`GPS settings...` to access the GPS :ref:`global options
+    <gps_options>` dialog
 
 
+.. tip:: **Live status bar information on position**
 
-
-
-
-
-
-
-
-
+  When a GPS device is connected and the user moves the cursor over the map canvas,
+  a live status bar message displays the distance and bearing from the cursor to the GPS position.
+  Project distance and bearing settings are respected in this display.
+  On a touch screen device, use a tap-and-hold event to trigger the live status bar message.
 
 
 Connect to a Bluetooth GPS for live tracking
@@ -167,6 +241,18 @@ or without it, by connecting the QGIS live tracking tool directly to the device
    please add it also to the substitutions.txt file in the
    source folder.
 
+.. |addTrackPoint| image:: /static/common/mActionAddTrackPoint.png
+   :width: 1.5em
+.. |captureLine| image:: /static/common/mActionCaptureLine.png
+   :width: 1.5em
+.. |capturePoint| image:: /static/common/mActionCapturePoint.png
+   :width: 1.5em
+.. |gpsConnect| image:: /static/common/mIconGpsConnect.png
+   :width: 1.5em
+.. |gpsDestinationLayer| image:: /static/common/mIconGpsDestinationLayer.png
+   :width: 1.5em
+.. |gpsDisconnect| image:: /static/common/mIconGpsDisconnect.png
+   :width: 1.5em
 .. |gpsTrackBarChart| image:: /static/common/gpstrack_barchart.png
    :width: 1.5em
 .. |metadata| image:: /static/common/metadata.png
@@ -177,3 +263,9 @@ or without it, by connecting the QGIS live tracking tool directly to the device
    :width: 1.5em
 .. |radioButtonOn| image:: /static/common/radiobuttonon.png
    :width: 1.5em
+.. |recenter| image:: /static/common/mActionRecenter.png
+   :width: 1.5em
+.. |reset| image:: /static/common/mActionReset.png
+   :width: 1.5em
+.. |unchecked| image:: /static/common/unchecked.png
+   :width: 1.3em