:blue_car: A Kotlin OBD-II API for reading engine data
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. :blue_car:
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 :thumbsup:).
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'
}
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>
You can download a jar from GitHub's releases page.
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 |
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}" }
}
Here are a handul list of the main supported commands (sensors). For a full list, see here.
NOTE: Support for those commands will vary from car to car.
Want to help or have something to add to the repo? problem on a specific feature?
We use SemVer for versioning. For the versions available, see the tags on this repository.
See also the list of contributors who participated in this project.
This project is licensed under the Apache 2.0 License - See the LICENCE file for more details.