Skip to content

Latest commit

 

History

History
623 lines (470 loc) · 27.8 KB

README.md

File metadata and controls

623 lines (470 loc) · 27.8 KB
Raw

Direct-BT LE and BREDR Library

Original document location.

Git Repository

This project's canonical repositories is hosted on Gothel Software.

Overview

Direct-BT provides direct Bluetooth LE and BREDR programming, offering robust high-performance support for embedded & desktop with zero overhead via C++ and Java.

It supports a fully event driven workflow from adapter management and device discovery to GATT programming, using its platform agnostic HCI, L2CAP, SMP and GATT protocol implementation.

Multiple Bluetooth adapter are handled, as well as multiple concurrent connections per adapter.

Peripheral server device programming is supported as well as the central client, which is also used for Java and C++ self unit testing across two or more Bluetooth adapter.

Further, the provided repeater application allows to connect between a Bluetooth client and server to analyze their protocol.

Direct-BT has been used successfully in a medical trial, as well as in a connected medical device application.

The Jau C++ and Java support library has been extracted to encapsulate its generic use-cases.

Below you can find a few notes about Direct-BT Origins.

The Direct-BT project needs funding and we offer commercial support
Please contact Göthel Software (Jausoft).

Further Readings

Details

You will find a detailed overview of Direct-BT (C++) and the same in the Java API.
See details on the C++ and Java API including its different C++ API level modules.

AdapterStatusListener allows listening to adapter changes and device discovery and BTGattCharListener to GATT indications and notifications.

Direct-BT is exposed via the following native libraries

  • libdirect_bt.so for the core C++ implementation.
  • libjavadirect_bt.so for the Java binding.

Direct-BT is C++20 conform.

Some elaboration on the implementation details

The host-side of HCI, L2CAP etc is usually implemented within the OS, e.g. Linux/BlueZ Kernel. These layers communicate with the actual BT controller and the user application, acting as the middleman.

Direct-BT offers packet types and handler facilities for HCI, L2CAP, SMP, ATT-PDU and GATT (as well to Linux/BlueZ-Mngr) to communicate with these universal host-side Bluetooth layers and hence to reach-out to devices.

Implementation Status

LE master/client mode is fully supported to work with LE BT devices.

  • In both roles, a GATT Server with listener can be attached

LE slave/server mode (peripheral) is fully supported with LE BT devices:

  • BTRole separation (master/slave)
  • Advertising
  • GATT Server with user code interaction via listener
  • Slave / Server SMP Security, reusing persisting SMPKeyBin files.
  • Resolvable Private Address (RPA) for remote LE master/GATT clients

SMP LE Secure Connections and LE legacy pairing is fully supported, exposing BTSecurityLevel and SMPIOCapability setup per connection and providing automatic security mode negotiation including authentication.

Provoding dbt_repeater00, a BT repeater forwading between GATT-Server and -Client, allowing protocol analysis between an external client and server.

Online unit testing with two BT adapter is provided.

BREDR support is planned and prepared for.

To support other platforms than Linux/BlueZ, we will have to

  • move specified HCI host features used in DBTManager to HCIHandler, SMPHandler,.. - and -
  • add specialization for each new platform using their non-platform-agnostic features.

Direct-BT Default Connection Parameter

Please check the Connection Paramter for details.

Supported Platforms

Minimum language requirements

See supported platforms for details.

C++ Minimum Requirements

C++20 is the minimum requirement for releases > 3.2.4, see jaulib C++ Minimum Requirements.

Release 3.2.4 is the last version conforming to C++17, see Changes.

Tested Bluetooth Adapter

  • Bluetooth 4.0

    • Intel Bluemoon Bluetooth Adapter (Internal, ID: 8087:0a2a) OK
    • Intel Wireless (Internal, ID: 8087:07dc) OK
    • CSR Bluetooth Adapter (USB-A, ID: 0a12:0001, CSR8510) OK
    • Raspberry Pi Bluetooth Adapter (Internal, BCM43455 on 3+, 4) OK
    • Asus BT-400 Broadcom BCM20702A Bluetooth (USB-A, ID 0b05:17cb, BCM20702A1) OK
    • Broadcom Corp. BCM2046B1, part of BCM2046 Bluetooth (Internal, ID 0a5c:4500) OK

  • Bluetooth 5.0

    • Intel AX200 (Internal, ID 8087:0029) OK
    • Intel AX201 (Internal, ID 8087:0026) OK
    • Asus BT-500 (USB-A, ID 0b05:190e, RTL8761BU) OK on Debian12/Kernel 5.14)
    • Realtek RTL8761BU OK (May need manual power-up, depending on firmware)

Please check the adapter list for more details.

Using Direct-BT Applications

System Preparations

Since Direct-BT is not using a 3rd party Bluetooth client library or daemon/service, they should be disabled to allow operation without any interference. To disable the BlueZ D-Bus userspace daemon bluetoothd via systemd, you may use the following commands.

systemctl stop bluetooth
systemctl disable bluetooth
systemctl mask bluetooth

Required Permissions for Direct-BT Applications

Since Direct-BT requires root permissions to certain Bluetooth network device facilities, non-root user require to be granted such permissions.

For GNU/Linux, these permissions are called capabilities. The following capabilites are required

  • CAP_NET_RAW (Raw HCI access)
  • CAP_NET_ADMIN (Additional raw HCI access plus (re-)setting the adapter etc)

On Debian >= 11 and Ubuntu >= 20.04 we can use package libcap2-bin, version 1:2.44-1, which provides the binaries /sbin/setcap and /sbin/getcap. It depends on package libcap2, version >= 1:2.33. If using earlier setcap binaries, your mileage may vary (YMMV).

Launch as root

In case your platform lacks support for mentioned setcap, you may need to execute your application as root using sudo, e.g.:

LD_LIBRARY_PATH=`pwd`/dist-amd64/lib sudo dist-amd64/bin/dbt_scanner10

Launch as user using setcap

To launch your Direct-BT application as a user, you may set the required capabilities before launch via setcap

sudo setcap 'cap_net_raw,cap_net_admin+eip' dist-amd64/bin/dbt_scanner10
LD_LIBRARY_PATH=`pwd`/dist-amd64/lib dist-amd64/bin/dbt_scanner10

Launch as user via capsh

Alternatively one can set the required capabilities of a Direct-BT application and launch it as a user via capsh.

sudo /sbin/capsh --caps="cap_net_raw,cap_net_admin+eip cap_setpcap,cap_setuid,cap_setgid+ep" \
   --keep=1 --user=$USER --addamb=cap_net_raw,cap_net_admin+eip \
   -- -c "YOUR FANCY direct_bt STUFF"

Notable here is that capsh needs to be invoked by root to hand over the capabilities and to pass over the cap_net_raw,cap_net_admin+eip via --addamb=... it also needs cap_setpcap,cap_setuid,cap_setgid+ep beforehand.

Launch Examples

The capsh method (default), setcap and root method is being utilized in

(FIXME: scripts needs to be overhauled to reflect new CMake build/dist folder)

See Examples below ...

Programming with Direct-BT

API

Exposed API closely follows and references the Bluetooth Specification.

API Documentation

Up to date API documentation can be found:

A guide for getting started with Direct-BT on C++ and Java may follow up.

Java Specifics

org.direct_bt.BTFactory provides a factory to instantiate the initial root org.direct_bt.BTManager, using the Direct-BT implementation.

Examples

Direct-BT C++ examples are available, demonstrating the event driven and multithreading workflow:

Direct-BT Java examples are availble, demonstrates the event driven and multithreading workflow:

(FIXME: scripts needs to be overhauled to reflect new CMake build/dist folder)

Building Direct-BT

This project also uses the Jau C++ and Java Support Library as a git submodule, which has been extracted from this project to encapsulate its generic use-cases.

This project also uses the TinyCrypt as a git submodule, supporting AES128 for IRK w/ LE Resolvable Private Address (RPA) matching.

Direct-BT does not require GLib/GIO nor shall the BlueZ userspace service bluetoothd be active for best experience.

To disable the bluetoothd service using systemd:

systemctl stop bluetooth
systemctl disable bluetooth
systemctl mask bluetooth

Build Dependencies

  • CMake >= 3.21 (2021-07-14)
  • C++ compiler
    • gcc >= 11 (C++20), recommended >= 12.2.0
    • clang >= 13 (C++20), recommended >= 18.1.6
  • Optional for lint validation
    • clang-tidy >= 18.1.6
  • Optional for eclipse and vscodium integration
    • clangd >= 18.1.6
    • clang-tools >= 18.1.6
    • clang-format >= 18.1.6
  • Optional
    • libunwind8 >= 1.2.1
    • libcurl4 >= 7.74 (tested, lower may work)
  • Optional Java support
    • OpenJDK >= 11
    • junit4 >= 4.12

Install on Debian or Ubuntu

Installing build dependencies for Debian >= 12 and Ubuntu >= 22:

apt install git
apt install build-essential g++ gcc libc-dev libpthread-stubs0-dev 
apt install clang-18 clang-tidy-18 clangd-18 clang-tools-18 clang-format-18
apt install libunwind8 libunwind-dev
apt install openjdk-17-jdk openjdk-17-jre junit4
apt install cmake cmake-extras extra-cmake-modules pkg-config
apt install doxygen graphviz

If using optional clang toolchain, perhaps change the clang version-suffix of above clang install line to the appropriate version.

After complete clang installation, you might want to setup the latest version as your default. For Debian you can use this clang alternatives setup script.

Build Procedure

Build preparations

git clone --recurse-submodules git://jausoft.com/srv/scm/direct_bt.git
cd direct_bt

CMake Build via Presets

Analog to jaulib CMake build presets ...

Following debug presets are defined in CMakePresets.json

  • debug
    • default generator
    • default compiler
    • C++20
    • debug enabled
    • disabled clang-tidy
    • java (if available)
    • libunwind enabled
    • no: libcurl
    • testing on
    • testing with 2 bluetooth trial on
    • testing with sudo off
    • binary-dir build/debug
    • install-dir dist/debug
  • debug-clang
    • inherits from debug
    • compiler: clang
    • enabled clang-tidy
    • binary-dir build/debug-clang
    • install-dir dist/debug-clang
  • debug-gcc
    • inherits from debug
    • compiler: gcc
    • disabled clang-tidy
    • binary-dir build/debug-gcc
    • install-dir dist/debug-gcc
  • release
    • inherits from debug
    • debug disabled
    • disabled clang-tidy
    • libunwind disabled
    • binary-dir build/release
    • install-dir dist/release
  • release-clang
    • compiler: clang
    • enabled clang-tidy
    • binary-dir build/release-clang
    • install-dir dist/release-clang
  • release-gcc
    • compiler: gcc
    • disabled clang-tidy
    • binary-dir build/release-gcc
    • install-dir dist/release-gcc
  • default
    • inherits from debug-clang
    • binary-dir build/default
    • install-dir dist/default

All presets enable full unit testing including actual Bluetooth trials, i.e. require two adapter to pass.

Kick-off the workflow by e.g. using preset release-gcc to configure, build, test, install and building documentation. You may skip install and doc by dropping it from --target.

cmake --preset release-gcc
cmake --build --preset release-gcc --parallel
cmake --build --preset release-gcc --target test install doc

You may utilize scripts/build-preset.sh for an initial build, install and test workflow.

CMake Build via Hardcoded Presets

Analog to jaulib CMake hardcoded presets ...

Besides above CMakePresets.json presets, JaulibSetup.cmake contains hardcoded presets for undefined variables if

  • CMAKE_INSTALL_PREFIX and CMAKE_CXX_CLANG_TIDY cmake variables are unset, or
  • JAU_CMAKE_ENFORCE_PRESETS cmake- or environment-variable is set to TRUE or ON

The hardcoded presets resemble debug-clang presets.

Kick-off the workflow to configure, build, test, install and building documentation. You may skip install and doc by dropping it from --target.

rm -rf build/default
cmake -B build/default
cmake --build build/default --parallel
cmake --build build/default --target test install doc

The install target of the last command will create the include/ and lib/ directories with a copy of the headers and library objects respectively in your dist location.

CMake Variables

Our cmake configure has a number of options, cmake-gui or ccmake can show you all the options. The interesting ones are detailed below:

See jaulib CMake variables for details.

Unit Testing

Building with enabled testing, i.e. offline testing without any potential interaction as user is provided via the cmake build argument -DBUILD_TESTING=ON, see above.

Building with enabled trial and testing , i.e. live testing with 2 Bluetooth adapter is provided via the cmake build argument -DBUILD_TRIAL=ON, see above.

Both is enabled with above CMake presets.

The trial tests utilize one or more actual Bluetooth adapter, hence using the capsh launch for the required permissions as described above. Therefor, sudo will be called and a user interaction to enter the sudo password may occur.

The trial tests cover Direct-BT's Bluetooth functionality, having its master/client and slave/server peripheral facilities communicating via actual adapter, supporting regression testing of the API, its implementation and adapter.

The tests are implemented in both, C++ and Java. The C++ unit tests are also being used for valgrind memory leak and data race validation. At this point we are free of leaks and use-after-free issues.

The trial tests take around 110 seconds, since TestDBClientServer1* performs the test twelve fold altogether:

  • Two fold between installed adapter in both directions
  • Three fold w/o encryption, in legacy mode (SC 0) and secure connections (SC 1)
  • Two fold each test
    • without encryption just twice
    • with encryption
      • with ENC_ONLY encryption and initial key pairing
      • with ENC_ONLY encryption and reusing pre-paired keys

All tests pass reproducible using two well working adapter, e.g. Raspi 3b+ (BT4) and CSR (BT4).

1/7 legacy security (SC 0) tests using at least one not well working BT5 adapter may timeout waiting for key completion. The following issues are known and are under investigation:

  • BlueZ is not sending us all new key information under legacy security (SC 0) using at least one BT5 adapter
    • This is mitigated by BTAdapter's smp_watchdog, leading to a retrial visible as SMP Timeout

Build Scripts

Build scripts use the recommended cmake presets, supported via e.g. scripts/build-preset.sh.

  • scripts/build-preset.sh .. initial build incl. install and unit testing using presets
  • scripts/rebuild-preset.sh .. rebuild using presets
  • scripts/build-preset-cross.sh .. cross-build using presets
  • scripts/rebuild-preset-cross.sh .. cross-build using presets
  • scripts/test_java.sh .. invoke a java unit test
  • scripts/test_exe_template.sh .. invoke the symlink'ed files to invoke native unit tests

Cross Build

Also provided is a cross-build script using chroot into a target system using QEMU User space emulation and Linux kernel binfmt_misc to run on other architectures than the host.

You may use our pi-gen branch to produce a Raspi-arm64, Raspi-armhf or PC-amd64 target image.

Build Status

Will be updated

IDE Integration

Eclipse

Tested Eclipse 2024-03 (4.31).

IDE integration configuration files are provided for

  • Eclipse with extensions
    • CDT or CDT @ eclipse.org
    • CDT-LSP recommended
      • Should work with clang toolchain >= 16
      • Utilizes clangd, clang-tidy and clang-format to support C++20 and above
      • Add to available software site: https://download.eclipse.org/tools/cdt/releases/cdt-lsp-latest
      • Install C/C++ LSP Support in the Eclipse CDT LSP Category
    • CMake Support, install C/C++ CMake Build Support with ID org.eclipse.cdt.cmake.feature.group

The Hardcoded CMake Presets will use build/default as the default build folder with debug enabled.

Make sure to set the environment variable CMAKE_BUILD_PARALLEL_LEVEL to a suitable high number, best to your CPU core count. This will enable parallel build with the IDE.

You can import the project to your workspace via File . Import... and Existing Projects into Workspace menu item.

For Eclipse one might need to adjust some setting in the .project and .cproject (CDT) via Eclipse settings UI, but it should just work out of the box.

Otherwise recreate the Eclipse project by

  • delete .project and .cproject
  • File . New . C/C++ Project and Empty or Existing CMake Project while using this project folder.

VSCodium or VS Code

IDE integration configuration files are provided for

For VSCodium one might copy the example root-workspace file to the parent folder of this project (note the filename change) and adjust the path to your filesystem.

cp .vscode/direct_bt.code-workspace_example ../direct_bt.code-workspace
vi ../direct_bt.code-workspace

Then you can open it via File . Open Workspace from File... menu item.

  • All listed extensions are referenced in this workspace file to be installed via the IDE
  • Select one of the CMake Presets for
    • Configuration
    • Build
    • Test

Support & Sponsorship

Direct-BT is the new implementation as provided by Gothel Software and Zafena ICT.

If you like to utilize Direct-BT in a commercial setting, please contact Gothel Software to setup a potential support contract.

Common issues

If you have any issues, please go through the Troubleshooting Guide.

If the solution is not there, please search for an existing issue in our Bugzilla DB, please contact us for a new bugzilla account via email to Sven Gothel [email protected].

Contributing to Direct-BT

You shall agree to Developer Certificate of Origin and Sign-off your code, using a real name and e-mail address.

Please check the Contribution document for more details.

Historical Notes

Direct-BT Origins

Direct-BT development started around April 2020, initially as an alternative TinyB Java-API implementation.

The work was motivated due to strict performance, discovery- and connection timing requirements, as well as being able to handle multiple devices concurrently using a real-time event driven low-overhead architecture.

Zafena's POC-Workstation was originally implemented using TinyB and hence the D-Bus layer to the BlueZ client library.

Real time knowledge when devices are discovered and connected were not available and cloaked by the caching mechanism. Advertising package details were not exposed.

Connections attempts often took up to 10 seconds to be completed. Detailed information from the Bluetooth layer were inaccessible including detailed error states.

Fine grained control about discovery and connection parameter were not exposed by the D-Bus API and hence TinyB.

In January 2020 we tried to remedy certain aspects to meet our goals, but concluded to require direct Bluetooth control via the BlueZ/Linux kernel implementation.

Direct-BT was born.

We then implemented data types for

  • HCI Packets to handle HCI communication with the adapter
  • Mgmt Packets to support BlueZ/Linux communication
  • ATT PDU Messages to handle GATT communication with the remote device
  • SMP Packets to implement Secure Connections (SC) and Legacy pairing.

Last but not least we added

  • Bluetooth version 5 support
  • GATT-Server support to enable implementing peripheral devices, as well as to allow self-testing of Direct-BT.

Today, Direct-BT's C++ and Java API match 1:1 and shall not contain legacy API artifacts.

TinyB Removal since version 2.3

Heading towards feature completion for Direct-BT, we completely removed the previously refactored TinyB.

Detailing full Bluetooth support in Direct-BT including the addition of GATT-Server support rendered TinyB an obstacle for the public API.

However, TinyB inspired us and was a great reference implementation while developing and testing Direct-BT.

We like to thank the authors of TinyB for their great work helping others and us moving forward. Thank you!

TinyB

TinyB was developed by the Intel Corporation and its main authors were

TinyB was licensed under the The MIT License (MIT) and the Intel Corporation holds its copyright from the year 2016.

Changes

See Changes.