Kotlin OBD API

You can install the library using Gradle (Kotlin or Groovy) or Maven by adding the JitPack repository and the dependency. For manual installation, download the JAR from the GitHub releases page.

### Gradle (Kotlin DSL)
```kotlin
repositories {
  maven("https://jitpack.io")
}

dependencies {
  implementation("com.github.eltonvs:kotlin-obd-api:1.4.1")
}

Gradle (Groovy)

repositories {
  maven { url 'https://jitpack.io' }
}

dependencies {
  implementation 'com.github.eltonvs:kotlin-obd-api:1.4.1'
}

Maven

<repositories>
  <repository>
      <id>jitpack.io</id>
      <url>https://jitpack.io</url>
  </repository>
</repositories>

<dependency>
  <groupId>com.github.eltonvs</groupId>
  <artifactId>kotlin-obd-api</artifactId>
  <version>1.4.1</version>
</dependency>

To use the library, you must provide an InputStream and an OutputStream (representing your transport layer, such as Bluetooth or Serial) to the ObdDeviceConnection constructor. You can optionally provide an ioDispatcher (defaults to Dispatchers.IO).

Note: Reuse one ObdDeviceConnection instance per physical adapter/session. Do not execute commands in parallel against the same connection instance, as commands are serialized internally via a Mutex.

val obdConnection = ObdDeviceConnection(inputStream, outputStream, Dispatchers.IO)

When connecting to an ELM327 adapter, it is recommended to run a sequence of setup commands to ensure a clean state and consistent behavior. You may also need to explicitly select a protocol if ObdProtocols.AUTO does not work for your specific vehicle.

// Standard initialization sequence
obdConnection.run(ResetAdapterCommand())
obdConnection.run(SetEchoCommand(Switcher.OFF))
obdConnection.run(SetLineFeedCommand(Switcher.OFF))
obdConnection.run(SetSpacesCommand(Switcher.OFF))
obdConnection.run(SetHeadersCommand(Switcher.OFF))
obdConnection.run(SetAdaptiveTimingCommand(AdaptiveTimingMode.AUTO_1))

// Optional: Explicit protocol selection
obdConnection.run(SelectProtocolCommand(ObdProtocols.AUTO))

The library uses a hierarchy of runtime exceptions under BadResponseException to signal failures. For robust applications, wrap run() calls in try-catch blocks to handle these specific errors:

• NoDataException: No data was returned.
• UnableToConnectException: Connection to the adapter failed.
• BusInitException: Error initializing the vehicle bus.
• MisunderstoodCommandException: The adapter did not understand the command.
• UnknownErrorException: An unspecified error occurred.
• UnSupportedCommandException: The command is not supported by the adapter/vehicle.

Below are common patterns for interacting with vehicle data using the library.

Read live telemetry:

val rpm = obdConnection.run(RPMCommand())
val speed = obdConnection.run(SpeedCommand())

Read VIN once and cache: Use useCache = true for static data like the VIN to avoid redundant requests.

val vin = obdConnection.run(VINCommand(), useCache = true)

Read and clear DTC (Trouble Codes):

val currentCodes = obdConnection.run(TroubleCodesCommand())
obdConnection.run(ResetTroubleCodesCommand())

The primary way to interact with the adapter is the suspend fun run(...) method. It executes a command and returns an ObdResponse.

Parameters:

• command: ObdCommand: The specific OBD command to execute.
• useCache: Boolean = false: If true, the result is cached using a key composed of the command class and the raw command.
• delayTime: Long = 0: Delay before execution.
• maxRetries: Int = 5: Number of retries. This maps to a legacy response timeout budget of maxRetries * 500ms.

Concurrency: Always call run() from a background coroutine context (e.g., Dispatchers.IO). On Android, never call run() on the main thread.

val response = obdConnection.run(
    command = RPMCommand(),
    useCache = false,
    delayTime = 0,
    maxRetries = 5
)

To create a custom command, extend ObdCommand and provide the required fields. You can optionally provide a handler to parse the ObdRawResponse into a human-readable string.

class CustomCommand : ObdCommand() {
    // Required
    override val tag = "CUSTOM_COMMAND"
    override val name = "Custom Command"
    override val mode = "01"
    override val pid = "FF"

    // Optional
    override val defaultUnit = ""
    override val handler = { response: ObdRawResponse ->
        "Calculated value from ${response.processedValue}"
    }
}

The run method executes an ObdCommand on the connection. It accepts the following parameters:

• command: Any ObdCommand instance.
• useCache (default false): If true, reuses previous raw responses for identical commands.
• delayTime (default 0): Delay in milliseconds after sending the command.
• maxRetries (default 5): Legacy compatibility timeout budget, mapped internally to maxRetries * 500ms.

The ObdRawResponse object contains the unprocessed data from the vehicle: