Guides
SIGN INSIGN UP

Setting up for Android app

Suggest Edits

Setting up the environment

First of all, you have to enable the Bluetooth OBD connection at initialization step:

**
* 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 bluetooth OBD connection  
*/
val settings = Settings(Settings.stopTrackingTimeHigh, Settings.accuracyHigh, true, true, true)

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

Check if the user's smartphone supports Bluetooth low energy.

📘

Bluetooth Low Energy (BLE) is required

Please, check whether the user's smartphone supports Bluetooth low energy. If it doesn't support BLE, you have to inform the user that his smartphone doesn't support that.

if (!packageManager.hasSystemFeature(PackageManager.FEATURE_BLUETOOTH_LE)) {
   // check whether the user smartphone supports BLE or not
 }

Turn on Bluetooth BLE 

// 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

📘

Bluetooth Low Energy (BLE) is required

If the user's smartphone supports BLE, and you turned it on, then you can scan a Bluetooth OBD device and connect it to the telematics SDK

All interactions with Bluetooth OBD run inside VehicleElmManager You can get it by:

TrackingApi.getInstance().getElmManager()

To receive a callback from VehicleElmManager you should register the ElmLinkingListener.
There are 4 methods inside:

  • onScanningComplete - the method will be called after the device searching completed successfully. It has a list of founded devices.
  • onScanningFailed - the method will be called if an error occurs during scanning Bluetooth OBD devices. The method has inside an error that you can process. Please refer to the example below.
  • onLinkingComplete - the method will be called once the user's smartphone has been successfully paired with the Bluetooth OBD device. It returns a vehicle token and Bluetooth OBD Mac-address string.
  • onLinkingFailed - the method will be called if an error occurs during the connection process.
    The method has inside an error that you can process. Please refer to the example below. 
// 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.
		}
	}

As the next step, you have to register the callback

Register callback

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

📘

Important

Don't forget to unregister the callback when it is not in use. It helps you to avoid memory leaks.

Unregister callback

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

Setting up the connection

1. Search Bluetooth device

Once you register the callback in VehicleElmManager you can start searching a Bluetooth OBD device.

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

getElmDevices method will scan Bluetooth OBD and submit them to onScanningComplete method. Then, you should choose your Bluetooth OBD from the list of available devices. If something went wrong, the error will be submitted to the callback onScanningFailed method.

2. Get a vehicle

Make sure you have a registered vehicle. If no, please refer to _Vehicle management 

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

📘

Important

You should call this method on a separate thread.
Otherwise android.os.NetworkOnMainThreadException will be thrown

It will return an array of registered vehicles with their car tokens Array<RegisteredVehicle>

3. Connect Bluetooth OBD to the vehicle (from the step above)

Choose your vehicle from the list and register the Bluetooth OBD from step 1 with the vehicle from step 2.

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

You should pass two parameters to connectAndRegisterDevice method:

  • ELM-device mac-Address (String)
  • Car token (String)
    The method will pair the Bluetooth OBD with your car and submit the result to the callback onLinkingComplete method. If something went wrong, an error will be submitted to onLinkingFailed method.

Get connection status

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

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

  • first - Boolean flag about is ELM-connected
  • second - Long is a UNIX-timestamp when Bluetooth OBD device was connected

Updated almost 3 years ago