intel-iot-devkit / littleb

This project aims to create a clean, modern and easy to use Bluetooth Low Energy API. LittleB exposes the BLE GATT API for Pure C using BlueZ over SD-Bus.

DISCONTINUATION OF PROJECT

This project will no longer be maintained by Intel. Intel has ceased development and contributions including, but not limited to, maintenance, bug fixes, new releases, or updates, to this project. Intel no longer accepts patches to this project. LittleB: Bluetooth Low Energy Library

This project aims to create a clean, modern and easy to use Bluetooth Low Energy API. LittleB exposes the BLE GATT API for Pure C using BlueZ over SD-Bus.

API Documentation

WIP

Using LittleB

LittleB requires CMake 3.1+ for building. 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.

mkdir build
cd build
cmake ..
make
make install

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

The hellolittleb example uses Arduino 101 flashed with StandardFirmataBLE (https://github.com/firmata/arduino/tree/master/examples/StandardFirmataBLE) It is looking for a bluetooth device named "FIRMATA" and will connect to it and make the on board LED blink.

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

Contributing to LittleB

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

littleb's Issues

lb_context is passed to all methods

Are there any use cases where there would be multiple lb_contexts used? I think lb_init should allocate a single lb_context and save it for any other method to use, instead of having it passed as a parameter every single time.

Cannot get primary UUIDs without connecting to device

It is possible to get primary UUIDs by getting UUIDsproperty but API does not get or expose this property.

littleb.c:1579:5: buffer owerflow

When bulding lillteb with following flags -fmessage-length=0 -grecord-gcc-switches -O2 -Wall -D_FORTIFY_SOURCE=2 -fstack-protector-strong -funwind-tables -fasynchronous-unwind-tables

following warning appears:

[    3s] /home/abuild/rpmbuild/BUILD/littleb-0.1.0/src/littleb.c:1466:12: warning: unused variable 'i' [-Wunused-variable]
[    3s]      int r, i;
[    3s]             ^
[    3s] In file included from /usr/include/stdio.h:936:0,
[    3s]                  from /home/abuild/rpmbuild/BUILD/littleb-0.1.0/api/littleb.h:29,
[    3s]                  from /home/abuild/rpmbuild/BUILD/littleb-0.1.0/src/littleb.c:24:
[    3s] In function 'snprintf',
[    3s]     inlined from 'lb_register_characteristic_read_event' at /home/abuild/rpmbuild/BUILD/littleb-0.1.0/src/littleb.c:1579:5:
[    3s] /usr/include/bits/stdio2.h:64:10: warning: call to __builtin___snprintf_chk will always overflow destination buffer
[    3s]    return __builtin___snprintf_chk (__s, __n, __USE_FORTIFY_LEVEL - 1,
[    3s]           ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[    3s]         __bos (__s), __fmt, __va_arg_pack ());
[    3s]         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Strongly suggesting that there is potential buffer overflow

Device does not have to be paired to get services

lb_get_ble_device_services() should not call lb_pair_device()

How can I query devices discovered by lb_get_bl_devices()

This call populates an internal list of devices that are only accessible via API calls. There appears to be no way of searching through devices to determine which ones expose a specific primary service.

I propose two new API calls to address this use case
lb_result_t lb_get_bl_device_count(lb_context lb_ctx, int* device_count);
lb_result_t lb_get_bl_device(lb_context lb_ctx, int device_index, lb_bl_device** bl_device);

Cannot determine if device is active and in range

Bluez caches devices found in previous discoveries so the lb_get_bl_devices() call can create a list with inactive entries. To speed up interrogation of devices it is useful to know which ones are active (i.e. powered on and and in range). This is possible by checking if the RSSI device property is greater than 0. However this property is only valid if discovery is in progress. To achieve this, we need to add an rssi field to device structure and three new API calls
lb_start_discovery()
lb_get_bl_devices_no_scan()
lb_stop_discovery()

Thanks to @petreeftime for this tip. If someone has a better idea, let me know.

I will implement for littleb.

Problems with thread management?

1. Each time lb_register_characteristic_read_event() is called a new thread is created. Only the last one to be created is closed down by lb_destroy() leading to memory leakage.
2. If lb_destroy() called is without lb_register_characteristic_read_event() being called, pthread_cancel() generates a segfault as it was invoked with an invalid thread handle.

I can fix these, but wanted to make sure they were valid problems.