README.md


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325


    Contents⊕
  
  
  Direct-BT
  LE and BREDR Library + Tiny Bluetooth LE Library
  Git Repository
  Goals
  Version 2
  
  Direct-BT
  TinyB
  TinyB and Direct-BT
  
  API Documentation
  Examples
  Supported Platforms
  Build Status
  Building Binaries
  Changes
  Common issues
  Contributing to TinyB
  / Direct-BT
  

Direct-BT
LE and BREDR Library + Tiny Bluetooth LE Library
Git Repository
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.
As of today, the TinyB Java API comprises two
implementations, Direct-BT and TinyB.
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 device
discovery to GATT programming, using its platform agnostic HCI and
GATT/L2CAP client-side protocol implementation.
AdapterStatusListener
allows listening to adapter changes and device discovery and GATTCharacteristicListener
to GATT indications and notifications.
Direct-BT may be utilized via its C++
API or via the refactored TinyB 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.
You will find a detailed overview of Direct-BT in the
doxygen generated C++
API doc of its direct_bt namespace.
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, ATT-PDU and GATT (as well to Linux/BlueZ-Mngr[1])
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 BT
devices, as well as LE w/o LE Secure Connections.
Work on LE Secure Connections is in progress and BREDR (non
LE, or classic mode) is planned and prepared for.
[1] Linux/BlueZ-Mngr is still used for adapter configuration
and shall be removed to support universal platforms, implementing the
Bluetooth host-side protocols.

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
Direct-BT is the new implementation as provided by Zafena ICT and Gothel Software.
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 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 tinyb2.jar,
avoiding conflicts.
General interfaces matching the original implementation and following
BlueZ
API were created in package org.tinyb.
org.tinyb.BluetoothFactory provides a factory to instantiate
the initial root org.tinyb.BluetoothManager, either using
Tiny-B, the original D-Bus implementation, or
Direct-BT, the direct implementation.
TinyB's C++ namespace and implementation kept mostly
unchanged.
The new Java interface of package org.tinyb has been kept
mostly compatible, however, changes were required to benefit from
Direct-BT's implementation.
since 2.x version tags have been added to the Java interface
specification for clarity.
API Documentation
Up to date API documentation can be found:

Brief
overview of direct_bt.
C++
API Doc.
Java
API Doc.
Jau
C++ Standalone API Doc.

A guide for getting started with Direct-BT on C++ and Java
may follow up.
Examples
Direct-BT C++
examples are available, dbt_scanner10.cpp
demonstrates the event driven and multithreading workflow.
Direct-BT Java
examples are availble, DBTScanner10.java
demonstrates the event driven and multithreading workflow - matching
dbt_scanner10.cpp.
A guide for getting started with TinyB on Java is available
from Intel: https://software.intel.com/en-us/java-for-bluetooth-le-apps.
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

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

After we have resolved the last Linux/Bluez dependency in DBTManager
for BT adapter configuration, we should be capable working on other
systems than GNU/Linux.
Build Status
Will be updated
Building Binaries
The project requires CMake 3.13+ for building and a Java JDK >=
11.
This project also uses the Jau C++ 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):
apt install git
apt install build-essential g++ gcc libc-dev libpthread-stubs0-dev 
apt install libunwind8 libunwind-dev
apt install libglib2.0 libglib2.0-0 libglib2.0-dev
apt install openjdk-11-jdk openjdk-11-jre
apt install cmake cmake-extras extra-cmake-modules pkg-config
apt install doxygen graphviz
For a generic build use:
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
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 not build the TinyB implementation:
-DSKIP_TINYB=ON
To build examples:
-DBUILDEXAMPLES=ON
To build documentation run:
make doc
Changes
2.1.30 Early Direct-BT Maturity (Bluetooth
LE)

TODO
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

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 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.