Go to file
Olivier Martin f99558d9b8 gattlib-py: Make pylint pass (and fix issue) 2024-04-24 14:37:28 +02:00
.github/workflows gattlib-py: Make pylint pass (and fix issue) 2024-04-24 14:37:28 +02:00
bluez Add support to retrieve all manufacturer data from GATT advertisement packets 2024-04-10 10:53:45 +02:00
ci gattlib-py: Fix setup.py when building source package 2024-04-11 22:01:28 +02:00
common common/gattlib_common: Add support to compare short UUID with long one 2024-04-24 14:37:28 +02:00
dbus gattlib_adapter_close: Do not block mutex while waiting for scan_loop_thread to complete 2024-04-11 00:28:24 +02:00
docs doc: Only build Python documention when Sphinx is installed 2020-04-03 23:59:27 +02:00
examples examples/notification: Port example to new gattlib API 2024-04-24 14:37:28 +02:00
gattlib-py gattlib-py: Make pylint pass (and fix issue) 2024-04-24 14:37:28 +02:00
include gattlib-py: Make pylint pass (and fix issue) 2024-04-24 14:37:28 +02:00
tests/test_continuous_connection Refactor code to better separate gattlib_adapter_t, gattlib_device_t, gattlib_connection_t and their backends 2024-04-05 13:20:40 +02:00
.gitignore Update ".gitignore" 2024-04-03 15:03:48 +02:00
.travis.yml Initial generated documentation support 2019-07-15 23:33:13 +02:00
CMakeLists.txt examples/notification: Port example to new gattlib API 2024-04-24 14:37:28 +02:00
CrossCompilation.cmake Clarify and update license 2021-09-01 00:04:00 +02:00
README.md Update README 2024-03-29 00:20:41 +01:00
requirements.dep Initial Python support 2019-07-07 22:17:49 +02:00
update-dev-tag.sh Update 'dev' tag on success 2019-05-19 11:44:47 +02:00


GattLib is a library used to access Generic Attribute Profile (GATT) protocol of BLE (Bluetooth Low Energy) devices. It has been introduced to allow to build applications that could easily communicate with BLE devices.

It supports Bluez v4 and v5.

Latest GattLib Release packages

  • The latest release can be found here. It contains:
  • Prebuilt Debian, RPM and ZIP packages for x86_64 and Bluez v5.x

  • Packages for ARM 32bit and 64bit would have to be built by the developer - see section Package GattLib.

  • Prebuilt Python packages are available on Pypi repository.

Build GattLib

  • Gattlib requires the following packages: libbluetooth-dev, libreadline-dev.
    On Debian based system (such as Ubuntu), you can installed these packages with the following command: sudo apt install libbluetooth-dev libreadline-dev
cd <gattlib-src-root>
mkdir build && cd build
cmake ..
  • Gattlib can also be built for a specific version of Bluez by specifying its version at build time:
mkdir build && cd build
cmake -DBLUEZ_VERSION=5.50 ..
  • On Bluez versions prior to v5.42, gattlib used Bluez source code while it uses D-Bus API from v5.42. D-Bus API can be used on version prior to Bluez v5.42 by using the CMake flag -DGATTLIB_FORCE_DBUS=TRUE:
mkdir build && cd build


To cross-compile GattLib, you must provide the following environment variables:

  • CROSS_COMPILE: prefix of your cross-compile toolchain
  • SYSROOT: an existing system root that contains the libraries and include files required by your application


cd <gattlib-src-root>
mkdir build && cd build
export CROSS_COMPILE=~/Toolchains/gcc-linaro-4.9-2015.05-x86_64_arm-linux-gnueabihf/bin/arm-linux-gnueabihf-
export SYSROOT=~/Distributions/debian-wheezy
cmake ..

Package GattLib

From the build directory: cpack ..

Note: It generates DEB, RPM and ZIP packages. Ensure you have the expected dependencies installed on your system (eg: to generate RPM package on Debian-based Linux distribution you must have rpm package installed).

Default install directory is defined as /usr by CPack variable CPACK_PACKAGE_INSTALL_DIRECTORY.
To change the install directory to /usr/local run: cpack -DCPACK_PACKAGE_INSTALL_DIRECTORY=/usr/local ..


Note 1: The example 'read/write mem' is similar to the example 'read/write' except a GLib loop is used to allows the memory to be freed by Glib. Without this loop, some memory could be locked.

Note 2: examples/gatttool has been partially ported to gattlib. There are two reasons: the laziness (some of the GATT functions could be replaced by their gattlib equivalent) and the completeness (there are still some missing functions in gattlib).

  • Notification is also supported. Example:
void notification_cb(uint16_t handle, const uint8_t* data, size_t data_length, void* user_data) {
	printf("Notification on handle 0x%02x\n", handle);

main() {
	uint16_t status_handle; // Handle of the 'status' characteristic
	uint16_t enable_notification = 0x0001;

	// Enable Status Notification
	gattlib_write_char_by_handle(connection, status_handle + 1, &enable_notification, sizeof(enable_notification));
	// Register notification handler
	gattlib_register_notification(connection, notification_cb, NULL);

Known limitations

  • gattlib and BLE: gattlib requires at least Bluez v4.100 to work with Bluetooth Low Energy (BLE) devices. Bluez does not allow to connect to BLE device prior to this version. But gattlib can still work with Bluetooth Classic (BR/EDR) prior to Bluez v4.100.
    Debian 7 "Wheezy" (supported until 31st of May 2018) relies on Bluez v4.99 while Debian 8 "Jessie" (supported until April/May 2020) uses Bluez v5.23.


  • Complete examples/gatttool port to GattLib to demonstrate the completeness of GattLib.
  • Remove GLib dependencies to GattLib (mainly replacing GLib IO Channels by Unix Domain Socket).


Gattlib with Bluez Legacy support (for Bluez v4) has a GPL v2.0 or later license.
While Gattlib for recent version of Bluez (v5.40+) has a BSD-3-Clause license - except dbus/bluez5/lib/uuid.c and dbus/bluez5/lib/uuid.h that have a GPL v2.0 or later license.


Commercial Support can be obtained through Lab A Part. Please contact us: https://labapart.com/about/.