Kotlin OBD API

A lightweight and developer-driven API to query and parse OBD commands.

Written in pure Kotlin and platform agnostic with a simple and easy to use interface, so you can hack your car without any hassle. 🚙

This is a flexible API that allows developers to plug-in to any connection interface (Bluetooth, Wifi, USB...). By default we use an ObdDeviceConnection that receives an InputStream and an OutputStream as parameters (so if you can get this from your connection interface, you're good to go 👍).

Installation

Gradle

In your root build.gradle file, at the end of repositories:

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

Add the dependency

dependencies {
  ...

  // Kolin OBD API
  implementation 'com.github.eltonvs:kotlin-obd-api:1.3.0'
}

Maven

Add jitpack to the repositories section

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

Add the dependency

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

Manual

You can download a jar from GitHub's releases page.

Basic Usage

Get an InputStream and an OutputStream from your connection interface and create an ObdDeviceConnection instance.

// Create ObdDeviceConnection instance
val obdConnection = ObdDeviceConnection(inputStream, outputStream)

With this, you're ready to run any command you want, just pass the command instance to the .run method. This command accepts 3 parameters: command, useCache (default = false) and delayTime (default = 0).

// Retrieving OBD Speed Command
val response = obdConnection.run(SpeedCommand())

// Using cache (use with caution)
val cachedResponse = obdConnection.run(VINCommand(), useCache = true)

// With a delay time - with this, the API will wait 500ms after executing the command
val delayedResponse = obdConnection(RPMCommand(), delayTime = 500L)

The retuned object is a ObdResponse and has the following attributes:

Attribute	Type	Description
command	ObdCommand	The command passed to the run method
rawResponse	ObdRawResponse	This class holds the raw data returned from the car
value	String	The parsed value
unit	String	The unit from the parsed value (e.g.: Km/h, RPM, ...

The ObdRawResponse has the following attributes:

Attribute	Type	Description
value	String	The raw value (hex)
elapsedTime	Long	The elapsed time (in milliseconds) to run the command
processedValue	String	The raw (hex) value without whitespaces, colons or any other "noise"
bufferedValue	IntArray	The raw (hex) value as a IntArray

Extending the library

It's easy to add a custom command using this library, all you need to do is create a class extending the ObdCommand class and overriding the following methods:

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 = { it: ObdRawResponse -> "Calculations to parse value from ${it.processedValue}" }
}

Commands

Here are a handul list of the main supported commands (sensors). For a full list, see here.

• Available Commands
• Vehicle Speed
• Engine RPM
• DTC Number
• Trouble Codes (Current, Pending and Permanent)
• Throttle Position
• Fuel Pressure
• Timing Advance
• Intake Air Temperature
• Mass Air Flow Rate (MAF)
• Engine Run Time
• Fuel Level Input
• MIL ON/OFF
• Vehicle Identification Number (VIN)

NOTE: Support for those commands will vary from car to car.

Contributing

Want to help or have something to add to the repo? problem on a specific feature?

• Open an issue to explain the issue you want to solve Open an issue
• After discussion to validate your ideas, you can open a PR or even a draft PR if the contribution is a big one Current PRs

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Elton Viana - Initial work - Also created the java-obd-api

See also the list of contributors who participated in this project.

License

This project is licensed under the Apache 2.0 License - See the LICENCE file for more details.

Acknowledgments

• Paulo Pires - Creator of the obd-java-api, on which the initial steps were based.
• SmartMetropolis Project (Digital Metropolis Institute - UFRN, Brazil) - Backed and sponsored the project development during the initial steps.
• Ivanovitch Silva - Helped a lot during the initial steps and with the OBD research.