OBDII API: A Developer’s Gateway to Vehicle Data

For automotive software developers and car enthusiasts, accessing real-time vehicle data is crucial. The Obdii Api provides a standardized way to retrieve this information, opening up possibilities for innovative applications, from performance monitoring to advanced diagnostics. This article introduces a lightweight, developer-centric OBDII API library built with Kotlin, designed to simplify interaction with your car’s onboard diagnostics system.

Why Choose a Kotlin OBDII API?

Kotlin, known for its conciseness and interoperability with Java, offers an excellent platform for developing robust and efficient OBDII API solutions. This particular Kotlin OBDII API library is engineered to be platform-agnostic, ensuring compatibility across various systems. Its straightforward interface allows developers to seamlessly integrate OBDII functionality into their projects, regardless of the underlying connection method. Whether you’re using Bluetooth, WiFi, or USB to connect to your vehicle’s OBDII port, this API provides the flexibility you need.

Installation Guide

Integrating the Kotlin OBDII API into your project is a breeze with multiple installation options:

Gradle Setup

For Gradle-based projects, add the JitPack repository to your root build.gradle file:

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

Next, include the OBDII API dependency in your module’s build.gradle file:

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

Maven Configuration

For Maven projects, add the JitPack repository to your pom.xml:

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

Then, add the OBDII API dependency:

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

Manual Installation

Alternatively, you can download the JAR file directly from the GitHub releases page and include it in your project.

Basic Usage of the OBDII API

To start using the OBDII API, you need to establish a connection with your vehicle’s OBDII interface. This typically involves obtaining InputStream and OutputStream from your chosen connection method (e.g., Bluetooth). Once you have these, create an ObdDeviceConnection instance:

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

With the ObdDeviceConnection established, you can execute OBDII commands using the .run() method. This method accepts an ObdCommand instance, along with optional parameters for caching and delay.

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

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

// Command with a delay of 500ms, useful for certain scenarios
val delayedResponse = obdConnection.run(RPMCommand(), delayTime = 500L)

The .run() method returns an ObdResponse object, which contains parsed data and raw response details.

Attribute	Type	Description
command	ObdCommand	The original command executed.
rawResponse	ObdRawResponse	The raw response data received from the vehicle’s OBDII system.
value	String	The parsed value of the OBDII command.
unit	String	The unit of the parsed value (e.g., “Km/h”, “RPM”).

The ObdRawResponse provides deeper insight into the communication with the OBDII interface:

Attribute	Type	Description
value	String	The raw hexadecimal value received.
elapsedTime	Long	Time taken (in milliseconds) to execute the command.
processedValue	String	Raw hexadecimal value with noise characters removed.
bufferedValue	IntArray	Raw hexadecimal value represented as an integer array.

Extending the OBDII API with Custom Commands

One of the key strengths of this OBDII API is its extensibility. Adding custom OBDII commands is straightforward. Create a new class that inherits from ObdCommand and override the necessary properties and the handler function:

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

    // Optional properties
    override val defaultUnit = ""
    override val handler = { rawResponse: ObdRawResponse ->
        "Calculations to parse value from ${rawResponse.processedValue}"
    }
}

Pre-built OBDII Commands

This OBDII API library includes a range of pre-defined commands for common OBDII Parameter IDs (PIDs). Here are a few examples of supported sensors. For a comprehensive list, refer to the SUPPORTED_COMMANDS.md file in the repository.

• Available PIDs
• Vehicle Speed
• Engine RPM
• Diagnostic Trouble Code (DTC) Count
• Trouble Codes (Current, Pending, and Permanent)
• Throttle Position
• Fuel Pressure
• Timing Advance
• Intake Air Temperature
• Mass Air Flow (MAF) Rate
• Engine Run Time
• Fuel Level Input
• MIL (Malfunction Indicator Lamp) Status
• Vehicle Identification Number (VIN)

Note: OBDII command support can vary between vehicle makes and models.

Contributing to the OBDII API Project

This Kotlin OBDII API is an open-source project, and contributions are welcome! If you have improvements, new features, or bug fixes to contribute, please feel free to submit pull requests or raise issues on the GitHub repository.

Versioning and Licensing

The project follows Semantic Versioning. You can find the available versions in the tags section of the repository.

This project is licensed under the Apache 2.0 License. See the LICENSE file for complete license details.

Acknowledgements

We extend our gratitude to all contributors and the open-source community for their support in making this OBDII API library a valuable resource for developers.

[