summaryrefslogtreecommitdiffstats
path: root/README.md
blob: 07b57149b2d985b8825aafa9c58e6da92c20eb3a (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

Tiny Bluetooth LE Library / Direct-BT LE and BREDR Library

Git Repository

This project's canonical repository is hosted on Zafena ICT.

Goals

This project aims to create a clean, modern and easy to use Bluetooth LE and BREDR API fully accessible through C++, Java and other languages.

TinyB Version 2

Starting with version 2.1.0, the specification has slightly changed and hence its implementation.

As of today, the TinyB Java API comprises two implementations, TinyB and Direct-BT.

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.

Direct-BT

Direct-BT provides direct Bluetooth LE and BREDR programming without intermediate layers targeting high-performance reliable Bluetooth support.

By having least system and userspace dependencies and no communication overhead, Direct-BT shall be suitable for embedded device configurations besides others.

Direct-BT supports a fully event driven workflow from discovery to GATT programming. 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.

You will find a detailed overview of Direct-BT in the doxygen generated C++ API doc of its direct_bt namespace.

To use Direct-BT in the most efficient way, the BlueZ userspace daemon bluetoothd should be disabled. Using systemd this should be:

systemctl stop bluetooth
systemctl disable bluetooth
systemctl mask bluetooth

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

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:

A guide for getting started with Direct-BT on C++ and Java will follow up soon from Zafena ICT.

Direct-BT C++ examples are available, dbt_scanner10.cpp demonstrates the event driven and multithreading workflow.

Direct-BT Java examples are availble, ScannerTinyB10.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.

Build Status

Will be updated soon

Using TinyB / Direct-BT

The project requires CMake 3.1+ for building and a Java JDK >= 11.

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

git clone https://ict.zafena.se/cgit/direct_bt.git
cd direct_bt
mkdir build
cd build
cmake -DBUILDJAVA=ON -DBUILDEXAMPLES=ON -DBUILD_TESTING=ON ..
make
make 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:

-DCMAKE_BUILD_TYPE=DEBUG

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

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.

Changes

  • 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 create a new issue on Zafena ICT.

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-02 10:41:33 +0000