This article describes the integration steps required to connect to a Bluetooth® device. It deals mainly with the AndroidTM impact of integrating the new Bluetooth solution. It is intended for Distribution Package users.
1. Prerequisites[edit source]
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[edit source]
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[1] for complementary information.
3. Integration Steps[edit source]
The Bluetooth solution must be integrated in three steps:
- Linux® kernel integration
- Android integration
- Validation
3.1. Linux kernel integration[edit source]
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[edit source]
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=yfor 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.shscript
3.1.2. Update the Linux device tree[edit source]
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[edit source]
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[edit source]
The following permission files should be present to ensure that the Bluetooth services are started correctly:
android.hardware.bluetooth.xmlfor Bluetooth servicesandroid.hardware.bluetooth_le.xmlfor 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)[edit source]
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[edit source]
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[edit source]
The Android distribution needs to be configured using How to configure Android distribution (Bluetooth)
3.3. Validation[edit source]
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[edit source]
By default, there are no specific tools available to validate Bluetooth Android distribution connection. The BlueZ tool can be used, loading the associated source[2]:
btmgmt(orhciconfigfor older version): used to configure local HCIi deviceshcitool: used to scan, find a remote device, connect to a remote device, manage device lists...
3.3.2. Check the Bluetooth connection[edit source]
Enable Bluetooth in Android Settings and connect to a known Bluetooth device (see Android One available answers for more information[3]).
3.3.3. Validate the Android Integration[edit source]
Several tests are available, refer to the official documents listed below:
4. References[edit source]
Android is a trademark of Google LLC