aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
blob: d0dd77b959b982b609784396a34e8b74c7a1db43 (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
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572

Direct-BT LE and BREDR Library

Original document location.

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.

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.

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

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

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.

SMP LE Secure Connections and LE legacy pairing is fully 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.

Supported Platforms

The following platforms are tested and hence supported

Debian 12 Bookworm (GNU/Linux)

  • amd64 (validated, Generic)

Debian 11 Bullseye (GNU/Linux)

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

Debian 10 Buster (GNU/Linux)

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

Ubuntu 18.04 (GNU/Linux)

  • amd64 (validated, Generic)

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

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

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:

Building Direct-BT

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.

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.13+ but >= 3.18 is recommended
  • GCC >= 8.3.0 (g++)
    • or clang >= 10.0
  • libunwind8 >= 1.2.1
  • For Java support
    • OpenJDK >= 11.
    • junit4 >= 4.12

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 openjdk-11-jdk openjdk-11-jre junit4
apt install cmake cmake-extras extra-cmake-modules pkg-config
apt install doxygen graphviz

Build Procedure

The following is covered with a convenient build script.

For a generic build use:

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

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

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

3.0.0 Direct-BT Maturity (Bluetooth LE)

  • TODO

2.4.0

  • Completed Java support for LE slave/server (peripheral) mode incl GATT-Server.
  • Add BTAdapter's Slave Peripheral SMP Key Management
    • Full SMP key persistence in peripheral mode
  • Reshape SMPKeyBin design: Set and upload from BTDevice (split functionality), v5.
  • BTDevice::unpair() is now issued directly by Direct-BT to have a consistent and stable security workflow:
    • when a BTRole::Slave BTDevice is discovered, see AdapterStatusListener::deviceFound().
    • when a BTRole::Slave BTDevice is disconnected, see AdapterStatusListener::deviceDisconnected().
    • when a BTRole::Master BTDevice gets connected, see AdapterStatusListener::deviceConnected().
  • LE slave/server mode (peripheral): 1st Milestone
    • BTRole separation implemented and tested
    • Advertising implemented and tested
    • GATT Server implemented and tested
    • Slave / Server SMP Security implemented and testing
  • SMPKeyBin v4, added localAddress (adapter) to filename + bin-fmt.
  • Simplified SMP*Key class names and set[Default|Connected]LE_PHY() args.
  • Added EUI48 endian conversion when passing/receiving to Bluetooth
  • Passed validation of multiple BT5 adapter.
  • Fixed EInfoReport::read_[ext_]ad_reports() multiple reports
  • Added Link-Key support in our SMP processing and SMPKeyBin, supporting non-legacy SC.
  • Aligned BTGatt* findGatt*() methods across Java/C++
  • Moved EUI48, EUI48Sub (C++/Java) and uuid_t, Octets (C++) to jaulib for general use.
  • Added BTRole and GATTRole for full master/client and slave/server support.
  • Added BTAdapter advertising support
  • Only use and program selected BTAdapter via BTAdapter::initialize() (required now)
    • Supports using multiple applications, each using one adapter, or
    • One application using multiple adapter for different tasks and BTRole

2.3.0

  • 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 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
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-01 07:33:01 +0000