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[edit source]
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).
2. Overview[edit source]
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 (bluetooth@1.0) → 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[1] for complementary information.
3. Integration Steps[edit source]
The BluetoothTM solution must be integrated in three steps:
- Linux® kernel integration
- AndroidTM integration
- Validation
3.1. Linux® kernel integration[edit source]
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[edit source]
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
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. AndroidTM integration[edit source]
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[edit source]
The following permission files should be present to ensure that the BluetoothTM services are started correctly:
android.hardware.bluetooth.xmlfor BluetoothTM servicesandroid.hardware.bluetooth_le.xmlfor BluetoothTM 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 BluetoothTM HAL (Hardware Abstraction Layer)[edit source]
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.
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 BluetoothTM device firmware[edit source]
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[edit source]
The AndroidTM distribution needs to be configured using How to configure AndroidTM distribution (BluetoothTM)
3.3. Validation[edit source]
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[edit source]
By default, there are no specific tools available to validate BluetoothTM AndroidTM 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 BluetoothTM connection[edit source]
Enable BluetoothTM in AndroidTM Settings and connect to a known BluetoothTM device (see AndroidTM One available answers for more information[3]).
3.3.3. Validate the AndroidTM Integration[edit source]
Several tests are available, refer to the official documents listed below:
4. References[edit source]