How to change Bluetooth device for Android

This article describes the integration steps required to connect to a Bluetooth^® device. It deals mainly with the Android^TM impact of integrating the new Bluetooth solution. It is intended for Distribution Package users.

1. Prerequisites

The environment must be installed using the Distribution Package adapted to the selected microprocessor device. See the list of Android Distribution Packages.

The Bluetooth (BT) device must be connected to the microprocessor device fitted to the board (generally through SDIO, UART or USB).

2. Overview

The Android Bluetooth software stack contains:

• Bluetooth Driver (hardware dependent) → device driver providing access to the Bluetooth hardware device through HCI sockets of the Bluetooth family (AF_BLUETOOTH / BTPROTO_HCI, hci0 interface).
• Bluetooth HAL (bluetooth) → Android native component implementing the Android Bluetooth HIDL (Hardware Interface Definition Language) on top of the kernel Bluetooth subsystem, used by the Bluetooth stack.
• Bluetooth Fluoride Stack (libbluetooth.so) → native Bluetooth stack built as a shared library. The stack integrates its own implementation of all required profiles and transport protocols, only using the HCI support of the host system through the HIDL offered by the Bluetooth HAL to communicate with the Bluetooth device.
• Bluetooth system service → Bluetooth application providing managed level Bluetooth profiles and services. The application uses JNI to load and run the Fluoride stack and exposes itself to the rest of the system through a system service implementing the Bluetooth AIDL (Android Interface Definition Language).
• Framework Bluetooth API → android.bluetooth APIs providing applications with framework level access to the Bluetooth subsystem. Internally, the code uses client side Bluetooth AIDL to interact with the Bluetooth system service exposed by the Bluetooth application through the Binder IPC mechanism.

Please see the Android Bluetooth guide for complementary information.

3. Integration Steps

The Bluetooth solution must be integrated in three steps:

• Linux^® kernel integration
• Android integration
• Validation

3.1. Linux kernel integration

The Bluetooth kernel integration is performed in two steps:

• Add the Bluetooth driver to the compilation process
• Update the device tree

3.1.1. Compile the Linux Bluetooth driver

The Bluetooth device is accessed through a dedicated driver (HCI sockets, hci0 interface).

Bluetooth support must be enabled in the kernel configuration.

CONFIG_BT=y → always needed
CONFIG_BT_HCIUART=y → in case of a Bluetooth device - microprocessor connection through UART
CONFIG_BT_HCIBTUSB=y → in case of a Bluetooth device - microprocessor connection through USB (Bluetooth dongle)
CONFIG_BT_HCIBTSDIO=y → in case of a Bluetooth device - microprocessor connection through SDIO

There are two Bluetooth device driver module configuration options:

• The driver is part of the Linux^® kernel sources → add the corresponding kernel configuration (ex: CONFIG_BT_HCIBTUSB_RTL=y for the Realtek BT USB dongle). Refer to Updating the kernel configuration for more information.
• The driver is provided separately → add it to the build_kernel.sh script

3.1.2. Update the Linux device tree

Depending on the selected driver, a device tree update may be required (refer to Changing the Device Tree for more information).

3.2. Android integration

The Android Bluetooth device integration is performed in several steps:

• Add permissions to allow the initialization of the appropriate Android services
• Add the Bluetooth HAL (Hardware Abstraction Layer)
• Add a Bluetooth firmware if required by your Bluetooth device
• Configure the Bluetooth stack

3.2.1. Add Android permissions

The following permission files should be present to ensure that the Bluetooth services are started correctly:

• android.hardware.bluetooth.xml for Bluetooth services
• android.hardware.bluetooth_le.xml for Bluetooth Low Energy services

The following lines will have to be added to the the device.mk:

 PRODUCT_COPY_FILES += \
 frameworks/native/data/etc/android.hardware.bluetooth.xml:system/etc/permissions/android.hardware.bluetooth.xml \
 frameworks/native/data/etc/android.hardware.bluetooth_le.xml:system/etc/permissions/android.hardware.bluetooth_le.xml \

3.2.2. Add the Bluetooth HAL (Hardware Abstraction Layer)

The HAL must be regenerates and the appropriate Bluetooth device vendor library must be available when generating it.

A Linux^® generic Bluetooth vendor library is available in system/bt/vendor_libs/. It is convenient to use this library for devices fully controlled through the Linux^® HCI socket abstraction. However, to take full advantage of all the device's functionality, the dedicated device vendor library should be used when available.

The file BoardConfig.mk must be updated in consequence:

 BOARD_HAVE_BLUETOOTH := true
 # Select BT vendor library
 BOARD_HAVE_BLUETOOTH_LINUX := true → enable Linux generic libbt-vendor generation
 # BOARD_HAVE_BLUETOOTH_<provider> := true → uncomment for a libbt-vendor dedicated to selected provider devices

3.2.3. Add the Bluetooth device firmware

Depending on the Bluetooth solution, the device may need to be loaded.

The firmware must be copied to the correct target directory, which can be configured through the kernel command line. For that purpose, add in BoardConfig.mk the following line:

 BOARD_KERNEL_CMDLINE += firmware_class.path=/vendor/firmware

The firmware must be added to the ramdisk (rootfs) to ensure that it is available during the first stage of the initialization

 PRODUCT_COPY_FILES += \
 device/stm/$(SOC_FAMILY)/$(BOARD_NAME)/network/bt/<bt_firmware>.bin:root/vendor/firmware/<bt_path>/<bt_firmware>.bin \
 device/stm/$(SOC_FAMILY)/$(BOARD_NAME)/network/bt/<bt_firmware>.bin:${TARGET_COPY_OUT_VENDOR}/firmware/<bt_path>/<bt_firmware>.bin

Note: if the driver is compiled as a module (.ko) and loaded after the on post-fs tag, it is not necessary to add the firmware to the rootfs

3.2.4. Configure the Android service

The Android distribution needs to be configured using How to configure Android distribution (Bluetooth)

3.3. Validation

The Bluetooth validation can be performed in several steps:

• Validate Kernel integration
• Validate Bluetooth connection using standard Android user interface
• Check Bluetooth Android compliance (CTS)

3.3.1. Validate the Kernel Integration

By default, there are no specific tools available to validate Bluetooth Android distribution connection. The BlueZ tool can be used, loading the associated source:

• btmgmt (or hciconfig for older version): used to configure local HCIi devices
• hcitool: used to scan, find a remote device, connect to a remote device, manage device lists...

3.3.2. Check the Bluetooth connection

Enable Bluetooth in Android Settings and connect to a known Bluetooth device (see Android One available answers for more information).

3.3.3. Validate the Android Integration

Several tests are available, refer to the official documents listed below:

• VTS
• CTS

4. References

Android is a trademark of Google LLC

BlueTooth

Secure digital input/output

Universal Asynchronous Receiver/Transmitter

GPIO alternate function

Hardware Abstraction Layer

HAL interface definition language (see https://source.android.com/devices/architecture/hidl)

Java Native Interface (for Android)

Android Interface Definition Language (see https://developer.android.com/guide/components/aidl)

Application programming interface

Inter-Processor Communication

Linux^® is a registered trademark of Linus Torvalds.

Compatibility Test Suite (Android specific) or Clear to send (in UART context)

Vendor Test Suite (Android specific)