How to change Bluetooth device for Android
This article describes the integration steps required to connect to a BluetoothTM device. It deals mainly with the AndroidTM impact of integrating the new BluetoothTM solution. It is intended for Distribution Package users.
- 1 Prerequisites
- 2 Overview
- 3 Integration Steps
- 3.1 Linux® kernel integration
- 3.2 AndroidTM integration
- 3.3 Validation
- 4 References
The environment must be installed using the Distribution Package adapted to the selected microprocessor device. See the list of AndroidTM Distribution Packages.
The BluetoothTM (BT) device must be connected to the microprocessor device fitted to the board (generally through SDIO, UART or USB).
The AndroidTM BluetoothTM software stack contains:
- BluetoothTM Driver (hardware dependent) → device driver providing access to the BluetoothTM hardware device through HCI sockets of the BluetoothTM family (AF_BLUETOOTH / BTPROTO_HCI, hci0 interface).
- BluetoothTM HAL (email@example.com) → AndroidTM native component implementing the AndroidTM BluetoothTM HIDL (Hardware Interface Definition Language) on top of the kernel BluetoothTM subsystem, used by the BluetoothTM stack.
- BluetoothTM Fluoride Stack (libbluetooth.so) → native BluetoothTM 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 BluetoothTM HAL to communicate with the BluetoothTM device.
- BluetoothTM system service → BluetoothTM application providing managed level BluetoothTM 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 BluetoothTM AIDL (AndroidTM Interface Definition Language).
- Framework BluetoothTM API → android.bluetooth APIs providing applications with framework level access to the BluetoothTM subsystem. Internally, the code uses client side BluetoothTM AIDL to interact with the BluetoothTM system service exposed by the BluetoothTM application through the Binder IPC mechanism.
Please see the AndroidTM BluetoothTM guide for complementary information.
3 Integration Steps
The BluetoothTM solution must be integrated in three steps:
- Linux® kernel integration
- AndroidTM integration
3.1 Linux® kernel integration
The BluetoothTM kernel integration is performed in two steps:
- Add the BluetoothTM driver to the compilation process
- Update the device tree
3.1.1 Compile the Linux® BluetoothTM driver
The BluetoothTM device is accessed through a dedicated driver (HCI sockets, hci0 interface).
BluetoothTM support must be enabled in the kernel configuration.
CONFIG_BT=y → always needed CONFIG_BT_HCIUART=y → in case of a BluetoothTM device - microprocessor connection through UART CONFIG_BT_HCIBTUSB=y → in case of a BluetoothTM device - microprocessor connection through USB (BluetoothTM dongle) CONFIG_BT_HCIBTSDIO=y → in case of a BluetoothTM device - microprocessor connection through SDIO
There are two BluetoothTM device driver module configuration options:
- The driver is part of the Linux® kernel sources → add the corresponding kernel configuration (ex:
CONFIG_RTL8723BU=yfor the Realtek RTL8723BU, for kernel version ≤ 4.9). Refer to Updating the kernel configuration for more information.
- The driver is provided separately → add it to the
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 AndroidTM integration
The AndroidTM BluetoothTM device integration is performed in several steps:
- Add permissions to allow the initialization of the appropriate AndroidTM services
- Add the BluetoothTM HAL (Hardware Abstraction Layer)
- Add a BluetoothTM firmware if required by your BluetoothTM device
- Configure the BluetoothTM stack
3.2.1 Add AndroidTM permissions
The following permission files should be present to ensure that the BluetoothTM services are started correctly:
android.hardware.bluetooth.xmlfor BluetoothTM services
android.hardware.bluetooth_le.xmlfor BluetoothTM Low Energy services
The following lines will have to be added to the the
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 BluetoothTM HAL (Hardware Abstraction Layer)
The HAL must be regenerates and the appropriate BluetoothTM device vendor library must be available when generating it.
A Linux® generic BluetoothTM 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.
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 BluetoothTM device firmware
Depending on the BluetoothTM 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=/etc/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/<STM32Series>/<BoardId>/network/bt/<bt_firmware>.bin:root/system/etc/firmware/<bt_path>/<bt_firmware>.bin \ device/stm/<STM32Series>/<BoardId>/network/bt/<bt_firmware>.bin:system/etc/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 AndroidTM service
The AndroidTM distribution needs to be configured using How to configure AndroidTM distribution (BluetoothTM)
The BluetoothTM validation can be performed in several steps:
- Validate Kernel integration
- Validate BluetoothTM connection using standard AndroidTM user interface
- Check BluetoothTM AndroidTM compliance (CTS)
3.3.1 Validate the Kernel Integration
By default, there are no specific tools available to validate BluetoothTM AndroidTM distribution connection. The BlueZ tool can be used, loading the associated source:
hciconfigfor 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 BluetoothTM connection
Enable BluetoothTM in AndroidTM Settings and connect to a known BluetoothTM device (see AndroidTM One available answers for more information).
3.3.3 Validate the AndroidTM Integration
Several tests are available, refer to the official documents listed below:
Secure digital input/output
Universal Asynchronous Receiver/Transmitter
GPIO alternate function
Hardware Abstraction Layer
Java Native Interface (for Android)
Application programming interface
Compatibility Test Suite (Android specific) or Clear To Send (in UART context)
Vendor Test Suite (Android specific) - NEW