# \*Android - ELM API

## Getting Started

First of all you should enable working with ELM feature on initialization step:

{% code title="Your Application class" %}

```kotlin
**
* Default Setting constructor
* Stop tracking time is 5 minute.
* Parking radius is 100 meters.
* Auto start tracking is true.
* hfOn - true if HIGH FREQUENCY data recording from sensors (acc, gyro) is ON and false otherwise.
* isElmOn - true <- to enable ELM  
*/
val settings = Settings(Settings.stopTrackingTimeHigh, Settings.accuracyHigh, true, true, true)

TrackingApi.getInstance().initialize(this, settings)
```

{% endcode %}

## Bluetooth Low Energy (BLE)

Feature will not work if smartphone doesn't support **Bluetooth Low Energy**.

First of all check it by this way:

```kotlin
if (!packageManager.hasSystemFeature(PackageManager.FEATURE_BLUETOOTH_LE)) {
   // inform user about his device doesn't support BLE
 }
```

If smartphone supports BLE you should turn it ON:

```kotlin
// get Bluetooth adapter and check is it enabled or not
val mBluetoothAdapter = BluetoothUtils.getBluetoothAdapter(this)
mBluetoothAdapter?.let {
    if (!mBluetoothAdapter.isEnabled) {
        // ask user to enable Bluetooth if it's off
        val intent = Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE)
        startActivityForResult(intent, Constants.REQUEST_BLUETOOTH_ENABLE_CODE)
    } else {
        // Bluetooth is enabled already
    }
}

...

// handle result of Bluetooth enable
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    if (requestCode == Constants.REQUEST_BLUETOOTH_ENABLE_CODE && resultCode == Activity.RESULT_OK) {
            // Bluetooth successfully enabled
    } else {
        // user didn't enabled Bluetooth
    }
    super.onActivityResult(requestCode, resultCode, data)
}
    
```

## Register a callback

If smartphone supports BLE and it's turned on you can scan ELM-devices and connect to it .

All interaction with ELM-devices are realised inside `VehicleElmManager` . You can get it by:

```kotlin
TrackingApi.getInstance().getElmManager()
```

To receive a callbacks from `VehicleElmManager` you should register a `ElmLinkingListener` .

It has 4 methods inside:

* `onScanningComplete` - method will be called after successfull devices searching. It has a list of founded devices inside.
* `onScanningFailed` - method will be called if error occures when scanning BLE-devices. Method has inside an error that you can handle like in example below.
* `onLinkingComplete` - method will be called when smartphone was successfully paired with ELM-device. Returnes token of the vehicle and ELM-device Mac-address string.
* `onLinkingFailed` - method will be called if some error occures during connection process.&#x20;

  Method has inside an error that you can handle like in example below.

```kotlin

// initialize callback
val elmLinkingLister = object : ElmLinkingListener {
		override fun onScanningComplete(foundDevices: List<ElmDevice>) {
			// choose your device from foundedDevices list
		}

		override fun onScanningFailed(error: ElmLinkingError) {
			// error occurred during the scanning
			when (error) {
				ElmLinkingError.SERVER_ERROR_NETWORK_CONNECTION_NOT_AVAILABLE-> {
					// network error, check your connection and try again
				}
				ElmLinkingError.SERVER_ERROR_UNKNOWN -> {
					// error on server side, try again or contact the support
				}
				else -> {
					// unknown error, try again
				}
			}
		}

		override fun onLinkingFailed(error: ElmLinkingError) {
			// error occurred when device was pairing with smartphone
			when (error) {
				ElmLinkingError.SERVER_ERROR_NETWORK_CONNECTION_NOT_AVAILABLE-> {
					// network error, check your connection and try again
				}
				ElmLinkingError.SERVER_ERROR_UNKNOWN -> {
					// error on server side, try again or contact the support
				}
				ElmLinkingError.VEHICLE_NOT_SUPPORTED -> {
					// not supported vehicle
				}
				else -> {
					// unknown error, try again
				}
			}
		}

		override fun onLinkingComplete(vehicleToken: String, elmMAC: String) {
			// elm device was successfully paired with vehicle.
		}
	}
```

After that you should register it:

```kotlin
TrackingApi.getInstance().getElmManager()?.registerLinkingListener(elmLinkingLister)
```

**Important!** Dont forget to unregister a callback when it isn't needed to avoid memory leaks:

```kotlin
TrackingApi.getInstance().getElmManager()?.unregisterLinkingListener()
```

## Scan devices

After successfully registering a callback to `VehicleElmManager` you can start a devices scanning:

```
TrackingApi.getInstance().getElmManager()?.getElmDevices()
```

`getElmDevices` method will scan Bluetooth devices and submit them to `onScanningComplete` method . After that you should choose your ELM-device from the list. If something went wrong error will be submitted to `onScanningFailed` method of the callback.

## Connect to ELM device

For further work you should have registered vehicle(-s) on your account. More information about managing vehicles you can find [here](/platform-features/car-service.md).

First of all you should get list of the registered vehicles:

```kotlin
TrackingApi.getInstance().getElmManager()?.getVehicles()
```

{% hint style="danger" %}
You should call this method on a separate thread. \
Otherwise `android.os.NetworkOnMainThreadException`will be thrown
{% endhint %}

It will return an array of registered vehicles (`Array<RegisteredVehicle>`).

Choose you vehicle from the list and connect it to ELM-device (that you found on scanning step):

```kotlin
TrackingApi.getInstance().getElmManager()?.connectAndRegisterDevice(device.deviceMacAddress!!, selectedCar.token)
```

You should pass to `connectAndRegisterDevice` method two parameters:

1. ELM-device mac-Address (`String`)
2. Car token (`String`)

Method will pair Bluetooth device with your car and submit the result to `onLinkingComplete` method of the callback. If something went wrong error will be submitted to `onLinkingFailed` method of the callback.

## Get information about session

You can get info about session:

```kotlin
TrackingApi.getInstance().getElmManager()?.getLastSession()?.let { info: Pair<Boolean, Long> ->
   // handle result
}
```

It has inside a `Pair<Boolean, Long>` where:

* fisrt - `Boolean` flag about is ELM-connected
* second - `Long` is a UNIX-timestamp when ELM device was connected

**Happy coding!**


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-old.telematicssdk.com/sdk-features/bluetooth-obd/android-elm-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.