This article describes the integration steps required to connect your own Bluetooth device. It deals mainly with the Android 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 your selected microprocessor device. See the list of Android Distribution Package.
The Bluetooth (BT) device must be connected to the microprocessor device within your 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@1.0) → 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 main steps:
- Linux kernel integration
- Android integration
- Validation
3.1. Linux kernel integration[edit source]
In kernel Bluetooth integration is performed in two steps:
- Add the Bluetooth driver within 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 is two options regarding the Bluetooth device driver module:
- 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 in the
build_kernel.shscript
3.1.2. Update the Linux device tree[edit source]
Depending on the driver selected, a device tree update may be required (refer to Changing the Device Tree for more information).
3.2. Android integration[edit source]
The Bluetooth device integration within Android is performed in several steps:
- Add permissions to allow starting the required 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 Bluetooth services are started correctly:
android.hardware.bluetooth.xmlfor Bluetooth servicesandroid.hardware.bluetooth_le.xmlfor Bluetooth Low Energy services
For that purpose, it is required to add the following lines within 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 Bluetooth HAL must be generated and provided with a vendor library convenient for your Bluetooth device.
A Linux generic Bluetooth vendor library is available in system/bt/vendor_libs/. It is convenient for devices fully controllable through the Linux HCI socket abstraction. However, to take full advantage of some devices, a dedicated vendor library should be preferred 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, it may be required to load a firmware within the device.
The firmware must be copied within the correct target's 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 in the ramdisk (rootfs) to ensure that it is available during the first stage of 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 required to add the firmware within the rootfs
3.2.4. Configure the Android service[edit source]
It is then required to configure the Android distribution: see 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 is no available tool to validate Bluetooth connection in the Android distribution. You may use the BlueZ tools, loading the associated source[2]:
btmgmt(orhciconfigfor older version): used to configure local hci 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 try to 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, please refer to the official documents associated:
4. References[edit source]