Merge pull request #719 from MerginMaps/iss_701-gnss-bundle

GNSS bundle

Author: alex-cit

src/field/external_gps/index.md

@@ -12,7 +12,7 @@ External GPS receivers can be connected to your mobile device via Bluetooth and
 
 There are several [extra position variables](../../layer/variables/#position-variables) that can be useful to record when doing the survey with external GPS, such as the GPS antenna height, GPS device name as well as metrics like horizontal, vertical or position dilution of precision (HDOP, VDOP, PDOP).
 
-Note that external GPS devices usually return orthometric heights (ellipsoid with the geoid separation applied).
+Note that external GPS devices usually return orthometric heights (ellipsoid with the geoid separation applied). The altitude and geoid separation in the [GPS info panel](../mobile-app-ui/#current-position-and-gps-info) in the <MobileAppNameShort /> is displayed as reported by the external GPS. 
 
 **Before you start**:
 - Set up your device according to the instructions of its manufacturer. You should continue only when you are sure that the device is working and sending data.
@@ -52,7 +52,7 @@ It is strongly recommended to use the direct connection in the <MobileAppNameSho
 3. Tap on the **Manage GPS receivers** option. Here, you can see the currently used receiver.
 
    Tap on the **Connect new receiver** button.
-   ![Select GPS receiver](./mobile-app-connect-gps-receiver.jpg "Select GPS receiver")
+   ![Select GPS receiver](./mobile-app-connect-gps-receiver.webp "Select GPS receiver")
 
 4. Choose your GPS receiver from the list of Bluetooth devices. 
 
@@ -67,8 +67,11 @@ It is strongly recommended to use the direct connection in the <MobileAppNameSho
    ![GPS info from external GPS in Mergin Maps mobile app](./mobile-app-external-gps-info.jpg "GPS info from external GPS in Mergin Maps mobile app") 
 
 ### How to connect external GPS receiver in Android via mock location
-:::warning
-Mock location should be only used if you are unable to connect the external GPS directly in the <MobileAppNameShort /> .
+
+:::warning Mock location and Internal (fused) GPS provider
+Mock location should be only used if you are unable to connect the external GPS directly in the <MobileAppNameShort />. 
+
+When setting up external GPS receiver on Android via mock location, we recommend using the *Internal (fused)* receiver option in [GPS Settings](../mobile-app-ui/#gps-settings) as this will show if mocked location is detected in the [GPS info](../mobile-app-ui/#current-position-and-gps-info) panel.
 :::
 
 External GPS can be connected and configured in Android to provide mock location using GPS apps (e.g. [Bluetooth GPS](https://play.google.com/store/apps/details?id=de.pilablu.gpsconnector) or apps from specific GPS manufacturers) as a source of GPS signal. the <MobileAppNameShort /> and other apps in your device will get the GPS position from the external GPS. 
@@ -89,12 +92,12 @@ The mock location will be used by the <MobileAppNameShort /> automatically as if
 
 Direct connection via the <MobileAppNameShort /> is not possible on iOS devices. 
 
-External GPS can be connected to your iOS device via Bluetooth. Depending on the GPS manufacturer, there may be a custom app, which then provides position to your iOS device. The <MobileAppNameShort /> sees this as an internal GPS receiver automatically, without additional configuration.
+External GPS can be connected to your iOS device via Bluetooth. Depending on the GPS manufacturer, there may be a custom app, which then provides position to your iOS device. The <MobileAppNameShort /> sees this as an internal GPS receiver automatically, without additional configuration. <MobileAppNameShort /> will report if external GPS receiver is connected.
 
 ![iOS GPS receiver](./external-gps-ios.jpg "iOS GPS receiver")
 
 ## External GPS troubleshooting
-If you encounter issues with external GPS in the <MobileAppNameShort /> , make sure that:
+If you encounter issues with external GPS in the <MobileAppNameShort />, make sure that:
 - your Bluetooth is turned on
 - GPS is paired with your mobile device
 - your GPS receiver is turned on, has battery and is sending data in NMEA format, which is readable by the <MobileAppNameShort />

src/field/external_gps/mobile-app-connect-gps-receiver.jpg

@@ -15,7 +15,7 @@ Current GPS accuracy is displayed above the bottom navigation panel in the <Mobi
 The colour of the **GPS** button denotes the accuracy threshold that can be set in the [GPS settings](../mobile-app-ui/#gps-settings) in the <MobileAppNameShort />. By default, it is set to 10 m. The indicator is green when the accuracy threshold is met, otherwise it turns yellow.
 
 Tapping the GPS button opens the [GPS info panel](../mobile-app-ui/#current-position-and-gps-info), which contains information about the horizontal and vertical accuracy, as well as number of satellites in use.
-![GPS accuracy and GPS info in Mergin Maps mobile app](../mobile-app-ui/mobile-app-gps-info.jpg "GPS accuracy and GPS info in Mergin Maps mobile app")
+![GPS accuracy and GPS info in Mergin Maps mobile app](../mobile-app-ui/mobile-app-gps-info.webp "GPS accuracy and GPS info in Mergin Maps mobile app")
 
 If you'd like to have higher accuracy, you can wait for your device to acquire a better GPS signal. For precise measurements, you may need to connect your device to an [external GPS](../external_gps/).
 

src/field/external_gps/mobile-app-connect-gps-receiver.webp

@@ -99,18 +99,24 @@ Tapping the **location button** in the right bottom corner of the screen centres
 In the left bottom corner of the screen, there is a **GPS** button that displays the GPS accuracy as reported by your mobile device. The colour of the button denotes the accuracy threshold set in [GPS settings](#gps-settings) in the <MobileAppNameShort />.
 
 Tapping the GPS accuracy button opens the GPS info panel:
-![GPS info panel](./mobile-app-gps-info.jpg "GPS info panel") 
+![GPS info panel](./mobile-app-gps-info.webp "GPS info panel") 
 
-- **Source**: internal GPS of the mobile device or [external](../external_gps/) GPS receiver connected via Bluetooth
+- **Source**
+   - *Internal* or *Internal (fused)* for the GPS of the mobile device
+   - the name of the receiver for [external GPS](../external_gps/) receiver connected via Bluetooth
 - **Longitude, Latitude**: current position
-- **X, Y**: current position in project's coordinate reference system
+- **X, Y**: current position in the project's coordinate reference system
 - **Horizontal** and **Vertical accuracy** of the GPS position
-- **Altitude**: ellipsoidal height if internal GPS is used. [External GPS](../external_gps/) devices usually return orthometric heights (ellipsoid with the geoid separation applied).
+- **Altitude**: orthometric height
+   - for *Internal* or *Internal (fused)* GPS, it is calculated from the ellipsoidal height using the <NoSpellcheck id="EGM96" /> geoid model by adding the geoid height (undulation) 
+   - for *[external GPS](../external_gps/)*, it is the orthometric height as reported by the external GPS
 - **Satellites (in use/view)**: number of satellites
 - **Speed**
 - **Last fix**: time of the last received GPS position
 - **GPS antenna height** that can be set in [GPS settings](#gps-settings)
-
+- **Geoid separation**: geoid height (undulation)
+   - calculated from the <NoSpellcheck id="EGM96" /> geoid model for *Internal* or *Internal (fused)* GPS
+   - as reported by the *[external GPS](../external_gps/)*
 
 ### Sync
 The **Sync** button can be used to synchronise changes during the field survey. 
@@ -162,7 +168,7 @@ To open the **Settings**, tap the **More** button. In Settings, you can find [GP
 
 ### GPS settings
 - **GPS accuracy threshold**: value used to change the colour of GPS accuracy indicator to yellow
-- **Manage GPS receivers**: option to switch between internal GPS and external GPS receiver connected via Bluetooth. See [External GPS](../external_gps/) for more details.
+- **Manage GPS receivers**: option to switch between internal, internal (fused) and external GPS receiver connected via Bluetooth. See [External GPS](../external_gps/) for more details.
 - **GPS antenna height**: option to enter the height of a GPS antenna (e.g. when a surveying pole is used)
 
 ![Mergin Maps mobile app GPS Settings](./mobile-app-gps-settings.jpg "Mergin Maps mobile app GPS settings")

src/field/external_gps/mobile-app-connect-gps-receiver.xcf

@@ -43,7 +43,9 @@ Following variables are supported:
  - `@position_coordinate` - A point with the coordinates in WGS84.
  - `@position_latitude` - Latitude
  - `@position_longitude` - Longitude
- - `@position_altitude` - Altitude
+ - `@position_elevation` - Orthometric or normal height
+ - `@position_elevation_ellipsoid` - Ellipsoidal height
+ - `@position_geoid_separation` - Geoid or quasi-geoid height (undulation)
  - `@position_direction` - The bearing measured in degrees clockwise from true north to the direction of travel.
  - `@position_ground_speed` - The ground speed, in meters/sec.
  - `@position_vertical_speed` - The vertical speed, in meters/sec.