# Direct-BT LE and BREDR Library

[Original document location](https://jausoft.com/cgit/direct_bt.git/about/).

## Git Repository
This project's canonical repositories is hosted on [Gothel Software](https://jausoft.com/cgit/direct_bt.git/).

## Goals
This project aims to create a clean, modern and easy to use API for [Bluetooth LE and BREDR](https://www.bluetooth.com/specifications/bluetooth-core-specification/), 
fully accessible through C++, Java and other languages.

## Overview
*Direct-BT* provides direct [Bluetooth LE and BREDR](https://www.bluetooth.com/specifications/bluetooth-core-specification/) programming,
offering robust high-performance support for embedded & desktop with zero overhead via C++ and Java.

You will find a [detailed overview of *Direct-BT*](https://jausoft.com/projects/direct_bt/build/documentation/cpp/html/namespacedirect__bt.html#details) (C++)
and the [same in the Java API](https://jausoft.com/projects/direct_bt/build/documentation/java/html/namespaceorg_1_1direct__bt.html#details).

*Direct-BT* supports a fully event driven workflow from adapter management via device discovery to GATT programming.
using its platform agnostic HCI, L2CAP, SMP and GATT client-side protocol implementation.

[AdapterStatusListener](https://jausoft.com/projects/direct_bt/build/documentation/cpp/html/classdirect__bt_1_1AdapterStatusListener.html) 
allows listening to adapter changes and device discovery and
[BTGattCharListener](https://jausoft.com/projects/direct_bt/build/documentation/cpp/html/classdirect__bt_1_1BTGattCharListener.html)
to GATT indications and notifications.

*Direct-BT* may be utilized via its [C++ API](https://jausoft.com/projects/direct_bt/build/documentation/cpp/html/index.html)
or via its [Java API](https://jausoft.com/projects/direct_bt/build/documentation/java/html/index.html).

*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++17 conform and shall upgrade towards C++20 when widely available on all target platforms.

Some more elaboration on the implementation and its status
> 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.
> 
> Currently only the master/client mode is supported to work with LE BT devices.
> 
> *LE Secure Connections* and *LE legacy pairing* is supported,
> exposing BTSecurityLevel and SMPIOCapability setup per connection
> and providing *automatic security mode negotiation*.
>
> BLE slave periphal and GATT server support is underway.
>
> 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.


## Supported Platforms
The following **platforms** are tested and hence supported

**Debian 10 Buster (GNU/Linux)**

- amd64 (validated, Generic)
- arm64 (validated, Raspberry Pi 3+ and 4)
- arm32 (validated, Raspberry Pi 3+ and 4)

**Debian 11 Bullseye (GNU/Linux)**

- amd64 (validated, Generic)
- arm64 (should work, Raspberry Pi 3+ and 4)
- arm32 (should work, Raspberry Pi 3+ and 4)

The following **Bluetooth Adapter** were tested

* Bluetooth 4.0
  - Intel Bluemoon Bluetooth Adapter
  - CSR Bluetooth Adapter (CSR8510,..)
  - Raspberry Pi Bluetooth Adapter (BCM43455 on 3+, 4)

* Bluetooth 5.0
  - Intel AX200 Bluetooth 5.0 (Wi-Fi 6 802.11ax (2.4Gbps) + BT 5.0)
  - Realtek Bluetooth 5.0 (`RTK_BT_5.0`)


## 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, there permissions are called [capabilities](https://linux.die.net/man/7/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 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](https://linux.die.net/man/8/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](https://linux.die.net/man/1/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

- [scripts/run-dbt_scanner10.sh](https://jausoft.com/cgit/direct_bt.git/tree/scripts/run-dbt_scanner10.sh)
- [scripts/run-java-scanner10.sh](https://jausoft.com/cgit/direct_bt.git/tree/scripts/run-java-scanner10.sh)

See *Examples* below ...


## Programming with *Direct-BT*

### API
Exposed API closely follows and references the [Bluetooth Specification](https://www.bluetooth.com/specifications/bluetooth-core-specification/).

#### API Documentation
Up to date API documentation can be found:

* [API Overview](https://jausoft.com/projects/direct_bt/build/documentation/cpp/html/namespacedirect__bt.html#details) (C++)
and the [same in the Java API](https://jausoft.com/projects/direct_bt/build/documentation/java/html/namespaceorg_1_1direct__bt.html#details).

* [C++ API Doc](https://jausoft.com/projects/direct_bt/build/documentation/cpp/html/index.html).

* [Java API Doc](https://jausoft.com/projects/direct_bt/build/documentation/java/html/index.html).

* [jaulib Standalone C++ API Doc](https://jausoft.com/projects/jaulib/build/documentation/cpp/html/index.html).

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](https://jausoft.com/projects/direct_bt/build/documentation/cpp/html/examples.html)
are available, [dbt_scanner10.cpp](https://jausoft.com/projects/direct_bt/build/documentation/cpp/html/dbt_scanner10_8cpp-example.html)
demonstrates the event driven and multithreading workflow.

*Direct-BT* [Java examples](https://jausoft.com/projects/direct_bt/build/documentation/java/html/examples.html)
are availble, [DBTScanner10.java](https://jausoft.com/projects/direct_bt/build/documentation/java/html/DBTScanner10_8java-example.html)
demonstrates the event driven and multithreading workflow - matching *dbt_scanner10.cpp*.


## Building *Direct-BT*
The project requires CMake 3.13+ for building and a Java JDK >= 11.

This project also uses the [Jau Library](https://jausoft.com/cgit/jaulib.git/about/)
as a git submodule, which has been extracted earlier from this project
to better encapsulation and allow general use.

*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:

~~~~~~~~~~~~~~~~~~~~~~~~~~~{.sh}
systemctl stop bluetooth
systemctl disable bluetooth
systemctl mask bluetooth
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Installing build dependencies on Debian (10 or 11):

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.sh}
apt install git
apt install build-essential g++ gcc libc-dev libpthread-stubs0-dev 
apt install libunwind8 libunwind-dev
apt install openjdk-11-jdk openjdk-11-jre junit4
apt install cmake cmake-extras extra-cmake-modules pkg-config
apt install doxygen graphviz
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For a generic build use:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.sh}
CPU_COUNT=`getconf _NPROCESSORS_ONLN`
git clone --recurse-submodules git://jausoft.com/srv/scm/direct_bt.git
cd direct_bt
mkdir build
cd build
cmake -DBUILDJAVA=ON -DBUILDEXAMPLES=ON -DBUILD_TESTING=ON ..
make -j $CPU_COUNT install test 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 build location. Note that
doing an out-of-source build may cause issues when rebuilding later on.

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

Changing install path from /usr/local to /usr

~~~~~~~~~~~~~
-DCMAKE_INSTALL_PREFIX=/usr
~~~~~~~~~~~~~

Building debug build:

~~~~~~~~~~~~~
-DDEBUG=ON
~~~~~~~~~~~~~

Disable stripping native lib even in non debug build:

~~~~~~~~~~~~~
-DUSE_STRIP=OFF
~~~~~~~~~~~~~

Override default javac debug arguments `source,lines`:

~~~~~~~~~~~~~
-DJAVAC_DEBUG_ARGS="source,lines,vars"

-DJAVAC_DEBUG_ARGS="none"
~~~~~~~~~~~~~

Building debug and instrumentation (sanitizer) build:

~~~~~~~~~~~~~
-DDEBUG=ON -DINSTRUMENTATION=ON
~~~~~~~~~~~~~

Using clang instead of gcc:

~~~~~~~~~~~~~
-DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++
~~~~~~~~~~~~~

Cross-compiling on a different system:

~~~~~~~~~~~~~
-DCMAKE_CXX_FLAGS:STRING=-m32 -march=i586
-DCMAKE_C_FLAGS:STRING=-m32 -march=i586
~~~~~~~~~~~~~

To build Java bindings:

~~~~~~~~~~~~~
-DBUILDJAVA=ON
~~~~~~~~~~~~~

To build examples:

~~~~~~~~~~~~~
-DBUILDEXAMPLES=ON
~~~~~~~~~~~~~

To build documentation run: 

~~~~~~~~~~~~~
make doc
~~~~~~~~~~~~~

## Build Status
*Will be updated*


## Support & Sponsorship

*Direct-BT* is the new implementation as provided by [Gothel Software](https://jausoft.com/) and [Zafena ICT](https://ict.zafena.se).

If you like to utilize *Direct-BT* in a commercial setting, 
please contact [Gothel Software](https://jausoft.com/) to setup a potential support contract.

## Common issues
If you have any issues, please go through the [Troubleshooting Guide](TROUBLESHOOTING.md). 

If the solution is not there, please search for an existing issue in our [Bugzilla DB](https://jausoft.com/bugzilla/describecomponents.cgi?product=Direct-BT),
please [contact us](https://jausoft.com/) for a new bugzilla account via email to Sven Gothel <sgothel@jausoft.com>.


## 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](CONTRIBUTING.md) document for more details.

## Historical Notes

### *TinyB* Removal since version 2.3
Starting with version 2.3, the previously refactored *TinyB* has been removed completely.

Motivation was lack of detailed Bluetooth support, inclusive increasing diversion with *Direct-BT*.
Furthermore, work is underway for `BLE slave periphal and GATT server` support and its mapping to *BlueZ D-Bus* is questionable
and would be resource intensive.

## Changes
**2.3.0 *Direct-BT* Maturity (Bluetooth LE)**

* TODO

**2.3.00**

* Removal of *TinyB*

**2.2.14**

* Bluetooth 5.0 Support
  - Using HCI extended scanning and connecting if supported (old API may not work on new adapter)
  - Parsing and translating extended and enhanced event types, etc
  - TODO: User selection of `LE_2M` and `L2_CODED`, ... ???

**2.2.13**

* Revised API: BTGattChar::addCharListener(..) in C++ and Java for a more intuitive use.
* Fix EUI48Sub::scanEUI48Sub(..): Fail on missing expected colon, i.e. after each two digits
* Fix JNIAdapterStatusListener::deviceConnected(..): NewObject(.., deviceClazzCtor, ..) used wrong argument order

**2.2.11**

* Fix EUI48 unit test and refine on application permissions for launching applications 
* Make `BTDeviceRegistry` and `BTSecurityRegistry` universal
* Move `BTDeviceRegistry` and `BTSecurityRegistry` to `direct_bt` library (from examples)
* EUI48Sub: Complement with `hash_code()`, `clear()`, `indexOf()`, `contains()`, ...
* SMPKeyBin: Tighten constraints, `readAndApply(..)` must validate `minSecLevel`.
* `BTAdapter::mgmtEvDeviceFoundHCI(..)`: Clarify code path, covering name change via AD EIR.
* Passthrough all paramter `BTAdapter::startDiscovery(..)` -> `HCIHandler::le_set_scan_param(..)`: Add `le_scan_active` and `filter_policy`. 
  Active scanning is used to gather device name in discovery mode (AD EIR).
* Add `-dbt_debug` argument for AD EIR `direct_bt.debug.hci.scan_ad_eir` and parse EIR GAPFlags
* Fix BTGattHandler: Gather all Descriptors from all Characteristics (only queried 1st Char.)
* SMPKeyBin's base filename compatibility with FAT32 Long Filename (LFN)

**2.2.5**

* Complete SMPKeyBin user API: Convenient static 'one shot' entries + support no-encryption case
* Fix leaked AdapterStatusListener
* Fixed HCIHandler and l2cap related issues
* Unified free function to_string(..) and member toString()
* Tested key regeneration use-case: Pairing failure (bad key), key removal and auto security negotiation.
* Adding SMPKeyBin file removal support.
* Tested negative passkey/boolean input, requested via auto security negotiation. 
* Using negative passkey response via `setPairingPasskey(passkey = 0)` for performance.

**2.2.4**

* Providing full featured `SMPKeyBin` for LTK, CSRK and secure connection param setup persistence and upload.
* Added Auto Security mode, negotiating the security setup with any device.
* Bugfixes in HCIHandler and ACL/SMP packet processing.
* Enhanced robusteness of underlying C++ API and implementation.

**2.2.00**

* Kicked off junit testing for Java implementation
* Adding *direct_bt-fat.jar* (fat jar) bootstrapping its contained native libraries using merged-in `jaulib`.
* Java API renaming, incl package: *org.tinyb* to *org.direct_bt*.
* Completing SMP/Security implementation (WIP)
* Replaced std::vector and jau::cow_vector with jau::darray and jau::cow_darray

**2.1.33**

* Added AdapterStatusListener callback methods devicePairingState(..) and deviceReady(..), supporting security/pairing. 
* Added support for *LE Secure Connections* and *LE legacy pairing* utilizing SMP and BlueZ/Kernel features.
* Exposing BTSecurityLevel and SMPIOCapability for connection oriented security setup on BlueZ/Kernel, see DBTDevice and BluetoothDevice.
* Covering SMP over L2CAP messaging via SMPPDUMsg types and retrieval via HCI/ACL/L2CAP on BlueZ/Kernel

**2.1.30**

* Use read lock-free jau::cow_vector for all callback-lists, avoiding locks in callback iteration
* Passed GCC all warnings, compile clean
* Passed GCC sanitizer runtime checks
* Using extracted *Jau C++ Support Library*, enhanced encapsulation
* Passed valgrind's memcheck, helgrind and drd validating no memory leak nor data race or deadlock using dbt_scanner10
* Added native de-mangled backtrace support using *libunwind* and and *abi::__cxa_demangle*
* Reaching robust implementation state of *Direct-BT*, including recovery from L2CAP transmission breakdown on Raspberry Pi.
* Resolved race conditions on rapid device discovery and connect, using one thread per device.
* API documentation with examples
* Tested on GNU/Linux x86_64, arm32 and arm64 with native and Java examples.
* Tested on Bluetooth Adapter: Intel, CSR and Raspberry Pi
* Almost removed non-standard *Linux/BlueZ-Mngr* kernel dependency using the universal HCI protocol, remaining portion configures the adapter.

**2.0.0**

* Java D-Bus implementation details of package 'tinyb' moved to *tinyb.dbus*.
* The *tinyb.jar* jar file has been renamed to *tinyb2.jar*, avoiding conflicts.
* General interfaces matching the original implementation and following [BlueZ API](http://git.kernel.org/cgit/bluetooth/bluez.git/tree/doc/device-api.txt)
were created in package *org.tinyb*.
* Class *org.tinyb.BluetoothFactory* provides a factory to instantiate the initial root *org.tinyb.BluetoothManager*, either using the original D-Bus implementation or an alternative implementation.
* C++ namespace and implementation kept unchanged.

**0.5.0**

* Added notifications API
* Capitalized RSSI and UUID properly in Java
* Added JNI Helper classes for managing lifetime of JNIEnv and Global Refences

**0.4.0**

* Added asynchronous methods for discovering BluetoothObjects