API Reference & KDoc

Complete Kotlin API specifications for public interfaces, builders, and data models in the Veg Sahayyak SDK.

---

🚀 SpeedAssistant

Singleton Builder package com.vegsahayyak.speedcore.api

The primary entry point to the telematics engine.

Builder & Lifecycle Methods

companion object.with(context: Context): SpeedAssistant

Retrieves or instantiates the singleton instance of SpeedAssistant. Automatically initializes core dependencies.

setWarningSpeedThreshold(limitInUserUnit: Float): SpeedAssistant

Sets the maximum speed ceiling. Converts user units to SI meters/second and updates TelematicsEngine.

setMinWarningSpeedThreshold(limitInUserUnit: Float): SpeedAssistant

Sets the minimum speed corridor limit.

setDrivingProfile(profile: DrivingProfile): SpeedAssistant

Applies a pre-configured or dynamic DrivingProfile and automatically resolves the ideal max and min speed limits according to the user's active unit.

setWarningPendingIntent(intent: PendingIntent): SpeedAssistant

Configures the PendingIntent fired when the driver breaks the speed threshold.

setColorScheme(colorScheme: SpeedColorScheme): SpeedAssistant

Configures custom brand colors for system notifications and alerts across the SDK.

useRepository(repository: ISpeedRepository): SpeedAssistant

Overrides the internal default SpeedRepositoryImpl with a custom implementation or test double (e.g. FakeSpeedRepository).

usePreferenceRepository(repository: IPreferenceRepository): SpeedAssistant

Overrides the internal persistent preferences repository with a custom implementation.

val tracker: ISpeedRepository

Direct accessor to the active speed repository instance.

val preferences: IPreferenceRepository

Direct accessor to the active persistent preferences repository instance.

start()

Starts the SpeedometerService foreground service and begins Fused Location Provider polling.

startIfEnabled(): Boolean

Checks user preferences and restarts the tracking service only if it was previously active. Returns true if started.

stop()

Halts the foreground service, removes location updates, and resets the TelematicsEngine.

companion object.observeFlow(): Flow<SpeedData>

Returns a Kotlin Coroutines Flow of real-time telematics updates.

---

🎨 SpeedColorScheme & SpeedUiColorScheme

Color Models package com.vegsahayyak.speedcore.api / package com.vegsahayyak.speedui.components

Data classes for branding SDK alerts and UI components.

data class SpeedColorScheme(
    @ColorInt val safeColor: Int = 0xFF00E676.toInt(),
    @ColorInt val warningApproachColor: Int = 0xFFFF9100.toInt(),
    @ColorInt val overSpeedColor: Int = 0xFFFF1744.toInt(),
    @ColorInt val underSpeedColor: Int = 0xFF00E5FF.toInt(),
    @ColorInt val warningGlowColor: Int = 0x88FF1744.toInt(),
    @ColorInt val needleColor: Int = 0xFF2979FF.toInt()
)

data class SpeedUiColorScheme(
    val safeColor: Color = Color(0xFF00E676),
    val warningApproachColor: Color = Color(0xFFFF9100),
    val overSpeedColor: Color = Color(0xFFFF1744),
    val underSpeedColor: Color = Color(0xFF00E5FF),
    val warningGlowColor: Color = Color(0x88FF1744),
    val needleColor: Color = Color(0xFF2979FF)
)

---

📡 SpeedData (Sealed Hierarchy)

Data Sealed Interface package com.vegsahayyak.speedcore.data.location

sealed interface SpeedData {
    data class SpeedChanged(
        val speedMps: Float,
        val isOverLimit: Boolean,
        val isUnderLimit: Boolean = false,
        val accuracyMeters: Float
    ) : SpeedData

    data class LowAccuracy(
        val reason: String
    ) : SpeedData

    object GPSDisabled : SpeedData
    object SpeedUnavailable : SpeedData
    object Disabled : SpeedData
}

---

📏 SpeedUnit

Enum package com.vegsahayyak.speedcore.units

Enum Constant	Label	MPS Conversion Factor	Gauge Max Scale	Major Step
KILOMETERS_PER_HOUR	km/h	3.6 × mps	180	20
METERS_PER_SECOND	m/s	1.0 × mps	50	10
MILES_PER_HOUR	mph	2.23694 × mps	120	20
FEET_PER_SECOND	ft/s	3.28084 × mps	160	20

Methods

• convertSpeed(metersPerSecond: Float): Float: Converts SI meters per second to the target unit.
• convertToMetersPerSecond(speedInUnit: Float): Float: Converts user-unit speed to SI m/s.

---

⚙️ TelematicsEngine

Internal Domain package com.vegsahayyak.speedcore.domain

Performs mathematical signal smoothing and state machine transitions.

data class TelematicsResult(
    val smoothedSpeedMps: Float,
    val isOverLimit: Boolean,
    val isUnderLimit: Boolean,
    val accuracyMeters: Float
)

• processLocation(rawSpeedMps: Float, accuracyMeters: Float): TelematicsResult?: Passes data to the C++ Native Vault which applies proprietary accuracy confidence gating, Exponential Moving Average smoothing, and Schmitt Trigger Hysteresis. Returns null if precision is insufficient.
• reset(): Flushes historical momentum states.

---

🗄️ ISpeedRepository & IPreferenceRepository

Interface Abstraction package com.vegsahayyak.speedcore.api

Repository abstractions allowing custom mock implementations for unit testing or integration testing.

interface ISpeedRepository {
    fun observeSpeed(): Flow<SpeedData>
    fun isEnable(): Boolean
    fun isLocationAvailable(): Boolean
    fun toggle(boolean: Boolean)
    fun enable()
    fun disable()
}

interface IPreferenceRepository {
    fun isRunning(): Boolean
    fun setRunning(value: Boolean)
    fun getUnit(): SpeedUnit
    fun setUnit(unit: SpeedUnit)
    fun isFirstRun(): Boolean
    fun setFirstRun(value: Boolean)
    fun getUpdateWhileScreenOff(): Boolean
    fun setUpdateWhileScreenOff(value: Boolean)
    fun getWarningSpeedThreshold(): Float
    fun setWarningSpeedThreshold(value: Float)
    fun getMinWarningSpeedThreshold(): Float
    fun setMinWarningSpeedThreshold(value: Float)
    fun setLocationPermissionRequested(value: Boolean)
    fun getLocationPermissionRequested(): Boolean
}

---

🪟 PipWidget & PipWidgetConfig

Composable / Model package com.vegsahayyak.speedoverlay

A floating, compact Picture-in-Picture (PiP) style speedometer designed to render over other apps (such as navigation or delivery apps) using SYSTEM_ALERT_WINDOW.

@Composable
fun PipWidget(
    speed: Float,
    unitLabel: String,
    isOverLimit: Boolean,
    modifier: Modifier = Modifier,
    isUnderLimit: Boolean = false,
    config: PipWidgetConfig = PipWidgetConfig()
)

data class PipWidgetConfig(
    val size: Dp = 100.dp,
    val safeColor: Color = Color(0xFF1FC95E),
    val warningColor: Color = Color(0xFFE31D23),
    val underSpeedColor: Color = Color(0xFF29B6F6),
    val backgroundColor: Color = Color(0x66000000), // Translucent dark glass
    val speedTextSize: TextUnit = 36.sp,
    val unitTextSize: TextUnit = 14.sp,
    val textColor: Color = Color.White
)

---

🚗 AutoStartManager

Plugin Utility package com.vegsahayyak.speedautostart

Manager object providing zero-friction background trip detection using Google Play Services Activity Recognition API.

object AutoStartManager {
    fun enable(
        context: Context,
        onPermissionRequired: () -> Unit,
        onSuccess: () -> Unit,
        onError: (Exception) -> Unit
    )
}

---

🚗 DrivingProfile

Sealed Class package com.vegsahayyak.speedcore.api

Pre-configured speed limit profiles for various vehicle classes and environments.

sealed class DrivingProfile {
    abstract val maxKmh: Float
    abstract val minKmh: Float
    abstract val maxMph: Float
    abstract val minMph: Float

    fun getMaxLimit(unit: SpeedUnit): Float
    fun getMinLimit(unit: SpeedUnit): Float

    object CarHighway : DrivingProfile()          // Max 120 km/h / 75 mph, Min 60 km/h / 40 mph
    object CarCity : DrivingProfile()             // Max 50 km/h / 30 mph, Min 0
    object Motorcycle : DrivingProfile()          // Max 120 km/h / 75 mph, Min 0
    object TruckHighway : DrivingProfile()        // Max 90 km/h / 60 mph, Min 50 km/h / 30 mph
    object BusCoach : DrivingProfile()            // Max 100 km/h / 65 mph, Min 50 km/h / 30 mph
    object TractorAgricultural : DrivingProfile() // Max 40 km/h / 25 mph, Min 0
    object EScooter : DrivingProfile()            // Max 20 km/h / 12.5 mph, Min 0
    object Bicycle : DrivingProfile()             // Max 25 km/h / 15 mph, Min 0
    object Walking : DrivingProfile()             // Max 8 km/h / 5 mph, Min 0
    object SchoolZone : DrivingProfile()          // Max 30 km/h / 20 mph, Min 0

    data class CustomProfile(
        val maxLimit: Float,
        val minLimit: Float,
        val unit: SpeedUnit
    ) : DrivingProfile()
}

---

🏎️ SpeedGauge & UI Models

Composable / Models package com.vegsahayyak.speedui.components / package com.vegsahayyak.speedui.models

Stateless hardware-accelerated speedometer gauge rendering with dynamic color schemes, theme presets, and screen reader accessibility.

enum class ThemeMode {
    SYSTEM,        // Follows system light/dark theme
    DARK_GRAY,     // Deep charcoal slate
    OLED_BLACK,    // Pure #000000 true black for OLED battery conservation
    HIGH_CONTRAST, // High-visibility bright yellow/white for direct sunlight
    HUD_MIRRORED   // Vertically inverted reflection mode
}

enum class UiSpeedUnit(val label: String) {
    KMH("km/h"),
    MPH("mph"),
    MPS("m/s"),
    FPS("ft/s")
}

@Composable
fun SpeedGauge(
    speed: Float,
    warningSpeed: Float,
    isTrackingActive: Boolean,
    isOverLimit: Boolean = false,
    modifier: Modifier = Modifier,
    minSpeedLimit: Float = 0f,
    maxSpeed: Float = SpeedGaugeTokens.DefaultMaxSpeed,
    unitLabel: String = "km/h",
    unitOptions: List<UiSpeedUnit> = UiSpeedUnit.entries,
    labelStep: Int = 20,
    onUnitSelected: ((Int) -> Unit)? = null,
    themeMode: ThemeMode = ThemeMode.SYSTEM,
    colorScheme: SpeedUiColorScheme? = null,
    showGpsAccuracy: Boolean = true,
    gpsAccuracyMeters: Float = -1f,
    isHudMirrored: Boolean = false
)

---

🌙 HudDisplay & Modifier.hudMirror

Composable / Modifier package com.vegsahayyak.speedui.components

Dedicated nighttime windshield projection component and transformation modifiers.

enum class HudMirrorAxis {
    VERTICAL,
    HORIZONTAL,
    BOTH
}

fun Modifier.hudMirror(
    isMirrored: Boolean = true,
    axis: HudMirrorAxis = HudMirrorAxis.VERTICAL
): Modifier

@Composable
fun HudDisplay(
    speed: Float,
    warningSpeed: Float,
    isTrackingActive: Boolean,
    modifier: Modifier = Modifier,
    minSpeedLimit: Float = 0f,
    isOverLimit: Boolean = false,
    unitLabel: String = "km/h",
    unitOptions: List<UiSpeedUnit> = UiSpeedUnit.entries,
    onUnitSelected: ((Int) -> Unit)? = null,
    isMirrored: Boolean = true,
    onToggleMirror: (() -> Unit)? = null,
    mirrorAxis: HudMirrorAxis = HudMirrorAxis.VERTICAL,
    colorScheme: SpeedUiColorScheme? = null,
    showGpsAccuracy: Boolean = true,
    gpsAccuracyMeters: Float = -1f
)

---

🎙️ VoiceCommandButton & VoiceCommandParser

Composable / Parser package com.vegsahayyak.speedui.components / package com.vegsahayyak.speedui.api

Hands-free STT transcription button and speech-intent parser interfaces.

sealed class VoiceAction {
    data class SetProfile(val profile: DrivingProfile) : VoiceAction()
    data class ChangeUnit(val unitName: String) : VoiceAction()
    object Unknown : VoiceAction()
}

interface VoiceCommandParser {
    suspend fun parse(text: String): VoiceAction?
    
    companion object {
        fun parse(text: String): VoiceAction
    }
}

@Composable
fun VoiceCommandButton(
    parser: VoiceCommandParser? = null,
    onCommandParsed: (VoiceAction) -> Unit,
    modifier: Modifier = Modifier
)