# \*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](https://docs-old.telematicssdk.com/platform-features/car-service).

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!**