summaryrefslogtreecommitdiffstats
path: root/README.md
blob: 6708ab214da8f0e36770b1139d726dc674b5e9f2 (plain) 
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
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432

Direct-BT LE and BREDR 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.

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.

You will find a detailed overview of Direct-BT (C++) and the same in the Java API.

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 allows listening to adapter changes and device discovery and BTGattCharListener to GATT indications and notifications.

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

Direct-BT Non-Root Usage

Since Direct-BT requires root permissions to certain Bluetooth network device facilities, non-root users requires 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)

Either root gives the application to the binary file itself via setcap

setcap -v 'cap_net_raw,cap_net_admin+eip' dist-amd64/bin/dbt_scanner10

or via capsh to start the program

sudo /sbin/capsh --caps="cap_net_raw,cap_net_admin+eip cap_setpcap,cap_setuid,cap_setgid+ep" \
   --keep=1 --user=nobody --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.

The capsh method is now being utilized in

See Examples below ...

Direct-BT Sponsorship

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

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.

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.

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)

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

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 not build the TinyB implementation:

-DSKIP_TINYB=ON

To build examples:

-DBUILDEXAMPLES=ON

To build documentation run:

make doc

Changes

2.3.0 Direct-BT Maturity (Bluetooth LE)

  • TODO

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

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.

generated by cgit v1.2.3 (git 2.39.1) at 2024-12-12 00:27:25 +0000