Bluetooth Low-Energy on Linux API

Question

I have a device with a few custom GATT services, and I would like to write a Linux program to interact with it. After some searching I found out that Linux is using BlueZ to handle the Bluetooth LE protocol. I'm using Ubuntu 15.10 with BlueZ 5.35, but I cannot figure out how use this BlueZ from a user-space program. I cannot find an API documentation anywhere, no tutorials, examples, nothing. Is it even possible to use this BlueZ stack to do anything other than just connecting to Bluetooth devices with default services? And if so, where is the documentation? (Preferably C/C++ API but at this point anything goes)

Answer 1

• Have a look at attrib/gatttool.c in the bluez sources [1]. Gatttool is a command line utility for connecting to BTLE devices using the C "API". The GATT interface is not exposed in libbluetooth though.

• A newer alternative to gatttool and thus another example to learn from is the btgatt-client, which you can find in tools/btgatt-client.c (to enable compilation configure bluez with --enable-experimental).

• Besides the C interface bluez integrated a DBUS interface. bluetoothctl is an example tool using the DBUS interface. The code of bluetoothctl can be found in client/ [2].

• Another example program using the C interface of bluez is the Anki Drive SDK [3]. It packaged the bluez GATT C interface in its own library libbzle [4]. When using the C interface you have to connect a socket when establishing a BTLE connection. The gatttool does this via the GATT interface, which in turn uses glib iirc. But you can also do this using syscalls (socket, connect, ...) as explained e.g. here [5]. This document also explains:

Unfortunately, as of now there is no official API reference to refer to, so more curious readers are advised to download and examine the BlueZ source code.

Gilbert Brault also extracted the GATT interface from bluez [6] and links to a rudimentary doxygen documentation of the GATT interface [7] with the following disclaimer:

This is a work in progress with the intent of documenting all important functions and data structures

Also Szymon Janc gave a nice overview in his talk "Bluetooth on Modern Linux" at the Embedded Linux Conference 2016 [8]. Starting at 42:00 he talks about the unexposed C interface. But in general he seems to recommend the DBUS API (see "Tips" slide at 45:30). Some DBUS documentation can be found in doc/gatt-api.txt [9] and Python examples using the DBUS interface can be found in test/.

Hope this helps.

[1] http://git.kernel.org/cgit/bluetooth/bluez.git/tree/attrib/gatttool.c
[2] http://git.kernel.org/cgit/bluetooth/bluez.git/tree/client/
[3] https://github.com/anki/drive-sdk/
[4] https://github.com/anki/drive-sdk/tree/master/deps/bzle/
[5] https://people.csail.mit.edu/albert/bluez-intro/c404.html
[6] https://github.com/gbrault/gattclient
[7] http://gbrault.github.io/gattclient/index.html
[8] https://www.youtube.com/watch?v=tclS9arLFzk
[9] http://git.kernel.org/cgit/bluetooth/bluez.git/tree/doc/gatt-api.txt