This project's canonical repositories is hosted on Gothel Software.
Goals
This project aims to create a clean, modern and easy to use API for
Bluetooth
LE and BREDR, fully accessible through C++, Java and other
languages.
Version 2
Starting with version 2.1.0, the TinyB Java API has been
refactored to support all new features of its new Direct-BT
implementation.
Starting with version 2.2.0, the Java API has changed to clarify
semantics, further support Direct-BT and to favor a shortened
naming convention, e.g. BluetoothManager to BTManager,
BluetoothGattCharacteristic to BTGattChar etc.
As of today, the Java API comprises two implementations,
Direct-BT (complete) and TinyB (incomplete).
Direct-BT
Direct-BT provides direct Bluetooth
LE and BREDR programming, offering robust high-performance support
for embedded & desktop with zero overhead via C++ and Java.
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.
Direct-BT may be utilized via its C++
API or via its Java
API.
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.
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 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. 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.:
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.
Examples
The capsh method (default), setcap and
root method is being utilized in
If you like to utilize Direct-BT in a commercial setting,
please contact us to setup a potential support contract.
TinyB
TinyB exposes the BLE GATT API for C++, Java and other
languages, using BlueZ over DBus.
TinyB does not expose the BREDR API.
TinyB is exposed via the following native libraries
libtinyb.so for the core C++ implementation.
libjavatinyb.so for the Java binding.
TinyB is the original implementation of the TinyB project by
Intel.
TinyB does not cover all API functionality anymore: Event
driven adapter, device and GATT handling nor SMP Secure Connections.
TinyB and Direct-BT
Pre version 2.0.0 D-Bus implementation details of the Java[tm]
classes of package tinyb has been moved to tinyb.dbus.
The tinyb.jar jar file has been renamed to
direct_bt.jar, avoiding conflicts.
Offering the fat jar direct_bt-fat.jar, bootstrapping its
contained native libraries. This functionality is provided by the
merged-in jaulib package.
General interfaces matching the Bluetooth
Specification were created in package org.direct_bt.
Direct-BT's C++ API and implementation contains detailed references to
the official specification.
org.direct_bt.BTFactory provides a factory to instantiate
the initial root org.direct_bt.BTManager, either using
Direct-BT or Tiny-B (D-Bus) implementation.
TinyB's C++ namespace and implementation kept mostly
unchanged.
The new Java interface has changed. Package renamed from
org.tinyb to org.direct_bt and most names have been
shortened, e.g. BluetoothManager to BTManager,
BluetoothGattCharacteristic to BTGattChar etc.
since 2.x version tags have been added to the Java interface
specification for clarity.
The hellotinyb example uses a TI
Sensor Tag from which it reads the ambient temperature. You have to
pass the MAC address of the Sensor Tag as a first parameter to the
program.
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)
The project requires CMake 3.13+ for building and a Java JDK >=
11.
This project also uses the Jau Library as a
git submodule, which has been extracted earlier from this project to
better encapsulation and allow general use.
TinyB requires GLib/GIO 2.40+. It also requires
BlueZ with GATT profile activated, which is currently
experimental (as of BlueZ 5.37), so you might have to run
bluetoothd with the -E flag. For example, on a system with systemd
(Fedora, poky, etc.) edit the bluetooth.service file (usually found in
/usr/lib/systemd/system/ or /lib/systemd/system) and append -E to
ExecStart line, restart the daemon with systemctl restart bluetooth.
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
Installing build dependencies on Debian (10 or 11):
CPU_COUNT=`getconf _NPROCESSORS_ONLN`
git clone --recurse-submodules https://jausoft.com/cgit/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:
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 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
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 TinyB /
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.
