Package com.tomtom.ivi.platform.bluetoothconnectivity.api.service.bluetoothconnectivity

This package contains the BluetoothConnectivityService interface which provides information about nearby Bluetooth devices, changes their connection state, and changes the policy of local Bluetooth profiles.

The Bluetooth connectivity service API

The Bluetooth connectivity service API provides properties and methods which allow the service to implement the following functionality:

1. #using-the-bluetooth-connectivity-service-api.

2. #bluetooth-device-information.

3. #creating-a-bond-with-a-bluetooth-device.

4. #connecting-and-disconnecting-from-a-bluetooth-device.

5. #changing-the-policy-of-a-local-bluetooth-device-profile.

Note: The Bluetooth connectivity service depends on the Android platform for maintaining Bluetooth devices and priority lists for each Bluetooth profile connection to the IVI platform. Devices are connected to profiles in a defined priority order according to this list. For more information, please read Android Automotive Bluetooth documentation.

Using the Bluetooth connectivity service API

To use the Bluetooth connectivity service, add a dependency to the BluetoothConnectivityService to your Gradle file:

dependencies {
    implementation("com.tomtom.ivi.platform:platform_bluetoothconnectivity_api_service_bluetoothconnectivity")
}

To get access to the BluetoothConnectivityService API, you need to first get a BluetoothConnectivityServiceApi instance by calling the companion function BluetoothConnectivityService.createApi.

val service = BluetoothConnectivityService.createApi(lifecycleOwner, iviServiceProvider)

Once you have a BluetoothConnectivityServiceApi instance, you can use it to call any API, and observe any property provided by the service.

Note: The service may not be ready when a client calls the service API, and could return a SERVICE_UNAVAILABLE result. It is possible to check the service availability by observing the serviceAvailable property:

service.serviceAvailable.observe(lifecycleOwner) {
    if (it) {
        // Service is available.
    } else {
        // Service is not available.
    }
}

Note: To prevent the Android platform system pairing dialog to be shown, the services which implement the Bluetooth connectivity interface should block incoming pairing request intents, by aborting the broadcast.

BroadcastReceiver.abortBroadcast()

Bluetooth device information

The BluetoothConnectivityService.deviceInformation property is a map of relevant Bluetooth device information. The information of a specific Bluetooth device can be retrieved by using its Bluetooth hardware address as a key.

The device information contains the following data:

• The name of the device.

• The major device class, which describes the general characteristics and capabilities of the Bluetooth device.

• The major service classes, which describe the general services of the Bluetooth device.

• The connectivity status of the Bluetooth device.

The connectivity status information can have one of the following bond states:

| Bond State   | Value      | Description                                                                              |
| ------------ | ---------- | ---------------------------------------------------------------------------------------- |
| Not paired   | `UNPAIRED` | The Bluetooth device does not have a bond with the IVI platform.                         |
| Being paired | `PAIRING`  | A pairing process is currently active between the Bluetooth device and the IVI platform. |
| Paired       | `PAIRED`   | The Bluetooth device has a bond with the IVI platform.                                   |

The connectivity status information can have the following connection state:

| Connection State | Value          | Description                                                 |
| ---------------- | -------------- | ------------------------------------------------------------|
| Disconnected     | `DISCONNECTED` | A Bluetooth device which is not connected via Bluetooth.    |
| Connected        | `CONNECTED`    | A nearby Bluetooth device which is connected via Bluetooth. |

Discovering nearby Bluetooth devices

Calling BluetoothConnectivityService.executeDiscoveryProcessOnce will start a discovery process. The process will add entries to the map of the BluetoothConnectivityService.deviceInformation property when a nearby Bluetooth device is found. The process will timeout after a period of approximately 12 seconds.

Note: When BluetoothConnectivityService.executeDiscoveryProcessOnce is called again, it will either add or update entries in BluetoothConnectivityService.deviceInformation. It will not remove any previously discovered devices, which allows clients to implement a seemingly indefinite discovery loop. Discovered devices can be removed by calling BluetoothConnectivityService.cleanupNeverPairedDevices.

Creating a bond with a Bluetooth device

A Bluetooth bond can be created by sending a pairing request to a nearby Bluetooth device by
calling BluetoothConnectivityService.startPairing. Once the pairing request has been sent, the connectivity status information for the particular Bluetooth device will reflect the bond state. See #bluetooth-device-information for more information about the bond state.

Connecting and disconnecting from a Bluetooth device

A connected Bluetooth device can be disconnected by calling BluetoothConnectivityService.disconnect. A nearby bonded, but disconnected, Bluetooth device can be connected by calling BluetoothConnectivityService.connect.

Changing the policy of a local Bluetooth device profile

The current local policy of a Bluetooth profile can be retrieved by calling
BluetoothConnectivityService.getProfileConnectionPolicy. The local Bluetooth device profile policy can be changed by calling BluetoothConnectivityService.setProfileConnectionPolicy. The supported policies are:

| Policy    | Value       | Description                                                                              |
| --------- | ----------- | ---------------------------------------------------------------------------------------- |
| Allowed   | `ALLOWED`   | Connection policy that allows incoming and outgoing connections for the profile.         |
| Forbidden | `FORBIDDEN` | Connection policy that does not allow incoming and outgoing connections for the profile. |

Note: Only the policy of the profiles which are provided by the BluetoothConnectivityService.connectableProfiles property can be changed. This property contains a list of Bluetooth profiles which can be (dis)connected and are supported by the platform.