Current Location Stage

Summary

• Internal name: GetCurrentLocation
• Category: Location
• Purpose: Retrieve the device's current GPS location (latitude, longitude, accuracy) with configurable timeout handling.
• Task type: Normal

---

Compatibility

• Minimum AndroMate version: 1.1.0

• Maximum AndroMate version: 1.1.0

• Minimum Android: Android 13 (API 33)

• Maximum Android tested: Android 16 (API 36)

• Supported manufacturers:

  • ✅ All manufacturers (tested on Samsung One UI 6.x / 7.x / 8.x and Google Pixel Android Stock)

• Required permissions:

  • ACCESS_FINE_LOCATION
  • ACCESS_COARSE_LOCATION
  • ACCESS_BACKGROUND_LOCATION (if used in background)
  • Location services must be enabled on the device

---

Detailed description

The Current Location Stage task requests the device GPS system to retrieve the current geographic position.

It is used to:

• Collect device geolocation (latitude / longitude)
• Measure GPS accuracy
• Attach location data to telemetry or monitoring reports
• Trigger actions based on geographic position
• Track device movement or presence in a defined area

The task handles:

• requesting GPS updates from Android location services,
• configurable timeout handling,
• retrieval of latitude, longitude, and accuracy values.

---

Input parameters

Parameter	Type	Required	Possible values	Android Compatibility	AndroMate Compatibility	Default
location_timeout_ms	Integer	No	Time in milliseconds	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	10000

---

Output parameters

Field	Type	Trigger condition	Android Compatibility	AndroMate Compatibility	Default
location_lat_output	Double	When location is successfully retrieved	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	<ANDROMATE_NULL_VALUE>
location_long_output	Double	When location is successfully retrieved	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	<ANDROMATE_NULL_VALUE>
location_accuracy_output	Float	When location is successfully retrieved	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	<ANDROMATE_NULL_VALUE>

---

Exceptions

Code	Description
GPS-ERROR-001	Failed to obtain GPS position within the specified timeout (location_timeout_ms).
GPS-ERROR-002	Location could not be obtained — the GPS provider returned a null position.
GPS-ERROR-003	Location services are disabled on the device. Enable GPS in device settings.
GPS-ERROR-004	The application does not have ACCESS_FINE_LOCATION or ACCESS_COARSE_LOCATION permission.

---

Execution flowchart

flowchart TD
    Start([▶ GetCurrentLocation]) --> CheckGps{Location services\nenabled?}
    CheckGps -->|No| E3[❌ GPS-ERROR-003\nDisabled location]
    CheckGps -->|Yes| CheckPerm{ACCESS_FINE_LOCATION\ngranted?}

    CheckPerm -->|No| E4[❌ GPS-ERROR-004\nNo location permission]
    CheckPerm -->|Yes| GetLoc[📍 getCurrentLocation\nPriority: HIGH_ACCURACY\nTimeout: location_timeout_ms]

    GetLoc -->|Timeout| E1[❌ GPS-ERROR-001\nGPS timeout]
    GetLoc -->|Success| CheckNull{Location\n== null?}

    CheckNull -->|Yes| E2[❌ GPS-ERROR-002\nNull location]
    CheckNull -->|No| ExtractData[📊 Extract\nlocation_lat_output\nlocation_long_output\nlocation_accuracy_output]

    ExtractData --> Success([✅ LocationTaskResult])

    E1 --> Error([❌ Exception])
    E2 --> Error
    E3 --> Error
    E4 --> Error

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Error fill:#ffcdd2
    style ExtractData fill:#fff9c4
    style GetLoc fill:#f3e5f5
    style E1 fill:#ffcdd2
    style E2 fill:#ffcdd2
    style E3 fill:#ffcdd2
    style E4 fill:#ffcdd2

How it works:

1. Check location services: Throws GPS-ERROR-003 if GPS is disabled on the device
2. Permission check: Throws GPS-ERROR-004 if ACCESS_FINE_LOCATION is not granted
3. GPS request: Gets the current position with high accuracy via FusedLocationProviderClient
4. Wait with timeout: Throws GPS-ERROR-001 if GPS does not respond within location_timeout_ms
5. Null check: Throws GPS-ERROR-002 if the GPS provider returns a null location
6. Extract data: Retrieves latitude → location_lat_output, longitude → location_long_output, accuracy → location_accuracy_output
7. Result: Returns LocationTaskResult on success

---

Input parameter details

1. Input parameter: location_timeout_ms

Maximum time (in milliseconds) to wait for a valid GPS fix before throwing GPS-ERROR-001.

Example

"location_timeout_ms": 15000

• Default: 10000 ms
• Recommended values: 5000–30000 ms

---

Output parameter details

2. Result variable: location_lat_output

Stores the latitude value returned by the GPS provider.

Example

"location_lat_output": "$LATITUDE"

---

3. Result variable: location_long_output

Stores the longitude value returned by the GPS provider.

Example

"location_long_output": "$LONGITUDE"

---

4. Result variable: location_accuracy_output

Stores the accuracy of the location fix in meters (rounded to 3 decimal places).

Example

"location_accuracy_output": "$ACCURACY"

• Lower value = better accuracy.

---

Complete JSON example

{
  "GetCurrentLocation": [
    {
      "id": "-1",
      "title": "Get Current Location",
      "location_timeout_ms": 15000,
      "location_lat_output": "$LATITUDE",
      "location_long_output": "$LONGITUDE",
      "location_accuracy_output": "$ACCURACY"
    }
  ]
}