Skip to content

Current Speed

Summary

  • Internal name: GetCurrentSpeed
  • Category: Location
  • Purpose: Measure the device's current speed in km/h using two GPS samples separated by a configurable interval.
  • 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
    • Location services must be enabled on the device

Detailed description

The GetCurrentSpeed task calculates the device's movement speed by taking two GPS samples separated by a configurable interval, then computing distance ÷ time.

It is used to:

  • Measure real-time speed (km/h)
  • Compute traveled distance (meters) over the sample interval
  • Filter GPS samples by accuracy threshold
  • Attach speed metrics to telemetry or monitoring reports

The task handles:

  • configurable GPS timeout (location_timeout_ms),
  • configurable sampling interval (sample_interval_ms),
  • maximum allowed GPS accuracy filtering (max_speed_accuracy_km_h),
  • calculation of speed in km/h and distance in meters (rounded to 3 decimal places).

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
sample_interval_ms Integer No Time in milliseconds Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 10000
max_speed_accuracy_km_h Integer No Accuracy threshold in meters Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 1000

Output parameters

Field Type Trigger condition Android Compatibility AndroMate Compatibility Default
speed_kmh_output Float When calculation is successful Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 <ANDROMATE_NULL_VALUE>
distance_m_output Float When calculation is successful Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 <ANDROMATE_NULL_VALUE>
accuracy_used_km_h_output Float When calculation is successful 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 location_timeout_ms.
GPS-ERROR-002 The GPS provider returned a null location.
GPS-ERROR-003 Location services are disabled on the device.
GPS-ERROR-004 The app does not have ACCESS_FINE_LOCATION permission.
GPS-ERROR-005 GPS accuracy exceeds max_speed_accuracy_km_h threshold.
GPS-ERROR-006 Time delta between the two GPS samples is too small (< 0.2 s) — speed cannot be computed reliably.

Execution flowchart

flowchart TD
    Start([▶ GetCurrentSpeed]) --> 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 permission]
    CheckPerm -->|Yes| GetA[📍 GPS sample A\nPriority: HIGH_ACCURACY\nTimeout: location_timeout_ms]

    GetA -->|Timeout| E1[❌ GPS-ERROR-001\nGPS timeout]
    GetA -->|Success| NullA{locA == null?}
    NullA -->|Yes| E2[❌ GPS-ERROR-002\nNull location]
    NullA -->|No| AccA{locA.accuracy >\nmax_speed_accuracy_km_h?}
    AccA -->|Yes| E5[❌ GPS-ERROR-005\nAccuracy too low]
    AccA -->|No| StoreA[⏱️ tA = System.nanoTime\nWait sample_interval_ms]

    StoreA --> GetB[📍 GPS sample B\nPriority: HIGH_ACCURACY\nTimeout: location_timeout_ms]
    GetB -->|Timeout| E1
    GetB -->|Success| NullB{locB == null?}
    NullB -->|Yes| E2
    NullB -->|No| AccB{locB.accuracy >\nmax_speed_accuracy_km_h?}
    AccB -->|Yes| E5
    AccB -->|No| Calc[🔢 tB = System.nanoTime\ndistanceM = locA.distanceTo locB\ndeltaSec = tB - tA / 1e9]

    Calc --> CheckDelta{deltaSec <= 0.2s?}
    CheckDelta -->|Yes| E6[❌ GPS-ERROR-006\nDelta too small]
    CheckDelta -->|No| Speed[speedKmh = distanceM / deltaSec × 3.6\nRound to 3 decimals]

    Speed --> Success([✅ GetSpeedTaskResult\nspeed_kmh_output\ndistance_m_output\naccuracy_used_km_h_output])

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

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Error fill:#ffcdd2
    style Calc fill:#fff9c4
    style Speed fill:#fff9c4
    style StoreA fill:#f3e5f5
    style E1 fill:#ffcdd2
    style E2 fill:#ffcdd2
    style E3 fill:#ffcdd2
    style E4 fill:#ffcdd2
    style E5 fill:#ffcdd2
    style E6 fill:#ffcdd2

How it works:

  1. Check location services: Throws GPS-ERROR-003 if GPS is disabled
  2. Permission check: Throws GPS-ERROR-004 if ACCESS_FINE_LOCATION is not granted
  3. GPS sample A: Gets first position — throws GPS-ERROR-001 on timeout, GPS-ERROR-002 if null, GPS-ERROR-005 if accuracy exceeds threshold
  4. Record time tA: Captures System.nanoTime() after sample A
  5. Wait: Sleeps for sample_interval_ms milliseconds
  6. GPS sample B: Same checks as sample A
  7. Record time tB: Captures System.nanoTime() after sample B
  8. Compute delta: deltaSec = (tB - tA) / 1e9 — throws GPS-ERROR-006 if < 0.2 s
  9. Compute speed: speedKmh = (distanceM / deltaSec) × 3.6
  10. Result: Returns GetSpeedTaskResult with speed_kmh_output, distance_m_output, accuracy_used_km_h_output (each rounded to 3 decimal places)

Input parameter details

1. Input parameter: location_timeout_ms

Maximum time (in milliseconds) to wait for each GPS sample before throwing GPS-ERROR-001.

"location_timeout_ms": 15000
  • Default: 10000 ms
  • Applied to both GPS sample A and GPS sample B independently.

2. Input parameter: sample_interval_ms

Wait time (in milliseconds) between GPS sample A and GPS sample B.

"sample_interval_ms": 5000
  • Default: 10000 ms (10 seconds)
  • Longer intervals improve speed accuracy for slow movements.

3. Input parameter: max_speed_accuracy_km_h

Maximum allowed GPS accuracy (in meters). Samples with accuracy worse than this value are rejected with GPS-ERROR-005.

"max_speed_accuracy_km_h": 50
  • Default: 1000 (very permissive — accepts nearly all GPS readings)
  • Lower values give more reliable measurements but may cause more GPS-ERROR-005 errors in poor GPS conditions.

Output parameter details

speed_kmh_output — Speed in km/h

Stores the calculated speed rounded to 3 decimal places.

"speed_kmh_output": "$SPEED_KMH"

distance_m_output — Distance in meters

Stores the distance traveled between the two GPS samples, in meters, rounded to 3 decimal places.

"distance_m_output": "$DISTANCE_M"

accuracy_used_km_h_output — GPS accuracy used

Stores the worst GPS accuracy among the two samples (in meters), rounded to 3 decimal places.

"accuracy_used_km_h_output": "$GPS_ACCURACY"

Complete JSON example

{
  "GetCurrentSpeed": [
    {
      "id": "-1",
      "title": "Get Current Speed",
      "location_timeout_ms": 15000,
      "sample_interval_ms": 5000,
      "max_speed_accuracy_km_h": 100,
      "speed_kmh_output": "$SPEED_KMH",
      "distance_m_output": "$DISTANCE_M",
      "accuracy_used_km_h_output": "$GPS_ACCURACY"
    }
  ]
}