Troubleshooting & Common Edge Cases

Find solutions to common integration hurdles, Android OEM background battery killers, and QA testing strategies for the Veg Sahayyak SDK.

---

🛑 1. ForegroundServiceStartNotAllowedException

Symptoms

App crashes on Android 12+ (API 31+) when calling SpeedAssistant.with(context, "YOUR_JWT_LICENSE").start() while the app is in the background.

Fatal Exception: android.app.ForegroundServiceStartNotAllowedException: 
Service.startForeground() not allowed due to mAllowStartForeground false

Cause

Android 12 strictly forbids starting foreground services while an application is in the background, with limited exceptions (e.g. high-priority FCM pushes, exact alarms).

Solution

Always invoke start() from an active foreground component (Activity or user interaction button), or verify isAppInForeground:

// Ensure start() is called when the driver is actively interacting with the UI
fun onStartTrackingClicked(activity: Activity) {
    if (SpeedPermissions(activity).hasPermission()) {
        SpeedAssistant.with(activity, "YOUR_JWT_LICENSE").start()
    } else {
        requestPermissions(activity)
    }
}

---

🔋 2. OEM Background Kills (Samsung, Xiaomi, Oppo)

Symptoms

The status bar speed notification disappears or freezes after the device screen has been turned off for several minutes.

Cause

Proprietary battery savers (Samsung Device Care, Xiaomi MIUI Battery Saver, Huawei PowerGenie) forcefully terminate background processes even if they run as foreground services.

Solutions

1. AutoStartManager (Recommended): Use the :speed-autostart module to leverage Google Play Services IN_VEHICLE transitions, which OEMs typically exempt from termination because they rely on the low-power sensor hub instead of CPU wakelocks.
2. Request Battery Optimization Exemption: Direct drivers to allow unconstrained background execution:

   val intent = Intent(Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS).apply {
       data = Uri.parse("package:${context.packageName}")
   }
   context.startActivity(intent)

3. Screen-Off Throttling: Configure the SDK to pause GPS during screen-off cycles if full background tracking is not strictly needed:

   SpeedAssistant.with(context, "YOUR_JWT_LICENSE").preferences.setUpdateWhileScreenOff(false)

---

🛰️ 3. Simulating Telemetry in Android Emulator & Local QA

Testing speed thresholds and alerts without a physical vehicle can be done using the following verified methods:

Option A: FakeSpeedRepository (Recommended for Local Dev & Tests)

For instant, deterministic speed simulation in ViewModels and Compose UI without waiting for GPS locks, use the FakeSpeedRepository:

val fakeRepo = FakeSpeedRepository()
SpeedAssistant.with(context, "YOUR_JWT_LICENSE").useRepository(fakeRepo).start()

// Emit 95 km/h over-speed violation
fakeRepo.emitSpeed(speedKmh = 95f, isOverLimit = true)

Option B: Android Studio Emulator Extended Controls (GPX Route Playback)

1. Open Emulator Extended Controls (...) → Location.
2. Click Routes and load a .gpx or .kml GPS route file.
3. Set playback speed to 1.0x or 2.0x and click Play Route.
4. The emulator streams live GPS coordinates, allowing FusedLocationProviderClient and SpeedGauge to animate smoothly in real time.

Option C: setMockLocation() Instrumentation

For programmatic end-to-end testing of FusedLocationProviderClient on test devices, see the End-to-End GPS Mocking Guide.

🏃 4. AutoStartManager Not Triggering

Symptoms

Trips are not starting automatically when the driver begins driving.

Cause & Solution

• Missing Google Play Services: AutoStartManager relies on the Google Play Services Activity Recognition API. If the device does not have Play Services installed (e.g., AOSP or Huawei HarmonyOS devices), the onError callback will trigger with an ApiException.
• Missing Permissions: Ensure the ACTIVITY_RECOGNITION permission is granted (Android 10+).

---

🎙️ 5. Voice Command Parsing Fails

Symptoms

The VoiceCommandButton spins or fails to parse actions like VoiceAction.SetProfile.

Cause & Solution

• Microphone Permission Denied: Ensure android.permission.RECORD_AUDIO is requested and granted at runtime before launching the voice recognizer intent.
• No Internet Connection: The default Android SpeechRecognizer requires an active internet connection on older API levels to perform transcription. Handle offline scenarios gracefully.

---

❓ FAQ

Does the SDK require Google Play Services?

Yes. The SDK leverages Google's FusedLocationProviderClient for optimal battery efficiency, and AutoStartManager requires the Activity Recognition API.

Why doesn't the Minimum Speed alert fire immediately when starting from 0 km/h?

The TelematicsEngine incorporates a startup safety guard. To prevent continuous, annoying alarms while parked, at stoplights, or pulling out of a driveway, the under-speed alert is only armed after the vehicle has initially accelerated past MinLimit + 3.0 km/h.

Can I override the default Notification layout?

Yes. You can supply custom notification channels and actions by interacting with SpeedAssistant.with(context, "YOUR_JWT_LICENSE").setWarningPendingIntent(...).